docs: reorganize navigation, remove Key Features duplication

- Remove redundant Key Features section from README (duplicated by Why ModelMesh table)
- Replace Key Features in docs/index.md with Why ModelMesh value proposition table
- Reorganize docs/index.md navigation into grouped sections:
  Getting Started, Core Concepts, Developer Guides, Deployment,
  API Reference, Runtime Services, Extending ModelMesh (CDK), Samples
- Surface 33 previously hidden docs (interfaces/ and system/ directories)
- Fix stale test badge count (1,873 → 1,879)

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

Author: apartsin

README.md

@@ -178,19 +178,6 @@ Ten reasons to add ModelMesh to your next project.
 | **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
-
-| Feature | Description |
-|---|---|
-| **OpenAI-compatible** | Drop-in replacement for any OpenAI SDK client |
-| **Multi-provider routing** | OpenAI, Anthropic, Gemini, Groq, and more |
-| **Automatic failover** | Retry with backoff, then rotate to next model |
-| **Free-tier aggregation** | Chain quotas across providers |
-| **Capability-based pools** | Request tasks, not specific providers |
-| **8 rotation strategies** | Stick-until-failure, cost-first, latency-first, round-robin, and more |
-| **Pluggable connectors** | Extend any integration point with the CDK |
-| **Zero dependencies** | Core library has no external dependencies |
-
 ## Documentation
 
 | Document | Description |

docs/index.md

@@ -17,7 +17,7 @@ title: ModelMesh Lite
   <img src="https://img.shields.io/badge/typescript-5.0%2B-blue" alt="TypeScript 5.0+">
   <img src="https://img.shields.io/badge/docker-supported-2496ED" alt="Docker">
   <a href="https://github.com/ApartsinProjects/ModelMesh/blob/master/LICENSE"><img src="https://img.shields.io/badge/license-MIT-green" alt="License"></a>
-  <a href="https://github.com/ApartsinProjects/ModelMesh/actions"><img src="https://img.shields.io/badge/tests-1%2C873%20passed-brightgreen" alt="Tests"></a>
+  <a href="https://github.com/ApartsinProjects/ModelMesh/actions"><img src="https://img.shields.io/badge/tests-1%2C879%20passed-brightgreen" alt="Tests"></a>
   <a href="https://apartsinprojects.github.io/ModelMesh/"><img src="https://img.shields.io/badge/docs-GitHub%20Pages-blue" alt="Documentation"></a>
 </p>
 
