docs: add FAQ with 10 tutorials mapped to value propositions

Each FAQ answer includes a working code example (Python + TypeScript
where applicable) and links to the relevant guide. README value
proposition table now links directly to FAQ anchors.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: apartsin

README.md

@@ -167,16 +167,16 @@ Ten reasons to add ModelMesh to your next project.
 
 | # | Value | Feature | How It Delivers |
 |---|---|---|---|
-| **1** | **Integrate in two minutes, scale the configuration as you grow** | **[Progressive Configuration](docs/index.md)** | **Env vars** for instant start. **YAML** for providers, pools, strategies, budgets, secrets. **Programmatic** for dynamic setups. All three compose seamlessly |
-| **2** | **One familiar API across every provider you will ever use** | **[Uniform OpenAI-Compatible API](docs/guides/Capabilities.md)** | Same `client.chat.completions.create()` for OpenAI, Anthropic, Gemini, DeepSeek, Mistral, Ollama, or custom models. Chat, embeddings, TTS, STT, image generation. Swap providers in config, never in code |
-| **3** | **Chain free tiers so you never hit a quota wall** | **[Free-Tier Aggregation](docs/guides/QuickStart.md)** | Set free API keys, call `create("chat")`. The library detects providers, pools them by capability, and rotates silently when a quota exhausts. Your code sees one provider; ModelMesh manages the rotation |
-| **4** | **Provider goes down, your app stays up** | **[Resilient Routing](docs/guides/ErrorHandling.md)** | Multiple rotation strategies: cost-first, latency-first, round-robin, sticky, rate-limit-aware. On failure the router deactivates the model, selects the next candidate, and retries within the same request |
-| **5** | **Request capabilities, not model names** | **[Capability Discovery](docs/guides/Capabilities.md)** | Ask for `"chat-completion"`, not `"gpt-4o"`. ModelMesh resolves to the best available model. New models appear, old ones deprecate, your code stays the same |
-| **6** | **Spending caps enforced before the overage, not after** | **[Budget Enforcement](docs/guides/QuickStart.md#usage-tracking)** | Real-time cost tracking per model and provider. Set daily or monthly limits in config. `BudgetExceededError` fires before the breaching request |
-| **7** | **One library for Python backend, TypeScript frontend, Docker proxy** | **[Full-Stack Deployment](docs/guides/QuickStart.md)** | `pip install`, `npm install`, or `docker run`. Each exposes the same API with zero core dependencies. One config file drives all deployment modes |
-| **8** | **Test AI code like regular code** | **[Mock Client and Testing](docs/guides/Testing.md)** | `mock_client(responses=[...])` returns an identical API with zero network calls and millisecond execution. Typed exceptions carry structured metadata. `client.explain()` dry-runs routing decisions |
-| **9** | **Production-grade observability without extra plumbing** | **[Observability Connectors](docs/ConnectorCatalogue.md)** | Pre-built sinks for console, file, JSON-log, Prometheus, and webhooks. Structured traces across routing, failover, and budget events. Plug in custom callbacks for existing dashboards |
-| **10** | **When pre-built doesn't fit, extend without forking** | **[CDK](docs/ConnectorCatalogue.md)** | Base classes for providers, rotation policies, secret stores, storage backends, and observability sinks. Inherit, override what you need, ship as a reusable package |
+| **1** | **Integrate in two minutes, scale the configuration as you grow** | **[Progressive Configuration](docs/guides/FAQ.md#1-how-quickly-can-i-integrate-modelmesh-into-my-project)** | **Env vars** for instant start. **YAML** for providers, pools, strategies, budgets, secrets. **Programmatic** for dynamic setups. All three compose seamlessly |
+| **2** | **One familiar API across every provider you will ever use** | **[Uniform OpenAI-Compatible API](docs/guides/FAQ.md#2-do-i-need-to-learn-a-new-api)** | Same `client.chat.completions.create()` for OpenAI, Anthropic, Gemini, DeepSeek, Mistral, Ollama, or custom models. Chat, embeddings, TTS, STT, image generation. Swap providers in config, never in code |
+| **3** | **Chain free tiers so you never hit a quota wall** | **[Free-Tier Aggregation](docs/guides/FAQ.md#3-how-does-free-tier-aggregation-work)** | Set free API keys, call `create("chat")`. The library detects providers, pools them by capability, and rotates silently when a quota exhausts. Your code sees one provider; ModelMesh manages the rotation |
+| **4** | **Provider goes down, your app stays up** | **[Resilient Routing](docs/guides/FAQ.md#4-what-happens-when-a-provider-goes-down)** | Multiple rotation strategies: cost-first, latency-first, round-robin, sticky, rate-limit-aware. On failure the router deactivates the model, selects the next candidate, and retries within the same request |
+| **5** | **Request capabilities, not model names** | **[Capability Discovery](docs/guides/FAQ.md#5-what-does-request-capabilities-not-model-names-mean)** | Ask for `"chat-completion"`, not `"gpt-4o"`. ModelMesh resolves to the best available model. New models appear, old ones deprecate, your code stays the same |
+| **6** | **Spending caps enforced before the overage, not after** | **[Budget Enforcement](docs/guides/FAQ.md#6-how-do-i-prevent-surprise-ai-bills)** | Real-time cost tracking per model and provider. Set daily or monthly limits in config. `BudgetExceededError` fires before the breaching request |
+| **7** | **One library for Python backend, TypeScript frontend, Docker proxy** | **[Full-Stack Deployment](docs/guides/FAQ.md#7-can-i-use-modelmesh-with-my-existing-stack)** | `pip install`, `npm install`, or `docker run`. Each exposes the same API with zero core dependencies. One config file drives all deployment modes |
+| **8** | **Test AI code like regular code** | **[Mock Client and Testing](docs/guides/FAQ.md#8-how-do-i-test-ai-code-without-burning-api-credits)** | `mock_client(responses=[...])` returns an identical API with zero network calls and millisecond execution. Typed exceptions carry structured metadata. `client.explain()` dry-runs routing decisions |
+| **9** | **Production-grade observability without extra plumbing** | **[Observability Connectors](docs/guides/FAQ.md#9-what-observability-does-modelmesh-provide)** | Pre-built sinks for console, file, JSON-log, Prometheus, and webhooks. Structured traces across routing, failover, and budget events. Plug in custom callbacks for existing dashboards |
+| **10** | **When pre-built doesn't fit, extend without forking** | **[CDK](docs/guides/FAQ.md#10-what-if-the-pre-built-connectors-dont-cover-my-use-case)** | Base classes for providers, rotation policies, secret stores, storage backends, and observability sinks. Inherit, override what you need, ship as a reusable package |
 
 ## Key Features