mozart-router 0.1.0

package/docs/FEATURE_MATRIX.md

@@ -0,0 +1,113 @@
+# Feature Matrix — Mozart Ultimate Core
+
+## Detection & Inventory
+
+| Feature | Status | Implementation | Notes |
+|---------|--------|---------------|-------|
+| Gateway/tool detection | implemented | 11 adapters: Ollama, LiteLLM, OpenRouter, OpenCode, OpenClaw, Hermes, Cursor, LM Studio, vLLM, NVIDIA NIM + Generic auto-discovery | Auto-discovers 11 common endpoints |
+| Provider inventory | implemented | `InventoryRegistry` — merge, dedup, source tracking | Reads from gateways, never stores raw keys |
+| Model inventory | implemented | `InventoryRegistry` — per-provider, per-gateway | Includes pricing, context window, capabilities |
+| Generic OpenAI auto-discovery | implemented | `GenericOpenAIAdapter` + `discoverAllGenericAdapters()` | Plug-and-play for any OpenAI-compatible endpoint |
+| DealsForge sync | implemented | `syncDealsForgeData()` — curated model catalog | Static data; future: live API |
+| CanRunIt local scan | implemented | `scanLocalCapability()` — CPU, RAM, OS | GPU detection needs native module |
+
+## Classification & Routing
+
+| Feature | Status | Implementation | Notes |
+|---------|--------|---------------|-------|
+| Task classifier | implemented | `TaskClassifier` — 19 patterns, priority scoring, heuristic | Local, no LLM needed |
+| Routing engine | implemented | `RoutingEngine` — 7-dimension scoring (quality, cost, latency, privacy, context, reliability, quota) | Produces fallback chain |
+| Multi-stage routing | implemented | `MultiStageRouter` — classify→generate→review pipelines | 4-stage for debugging, 3-stage for code gen |
+| Fallback manager | implemented | `FallbackManager` — retry, exponential backoff, event tracking | Max retries configurable |
+| Cost/token estimator | implemented | `CostEstimator` — per-model pricing, token estimation, savings vs premium | Declares uncertainty when price unknown |
+| Explainability engine | implemented | `ExplainabilityEngine` — full text explanation per route | Why selected, why others not, privacy reasoning |
+
+## Policy & Privacy
+
+| Feature | Status | Implementation | Notes |
+|---------|--------|---------------|-------|
+| Policy engine | implemented | `PolicyEngine` — privacy, budget, routing rules | 10 built-in profiles |
+| Privacy guard | implemented | `PrivacyGuard` — API keys, tokens, private keys, passwords, .env | 5 actions: allow, redact, block_cloud, local_only, require_confirmation |
+| Built-in profiles | implemented | 10 profiles: coding-agent, cheap-loops, privacy-first, long-context, startup-budget, max-quality, local-first, research-agent, reviewer-agent, multi-agent | Extensible via `mozart.config.yaml` |
+| YAML config loading | implemented | `loadMozartConfig()` — parses mozart.config.yaml | Optional; Mozart works without it |
+
+## Execution Modes
+
+| Feature | Status | Implementation | Notes |
+|---------|--------|---------------|-------|
+| Recommend-only mode | implemented | All routing methods return decision without executing | Default mode |
+| Delegated execution | implemented | `Mozart.delegate()` — routes to gateway adapter | Only executes if adapter supports it |
+| OpenAI-compatible middleware | implemented | `MozartMiddleware` — `/v1/chat/completions` with auto-routing | Transparent proxy mode |
+| HTTP API | implemented | `MozartApiServer` — 8 endpoints (health, inventory, route, simulate, explain, report, compress, policy) | Local-only by default |
+
+## Context & Cache
+
+| Feature | Status | Implementation | Notes |
+|---------|--------|---------------|-------|
+| Context optimizer | implemented | `ContextOptimizer` — 4 strategies (send_all, compress, truncate, select_relevant) | Token estimation, budget-aware |
+| Result cache | implemented | `ResultCache` — TTL, LRU eviction, hit tracking | In-memory, configurable size |
+
+## Logging & Persistence
+
+| Feature | Status | Implementation | Notes |
+|---------|--------|---------------|-------|
+| Local logs | implemented | `Logger` — leveled, event-based, session references | In-memory |
+| Secret redaction | implemented | `Redactor` — strips API keys, tokens, passwords | 10+ patterns covered |
+| Disk persistence | implemented | `saveInventory`, `loadInventory`, `saveSession`, `loadSession`, `saveConfig`, `clearAllData` | JSON files in `~/.mozart/` |
+
+## Adapters — Real
+
+| Adapter | Status | Detection method |
+|---------|--------|-----------------|
+| Ollama | implemented | CLI: `ollama --version`, `ollama list` |
+| OpenClaw | implemented | File: reads `~/.openclaw/openclaw.json` |
+| OpenCode | implemented | Env vars + file: checks `OPENCODE_CLIENT`, data dir |
+| LiteLLM | implemented | File: scans 6 paths for `litellm_config.yaml` |
+| OpenRouter | implemented | Env: checks `OPENROUTER_API_KEY` |
+| LM Studio | implemented | HTTP: queries `localhost:1234/v1/models` |
+| vLLM | implemented | HTTP: queries `localhost:8000/v1/models` |
+| NVIDIA NIM | implemented | Env + HTTP: checks `NVIDIA_API_KEY`, local endpoint |
+| Generic OpenAI | implemented | HTTP: queries any `/v1/models` endpoint. Auto-discovers 11 endpoints |
+
+## Adapters — Stubs
+
+| Adapter | Status | Notes |
+|---------|--------|-------|
+| Hermes Agent | adapter stub | Full interface + manifest at `examples/hermes/mozart-tool.json` |
+| Cursor | adapter stub | Full interface, documented integration path |
+
+## Skills & Tools
+
+| Feature | Status | Implementation |
+|---------|--------|---------------|
+| mozart.route_model | implemented | `SkillDefinition` with full I/O schema |
+| mozart.explain_route | implemented | `SkillDefinition` |
+| mozart.estimate_cost | implemented | `SkillDefinition` |
+| mozart.compress_context | implemented | `SkillDefinition` |
+| mozart.privacy_check | implemented | `SkillDefinition` |
+| mozart.fallback_plan | implemented | `SkillDefinition` |
+| mozart.inventory | implemented | `SkillDefinition` |
+| OpenCode skill manifest | implemented | `examples/opencode/mozart-skill.json` |
+| OpenClaw skill manifest | implemented | `examples/openclaw/mozart-skill.yaml` |
+| Hermes tool manifest | implemented | `examples/hermes/mozart-tool.json` |
+| Generic tool manifests | implemented | `examples/generic-tools/` |
+
+## Developer Experience
+
+| Feature | Status | Implementation |
+|---------|--------|---------------|
+| CLI | implemented | 13 commands |
+| SDK | implemented | Full TypeScript exports |
+| Tests | implemented | 102 tests, 15 files, Vitest |
+| Docs | implemented | 12 docs files |
+| Examples | implemented | 7 example directories |
+| CI/Lint | implemented | `tsc --noEmit` |
+
+---
+
+**Status key:**
+- **implemented** — Fully coded, tested, functional
+- **partially implemented** — Core logic exists, some edges incomplete
+- **adapter stub** — Full interface exists, requires target environment
+- **documented** — Design docs exist, not yet coded
+- **planned** — On roadmap, not yet started

