model-orchestrator 0.1.35 → 1.0.1

package/docs/README.md

@@ -1,20 +1,17 @@
-# docs/
+# Documentation
 
-Reference, then reading. The reference pages carry the detail the README links out to; the three parts explain the thinking behind each level and how to grow from one to the next.
+Use these pages for setup, operation and evidence. The [front page](../README.md) gives the short introduction.
 
-| Reference | What is in it | File |
-|---|---|---|
-| Installing | every flag, the two folders a run writes to, headless examples, the full file list | [install.md](install.md) |
-| How it routes | role, complexity and stakes; the three verifier agents; pinning model and effort | [how-it-routes.md](how-it-routes.md) |
-| Guarantees | what is enforced by code, delegated to a vendor flag, or only an instruction | [guarantees.md](guarantees.md) |
-| Companion tools | codecalc, obsidian-tc and Context7: what each closes and what it needs first | [companions.md](companions.md) |
-
-| Part | Read if | File |
-|---|---|---|
-| 1 Beginner | you use one LLM or one agent and want it to route well | [part-1-beginner.md](part-1-beginner.md) |
-| 2 Intermediate | you have several AIs and want to call them through their CLIs from one orchestrator | [part-2-intermediate.md](part-2-intermediate.md) |
-| 3 Advanced | you want the whole thing running unattended on a virtual machine | [part-3-advanced.md](part-3-advanced.md) |
-| Audit brief | the security notes and the two second-opinion audit rounds this shipped with | [audit-brief.md](audit-brief.md) |
-| Catalog | what each AI and companion tool in the installer is for, how it installs, how it signs in | [catalog.md](catalog.md) |
-
-Each part ends with "what the installer gives you at this level" so the doc and the files agree.
+| Page | What it gives you |
+|---|---|
+| [Install and upgrade](install.md) | One-confirm setup, edit menu, flags, project commands, safe updates and uninstall |
+| [How routing works](how-it-routes.md) | Stack-dependent role assignment, model tiers and independent verification |
+| [Guarantees](guarantees.md) | What code enforces and what the agent follows as instructions |
+| [Companions](companions.md) | Optional projects, setup links and alternatives using existing tools |
+| [Beginner](part-1-beginner.md) | Routing inside one agent or chat app |
+| [Intermediate](part-2-intermediate.md) | Delegation across several AI CLIs |
+| [Advanced](part-3-advanced.md) | Gateway templates and scheduled work on a Linux host |
+| [Catalog](catalog.md) | Supported tools, capability facts, unverified values, installation and sign-in notes |
+| [Security review history](security-review-history.md) | Review rounds, reproduced findings, fixes and regression tests |
+| [Proof](../proof/README.md) | Dated measurements, methods, sample sizes and reproduction scripts |
+| [Commands](../bin/README.md) | `aunx` subcommands and lane-runner exit codes |

package/docs/catalog.md

@@ -1,144 +1,336 @@
 # Catalog
 
-Generated from `src/catalog.js`. Do not hand-edit; `npm run gen:catalog` rewrites it. Protocols shipped at every level: 7 (counted from `templates/common/protocols/`).
+Generated from `src/catalog.js`. Do not hand-edit; `npm run gen:catalog` rewrites it. Protocols shipped at every level: 10 (counted from `templates/common/protocols/`).
 
 ## Levels
 
 | Level | Name | Tagline | Gives |
 |---|---|---|---|
 | 1 | Beginner | one LLM or agent, routed well | tiers, task classification, every protocol, one agent set up to follow them |
-| 2 | Intermediate | several LLMs and agents, called through their CLIs | everything in Beginner plus cli-run, a delegation matrix, task bundles and three-engine research triage |
-| 3 | Advanced | everything above, plus a virtual machine that runs it unattended | everything in Intermediate plus a gateway config, scheduled jobs, a dispatch layer and privacy gates for a box |
+| 2 | Intermediate | several LLMs and agents, called through their CLIs | everything in Beginner plus cli-run, a delegation matrix and multi-engine research triage |
+| 3 | Advanced | everything above, plus templates for your always-on Linux machine | everything in Intermediate plus a gateway config, a scheduled review job, dispatch guidance and configurable privacy gates |
 
 ## AIs
 
 ### `claude-code` · Claude Code (Anthropic)
 