@@ -166,52 +166,83 @@ pools:
 client = modelmesh.create(config="modelmesh.yaml")
 ```
 
-## Key Features
+## Why ModelMesh
 
-| Feature | Description |
-|---|---|
-| **OpenAI-compatible** | Drop-in replacement for any OpenAI SDK client |
-| **Multi-provider routing** | OpenAI, Anthropic, Gemini, Groq, and more |
-| **Automatic failover** | Retry with backoff, then rotate to next model |
-| **Free-tier aggregation** | Chain quotas across providers |
-| **Capability-based pools** | Request tasks, not specific providers |
-| **8 rotation strategies** | Stick-until-failure, cost-first, latency-first, round-robin, and more |
-| **Structured error handling** | Typed exceptions with retry hints and structured metadata |
-| **Request/response middleware** | Intercept calls for logging, transforms, caching, error fallbacks |
-| **Built-in test mocking** | `mock_client()` / `mockClient()` for unit testing without APIs |
-| **Usage & budget tracking** | Real-time cost, token, and budget monitoring via `client.usage` |
-| **Capability discovery** | Search, resolve, and explore capabilities without memorizing paths |
-| **Routing explanation** | Debug routing decisions with `client.explain()` dry-run API |
-| **Pluggable connectors** | Extend any integration point with the CDK |
-| **Zero dependencies** | Core library has no external dependencies |
+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](guides/FAQ.html#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](guides/FAQ.html#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](guides/FAQ.html#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](guides/FAQ.html#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](guides/FAQ.html#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](guides/FAQ.html#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](guides/FAQ.html#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](guides/FAQ.html#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](guides/FAQ.html#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](guides/FAQ.html#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 |
 
 ## Documentation
 
+### Getting Started
+
+| Document | Description |
+|---|---|
+| **[FAQ](guides/FAQ.html)** | Ten questions developers ask before adopting, each with a working code tutorial |
+| **[Developer Quick Start](guides/QuickStart.html)** | Get productive in 5 minutes: all features walkthrough with cheat sheet |
+
+### Core Concepts
+
 | Document | Description |
 |---|---|
 | **[System Concept](SystemConcept.html)** | Architecture, design, and full feature overview |
 | **[Model Capabilities](ModelCapabilities.html)** | Capability hierarchy tree and predefined pools |
 | **[System Configuration](SystemConfiguration.html)** | Full YAML configuration reference |
 | **[Connector Catalogue](ConnectorCatalogue.html)** | All pre-shipped connectors with config schemas |
-| **[Connector Interfaces](ConnectorInterfaces.html)** | Interface definitions for all connector types |
-| **[System Services](SystemServices.html)** | Runtime objects: Router, Pool, Model, State |
 
-### Guides
+### Developer Guides
 
 | Document | Description |
 |---|---|
-| **[FAQ](guides/FAQ.html)** | Ten questions developers ask before adopting, each with a working code tutorial |
-| **[Developer Quick Start](guides/QuickStart.html)** | Get productive in 5 minutes: all features walkthrough with cheat sheet |
 | **[Error Handling](guides/ErrorHandling.html)** | Exception hierarchy, catch patterns, retry guidance |
 | **[Middleware](guides/Middleware.html)** | Write custom middleware: logging, transforms, caching, error fallbacks |
 | **[Testing](guides/Testing.html)** | Unit testing with `mock_client()` — no API keys needed |
 | **[Capabilities](guides/Capabilities.html)** | Discover, resolve, and search capability aliases |
+| **[Audio (TTS/STT)](ConnectorInterfaces.html#audio)** | AudioRequest/AudioResponse types, `client.audio` namespace |
+
+### Deployment
+
+| Document | Description |
+|---|---|
 | **[Proxy Guide](guides/ProxyGuide.html)** | Deploy as OpenAI-compatible proxy: Docker, CLI, config, browser access |
-| **[AI Agent Integration](ForAIAgent.html)** | Guide for AI coding agents (Claude Code, Cursor, etc.) to integrate ModelMesh |
 | **[Browser Usage](guides/BrowserUsage.html)** | BrowserBaseProvider, CORS proxy setup, and browser-specific patterns |
-| **[Audio (TTS/STT)](ConnectorInterfaces.html#audio)** | AudioRequest/AudioResponse types, `client.audio` namespace |
+| **[AI Agent Integration](ForAIAgent.html)** | Guide for AI coding agents (Claude Code, Cursor, etc.) to integrate ModelMesh |
+
+### API Reference
 
-### CDK (Connector Development Kit)
+| Document | Description |
+|---|---|
+| **[Connector Interfaces](ConnectorInterfaces.html)** | Interface definitions for all connector types |
+| **[Provider](interfaces/Provider.html)** | Provider connector interface spec |
+| **[Rotation Policy](interfaces/RotationPolicy.html)** | Rotation policy interface spec |
+| **[Secret Store](interfaces/SecretStore.html)** | Secret store interface spec |
+| **[Storage](interfaces/Storage.html)** | Storage backend interface spec |
+| **[Observability](interfaces/Observability.html)** | Observability connector interface spec |
+| **[Discovery](interfaces/Discovery.html)** | Discovery connector interface spec |
+
+### Runtime Services
+
+| Document | Description |
+|---|---|
+| **[Overview](system/Overview.html)** | Runtime architecture and object graph |
+| **[System Services](SystemServices.html)** | Router, Pool, Model, and State runtime objects |
+| **[Router](system/Router.html)** | Request routing and retry logic |
+| **[Capability Pool](system/CapabilityPool.html)** | Pool lifecycle and model selection |
+| **[State Manager](system/StateManager.html)** | State persistence and recovery |
+| **[Event Emitter](system/EventEmitter.html)** | Event system for routing, failover, and budget events |
+
+### Extending ModelMesh (CDK)
 
 | Document | Description |
 |---|---|