docs: add provider onboarding guide and update documentation for ProviderManager, health worker, and multi‑provider architecture

docs/adding-providers.md

@@ -0,0 +1,62 @@
+# Adding a Provider to Owlen
+
+This guide complements `docs/provider-implementation.md` with a practical checklist for wiring a new model backend into the Phase 10 architecture.
+
+## 1. Define the Provider Type
+
+Providers live in their own crate (for example `owlen-providers`). Create a module that implements the `owlen_core::provider::ModelProvider` trait:
+
+```rust
+pub struct MyProvider {
+    client: MyHttpClient,
+    metadata: ProviderMetadata,
+}
+
+#[async_trait]
+impl ModelProvider for MyProvider {
+    fn metadata(&self) -> &ProviderMetadata { &self.metadata }
+    async fn health_check(&self) -> Result<ProviderStatus> { ... }
+    async fn list_models(&self) -> Result<Vec<ModelInfo>> { ... }
+    async fn generate_stream(&self, request: GenerateRequest) -> Result<GenerateStream> { ... }
+}
+```
+
+Set `ProviderMetadata::provider_type` to `ProviderType::Local` or `ProviderType::Cloud` so the TUI can label it correctly.
+
+## 2. Register with `ProviderManager`
+
+`ProviderManager` owns provider instances and tracks their health. In your startup code (usually `owlen-cli` or an MCP server), construct the provider and register it:
+
+```rust
+let manager = ProviderManager::new(config);
+manager.register_provider(Arc::new(MyProvider::new(config)?.into())).await;
+```
+
+The manager caches `ProviderStatus` values so the TUI can surface availability in the picker and background worker events.
+
+## 3. Expose Through MCP (Optional)
+
+For providers that should run out-of-process, implement an MCP server (`owlen-mcp-llm-server` demonstrates the pattern). The TUI uses `RemoteMcpClient`, so exposing `generate_text` keeps the UI completely decoupled from provider details.
+
+## 4. Add Tests
+
+Commit 13 introduced integration tests in `crates/owlen-providers/tests`. Follow this pattern to exercise:
+
+- registration with `ProviderManager`
+- model aggregation across providers
+- routing of `generate` requests
+- provider status transitions when generation succeeds or fails
+
+In-memory mocks are enough; the goal is to protect the trait contract and the manager’s health cache.
+
+## 5. Document Configuration
+
+Update `docs/configuration.md` and the default `config.toml` snippet so users can enable the new provider. Include environment variables, auth requirements, or special flags.
+
+## 6. Update User-Facing Docs
+
+- Add a short entry to the feature list in `README.md`.
+- Mention the new provider in `CHANGELOG.md` under the “Added” section.
+- If the provider requires troubleshooting steps, append them to `docs/troubleshooting.md`.
+
+Following these steps keeps the provider lifecycle consistent with Owlen’s multi-provider architecture: providers register once, the manager handles orchestration, and the TUI reacts via message-driven updates.