-- **Kind:** agent-cli · **Access:** subscription · **Lane:** A · **Level:** 1+
-- **Wins at:** orchestrator: routes, maps, builds, verifies, records
+- **Kind:** agent-cli · **Billing:** subscription · **Level:** 1+
+- **What it is:** Anthropic's terminal coding agent; its subagents load the project rules file
 - **Install:** `npm install -g @anthropic-ai/claude-code@2.1.226`
 - **Sign in:** run `claude` once and sign in with your Anthropic account
 - **Reads rules from:** `CLAUDE.md` · subagents in `.claude/agents/`
 - **Plans:**
-  - Claude Pro (base headroom, checked 2026-09-12): https://support.claude.com/en/articles/11049762-choose-a-claude-plan
-  - Claude Max 5x (high headroom, checked 2026-09-12): https://support.claude.com/en/articles/11049762-choose-a-claude-plan
-  - Claude Max 20x (max headroom, checked 2026-09-12): https://support.claude.com/en/articles/11049762-choose-a-claude-plan
+  - Claude Pro (base headroom, checked 2026-09-12; tier models: unverified): https://claude.com/pricing
+  - Claude Max 5x (high headroom, checked 2026-09-12; tier models: unverified): https://claude.com/pricing
+  - Claude Max 20x (max headroom, checked 2026-09-12; tier models: unverified): https://claude.com/pricing
 - **Built against:** 2.1.226 (the same number the npm pin uses)
 
+**Capability facts.** An unverified value needs a current capability check before use. Role assignments come from the selected stack, using these facts.
+
+| Fact | Value |
+|---|---|
+| `modelFamily` | Anthropic |
+| `kind` | agent-cli |
+| `billing` | subscription |
+| `pricing` | unverified |
+| `headless` | yes |
+| `cliRun` | no |
+| `writesFiles` | yes |
+| `readOnlyMode` | no |
+| `liveWeb` | yes |
+| `runsLocally` | no |
+| `fanOut` | unverified |
+| `contextWindow` | unverified |
+| `loadsProjectRules` | yes |
+| `agentDefinitions` | .claude/agents |
+
 ### `codex` · Codex CLI (OpenAI, ChatGPT plan)
 
-- **Kind:** agent-cli · **Access:** subscription · **Lane:** A · **Level:** 1+
-- **Wins at:** second coder and second-opinion reviewer (a different model family reading your diff)
+- **Kind:** agent-cli · **Billing:** subscription · **Level:** 1+
+- **What it is:** OpenAI's terminal coding agent on a ChatGPT plan; `--audit` runs it in a read-only filesystem sandbox
 - **Install:** `npm install -g @openai/codex@0.153.4`
 - **Sign in:** `codex login` (add `--device-auth` on a machine with no browser)
 - **Reads rules from:** `AGENTS.md`
 - **cli-run lane:** yes
 - **Plans:**
-  - ChatGPT Plus (base headroom, checked 2026-09-12): https://learn.chatgpt.com/codex/pricing.md
-  - ChatGPT Pro 5x (high headroom, checked 2026-09-12): https://learn.chatgpt.com/codex/pricing.md
-  - ChatGPT Pro 20x (max headroom, checked 2026-09-12): https://learn.chatgpt.com/codex/pricing.md
+  - ChatGPT Plus (base headroom, checked 2026-09-12; tier models: unverified): https://learn.chatgpt.com/codex/pricing.md
+  - ChatGPT Pro 5x (high headroom, checked 2026-09-12; tier models: unverified): https://learn.chatgpt.com/codex/pricing.md
+  - ChatGPT Pro 20x (max headroom, checked 2026-09-12; tier models: unverified): https://learn.chatgpt.com/codex/pricing.md
 - **Built against:** 0.153.4 (the same number the npm pin uses)
 
+**Capability facts.** An unverified value needs a current capability check before use. Role assignments come from the selected stack, using these facts.
+
+| Fact | Value |
+|---|---|
+| `modelFamily` | OpenAI |
+| `kind` | agent-cli |
+| `billing` | subscription |
+| `pricing` | unverified |
+| `headless` | yes |
+| `cliRun` | yes |
+| `writesFiles` | yes |
+| `readOnlyMode` | yes |
+| `liveWeb` | unverified |
+| `runsLocally` | no |
+| `fanOut` | no |
+| `contextWindow` | unverified |
+| `loadsProjectRules` | no |
+| `agentDefinitions` | unverified |
+
 ### `agy` · Antigravity CLI `agy` (Google AI plan)
 
