docs: fix broken links, add cross-references across all documentation

apartsin · claude · apartsin · commit 6de45bafe0bb · 2026-03-11T13:06:21.000+02:00
- Fix 5 broken .md extension links in ForAIAgent.md (→ .html)
- Fix broken anchor #browserbAseprovider → #browserbaseprovider in ConnectorCatalogue.md
- Fix 4 wrong rotation strategy connector IDs in ProxyGuide.md to match actual code
- Standardize all FAQ internal links from .md to .html for GitHub Pages
- Add in-text cross-references throughout FAQ: capability pools → SystemConcept,
  hierarchy tree → ModelCapabilities, configuration → SystemConfiguration,
  BudgetExceededError → ErrorHandling, Docker proxy → ProxyGuide
- Add in-text cross-references to all 8 guide intros linking to related docs
- Add "See also" footer links to all 5 core reference docs (SystemConcept,
  SystemConfiguration, SystemServices, ConnectorInterfaces, ConnectorCatalogue)
- Add comprehensive reference table at end of FAQ linking all 14 documents
- Add FAQ link to ForAIAgent.md reference section

Co-Authored-By: Claude Opus 4.6 &lt;noreply@anthropic.com&gt;
diff --git a/docs/ConnectorCatalogue.md b/docs/ConnectorCatalogue.md
@@ -240,7 +240,7 @@ Non-AI web services can be wrapped as provider connectors using the same interfa
 | **BaseProvider** | Node.js | `http`/`https` | Node.js streams | Server-side applications, CLI tools, backend services |
 | **BrowserBaseProvider** | Browser, Deno, Bun, Workers | Fetch API | `ReadableStream` | Single-page apps, browser extensions, edge runtimes |
 