package/docs/GATEWAY_FIRST_PRINCIPLES.md

@@ -0,0 +1,66 @@
+# Gateway-First Principles
+
+## Core rule
+
+```
+Do not rebuild what the gateway already does.
+Detect it, understand it, orchestrate it.
+```
+
+## What gateways already do
+
+Gateways like LiteLLM, OpenRouter, and agent tools like OpenCode already manage:
+
+- API key storage and management
+- Provider authentication
+- Model inventory
+- Low-level HTTP calls to LLM APIs
+- Rate limiting and quota management
+- Billing (in some cases)
+- Fallback/retry (in some cases)
+
+## What Mozart adds
+
+Mozart adds intelligence on top of gateways without duplicating:
+
+| Capability   | In Gateway | Mozart adds                       |
+|-------------|-----------|----------------------------------|
+| API keys    | Yes       | Reference management only         |
+| Auth        | Yes       | Delegates to gateway              |
+| Providers   | Yes       | Enriched inventory from all gateways |
+| Models      | Yes       | Scored and ranked per task        |
+| Execution   | Yes       | Routes to best gateway            |
+| Routing     | Partial   | Full intelligent routing           |
+| Privacy     | No        | Content scanning + policy         |
+| Cost        | Basic     | Estimation + optimization         |
+| Context     | No        | Token optimization + compression  |
+| Explanation | No        | Full explainability               |
+| Policy      | No        | Configurable policies             |
+| Logging     | Partial   | Local logs with secret redaction   |
+
+## Anti-patterns to avoid
+
+### DON'T: Create a new proxy that replaces gateways
+Mozart should delegate to existing gateways, not become a new proxy.
+
+### DON'T: Ask users to copy all their API keys
+If a gateway manages keys, Mozart only references that relationship.
+
+### DON'T: Rebuild provider/model management
+Mozart reads from gateways and enriches with intelligence.
+
+### DON'T: Build a desktop application
+Mozart is primarily an importable SDK and CLI tool.
+
+### DON'T: Force cloud dependency
+All core processing is local-first.
+
+## Gateway introspection pattern
+
+Every adapter follows this pattern:
+
+1. **Detect** — Find configuration files, environment variables, or running services
+2. **Read** — Parse existing config without duplicating it
+3. **List** — Enumerate available providers and models
+4. **Reference** — Store abstract references, never raw secrets
+5. **Delegate** — Route execution back to the gateway