-- **Kind:** agent-cli · **Access:** subscription · **Lane:** A · **Level:** 1+
-- **Wins at:** deep research sweeps and concurrent fan-out (its subagent call takes an array)
+- **Kind:** agent-cli · **Billing:** subscription · **Level:** 1+
+- **What it is:** Google's Antigravity terminal agent; one subagent call starts several children. fanOut: UNVERIFIED against a vendor doc; inherited from the 0.1.x catalog.
 - **Install:** vendor script (read it first): `https://antigravity.google/cli/install.sh`
-- **Sign in:** first run opens a device-code sign-in with your Google account
+- **Sign in:** run `agy`; the first run opens a device-code sign-in with your Google account
 - **Reads rules from:** `GEMINI.md` · subagents in `.agents/agents/`
 - **cli-run lane:** yes
 - **Plans:**
-  - Google AI Pro (base headroom, checked 2026-09-12): https://gemini.google/subscriptions/
-  - Google AI Ultra 5x (high headroom, checked 2026-09-12): https://gemini.google/subscriptions/
-  - Google AI Ultra 20x (max headroom, checked 2026-09-12): https://gemini.google/subscriptions/
+  - Google AI Pro (base headroom, checked 2026-09-12; tier models: unverified): https://gemini.google/subscriptions/
+  - Google AI Ultra 5x (high headroom, checked 2026-09-12; tier models: unverified): https://gemini.google/subscriptions/
+  - Google AI Ultra 20x (max headroom, checked 2026-09-12; tier models: unverified): https://gemini.google/subscriptions/
 - **Built against:** 1.1.27
 - **Note:** Gemini CLI was retired by Google in June 2026. agy is the successor. Do not install `gemini`.
 
+**Capability facts.** An unverified value needs a current capability check before use. Role assignments come from the selected stack, using these facts.
+
+| Fact | Value |
+|---|---|
+| `modelFamily` | Google |
+| `kind` | agent-cli |
+| `billing` | subscription |
+| `pricing` | unverified |
+| `headless` | yes |
+| `cliRun` | yes |
+| `writesFiles` | yes |
+| `readOnlyMode` | no |
+| `liveWeb` | unverified |
+| `runsLocally` | no |
+| `fanOut` | yes (UNVERIFIED against a vendor doc; inherited from the 0.1.x catalog.) |
+| `contextWindow` | unverified |
+| `loadsProjectRules` | unverified |
+| `agentDefinitions` | .agents/agents |
+
 ### `grok` · Grok CLI (xAI, X Premium)
 
-- **Kind:** agent-cli · **Access:** subscription · **Lane:** A · **Level:** 1+
-- **Wins at:** X and live web reads at no per-call cost (its search tools bill on the API, not on the CLI)
+- **Kind:** agent-cli · **Billing:** subscription · **Level:** 1+
+- **What it is:** xAI's terminal agent with first-party X and web search tools; searches are covered by the subscription rather than billed per call. liveWeb: UNVERIFIED against a vendor doc; inherited from the 0.1.x catalog.
 - **Install:** vendor script (read it first): `https://x.ai/cli/install.sh`
 - **Sign in:** `grok login` (add `--device-auth` on a headless machine)
 - **cli-run lane:** yes
 - **Plans:**
-  - SuperGrok (base headroom, checked 2026-09-12): https://x.ai/news/grok-build-cli
-  - SuperGrok Plus (high headroom, checked 2026-09-12): https://x.ai/pricing
-  - X Premium Plus (base headroom, checked 2026-09-12): https://x.ai/news/grok-build-cli
+  - SuperGrok (base headroom, checked 2026-09-12; tier models: unverified): https://x.ai/news/grok-build-cli
+  - SuperGrok Plus (high headroom, checked 2026-09-12; tier models: unverified): https://x.ai/pricing
+  - X Premium Plus (base headroom, checked 2026-09-12; tier models: unverified): https://x.ai/news/grok-build-cli
 - **Built against:** 1.0.5
 
+**Capability facts.** An unverified value needs a current capability check before use. Role assignments come from the selected stack, using these facts.
+
+| Fact | Value |
+|---|---|
+| `modelFamily` | xAI |
+| `kind` | agent-cli |
+| `billing` | subscription |
+| `pricing` | unverified |
+| `headless` | yes |
+| `cliRun` | yes |
+| `writesFiles` | yes |
+| `readOnlyMode` | no |
+| `liveWeb` | yes (UNVERIFIED against a vendor doc; inherited from the 0.1.x catalog.) |
+| `runsLocally` | no |
+| `fanOut` | no |
+| `contextWindow` | unverified |
+| `loadsProjectRules` | no |
+| `agentDefinitions` | unverified |
+
 ### `hermes` · Hermes Agent (Nous Research)
 