-Both classes expose the same provider interface and the same protected hooks for subclassing. See [cdk/BaseClasses.md](cdk/BaseClasses.html#browserbAseprovider) for details and [guides/BrowserUsage.md](guides/BrowserUsage.html) for browser setup.
+Both classes expose the same provider interface and the same protected hooks for subclassing. See [cdk/BaseClasses](cdk/BaseClasses.html#browserbaseprovider) for details and [guides/BrowserUsage](guides/BrowserUsage.html) for browser setup.
 
 ### Runtime Environment Metadata
 
@@ -646,3 +646,7 @@ Interface: [ConnectorInterfaces.md — Discovery](ConnectorInterfaces.html#disco
 | --- | --- |
 | **`discovery.modelmesh.registry-sync.v1`** | Synchronizes the local model catalogue with provider APIs on a configurable schedule. Detects new models, deprecated models, and pricing changes. Sync frequency and auto-registration are configurable per provider. |
 | **`discovery.modelmesh.health-monitor.v1`** | Probes providers at a configurable interval. Records latency, success/failure, and error codes; maintains rolling availability scores; feeds results into rotation policies for proactive deactivation. |
+
+---
+
+See also: [FAQ](guides/FAQ.html) · [Connector Interfaces](ConnectorInterfaces.html) · [CDK Base Classes](cdk/BaseClasses.html) · [System Configuration](SystemConfiguration.html)
diff --git a/docs/ConnectorInterfaces.md b/docs/ConnectorInterfaces.md
@@ -5,7 +5,7 @@ title: "Connector Interfaces"
 
 # Connector Interfaces
 
-**Interface overview for every ModelMesh Lite connector type.** Each section describes the connector's purpose and the interfaces it exposes. This is a conceptual overview, not a full specification. Full interface definitions with code are in [interfaces/](interfaces/Provider.html). Pre-shipped implementations are listed in [ConnectorCatalogue.md](ConnectorCatalogue.html).
+**Interface overview for every ModelMesh Lite connector type.** Each section describes the connector's purpose and the interfaces it exposes. This is a conceptual overview, not a full specification. Full interface definitions with code are in [interfaces/](interfaces/Provider.html). Pre-shipped implementations are listed in [ConnectorCatalogue.md](ConnectorCatalogue.html). For a tutorial on building custom connectors, see the [FAQ — CDK guide](guides/FAQ.html#10-what-if-the-pre-built-connectors-dont-cover-my-use-case).
 
 > **CDK:** Base classes with sensible defaults for each interface are available in the [Connector Development Kit](cdk/Overview.html). See [cdk/BaseClasses.md](cdk/BaseClasses.html) for implementations.
 
@@ -251,4 +251,8 @@ The `MeshClient` exposes audio through an OpenAI SDK-compatible namespace:
 | `client.audio.speech.create()` | `generation.audio.text-to-speech` | Generate speech from text. Routes to TTS providers (ElevenLabs, OpenAI, Google Cloud). |
 | `client.audio.transcriptions.create()` | `understanding.audio.speech-to-text` | Transcribe audio to text. Routes to STT providers (AssemblyAI, OpenAI Whisper, Groq). |
 
-Audio requests follow the same routing pipeline as text requests: capability resolution, pool selection, rotation policy, retry, and failover. Pools targeting `generation.audio` or `understanding.audio` collect all audio-capable models automatically.
+Audio requests follow the same routing pipeline as text requests: capability resolution, pool selection, [rotation policy](guides/FAQ.html#4-what-happens-when-a-provider-goes-down), retry, and failover. Pools targeting `generation.audio` or `understanding.audio` collect all audio-capable models automatically.
+
+---
+
+See also: [FAQ](guides/FAQ.html) · [Connector Catalogue](ConnectorCatalogue.html) · [CDK Base Classes](cdk/BaseClasses.html) · [System Configuration](SystemConfiguration.html)
diff --git a/docs/ForAIAgent.md b/docs/ForAIAgent.md
@@ -555,8 +555,9 @@ curl -s http://localhost:8080/v1/models | grep -q 'text-generation'
 
 - **Repository:** https://github.com/ApartsinProjects/ModelMesh
 - **Documentation:** https://apartsinprojects.github.io/ModelMesh/
-- **System Concept:** [docs/SystemConcept.md](SystemConcept.md)
-- **Configuration Reference:** [docs/SystemConfiguration.md](SystemConfiguration.md)
-- **Connector Catalogue:** [docs/ConnectorCatalogue.md](ConnectorCatalogue.md)
-- **Proxy Guide:** [docs/guides/ProxyGuide.md](guides/ProxyGuide.md)
-- **CDK Overview:** [docs/cdk/Overview.md](cdk/Overview.md)
+- **System Concept:** [docs/SystemConcept](SystemConcept.html)
+- **Configuration Reference:** [docs/SystemConfiguration](SystemConfiguration.html)
+- **Connector Catalogue:** [docs/ConnectorCatalogue](ConnectorCatalogue.html)
+- **Proxy Guide:** [docs/guides/ProxyGuide](guides/ProxyGuide.html)
+- **CDK Overview:** [docs/cdk/Overview](cdk/Overview.html)
+- **FAQ:** [docs/guides/FAQ](guides/FAQ.html)
diff --git a/docs/ModelCapabilities.md b/docs/ModelCapabilities.md
@@ -5,7 +5,7 @@ title: "Model Capability Taxonomy"
 
 # Model Capability Taxonomy
 
-**The complete capability hierarchy for ModelMesh Lite.** Models register at leaf nodes; pools target any node and include all descendants. The hierarchy is extensible — custom categories, subcategories, and leaf nodes follow the same routing, pooling, and inheritance rules as pre-shipped ones.
+**The complete capability hierarchy for ModelMesh Lite.** Models register at leaf nodes; pools target any node and include all descendants. The hierarchy is extensible — custom categories, subcategories, and leaf nodes follow the same routing, pooling, and inheritance rules as pre-shipped ones. For the programmatic discovery API, see [Capability Discovery](guides/Capabilities.html). For which providers support which capabilities, see [Connector Catalogue](ConnectorCatalogue.html).
 
 ---
 
@@ -147,4 +147,8 @@ Users add custom pools (e.g., `code-review`, `medical-summarization`, `long-cont
 
 ## Extending the Hierarchy
 
-Custom categories, subcategories, and leaf nodes can be added at any level (e.g., `compliance` → `pii-detection`, `regulatory-review`). Custom nodes follow the same routing, pooling, and inheritance rules as pre-shipped ones. Extension points are defined via configuration or at runtime through the API.
+Custom categories, subcategories, and leaf nodes can be added at any level (e.g., `compliance` → `pii-detection`, `regulatory-review`). Custom nodes follow the same routing, pooling, and inheritance rules as pre-shipped ones. Extension points are defined via [YAML configuration](SystemConfiguration.html) or at runtime through the API — see [Capability Discovery](guides/Capabilities.html) for both approaches.
+
+---
+
+See also: [System Concept](SystemConcept.html) · [Capability Discovery Guide](guides/Capabilities.html) · [Connector Catalogue](ConnectorCatalogue.html) · [FAQ](guides/FAQ.html)
diff --git a/docs/SystemConcept.md b/docs/SystemConcept.md
@@ -306,3 +306,5 @@ ModelMesh Lite ships with a **User Manual** (integration, configuration, deploym
 ---
 
 The capability taxonomy and predefined pools are in **[ModelCapabilities.md](ModelCapabilities.html)**. Runtime objects and services (Router, CapabilityPool, Model, Provider, and others) are in **[SystemServices.md](SystemServices.html)** with individual service docs in **[system/](system/Overview.html)**. Connector interface definitions are in **[ConnectorInterfaces.md](ConnectorInterfaces.html)** with full interface specifications in **[interfaces/](interfaces/Provider.html)**. The full connector and provider catalogue is in **[ConnectorCatalogue.md](ConnectorCatalogue.html)** with individual connector docs in **[connectors/](connectors/openai-llm.html)**. YAML configuration reference is in **[SystemConfiguration.md](SystemConfiguration.html)**. The Connector Development Kit documentation is in **[cdk/Overview.md](cdk/Overview.html)** with base class reference in **[cdk/BaseClasses.md](cdk/BaseClasses.html)** and tutorials in **[cdk/DeveloperGuide.md](cdk/DeveloperGuide.html)**.
+
+For a hands-on introduction with working code samples, see the **[FAQ](guides/FAQ.html)** and **[Quick Start](guides/QuickStart.html)** guides.
diff --git a/docs/SystemConfiguration.md b/docs/SystemConfiguration.md
@@ -5,7 +5,7 @@ title: "System Configuration"
 
 # System Configuration
 
-**YAML configuration reference for ModelMesh Lite.** The system is configured declaratively via YAML, programmatically via API, or both. Configuration can be serialized to and deserialized from [storage connectors](ConnectorInterfaces.html#storage) for centralized management and sharing across instances. For the runtime objects that consume this configuration see [SystemServices.md](SystemServices.html).
+**YAML configuration reference for ModelMesh Lite.** The system is configured declaratively via YAML, programmatically via API, or both. Configuration can be serialized to and deserialized from [storage connectors](ConnectorInterfaces.html#storage) for centralized management and sharing across instances. For the runtime objects that consume this configuration see [SystemServices.md](SystemServices.html). For a tutorial-style introduction, see the [FAQ](guides/FAQ.html) and [Quick Start](guides/QuickStart.html).
 
 ---
 
@@ -652,3 +652,7 @@ Request: "parse 500 invoice PDFs, return structured JSON"
 5. Strategy application      → cost-first → Claude Sonnet (Anthropic)
 6. Intelligent retry         → on transient failure, retry with backoff → rotate to GPT-4o (OpenAI)
 ```
+
+---
+
+See also: [FAQ](guides/FAQ.html) · [Quick Start](guides/QuickStart.html) · [Connector Catalogue](ConnectorCatalogue.html) · [Connector Interfaces](ConnectorInterfaces.html) · [System Concept](SystemConcept.html)
diff --git a/docs/SystemServices.md b/docs/SystemServices.md
@@ -668,3 +668,7 @@ Coordinates persistence of runtime state (ModelState, ProviderState, pool member
 | `storage.persistence.sync_interval` | duration | Interval for `periodic` sync (e.g., `300s`). |
 
 **Depends on:** StorageConnector.
+
+---
+
+See also: [FAQ](guides/FAQ.html) · [System Concept](SystemConcept.html) · [System Configuration](SystemConfiguration.html) · [Connector Interfaces](ConnectorInterfaces.html)
diff --git a/docs/guides/BrowserUsage.md b/docs/guides/BrowserUsage.md
@@ -1,6 +1,6 @@
 # Browser Usage Guide
 
-ModelMesh TypeScript works in browsers, calling AI provider APIs directly from client-side JavaScript. This guide covers setup, CORS handling, and security.
+ModelMesh TypeScript works in browsers, calling AI provider APIs directly from client-side JavaScript. This guide covers setup, CORS handling, and security. For the full list of browser-compatible connectors (storage, secret stores, providers), see the [Connector Catalogue](../ConnectorCatalogue.html). For the CORS proxy deployment, see the [Proxy Guide](ProxyGuide.html).
 
 ## Architecture
 
diff --git a/docs/guides/Capabilities.md b/docs/guides/Capabilities.md
@@ -1,6 +1,6 @@
 # Capability Discovery
 
-ModelMesh uses a hierarchical capability system to route requests. Instead of memorizing full dotted paths like `generation.text-generation.chat-completion`, you can use short aliases and the discovery API.
+ModelMesh uses a hierarchical capability system to route requests. Instead of memorizing full dotted paths like `generation.text-generation.chat-completion`, you can use short aliases and the discovery API. For the complete hierarchy tree, see [Model Capabilities](../ModelCapabilities.html). For how capabilities map to [pools and routing](../SystemConcept.html), see the architecture overview.
 
 ## Capability Aliases
 
diff --git a/docs/guides/ErrorHandling.md b/docs/guides/ErrorHandling.md
@@ -1,6 +1,6 @@
 # Error Handling
 
-ModelMesh provides a structured exception hierarchy so you can catch failures at the right level of specificity.
+ModelMesh provides a structured exception hierarchy so you can catch failures at the right level of specificity. The [router](../SystemConcept.html) raises these exceptions during the request pipeline; [middleware](Middleware.html) can intercept them via `on_error` hooks.
 
 ## Exception Tree
 
@@ -108,7 +108,7 @@ Every ModelMesh exception carries structured metadata:
 | Exception | Extra Fields | When Raised |
 |-----------|-------------|-------------|
 | `ConfigurationError` | — | Invalid config, missing fields |
-| `BudgetExceededError` | `limit_type`, `limit_value`, `actual_value` | Cost limit breached |
+| `BudgetExceededError` | `limit_type`, `limit_value`, `actual_value` | Cost limit breached (see [budget controls](FAQ.html#6-how-do-i-prevent-surprise-ai-bills)) |
 
 ## Retry Guidance
 
diff --git a/docs/guides/FAQ.md b/docs/guides/FAQ.md
@@ -1,6 +1,6 @@
 # Frequently Asked Questions
 
-Ten questions developers ask before adopting ModelMesh, each answered with a short explanation and working code.
+Ten questions developers ask before adopting ModelMesh, each answered with a short explanation and working code. For architecture details, see [System Concept](../SystemConcept.html). For the YAML reference, see [System Configuration](../SystemConfiguration.html).
 
 ---
 
@@ -25,7 +25,7 @@ response = client.chat.completions.create(
 print(response.choices[0].message.content)
 ```
 
-**How does this work?** Setting `OPENAI_API_KEY` triggers auto-discovery: ModelMesh finds the OpenAI provider, registers its models, and groups them into **capability pools** by what each model can do. `create("chat-completion")` returns a client wired to the pool containing all chat-capable models. The shortcut `"chat-completion"` resolves to the full dot-notation path `generation.text-generation.chat-completion` automatically (see [Q5](#5-what-does-request-capabilities-not-model-names-mean)).
+**How does this work?** Setting `OPENAI_API_KEY` triggers auto-discovery: ModelMesh finds the OpenAI provider, registers its models, and groups them into **[capability pools](../SystemConcept.html#capability-based-model-pools)** by what each model can do. `create("chat-completion")` returns a client wired to the pool containing all chat-capable models. The shortcut `"chat-completion"` resolves to the full dot-notation path `generation.text-generation.chat-completion` automatically (see [Q5](#5-what-does-request-capabilities-not-model-names-mean)).
 
 When you need more control, add a YAML file or pass options programmatically. All three layers compose: env vars for secrets, YAML for topology, code for runtime overrides.
 
@@ -111,15 +111,15 @@ for i in range(100):
 
 Your code makes the same call every time. The library handles detection, pooling, and rotation internally.
 
-**How are pools formed?** Each provider registers its models with capability tags (e.g. `generation.text-generation.chat-completion`). ModelMesh groups all models sharing a capability into a single pool. When you call `create("chat-completion")`, you get a client backed by every chat-capable model across all discovered providers. Adding a new API key adds that provider's models to the existing pools automatically.
+**How are pools formed?** Each provider registers its models with [capability tags](../ModelCapabilities.html) (e.g. `generation.text-generation.chat-completion`). ModelMesh groups all models sharing a capability into a single pool. When you call `create("chat-completion")`, you get a client backed by every chat-capable model across all discovered providers. Adding a new API key adds that provider's models to the existing pools automatically.
 
 See the [Free-Tier Aggregation](QuickStart.html) guide.
 
 ---
 
 ## 4. What happens when a provider goes down?
 
-ModelMesh retries with backoff, then rotates to the next model in the pool. All within the same request. Your code never sees the failure.
+ModelMesh retries with backoff, then [rotates](../SystemConcept.html) to the next model in the pool. All within the same request. Your code never sees the failure (see [Error Handling](ErrorHandling.html) for the full exception hierarchy).
 
 ```python
 import modelmesh
@@ -209,7 +209,7 @@ matches = modelmesh.capabilities.search("text")
 client = modelmesh.create("chat-completion")
 ```
 
-**Shortcuts vs dot-notation:** Every capability has a full dot-notation path reflecting its position in the hierarchy tree (e.g. `generation.text-generation.chat-completion`). Shortcuts like `"chat-completion"` are leaf-node aliases that resolve automatically. Both forms work everywhere: `create("chat-completion")` and `create("generation.text-generation.chat-completion")` are equivalent. Providers tag their models with full paths; you use whichever form is convenient.
+**Shortcuts vs dot-notation:** Every capability has a full dot-notation path reflecting its position in the [hierarchy tree](../ModelCapabilities.html) (e.g. `generation.text-generation.chat-completion`). Shortcuts like `"chat-completion"` are leaf-node aliases that resolve automatically. Both forms work everywhere: `create("chat-completion")` and `create("generation.text-generation.chat-completion")` are equivalent. Providers tag their models with full paths; you use whichever form is convenient.
 
 When a new model launches or an old one is deprecated, update your config. Your application code stays the same.
 
@@ -219,7 +219,7 @@ See the [Capability Discovery](Capabilities.html) guide.
 
 ## 6. How do I prevent surprise AI bills?
 
-Set daily or monthly spending limits in your configuration. ModelMesh tracks cost per request in real time and raises `BudgetExceededError` before the breaching request is sent.
+Set daily or monthly spending limits in your [configuration](../SystemConfiguration.html#providers). ModelMesh tracks cost per request in real time and raises [`BudgetExceededError`](ErrorHandling.html) before the breaching request is sent.
 
 ```yaml
 providers:
@@ -271,7 +271,7 @@ See the [Budget Enforcement](QuickStart.html#usage-tracking) guide and [System C
 
 ## 7. Can I use ModelMesh with my existing stack?
 
-Yes. ModelMesh ships as a Python library, a TypeScript library, and a Docker image. Each exposes the same OpenAI-compatible API. Pick the one that fits your stack.
+Yes. ModelMesh ships as a Python library, a TypeScript library, and a [Docker proxy](ProxyGuide.html). Each exposes the same OpenAI-compatible API. Pick the one that fits your stack.
 
 **Python backend:**
 ```bash
@@ -297,9 +297,9 @@ curl http://localhost:8080/v1/chat/completions \
   -d '{"model":"chat-completion","messages":[{"role":"user","content":"Hello"}]}'
 ```
 
-All three share the same YAML configuration format. Zero core dependencies in the Python and TypeScript libraries.
+All three share the same [YAML configuration format](../SystemConfiguration.html). Zero core dependencies in the Python and TypeScript libraries. For browser usage with TypeScript, see the [Browser Guide](BrowserUsage.html).
 
-See the [Full-Stack Deployment](QuickStart.html) guide.
+See the [Full-Stack Deployment](QuickStart.html) guide and [Proxy Guide](ProxyGuide.html).
 
 ---
 
@@ -952,3 +952,24 @@ pools:
 ```
 
 See the [Connector Catalogue](../ConnectorCatalogue.html) for all pre-shipped connectors and [Connector Interfaces](../ConnectorInterfaces.html) for interface specifications.
+
+---
+
+## Reference
+
+| Document | What it covers |
+|----------|---------------|
+| [System Concept](../SystemConcept.html) | Architecture overview — routing pipeline, pools, providers |
+| [Model Capabilities](../ModelCapabilities.html) | Complete capability hierarchy tree |
+| [System Configuration](../SystemConfiguration.html) | YAML schema reference for all sections |
+| [System Services](../SystemServices.html) | Runtime objects — Router, Pool, Model, StateManager |
+| [Connector Catalogue](../ConnectorCatalogue.html) | All 54 pre-shipped connectors with config schemas |
+| [Connector Interfaces](../ConnectorInterfaces.html) | Interface specs for all 6 connector types |
+| [Quick Start](QuickStart.html) | 5-minute hands-on tutorial |
+| [Error Handling](ErrorHandling.html) | Exception hierarchy and retry guidance |
+| [Middleware](Middleware.html) | Request/response interception patterns |
+| [Testing](Testing.html) | Mock client for unit tests |
+| [Capabilities](Capabilities.html) | Capability discovery API |
+| [Secret Stores](SecretStores.html) | Secret store configuration and usage |
+| [Browser Usage](BrowserUsage.html) | Browser-specific setup and CORS |
+| [Proxy Guide](ProxyGuide.html) | Docker proxy deployment |
diff --git a/docs/guides/Middleware.md b/docs/guides/Middleware.md
diff --git a/docs/guides/ProxyGuide.md b/docs/guides/ProxyGuide.md
diff --git a/docs/guides/QuickStart.md b/docs/guides/QuickStart.md
diff --git a/docs/guides/SecretStores.md b/docs/guides/SecretStores.md
diff --git a/docs/guides/Testing.md b/docs/guides/Testing.md