package/docs/INTEGRATIONS.md

@@ -0,0 +1,94 @@
+# Integrations
+
+Mozart integrates with multiple AI gateways, agents, and tools. Each integration follows the gateway-first principle: Mozart adds intelligence without duplicating functionality.
+
+## Integration modes
+
+### 1. Adapter mode (for gateways)
+Mozart ships with adapters that detect and read from existing gateway configurations.
+
+### 2. Skill mode (for agent tools)
+Mozart exposes skills (route_model, estimate_cost, privacy_check, etc.) that agents can call.
+
+### 3. Tool mode (for agent frameworks)
+Mozart can be called as a tool within OpenClaw, Hermes, or custom agents.
+
+### 4. Middleware mode (for pipelines)
+Mozart can sit between an agent and its gateway, injecting routing decisions.
+
+### 5. Recommend-only mode (universal)
+Mozart can function in pure advisory mode, generating recommendations without execution.
+
+## Supported integrations
+
+### OpenCode
+**Status:** Real detection + skill manifest available
+
+Mozart detects:
+- OpenCode installation via environment variables (OPENCODE_CLIENT, OPENCODE_SERVER_USERNAME)
+- OpenCode data directory
+
+Mozart provides:
+- `examples/opencode/mozart-skill.json` — skill manifest
+- Routing recommendations for coding tasks via the SDK
+
+### OpenClaw
+**Status:** Real detection — reads openclaw.json config
+
+Mozart detects:
+- OpenClaw config at `~/.openclaw/openclaw.json`
+- All configured providers and models
+- Gateway mode and port
+
+Mozart provides:
+- `examples/openclaw/mozart-skill.yaml` — skill definition
+- Skills: route_model, estimate_cost, compress_context
+- Multi-agent workflow support
+
+### Hermes Agent
+**Status:** Adapter stub + manifest available
+
+Mozart provides:
+- `examples/hermes/mozart-tool.json` — tool definition
+- Provider decision layer
+- Policy enforcement for agentic workflows
+
+### LiteLLM
+**Status:** Real adapter with config detection
+
+Mozart detects:
+- `litellm_config.yaml` / `litellm_config.yml` in common locations
+- Parses model entries from config
+- Delegates execution to LiteLLM proxy
+
+### OpenRouter
+**Status:** Real adapter with env detection
+
+Mozart detects:
+- `OPENROUTER_API_KEY`, `OR_API_KEY`, `OPENROUTER_KEY` in environment
+- Provides curated model inventory with pricing data
+- Routes via OpenRouter for cloud models
+
+### Ollama
+**Status:** Real adapter with CLI detection
+
+Mozart detects:
+- Ollama installation via `ollama --version`
+- Local models via `ollama list`
+- Provides execution target for local inference
+
+### Cursor
+**Status:** Adapter stub + documentation
+
+Mozart can be used as:
+- Advisory layer via CLI/SDK
+- Local endpoint for model selection
+- Context optimization for IDE usage
+
+## Adding a new integration
+
+1. Create a new adapter in `src/adapters/` implementing the `GatewayAdapter` interface
+2. Register in `src/adapters/index.ts`
+3. Add a manifest in `examples/<name>/`
+4. Add documentation in `docs/INTEGRATIONS.md`
+5. Write tests in `tests/<name>.test.ts`