-- **Kind:** agent-cli · **Access:** free · **Lane:** A · **Level:** 2+
-- **Wins at:** the free tier: rough drafts, first-pass summaries, cheap divergent reads, cron jobs on a box
+- **Kind:** agent-cli · **Billing:** free · **Level:** 2+
+- **What it is:** A free terminal agent that chains whichever providers you authenticate
 - **Install:** https://github.com/NousResearch/hermes-agent
 - **Sign in:** `hermes auth add <provider>` per provider; its own fallback chain handles outages
 - **cli-run lane:** yes
 - **Built against:** 0.20.0
 
+**Capability facts.** An unverified value needs a current capability check before use. Role assignments come from the selected stack, using these facts.
+
+| Fact | Value |
+|---|---|
+| `modelFamily` | unverified |
+| `kind` | agent-cli |
+| `billing` | free |
+| `pricing` | unverified |
+| `headless` | yes |
+| `cliRun` | yes |
+| `writesFiles` | yes |
+| `readOnlyMode` | no |
+| `liveWeb` | unverified |
+| `runsLocally` | no |
+| `fanOut` | no |
+| `contextWindow` | unverified |
+| `loadsProjectRules` | no |
+| `agentDefinitions` | unverified |
+
 ### `qwen` · Qwen Code CLI (Alibaba, provider-agnostic)
 
-- **Kind:** agent-cli · **Access:** metered · **Lane:** B · **Level:** 2+
-- **Wins at:** cheapest metered bulk lane for structured output; never for anything that cites a line, a number or a source
+- **Kind:** agent-cli · **Billing:** pay-per-token · **Level:** 2+
+- **What it is:** A provider-agnostic terminal agent; you supply the API key, so its rate is your provider's rate
 - **Install:** `npm install -g @qwen-code/qwen-code@0.22.3`
-- **Sign in:** a provider key in an environment variable, named (not stored) in ~/.qwen/settings.json. There is no free Qwen cloud tier any more.
+- **Sign in:** run `qwen` and use `/auth` to configure your provider
 - **Reads rules from:** `QWEN.md`
 - **cli-run lane:** yes
 - **Built against:** 0.22.3 (the same number the npm pin uses)
 - **Note:** Its own success flags lie on API failures. cli-run checks the two honest signals for you.
 
+**Capability facts.** An unverified value needs a current capability check before use. Role assignments come from the selected stack, using these facts.
+
+| Fact | Value |
+|---|---|
+| `modelFamily` | unverified |
+| `kind` | agent-cli |
+| `billing` | pay-per-token |
+| `pricing` | unverified |
+| `headless` | yes |
+| `cliRun` | yes |
+| `writesFiles` | yes |
+| `readOnlyMode` | no |
+| `liveWeb` | unverified |
+| `runsLocally` | no |
+| `fanOut` | no |
+| `contextWindow` | unverified |
+| `loadsProjectRules` | no |
+| `agentDefinitions` | unverified |
+
 ### `ollama` · Ollama (local models)
 
-- **Kind:** local · **Access:** local · **Lane:** local · **Level:** 2+
-- **Wins at:** the privacy lane: anything that must never leave the machine. Not a cost lane.
+- **Kind:** local-runtime · **Billing:** local · **Level:** 2+
+- **What it is:** A local model runtime; work sent here stays on the machine
 - **Install:** https://ollama.com/download (or `brew install ollama`)
 - **Sign in:** none
 - **Built against:** 0.33.3
 
+**Capability facts.** An unverified value needs a current capability check before use. Role assignments come from the selected stack, using these facts.
+
+| Fact | Value |
+|---|---|
+| `modelFamily` | unverified |
+| `kind` | local-runtime |
+| `billing` | local |
+| `pricing` | unverified |
+| `headless` | yes |
+| `cliRun` | no |
+| `writesFiles` | no |
+| `readOnlyMode` | no |
+| `liveWeb` | no |
+| `runsLocally` | yes |
+| `fanOut` | no |
+| `contextWindow` | unverified |
+| `loadsProjectRules` | no |
+| `agentDefinitions` | unverified |
+
 ### `claude-app` · Claude app or claude.ai (chat only, no CLI)
 
