Add comprehensive documentation and examples for Owlen architecture and usage

- Include detailed architecture overview in `docs/architecture.md`.
- Add `docs/configuration.md`, detailing configuration file structure and settings.
- Provide a step-by-step provider implementation guide in `docs/provider-implementation.md`.
- Add frequently asked questions (FAQ) document in `docs/faq.md`.
- Create `docs/migration-guide.md` for future breaking changes and version upgrades.
- Introduce new examples in `examples/` showcasing basic chat, custom providers, and theming.
- Add a changelog (`CHANGELOG.md`) for tracking significant changes.
- Provide contribution guidelines (`CONTRIBUTING.md`) and a Code of Conduct (`CODE_OF_CONDUCT.md`).

crates/owlen-core/src/provider.rs

@@ -9,6 +9,72 @@ use std::sync::Arc;
 pub type ChatStream = Pin<Box<dyn Stream<Item = Result<ChatResponse>> + Send>>;
 
 /// Trait for LLM providers (Ollama, OpenAI, Anthropic, etc.)
+///
+/// # Example
+///
+/// ```
+/// use std::pin::Pin;
+/// use std::sync::Arc;
+/// use futures::Stream;
+/// use owlen_core::provider::{Provider, ProviderRegistry, ChatStream};
+/// use owlen_core::types::{ChatRequest, ChatResponse, ModelInfo, Message};
+/// use owlen_core::Result;
+///
+/// // 1. Create a mock provider
+/// struct MockProvider;
+///
+/// #[async_trait::async_trait]
+/// impl Provider for MockProvider {
+///     fn name(&self) -> &str {
+///         "mock"
+///     }
+///
+///     async fn list_models(&self) -> Result<Vec<ModelInfo>> {
+///         Ok(vec![ModelInfo {
+///             provider: "mock".to_string(),
+///             name: "mock-model".to_string(),
+///             ..Default::default()
+///         }])
+///     }
+///
+///     async fn chat(&self, request: ChatRequest) -> Result<ChatResponse> {
+///         let content = format!("Response to: {}", request.messages.last().unwrap().content);
+///         Ok(ChatResponse {
+///             model: request.model,
+///             message: Message { role: "assistant".to_string(), content, ..Default::default() },
+///             ..Default::default()
+///         })
+///     }
+///
+///     async fn chat_stream(&self, request: ChatRequest) -> Result<ChatStream> {
+///         unimplemented!();
+///     }
+///
+///     async fn health_check(&self) -> Result<()> {
+///         Ok(())
+///     }
+/// }
+///
+/// // 2. Use the provider with a registry
+/// #[tokio::main]
+/// async fn main() {
+///     let mut registry = ProviderRegistry::new();
+///     registry.register(MockProvider);
+///
+///     let provider = registry.get("mock").unwrap();
+///     let models = provider.list_models().await.unwrap();
+///     assert_eq!(models[0].name, "mock-model");
+///
+///     let request = ChatRequest {
+///         model: "mock-model".to_string(),
+///         messages: vec![Message { role: "user".to_string(), content: "Hello".to_string(), ..Default::default() }],
+///         ..Default::default()
+///     };
+///
+///     let response = provider.chat(request).await.unwrap();
+///     assert_eq!(response.message.content, "Response to: Hello");
+/// }
+/// ```
 #[async_trait::async_trait]
 pub trait Provider: Send + Sync {
     /// Get the name of this provider