package/docs/LIMITATIONS.md

@@ -0,0 +1,43 @@
+# Limitations — Mozart v0.1.0
+
+Mozart is honest about what it can and cannot do. This document lists all known limitations.
+
+## Core limitations
+
+| Area | Limitation | Why |
+|------|-----------|-----|
+| Context compression | Token estimation is approximate (4 chars ≈ 1 token) | Accurate tokenization requires model-specific tokenizers |
+| Cost estimation | Estimates assume known pricing; returns "unknown" when pricing data is missing | Provider APIs don't always expose real-time pricing |
+| Model capabilities | Defaults to 'unknown' for tools, JSON, vision unless known | Cannot test capabilities without executing against each model |
+| Multi-stage routing | Works but requires manual pipeline definition per task type | Fully dynamic pipeline routing needs LLM-level planning |
+
+## Adapter limitations
+
+| Adapter | Limitation |
+|---------|-----------|
+| OpenCode | Detects installation but cannot read internal provider config (managed by OpenCode's proprietary format) |
+| Hermes Agent | Stub — full interface exists but requires Hermes runtime for real detection |
+| Cursor | Stub — integration depends on Cursor extension API which is not publicly documented |
+| Ollama | If Ollama is not running, cannot detect models. Requires `ollama list` to work. |
+| LiteLLM | Parses `litellm_config.yaml` structure but does not support all LiteLLM config variants |
+| OpenRouter | Uses static curated model list; real-time model inventory would require API call |
+| LM Studio / vLLM / NIM | Requires running server on expected port; cannot auto-discover non-standard ports |
+
+## System limitations
+
+| Area | Limitation |
+|------|-----------|
+| GPU/VRAM detection | Requires native Node.js addon; currently reports "not detected" |
+| Session persistence | CLI invocations are stateless; each run creates a new session |
+| npm publication | Not yet published to npm registry — requires `npm publish` |
+| Windows paths | Some filesystem detection uses Unix-style paths; tested on Windows |
+
+## Design decisions (not bugs)
+
+| Decision | Rationale |
+|----------|-----------|
+| No API key storage | Gateways (LiteLLM, OpenRouter, etc.) already manage keys. Mozart doesn't duplicate. |
+| No desktop application | Mozart is an SDK/CLI/skill, not a standalone app. |
+| No mandatory cloud dependency | All core processing (classification, routing, privacy scanning) is local. |
+| No official integration claims | Integrations with OpenCode, OpenClaw, Hermes, Cursor are community efforts unless otherwise stated. |
+| Default recommend-only | Mozart decides; gateways execute. Execution is opt-in. |

package/docs/RECOMMEND_ONLY_MODE.md

@@ -0,0 +1,82 @@
+# Recommend-Only Mode — Mozart
+
+Mozart's default mode is **recommend-only** — it decides, it does not execute.
+
+## Principle
+
+```
+Gateways execute. Mozart decides.
+```
+
+Mozart's purpose is to provide intelligent routing decisions. The actual execution is delegated to the gateway that the user already has configured. Mozart does not need to execute directly to be useful.
+
+## How it works
+
+When you call:
+
+```typescript
+const route = await mozart.recommend('debug the authentication error');
+```
+
+Mozart:
+1. Classifies the task (type, complexity, context needs)
+2. Scans for sensitive data (privacy guard)
+3. Evaluates policies (budget, routing rules)
+4. Scores all available models across 7 dimensions
+5. Returns a `RouteDecision` with:
+   - Selected gateway, provider, model
+   - Confidence score
+   - Estimated cost and tokens
+   - Full explanation
+   - Fallback chain
+
+**No execution happens.** Your existing gateway handles the actual API call.
+
+## Why recommend-only?
+
+1. **No key duplication.** Your gateways (LiteLLM, OpenRouter, Ollama) already manage API keys. Mozart doesn't need them.
+2. **No new proxy.** Mozart adds intelligence without adding infrastructure.
+3. **Universal compatibility.** Even agents that can't route through Mozart can still use its recommendations.
+4. **Safe by default.** Until you explicitly configure execution, Mozart is read-only advisory.
+
+## Enabling execution
+
+If you want Mozart to execute:
+
+```typescript
+const response = await mozart.process({
+  input: 'write a function',
+  executionMode: 'execute', // or 'delegate'
+});
+```
+
+Mozart will then attempt to execute via the selected gateway adapter. If the adapter doesn't support execution, it falls back to recommend-only.
+
+## CLI
+
+All CLI commands are recommend-only by default:
+
+```bash
+npm run mozart -- simulate "debug my build"  # Simulates, doesn't execute
+npm run mozart -- route "write tests"          # Routes, doesn't execute
+```
+
+## API
+
+The HTTP API also defaults to recommend-only:
+
+```json
+POST /v1/route
+{
+  "task": "refactor auth module",
+  "execution_mode": "recommend"
+}
+```
+
+## Design intent
+
+Recommend-only mode is not a limitation — it's the core design decision that makes Mozart:
+- Lightweight (no provider logic)
+- Secure (no key management)
+- Compatible (works with any gateway)
+- Honest (never claims it executes when it recommends)

package/docs/ROADMAP.md

@@ -0,0 +1,70 @@
+# Roadmap
+
+## Phase Alpha — Core (v0.1.0) ✅
+
+All core features implemented, tested, and documented.
+- [x] Core types and interfaces (28+)
+- [x] CLI (14 commands)
+- [x] SDK importable (full exports)
+- [x] Provider/Model registry with merge, dedup, persistence
+- [x] Ollama detection (real — CLI + HTTP)
+- [x] LiteLLM config detection (real — YAML parsing)
+- [x] OpenRouter env detection (real)
+- [x] OpenCode detection (real — config + models cache reading)
+- [x] OpenClaw detection (real — full openclaw.json parsing)
+- [x] Hermes Agent detection (real — config file scanning)
+- [x] LM Studio detection (real — HTTP)
+- [x] vLLM detection (real — HTTP)
+- [x] NVIDIA NIM detection (real — env + HTTP)
+- [x] Generic OpenAI auto-discovery (11 endpoints)
+- [x] Task classifier (19 patterns, priority scoring)
+- [x] Policy engine (10 built-in profiles)
+- [x] Privacy guard (6 detection types, 5 actions)
+- [x] Context optimizer (4 strategies)
+- [x] Cost/token estimator
+- [x] Explainability engine
+- [x] Routing engine (7-dimension scoring)
+- [x] Fallback manager (retry, backoff, circuit breaker)
+- [x] Multi-stage routing (classify → generate → review)
+- [x] Local logs with secret redaction (10+ patterns)
+- [x] Recommend-only mode
+- [x] Delegated execution model
+- [x] Skill manifests (7 skills)
+- [x] Tool manifests (OpenCode, OpenClaw, Hermes, generic)
+- [x] Cursor endpoint documentation
+- [x] Config YAML loading (mozart.config.yaml)
+- [x] Disk persistence (inventory, session, config)
+- [x] Result cache (TTL, LRU eviction)
+- [x] HTTP API server (8 endpoints + dashboard)
+- [x] OpenAI-compatible middleware proxy (streaming SSE support)
+- [x] MCP server (6 tools, stdio)
+- [x] Plugin system (auto-discovery of mozart-router-adapter-*)
+- [x] Metrics export (JSON + Prometheus)
+- [x] Health check background (circuit breaker)
+- [x] Docker support (Dockerfile + docker-compose)
+- [x] CI/CD (GitHub Actions)
+- [x] Tests (118 tests, 19 files)
+- [x] Full documentation (12 docs)
+- [x] Integration examples (7 directories with READMEs)
+- [x] OpenCode SKILL.md integration
+
+## Phase Beta — Polish (v0.2.0)
+
+- [ ] npm publication (`npm publish`)
+- [ ] DealsForge live sync (when API available)
+- [ ] CanRunIt GPU detection (native addon)
+- [ ] Advanced context optimizer (local LLM summarization)
+- [ ] Dynamic pricing updates (live pricing API)
+- [ ] Source confidence scoring improvements
+- [ ] Agent workflow profiles refinement
+- [ ] Provider reliability learning (ML-based trust scoring)
+- [ ] Community adapters ecosystem
+
+## Phase 1.0 — Stable
+
+- [ ] npm package published and stable
+- [ ] Demo video
+- [ ] Community contributions
+- [ ] Production usage reports
+- [ ] Performance benchmarks
+- [ ] Windows/Mac/Linux CI verified

package/docs/SECURITY.md

@@ -0,0 +1,74 @@
+# Security
+
+## Design principles
+
+1. **Local-first** — All core processing happens locally. No cloud dependency.
+2. **No cloud by default for sensitive data** — Privacy Guard prevents secrets from reaching cloud models.
+3. **Secrets never logged** — Redactor strips API keys, tokens, and credentials from logs.
+4. **Policies explicit** — Users configure privacy and budget policies explicitly.
+5. **No mandatory telemetry** — Mozart sends no data anywhere without explicit user action.
+6. **User owns their keys** — Mozart never stores or manages API keys that gateways already manage.
+
+## Privacy Guard
+
+The Privacy Guard scans all content before routing to detect:
+
+- API keys (sk-*, etc.)
+- OAuth/access tokens
+- GitHub tokens (ghp_*, gho_*, etc.)
+- Private keys (RSA/EC/DSA/SSH)
+- Credentials and secrets
+- Environment variable files (.env-like patterns)
+
+### Actions
+
+| Action | Behavior |
+|--------|----------|
+| `allow` | Content is safe, can be sent anywhere |
+| `redact` | Secrets are masked before sending |
+| `block_cloud` | Content must not be sent to cloud models |
+| `local_only` | Content must only be processed locally |
+| `require_confirmation` | User must approve before sending |
+
+### Privacy modes
+
+| Mode | Description |
+|------|-------------|
+| `open` | Minimal restrictions |
+| `balanced` | Standard protection (default) |
+| `privacy_first` | Aggressive protection |
+| `local_only` | All processing must be local |
+
+## Log redaction
+
+All logs pass through the `Redactor` before being written. It strips:
+
+- API key patterns (sk-, AIza, etc.)
+- GitHub tokens (ghp_, gho_, ghu_, ghs_)
+- Slack tokens (xoxb-, xoxp-, etc.)
+- HuggingFace tokens (hf_)
+- Common secret environment variables (API_KEY, SECRET, TOKEN, etc.)
+
+## Key management policy
+
+Mozart follows a strict key management hierarchy:
+
+1. **Gateway-managed keys** — Reference only (`managed_by_litellm`, `managed_by_opencode`)
+2. **Environment variables** — Reference the variable name, never the value
+3. **Manual keys** — Only for providers not covered by any gateway
+4. **No raw key storage** — Keys are never written to disk by Mozart
+
+## Budget protection
+
+- Daily spending limits configurable via policy
+- Warning threshold at configurable percentage
+- Premium models only allowed for critical tasks (configurable)
+- Cost estimation before execution
+
+## Best practices
+
+1. Always run `mozart doctor` to understand your detected stack
+2. Set budget limits appropriate for your use case
+3. Use `privacy_first` mode when handling customer data
+4. Review `mozart why` explanations for routing decisions
+5. Run `mozart simulate` before executing expensive tasks

package/docs/SKILLS_AND_TOOLS.md

@@ -0,0 +1,141 @@
+# Skills and Tools — Mozart
+
+Mozart exposes 7 skills callable by agents. Each skill has a typed definition (input/output schema) and integration manifests for OpenClaw, OpenCode, and Hermes Agent.
+
+## Skill definitions
+
+Located in `src/skills/definitions.ts`. Each skill implements the `SkillDefinition` interface:
+
+```typescript
+interface SkillDefinition {
+  name: string;
+  description: string;
+  input: Record<string, SkillInputField>;
+  output: Record<string, SkillOutputField>;
+}
+```
+
+## Available skills
+
+### mozart.route_model
+
+Choose the best available model/provider/gateway for an AI task.
+
+**Input:**
+| Field | Type | Required |
+|-------|------|----------|
+| task | string | yes |
+| context_size | number | no |
+| privacy_mode | open \| balanced \| privacy_first \| local_only | no |
+| budget_mode | lowest \| balanced \| quality | no |
+
+**Output:** selected_gateway, selected_provider, selected_model, confidence, context_strategy, estimated_cost, fallback_chain, explanation
+
+### mozart.explain_route
+
+Explain why Mozart chose a specific model/provider for the last task.
+
+**Output:** explanation (string)
+
+### mozart.estimate_cost
+
+Estimate token usage and cost for a task before execution.
+
+**Input:** task, context (string), model (string, optional)
+
+**Output:** estimated_input_tokens, estimated_output_tokens, estimated_cost, currency
+
+### mozart.compress_context
+
+Optimize and compress context to reduce token usage.
+
+**Input:** content (string), max_tokens (number), strategy (string)
+
+**Output:** strategy, original_tokens, compressed_tokens, compression_ratio
+
+### mozart.privacy_check
+
+Scan content for secrets, API keys, tokens before sending to models.
+
+**Input:** content (string), privacy_mode (string, optional)
+
+**Output:** allowed, findings (array), action, redacted_content
+
+### mozart.fallback_plan
+
+Generate a fallback execution plan.
+
+**Input:** task (string), primary_model (string, optional)
+
+**Output:** primary (object), fallbacks (array), retry_policy
+
+### mozart.inventory
+
+Return the current inventory of detected gateways, providers, and models.
+
+**Output:** gateways (array), providers (array), models (array), generated_at
+
+## Integration manifests
+
+### OpenCode
+
+Manifest: `examples/opencode/mozart-skill.json`
+
+```json
+{
+  "name": "mozart.route_model",
+  "type": "skill",
+  "integration": { "package": "mozart-router", "method": "sdk" }
+}
+```
+
+### OpenClaw
+
+Manifest: `examples/openclaw/mozart-skill.yaml`
+
+```yaml
+skills:
+  - name: mozart.route_model
+    input: { task: { type: string, required: true } }
+```
+
+### Hermes Agent
+
+Manifest: `examples/hermes/mozart-tool.json`
+
+```json
+{
+  "name": "mozart.route_model",
+  "type": "tool",
+  "source": { "package": "mozart-router", "method": "sdk" }
+}
+```
+
+### Generic tools
+
+Manifest: `examples/generic-tools/mozart-tools.json`
+
+A collection of all 7 skills in a generic JSON format suitable for any agent framework.
+
+## Using skills from code
+
+```typescript
+import { Mozart, ALL_SKILLS } from 'mozart-router';
+
+// Inspect skill definitions
+for (const skill of ALL_SKILLS) {
+  console.log(skill.name, Object.keys(skill.input));
+}
+
+// Use Mozart SDK directly
+const mozart = new Mozart();
+const route = await mozart.recommend('analyze this code for bugs');
+```
+
+## Adding a new skill
+
+1. Add definition to `src/skills/definitions.ts`
+2. Add to the `ALL_SKILLS` array
+3. Implement the corresponding method in `Mozart` core
+4. Add CLI command if needed
+5. Update manifests in `examples/`