-- **Kind:** chat · **Access:** subscription · **Lane:** chat · **Level:** 1+
-- **Wins at:** single-agent use through Projects and custom instructions
+- **Kind:** chat · **Billing:** subscription · **Level:** 1+
+- **What it is:** A chat app; it reads pasted instructions, not files
 - **Install:** https://claude.ai
 - **Sign in:** sign in
 
+**Capability facts.** An unverified value needs a current capability check before use. Role assignments come from the selected stack, using these facts.
+
+| Fact | Value |
+|---|---|
+| `modelFamily` | Anthropic |
+| `kind` | chat |
+| `billing` | subscription |
+| `pricing` | unverified |
+| `headless` | no |
+| `cliRun` | no |
+| `writesFiles` | no |
+| `readOnlyMode` | no |
+| `liveWeb` | unverified |
+| `runsLocally` | no |
+| `fanOut` | no |
+| `contextWindow` | unverified |
+| `loadsProjectRules` | no |
+| `agentDefinitions` | unverified |
+
 ### `chatgpt-app` · ChatGPT (chat only, no CLI)
 
-- **Kind:** chat · **Access:** subscription · **Lane:** chat · **Level:** 1+
-- **Wins at:** single-agent use through custom instructions and Projects
+- **Kind:** chat · **Billing:** subscription · **Level:** 1+
+- **What it is:** A chat app; it reads pasted instructions, not files
 - **Install:** https://chatgpt.com
 - **Sign in:** sign in
 
+**Capability facts.** An unverified value needs a current capability check before use. Role assignments come from the selected stack, using these facts.
+
+| Fact | Value |
+|---|---|
+| `modelFamily` | OpenAI |
+| `kind` | chat |
+| `billing` | subscription |
+| `pricing` | unverified |
+| `headless` | no |
+| `cliRun` | no |
+| `writesFiles` | no |
+| `readOnlyMode` | no |
+| `liveWeb` | unverified |
+| `runsLocally` | no |
+| `fanOut` | no |
+| `contextWindow` | unverified |
+| `loadsProjectRules` | no |
+| `agentDefinitions` | unverified |
+
 ### `gemini-app` · Gemini app (chat only, no CLI)
 
-- **Kind:** chat · **Access:** subscription · **Lane:** chat · **Level:** 1+
-- **Wins at:** single-agent use through Gems and saved instructions
+- **Kind:** chat · **Billing:** subscription · **Level:** 1+
+- **What it is:** A chat app; it reads pasted instructions, not files
 - **Install:** https://gemini.google.com
 - **Sign in:** sign in
 
+**Capability facts.** An unverified value needs a current capability check before use. Role assignments come from the selected stack, using these facts.
+
+| Fact | Value |
+|---|---|
+| `modelFamily` | Google |
+| `kind` | chat |
+| `billing` | subscription |
+| `pricing` | unverified |
+| `headless` | no |
+| `cliRun` | no |
+| `writesFiles` | no |
+| `readOnlyMode` | no |
+| `liveWeb` | unverified |
+| `runsLocally` | no |
+| `fanOut` | no |
+| `contextWindow` | unverified |
+| `loadsProjectRules` | no |
+| `agentDefinitions` | unverified |
+
 ## Companion tools
 
+Model-orchestrator project activation merges supported MCP entries for selected companions when activation is enabled. The vendor command auto-registration field below describes what the listed vendor command does when you run it yourself. Global client configuration remains manual.
+
 ### `codecalc` · codecalc (calculator, code runner, logic checker for your agent)
 
 - **Repo:** https://github.com/The-40-Thieves/codecalc
 - **Gives:** exact arithmetic, code execution in 31 languages, SMT logic checks, complexity and equivalence proofs; offline, no key, no telemetry
-- **Install:** `uvx 'codecalc[full]' setup --write` (needs uv (https://docs.astral.sh/uv/) and Python 3.10+)
-- **Registers itself with:** Claude Code, Claude Desktop, Cursor, VS Code, Zed; snippets for the rest are written to `mcp/`
-- **Default:** selected
+- **Install:** `uvx 'codecalc[full]==0.5.0' setup --write` (needs uv (https://docs.astral.sh/uv/) and Python 3.10+)
+- **Vendor command auto-registration:** Claude Code, Claude Desktop, Cursor, VS Code, Zed; snippets for the rest are written to `mcp/`
+- **Default:** not selected
 
 ### `obsidian-tc` · obsidian-tc (governed memory: an agent-ready MCP server over an Obsidian vault)
 
 - **Repo:** https://github.com/The-40-Thieves/obsidian-tc
 - **Gives:** durable memory and record for your agents: hybrid retrieval (BM25 + dense + link graph), backlinks, compare-and-swap writes with a confirmation gate, folder ACLs, a poison scan on inferred writes; 163 tools, local by default
-- **Install:** `npm install -g obsidian-tc && obsidian-tc /path/to/your/vault` (needs an Obsidian vault folder (the Obsidian app itself is only needed for live plugin bridges); Node 24+ or Bun 1.1+ (stricter than this installer); Ollama with `nomic-embed-text` for local embeddings, or a cloud embeddings key; the Local REST API plugin only for bridge tools)
-- **Registers itself with:** Cursor, VS Code; snippets for the rest are written to `mcp/`
+- **Install:** `npm install -g obsidian-tc@1.26.0 && obsidian-tc /path/to/your/vault` (needs an Obsidian vault folder (the Obsidian app itself is only needed for live plugin bridges); Node 24+ or Bun 1.1+ (stricter than this installer); Ollama with `nomic-embed-text` for local embeddings, or a cloud embeddings key; the Local REST API plugin only for bridge tools)
+- **Vendor command auto-registration:** Cursor, VS Code; snippets for the rest are written to `mcp/`
 - **Default:** not selected
 
 ### `context7` · Context7 (Upstash: version-aware docs for the libraries your agent calls)
 
 - **Repo:** https://github.com/upstash/context7
 - **Gives:** up-to-date, version-specific documentation and code examples for libraries, SDKs, APIs and CLIs, pulled into the prompt; tells the agent what the code is SUPPOSED to do. Paired with codecalc, which runs the code and proves what it actually does: docs never stand as proof, and where they disagree the run wins
-- **Install:** `npx ctx7 setup` (needs Node.js 18+ for the local server or the ctx7 CLI; a free CONTEXT7_API_KEY is optional, for higher rate limits (it works anonymously at the base rate))
-- **Registers itself with:** Claude Code, Cursor, Codex CLI, Qwen Code; snippets for the rest are written to `mcp/`
+- **Install:** `npx -y @upstash/context7-mcp@4.1.1` (needs Node.js 18+ for the local server or the ctx7 CLI; a free CONTEXT7_API_KEY is optional, for higher rate limits (it works anonymously at the base rate))
+- **Vendor command auto-registration:** none; use project activation or merge the supplied snippets in `mcp/` using the tool guide
 - **Default:** not selected
 

package/docs/companions.md

@@ -1,17 +1,35 @@
-# Companion tools
+# Works well with
 
-All optional. The installer asks about each one separately; selecting one writes a doc and config snippets, it installs nothing. `--tools codecalc,obsidian-tc,context7` or `--no-tools` for scripted runs; `--yes` alone selects only the recommended one.
+Companions add calculation, searchable notes or current library documentation. They are other authors' projects, with their own releases and support channels. All are opt-in; a default install and `--yes` both select none.
 
-## Companion tools (all optional)
+```bash
+npx model-orchestrator --tools codecalc,obsidian-tc,context7
+```
 
-An orchestrator routes work. It does not make a model stop guessing numbers, it does not give it a memory, and it does not make it check a library's current docs before writing against it. Three tools close those gaps: codecalc and obsidian-tc are from the same maintainer, Context7 is from Upstash. The installer asks about each one separately; selecting one writes a doc and config snippets, it installs nothing. `--tools codecalc,obsidian-tc,context7` or `--no-tools` for scripted runs; `--yes` alone selects only the recommended one.
+Selecting a companion writes model-orchestrator's setup guide and configuration snippets. With automatic activation enabled, a Claude Code main agent also gets the selected servers merged into the project's `.mcp.json`. The summary names this file before the single confirmation; an existing file gets a backup, and existing server entries stay intact. Other hosts keep a manual registration step when the catalog has no verified project-scoped config. `--no-apply` leaves registration manual; `--yes` applies it only with `--apply-snippets`.
 
-| Tool | Closes | Default | You need first |
+The installer writes its managed files and the project configuration changes named in the summary, prints missing tools together under **Install these yourself**, and leaves third-party commands for you to run. It never edits global user config. codecalc still needs uv and Python 3.10+; obsidian-tc still needs your vault configuration path. Context7's hosted connection needs no local package install. `--no-tools` remains accepted for existing scripts.
+
+## Choose a companion
+
+| Project | Maintainer | What it adds | Setup and support |
 |---|---|---|---|
-| [codecalc](https://github.com/The-40-Thieves/codecalc) | guessed numbers, comparisons, complexity and equivalence claims: exact arithmetic, code execution in 31 languages, SMT logic checks, `verify_translation` / `verify_optimization`; offline, no key | yes | Python 3.10+ and `uv`. `uvx 'codecalc[full]' setup --write` registers it with Claude Code, Claude Desktop, Cursor, VS Code, Zed; snippets for Codex, Antigravity, Qwen Code are written for you |
-| [obsidian-tc](https://github.com/The-40-Thieves/obsidian-tc) | no durable memory: hybrid search, backlinks, compare-and-swap writes with a confirmation gate, folder ACLs, a poison scan on inferred writes; 163 tools, local by default; AGPL-3.0 | no | an Obsidian vault folder; Node 24+ or Bun 1.1+ (stricter than this installer); Ollama with `nomic-embed-text` or a cloud embeddings key; the Obsidian app and its Local REST API plugin only for live bridge tools. Skip it if you do not keep notes in Obsidian |
-| [Context7](https://github.com/upstash/context7) | stale library recall: current, version-specific docs and code examples pulled into the prompt for any library, SDK, API or CLI; hosted, or `npx` locally; MIT | no | nothing to install for the hosted endpoint; Node.js 18+ for the local alternative; a free API key is optional, for a higher rate limit. Always makes a network call, unlike the other two: skip it offline |
+| [codecalc](https://github.com/The-40-Thieves/codecalc) | The-40-Thieves | Local arithmetic, code execution, logic and equivalence checks | Follow the generated `CODECALC.md` and the [upstream instructions](https://github.com/The-40-Thieves/codecalc#readme); report tool issues [upstream](https://github.com/The-40-Thieves/codecalc/issues) |
+| [obsidian-tc](https://github.com/The-40-Thieves/obsidian-tc) | The-40-Thieves | Search, backlinks and controlled writes for an Obsidian notes folder | Follow `OBSIDIAN-TC.md` and the [upstream instructions](https://github.com/The-40-Thieves/obsidian-tc#readme); report tool issues [upstream](https://github.com/The-40-Thieves/obsidian-tc/issues) |
+| [Context7](https://github.com/upstash/context7) | Upstash | Current documentation and examples for a specific library version | Follow `CONTEXT7.md` and the [upstream instructions](https://github.com/upstash/context7#readme); report tool issues [upstream](https://github.com/upstash/context7/issues) |
+
+Check each project's current runtime and sign-in requirements before installing it. Context7 sends documentation queries over the network, including when its MCP server runs locally. Keep private source and secrets out of query text.
+
+## Use the protocols with your existing tools
+
+| Need | With a companion | With your existing tools |
+|---|---|---|
+| Compute and verify | codecalc | A calculator, a local runtime or your project's test command |
+| Search and record | obsidian-tc | A notes folder, file search and version control |
+| Check an API | Context7 | Current official documentation and upstream source, then a local execution check |
+
+Every install includes `protocols/numbers-and-logic.md`, `protocols/memory-and-record.md` and `protocols/docs-then-prove.md`. The protocols describe the job; companion selection changes which tool can do it.
 
-Context7 pairs with codecalc rather than duplicating it: Context7 tells the agent what a library is documented to do on this version, codecalc runs the code and proves what it actually does. Docs never stand as proof on their own, and where the two disagree the run wins.
+## Keep an existing setup
 
-Whether or not you select them, every level carries the three rules they serve: `protocols/numbers-and-logic.md` (when calling a calculator is mandatory, how to report a computed figure, why a thought log is not evidence), `protocols/memory-and-record.md` (search before writing, the folder index is part of the change, one writer, inferred content marked as inferred), and `protocols/docs-then-prove.md` (current docs before writing a call, then a run proves it, the run wins on disagreement).
+Upgrading from 0.1.x preserves existing codecalc files. `--uninstall` removes a managed companion guide or snippet only when its content still matches the recorded hash; edited files stay and are listed. Automatically merged project MCP entries are recorded separately: uninstall removes only entries the installer added that still match their recorded configuration. Other servers, user edits and backups stay. See [Upgrading from 0.1.x](install.md#upgrading-from-01x).

package/docs/guarantees.md

@@ -1,18 +1,27 @@
-# What holds, and what is only asked for
+# Guarantees and verification
 
-Read this before running any of it unattended.
+model-orchestrator writes its managed files and the project activation changes shown in the summary. It runs no third-party installs, edits no global user config and sends no telemetry. `npx` itself downloads this package through npm before the installer starts.
 
-Most of what this package ships is text an agent is asked to follow. Be clear about which is which before relying on it unattended.
+Use the distinction below when choosing which parts to run unattended.
 
-| Property | How it holds |
+| Property | What enforces it |
 |---|---|
-| Installer writes only inside `--dir` and `--project`, never a secret, never over a document without `--force` (or `--update-docs`, which touches only documents provably untouched since a previous run); machine-owned config always, runtime files only when provably untouched or with `--upgrade-runtime` | **enforced by code** (preflight, exclusive create, rollback, manifest hashes; tested) |
-| `cli-run` exit codes, process-group kill on timeout and on SIGINT/SIGTERM, UTF-8-safe streaming, fixed-code durable log, `--expect-*` contracts with a pre-run snapshot | **enforced by code** (tested with stub lanes) |
-| Codex audit lane runs read-only | **delegated to the vendor flag** (`--audit` → `--sandbox read-only`); commands and network still follow your codex config |
-| Other lanes' permissions, sign-in state, model versions | **delegated to each vendor's own config**; `--doctor` checks presence, not versions |
-| Gateway binds to loopback, keys by name only | **enforced in the generated files**; whether the gateway authenticates is your environment |
-| Lane selection, tiers, privacy classes, one-writer, escalation, the protocols | **agent instructions**. Nothing here stops an agent that ignores its rules; the task bundle and the protocols make ignoring them visible, not impossible |
-| Weekly audit bounded, previous report preserved | **enforced in the generated script and unit** (watchdog, temp-and-rename, `TimeoutStartSec`) |
+| Installer writes stay inside `--dir` and `--project`; existing edits are preserved by default | Code: path preflight, exclusive creation, rollback and manifest hashes |
+| Companion tools start unselected, including with `--yes` | Code: explicit tool selection; missing tools get printed setup commands |
+| `--update-docs` refreshes unedited documents; `--upgrade-runtime` replaces runtime files only | Code: recorded hashes, file classes and named conflicts |
+| Interactive activation applies the main agent's supported rules and settings with backups; `--yes` requires `--apply-snippets` | Code: one confirmation, the `--no-apply` flag and edit toggle, marked rules blocks and validated settings merges |
+| Selected companions register automatically only in the main agent's catalog-supported project config | Code: Claude Code's project `.mcp.json` target; other hosts retain manual setup steps |
+| Uninstall removes unchanged managed files and unchanged recorded activation entries | Code: complete manifest validation before removal, containment checks, hash comparison and activation ownership records |
+| Every non-dry install checks CLI presence; live prompts stay opt-in | Code: automatic `--doctor`; `--doctor --run` explicitly enables vendor canaries |
+| `cli-run` returns nonzero for missing results, timeouts and rejected output contracts | Code: vendor-specific output checks, process cleanup and `--expect-*` checks against a pre-run snapshot |
+| Acceptance checks report PASS or FAIL and return exit 1 for any failure | Code: `aunx checks run ACCEPTANCE_CHECKS.json`; run it before the action you want to gate |
+| Proof entries carry measurement dates, methods and expiry dates | Code: data validation and an expiry check in `npm test` |
+| Codex audits request read-only filesystem access | Vendor flag: `--audit` selects `--sandbox read-only`; command and network permissions still follow the vendor configuration |
+| Other workers' permissions, sign-in state and model availability | Vendor configuration and your live verification with `aunx cli-run --doctor --run` |
+| Gateway listens on loopback and refers to secrets by environment-variable name | Generated configuration; authentication and deployment remain your responsibility |
+| Model choice, effort guidance, privacy rules, one writer and independent review | Agent instructions in the routing rules, task brief and protocols |
+| Weekly review has bounded execution and preserves the previous report on failure | Generated script and service: watchdog, temporary output and rename |
 
-If you need a property in the third row to be enforced, that is a router, a policy engine or a sandbox, and this package does not claim to be one.
+The acceptance-check runner executes commands you supply, with your shell's permissions. Review a check file before running it. Wire its exit code into your own release command or CI when you want it to block that action.
 
+The plugin's routing hooks only read files and emit context; they run no subprocess, perform no network access and write no files. The separate installed metrics hook writes a local routing log without prompt text. [Security review history](security-review-history.md) links the regression evidence for these boundaries.