model-orchestrator 0.1.23 → 0.1.25

package/CHANGELOG.md

@@ -4,6 +4,20 @@ All notable changes to this project are documented here. The format follows [Kee
 
 ## [Unreleased]
 
+## [0.1.25] - 2026-09-19
+
+### Fixed
+
+- **Context7 on Windows: a Zed snippet that can start the local server** ([#34](https://github.com/aunysillyme/model-orchestrator/issues/34)). `mcp/context7.zed.settings.json` spawns `"command": "npx"`, and on Windows `npx` is `npx.cmd`, a batch file a client cannot spawn as a bare command. New `mcp/context7.zed.windows.settings.json` runs `"command": "cmd"` with `"args": ["/c", "npx", "-y", "@upstash/context7-mcp@<pin>"]`, the shape Context7's own client guide ships for Windows. `CONTEXT7.md` gains a "Local `npx` on Windows" table saying which Zed snippet to use on which OS, and the same by-hand change for any other client taking the local alternative. The remote snippets spawn nothing and are unchanged. A test pins the Windows args to the POSIX args behind `/c npx` and the catalog pin; not yet run on a Windows machine.
+
+## [0.1.24] - 2026-09-18
+
+### Added
+
+- **Context7 as a third companion tool, paired with codecalc.** [Context7](https://github.com/upstash/context7) (Upstash) hands the agent current, version-specific documentation and code examples for any library, SDK, API or CLI, hosted or run locally with `npx`. It answers what a library is documented to do; codecalc still answers what the code actually does by running it. A new protocol, `protocols/docs-then-prove.md`, states the rule the pairing serves: pull current docs before writing against anything unconfirmed this session, then a run proves it, and where a doc and a run disagree the run wins. Optional and off by default, like obsidian-tc (`--tools context7`, or the interactive question); unlike the other two companions it always makes a network call, so it is the one to skip offline. `src/catalog.js` carries the entry (repo, role, install, requirements, the clients it self-registers with); `CONTEXT7_STATUS` renders both selected and not-selected wording the same way `CODECALC_STATUS` and `OBSIDIAN_TC_STATUS` already do, at every level and in `ROUTING.md`.
+- **`templates/tools/context7/CONTEXT7.md` plus seven per-client `mcp/` snippets**, each read from that client's own docs rather than shared across clients that do not actually share a config shape: `context7.claude-code.mcp.json` (`"type": "http"` next to `url`, required or Claude Code skips the server), `context7.mcpServers.json` (Cursor's own documented shape, `url` with no `type`), `context7.vscode.mcp.json`, `context7.qwen.settings.json` (`httpUrl`, not `url`, plus the non-credential `Accept` header upstream ships), `context7.zed.settings.json` (local `npx`, pinned to the catalog's `context7` version), `context7.codex.config.toml`, `context7.agy.mcp_config.json`. Claude Desktop has no file: its remote connection is a UI step (`Settings > Connectors > Add Custom Connector`), documented in `CONTEXT7.md` instead of a snippet nothing there reads.
+- **Every context7 snippet ships keyless by default.** The anonymous tier works with no header, while an unexpanded or empty `Bearer ${CONTEXT7_API_KEY}` makes every call return "Invalid API key" (probed live against `https://mcp.context7.com/mcp`), and clients like Codex `http_headers` never expand it. `CONTEXT7.md` has a "Higher rate limits (optional key)" section with one mechanism per client: Codex `bearer_token_env_var`, Claude Code `${VAR}` expansion in `.mcp.json` headers, Claude Desktop's own Connectors key field, an exported shell variable for local `npx`, and "check your client's docs" where expansion is not confirmed; the fallback for a client that does not pass its environment to a spawned child is to stay anonymous, never to paste the key into a snippet's args. A test fails if a shipped snippet carries `Authorization` or `CONTEXT7_API_KEY`.
+
 ## [0.1.23] - 2026-09-15
 
 ### Added
@@ -351,7 +365,9 @@ First release.
 - Tests: a case per fix, judges proven to go red, mutation checks; `npm test` prints the current count.
 - Adversarial audit: two Codex rounds plus a two-engine review (Codex, Antigravity); findings and fixes in `docs/audit-brief.md`. After the review: subagents go to the project root (`--project`), snippet paths computed from `--dir`, lane sections rendered from the selection, a primary agent required, level 3 asks for API keys separately from CLIs, images and CLI installs pinned, an activation summary at the end of every install.
 
-[Unreleased]: https://github.com/aunysillyme/model-orchestrator/compare/v0.1.23...HEAD
+[Unreleased]: https://github.com/aunysillyme/model-orchestrator/compare/v0.1.25...HEAD
+[0.1.25]: https://github.com/aunysillyme/model-orchestrator/compare/v0.1.24...v0.1.25
+[0.1.24]: https://github.com/aunysillyme/model-orchestrator/compare/v0.1.23...v0.1.24
 [0.1.23]: https://github.com/aunysillyme/model-orchestrator/compare/v0.1.22...v0.1.23
 [0.1.22]: https://github.com/aunysillyme/model-orchestrator/compare/v0.1.21...v0.1.22
 [0.1.21]: https://github.com/aunysillyme/model-orchestrator/compare/v0.1.20...v0.1.21

package/README.md

@@ -38,7 +38,7 @@ State known subscription plans with `--plans codex=pro-20x,agy=ultra-5x`. The ge
 
 | Level | You have | You get |
 |---|---|---|
-| **1 · Beginner** | one LLM or one agent | tiers, task classification, the two build checkpoints, the protocols (build, propagate, gap analysis, deep research, numbers and logic, memory and record), a task-bundle template, and your agent set up to follow them |
+| **1 · Beginner** | one LLM or one agent | tiers, task classification, the two build checkpoints, the protocols (build, propagate, gap analysis, deep research, numbers and logic, memory and record, docs and proof), a task-bundle template, and your agent set up to follow them |
 | **2 · Intermediate** | several AIs with CLIs | everything above, plus `cli-run` (exit 0 means a structurally accepted non-empty response; opt-in `--expect-file` / `--expect-json` for real contracts; `--model` / `--effort` to pin the route and log it), a delegation matrix generated from your selection, research triage across the lanes you have |
 | **3 · Advanced** | a virtual machine | everything above, plus a gateway config rendered from the API keys you hold (asked separately from your CLIs), pinned images, box rules, privacy gates, and a weekly gap-analysis job with "what watches it" written down |
 
@@ -59,16 +59,19 @@ Read the thinking behind each level in [docs/](docs/README.md): [Part 1](docs/pa
 
 `npx model-orchestrator --list` prints the catalog with install and sign-in notes. Details: [docs/catalog.md](docs/catalog.md).
 
-## Companion tools (both optional)
+## Companion tools (all optional)
 
-An orchestrator routes work. It does not make a model stop guessing numbers, and it does not give it a memory. Two tools from the same maintainer close those gaps. The installer asks about each one separately; selecting one writes a doc and config snippets, it installs nothing. `--tools codecalc,obsidian-tc` or `--no-tools` for scripted runs; `--yes` alone selects only the recommended one.
+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.
 
 | Tool | Closes | Default | You need first |
 |---|---|---|---|
 | [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 |
 
-Whether or not you select them, every level carries the two 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) and `protocols/memory-and-record.md` (search before writing, the folder index is part of the change, one writer, inferred content marked as inferred).
+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.
+
+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).
 
 ## The two folders every run writes to
 
@@ -88,7 +91,7 @@ An install has two targets, and a scripted run should set both.
 npx model-orchestrator --yes --level 2 --ais claude-code,codex,grok --primary claude-code \
   --dir ./ai-orchestrator --project ./my-app
 # --yes selects the recommended companion tool (codecalc), which writes CODECALC.md and mcp/ snippets.
-# Add --no-tools for none, or --tools codecalc,obsidian-tc to choose.
+# Add --no-tools for none, or --tools codecalc,obsidian-tc,context7 to choose.
 
 npx model-orchestrator --yes --level 3 --ais claude-code,codex,agy,grok,hermes,qwen,ollama --apis anthropic,openrouter --dry   # print the plan, write nothing
 npx model-orchestrator --yes --level 2 --ais claude-code,codex --project ~/my-app --dir ~/my-app/ai-orchestrator --no-tools  # subagents into ~/my-app/.claude/agents
@@ -118,8 +121,8 @@ ai-orchestrator/
   README.md                 start here, written for your level and your AIs
   ORCHESTRATOR.md           single-agent routing rules (level 1)
   TASK_BUNDLE.md            the brief every delegation carries
-  protocols/                build-protocol · propagate · gap-analysis · deep-research · numbers-and-logic · memory-and-record
-  CODECALC.md  OBSIDIAN-TC.md  mcp/   companion-tool install docs + per-agent registration snippets (if selected)
+  protocols/                build-protocol · propagate · gap-analysis · deep-research · numbers-and-logic · memory-and-record · docs-then-prove
+  CODECALC.md  OBSIDIAN-TC.md  CONTEXT7.md  mcp/   companion-tool install docs + per-agent registration snippets (if selected)
   <project>/.claude/agents/ one per tier plus finding-verifier, done-verifier, reader, at the PROJECT root (if Claude Code is primary)
   <project>/.claude/hooks/  route-gate.mjs (UserPromptSubmit) + subagent-context.mjs (SubagentStart) + route-metrics.mjs (all five: see "Measuring routing" below), Claude Code only
   CLAUDE.snippet.md         the block to paste into your CLAUDE.md

package/docs/catalog.md

@@ -1,6 +1,6 @@
 # Catalog
 
-Generated from `src/catalog.js`. Do not hand-edit; `npm run gen:catalog` rewrites it. Protocols shipped at every level: 6 (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: 7 (counted from `templates/common/protocols/`).
 
 ## Levels
 
@@ -134,3 +134,11 @@ Generated from `src/catalog.js`. Do not hand-edit; `npm run gen:catalog` rewrite
 - **Registers itself with:** 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/`
+- **Default:** not selected
+

package/docs/part-1-beginner.md

@@ -58,9 +58,13 @@ Logic flow follows the same rule. Reasoning scaffolds help models with no native
 
 Every protocol ends in a write. Search before you write (duplicates are how a store starts lying), correct the folder index in the same pass, one writer per session, mark inferred content as inferred. The optional companion for that is [obsidian-tc](https://github.com/The-40-Thieves/obsidian-tc), a governed MCP server over an Obsidian vault: hybrid search, backlinks, compare-and-swap writes, folder ACLs. It needs an Obsidian vault, Node 24+ or Bun, and Ollama or a cloud embeddings key, so it is off by default; without it the rule still binds against a notes folder and `grep`.
 
+## 9. Docs, then prove
+
+A model's recall of a library's API is training data, not a live source; it goes stale the moment the vendor ships a release it never saw. Before writing code against a library, SDK, API or CLI you have not confirmed this session, pull current, version-specific docs; then a run, not the doc, is what proves the code behaves that way. The optional companion is [Context7](https://github.com/upstash/context7) (Upstash): it hands the agent current, version-aware documentation and code examples on request, hosted or run locally with `npx`. It pairs with codecalc rather than replacing it: Context7 says what the code is supposed to do, codecalc's run says what it actually does, and the run wins where they disagree. It needs a network call (there is no offline mode), so it is off by default; without it the rule still binds, read the vendor's own docs or source by hand.
+
 ## What the installer gives you at this level
 
-`README.md` (start here) · `ORCHESTRATOR.md` · `TASK_BUNDLE.md` · `protocols/{build-protocol, propagate, gap-analysis, deep-research, numbers-and-logic, memory-and-record}.md` · `CODECALC.md` and `OBSIDIAN-TC.md` with `mcp/` snippets for the companion tools you selected · the loading surface for your primary agent (Claude Code subagents, Antigravity custom agents, a rules-file snippet, or a paste block for a chat app).
+`README.md` (start here) · `ORCHESTRATOR.md` · `TASK_BUNDLE.md` · `protocols/{build-protocol, propagate, gap-analysis, deep-research, numbers-and-logic, memory-and-record, docs-then-prove}.md` · `CODECALC.md`, `OBSIDIAN-TC.md` and `CONTEXT7.md` with `mcp/` snippets for the companion tools you selected · the loading surface for your primary agent (Claude Code subagents, Antigravity custom agents, a rules-file snippet, or a paste block for a chat app).
 
 ## When you have outgrown it
 

package/docs/part-2-intermediate.md

@@ -66,6 +66,10 @@ Measured on the cheapest metered lane: conclusions right, 0 of 11 line citations
 
 With several lanes proposing, the store is where they meet. obsidian-tc (optional) gives every CLI the same `semantic_search`, `get_backlinks` and compare-and-swap `write_note`, with folder ACLs so a research lane can read what it needs and write nothing. The orchestrator stays the one writer.
 
+## 11. Docs, then prove, across lanes
+
+Every lane's recall of a library's API is a lead, the same as its arithmetic (see item 9 above). Context7 (optional) gives every CLI the same current, version-aware docs lookup, registered for Claude Code, Cursor, Codex and Qwen Code with the snippets in `CONTEXT7.md`. It pairs with codecalc: a lane's claim about what a library does, cited from memory or from a doc, is confirmed by a run before code ships on it.
+
 ## What the installer gives you at this level
 
 Everything from Part 1, plus `ROUTING.md` · `TIERS.md` · `DELEGATION_MATRIX.md` (generated from your selection) · `RESEARCH_TRIAGE.md` · `CLI-RUN.md` · `bin/cli-run.mjs` · `bin/lanes.json`.

package/docs/part-3-advanced.md

@@ -60,6 +60,10 @@ Runs as a stdio MCP server next to the orchestrator CLI: offline, no key, nothin
 
 Stdio next to the orchestrator, or the upstream Docker service against a bind-mounted vault. Embeddings on the box's Ollama, so nothing leaves the machine. HTTP transport stays off unless every caller is on the private mesh and auth is on.
 
+## 10. context7 on the box
+
+Unlike the other two companions, it is never fully local: the hosted endpoint is a network call over HTTPS from the box, or a local `npx` server over stdio still needs no cloud account to run anonymously. Either way, only the library name and the query text leave the box, never source code. Scheduled jobs that write code against a vendored dependency pull its current docs through Context7 first, then prove the shape with codecalc before it ships.
+
 ## What the installer gives you at this level
 
 Everything from Parts 1 and 2, plus `vm/README.md` · `vm/setup-vm.sh` · `vm/docker-compose.yml` · `vm/gateway.config.yaml` (one lane per provider you selected, keys by name only) · `vm/ENVIRONMENT.md` · `vm/box-CLAUDE.md` · `vm/PRIVACY_GATES.md` · `vm/jobs/` (a weekly audit timer + service, and an index that names what watches each job).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "model-orchestrator",
-  "version": "0.1.23",
+  "version": "0.1.25",
   "description": "Model orchestrator for AI coding agents and LLMs: Claude Code, Codex, Gemini, Grok, Qwen, Ollama. Routing rules tell your agent which model, subagent or CLI to use for each task, so small work goes to cheap tiers and fewer tokens go to frontier models. One installer, plus a CLI runner that logs every route.",
   "type": "module",
   "bin": {

package/src/catalog.js

@@ -287,6 +287,18 @@ export const TOOLS = [
     autoClients: ['Cursor', 'VS Code'],
     recommended: false,
     optionalNote: 'Optional and heavier than codecalc. Skip it if you do not keep notes in Obsidian. AGPL-3.0.'
+  },
+  {
+    id: 'context7',
+    name: 'Context7 (Upstash: version-aware docs for the libraries your agent calls)',
+    repo: 'https://github.com/upstash/context7',
+    role: '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',
+    pin: '4.1.1',
+    requires: '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)',
+    autoClients: ['Claude Code', 'Cursor', 'Codex CLI', 'Qwen Code'],
+    recommended: false,
+    optionalNote: 'Optional, and from a different maintainer than codecalc and obsidian-tc (Upstash, not The-40-Thieves). Needs a network call even at the anonymous rate; skip it offline. MIT.'
   }
 ];
 export const toolById = Object.fromEntries(TOOLS.map((t) => [t.id, t]));

package/src/install.js

@@ -482,6 +482,7 @@ function vars(opts) {
     OLLAMA_IMAGE: IMAGES.ollama,
     CODECALC_PIN: pinOf('codecalc'),
     OBSIDIAN_TC_PIN: pinOf('obsidian-tc'),
+    CONTEXT7_PIN: pinOf('context7'),
     APIS_LIST: apis.length ? apis.map((prov) => '- ' + prov.name + ' (`' + prov.envName + '`)').join('\n') : '- none: no metered provider key was selected, so the gateway serves only a local lane if you picked one',
     INSTALL_DIR: dirPosix,
     INSTALL_DIR_SH: shellQuote(dirPosix),
@@ -507,6 +508,7 @@ function vars(opts) {
     TOOLS_LIST: tools.length ? tools.map((t) => '- ' + t.name + ': ' + t.role).join('\n') : '- none selected (re-run the installer with --tools codecalc to add the calculator and code runner)',
     CODECALC_STATUS: codecalc ? 'installed alongside this folder (see `CODECALC.md`)' : 'not selected; the rule below still binds, do the arithmetic with any tool that computes rather than guesses',
     OBSIDIAN_TC_STATUS: tools.some((t) => t.id === 'obsidian-tc') ? 'selected (see `OBSIDIAN-TC.md`); the tool names below are live calls' : 'not selected; the rule below still binds against whatever store you keep (a notes folder, a wiki, a repo of markdown), the tool names are what obsidian-tc would give you',
+    CONTEXT7_STATUS: tools.some((t) => t.id === 'context7') ? 'selected (see `CONTEXT7.md`); the tool names below are live calls' : 'not selected; the rule below still binds, read the vendor docs or source by hand before trusting them',
     DATE: new Date().toISOString().slice(0, 10),
     LEVEL_ID: String(level),
     LEVEL_NAME: lvl.name,

package/templates/README.md

@@ -4,11 +4,11 @@ Everything the installer can write, organized by the level that adds it. Files a
 
 | Folder | Written at | Contents |
 |---|---|---|
-| `common/` | every level | the start-here README, `TASK_BUNDLE.md`, `protocols/` (build, propagate, gap analysis, deep research, numbers and logic, memory and record) |
+| `common/` | every level | the start-here README, `TASK_BUNDLE.md`, `protocols/` (build, propagate, gap analysis, deep research, numbers and logic, memory and record, docs then prove) |
 | `beginner/` | every level | `ORCHESTRATOR.md`, the single-agent routing rules |
 | `agents/` | every level, one variant | the primary agent's loading surface: Claude Code subagents (plus `.claude/hooks/route-gate.mjs` and `subagent-context.mjs`, and `settings.hooks.snippet.json` to wire them in), Antigravity custom agents, or a paste snippet |
 | `intermediate/` | level 2+ | `ROUTING.md`, `TIERS.md`, `DELEGATION_MATRIX.md`, `RESEARCH_TRIAGE.md`, `CLI-RUN.md` |
 | `advanced/` | level 3 | `vm/`: gateway config, compose file, box rules, privacy gates, scheduled jobs |
-| `tools/` | when selected | companion tools the AIs call: `codecalc/` and `obsidian-tc/` (install doc + MCP snippets each). See `tools/README.md` |
+| `tools/` | when selected | companion tools the AIs call: `codecalc/`, `obsidian-tc/` and `context7/` (install doc + MCP snippets each). See `tools/README.md` |
 
 Agent definitions under `agents/claude-code/` and `agents/agy/` are written to the PROJECT root (`--project`), not `--dir`, because that is where those CLIs read them. A `README.md` at the root of a tier folder (like this one) documents the repo and is not installed. `common/README.md` is the exception: it is the user's start-here file. READMEs deeper in (`protocols/`, `vm/`, `vm/jobs/`) are installed as folder indexes.

package/templates/advanced/vm/README.md

@@ -18,6 +18,7 @@ Generated {{DATE}} for: `{{AI_IDS}}`. Installed at `{{INSTALL_DIR}}`; the system
 | A local model runtime (if selected) | the privacy lane | nothing leaves the box |
 | Scheduled jobs (`jobs/`) | the weekly gap-analysis audit (lane: `{{AUDIT_LANE}}`), and anything else recurring | the gateway, or `cli-run` |
 | codecalc (if selected) | the calculator, code runner and logic checker every agent here calls; stdio, offline, no key | nothing; it computes locally |
+| context7 (if selected) | version-aware docs for the libraries the box's agents build against; paired with codecalc, docs then a run | the hosted endpoint over HTTPS (or a local `npx` server over stdio, still no cloud account required) |
 
 ## Setup, in order
 

package/templates/beginner/ORCHESTRATOR.md

@@ -46,9 +46,13 @@ Any figure someone will act on, any comparison you state, any complexity, equiva
 
 Anything durable is searched for before it is written, its folder index is corrected in the same pass, and one writer records. `protocols/memory-and-record.md`. Companion tool (optional, needs an Obsidian vault): obsidian-tc, {{OBSIDIAN_TC_STATUS}}.
 
-## The six protocols
+## Docs, then prove
 
-`protocols/build-protocol.md` · `protocols/propagate.md` · `protocols/gap-analysis.md` · `protocols/deep-research.md` · `protocols/numbers-and-logic.md` · `protocols/memory-and-record.md`. Each is a set of questions that can be answered wrong. That is the design, not a flaw.
+Before writing code against a library, SDK, API or CLI you have not confirmed the current shape of, pull current docs; then a run, not the doc, is what proves it behaves that way. `protocols/docs-then-prove.md`. Companion tool (optional, needs a network call): Context7, {{CONTEXT7_STATUS}}. Paired with codecalc, {{CODECALC_STATUS}}: docs say what it is supposed to do, codecalc's run says what it actually does.
+
+## The seven protocols
+
+`protocols/build-protocol.md` · `protocols/propagate.md` · `protocols/gap-analysis.md` · `protocols/deep-research.md` · `protocols/numbers-and-logic.md` · `protocols/memory-and-record.md` · `protocols/docs-then-prove.md`. Each is a set of questions that can be answered wrong. That is the design, not a flaw.
 
 ## When you outgrow this
 

package/templates/common/README.md

@@ -35,8 +35,10 @@ These are the same steps, in the same order, that the installer printed in your
 | `protocols/deep-research.md` | The source set is unknown, several sources must be reconciled, and the answer will be cited later. |
 | `protocols/numbers-and-logic.md` | You are about to state a number, a comparison, a complexity or an equivalence. Compute it. |
 | `protocols/memory-and-record.md` | You are about to write anything durable. Search first, keep the index true, one writer. |
+| `protocols/docs-then-prove.md` | You are about to write code against a library, SDK, API or CLI. Current docs first, then a run proves it. |
 | `CODECALC.md` | Present when you selected codecalc: install, per-agent registration, the skill. |
 | `OBSIDIAN-TC.md` | Present when you selected obsidian-tc: what you need first, install, per-agent registration, the security posture. |
+| `CONTEXT7.md` | Present when you selected context7: what you need first, install, per-agent registration, the security posture. |
 
 Level 2 adds `ROUTING.md`, `TIERS.md`, `DELEGATION_MATRIX.md`, `RESEARCH_TRIAGE.md`, `CLI-RUN.md` and `bin/cli-run.mjs`. Level 3 adds `vm/`. If those files are here, read `ROUTING.md` instead of `ORCHESTRATOR.md`: it is the multi-lane version, and the snippet your agent loads already points at it. `ORCHESTRATOR.md` stays as the single-agent fallback for a session where only one AI is available.
 

package/templates/common/protocols/README.md

@@ -1,6 +1,6 @@
 # protocols/
 
-Six procedures. Each one is a list of questions whose answers can be wrong.
+Seven procedures. Each one is a list of questions whose answers can be wrong.
 
 | File | Fires when | The gate |
 |---|---|---|
@@ -10,5 +10,6 @@ Six procedures. Each one is a list of questions whose answers can be wrong.
 | `deep-research.md` | The source set is unknown and the answer will be cited later | Parallel engines, then triage; disagreement is the signal |
 | `numbers-and-logic.md` | You are about to state a number, a comparison, a complexity, an equivalence | Computed by a tool (codecalc) or not stated |
 | `memory-and-record.md` | You are about to write anything durable | Searched first, indexed in the same pass, one writer (obsidian-tc when selected) |
+| `docs-then-prove.md` | You are about to write code against a library, SDK, API or CLI | Current docs first (Context7 when selected), then a run proves it; the run wins on disagreement |
 
 Not for lookups, prose edits, bulk classification or one-line config. Those get none of this.

package/templates/common/protocols/docs-then-prove.md

@@ -0,0 +1,26 @@
+# Docs, then prove: documentation is a lead, never a verdict
+
+**Why this is not `numbers-and-logic.md`.** That protocol is scoped to arithmetic, comparisons and complexity claims. This one is scoped to a different failure: trusting what a library, SDK, API or CLI is documented to do instead of checking what it actually does on this version, in this codebase. Two different mistakes, two different tools, one rule underneath both: a model that feels finished is not the same thing as a model that checked.
+
+Companion tool for this rule: **Context7** (Upstash), {{CONTEXT7_STATUS}}. It pairs with **codecalc**, {{CODECALC_STATUS}}: Context7 tells the agent what the library is SUPPOSED to do (current, version-aware docs); codecalc runs the code and proves what it actually does. Docs never stand as proof on their own, and where a doc and a run disagree, the run wins and the source settles it.
+
+## When calling is mandatory
+
+| You are about to | Use |
+|---|---|
+| write code against a library, SDK, API or CLI you have not confirmed the current signature for | Context7 (`resolve-library-id` then `query-docs`, or `ctx7 library` / `ctx7 docs`), then write the call |
+| claim a documented behaviour is what the code actually does | run it (`execute_code`, the project's own test suite, or a REPL), never the doc alone |
+| a doc and a run disagree | the run wins. Say so, and say what the doc got wrong (a stale version, a changed default, a deprecated flag) |
+| training-data recall of a library's API surface, with no source open | treat it as a guess until a doc or a run confirms it; version drift and renamed APIs are the common failure, not a rare one |
+
+Trivial, unversioned standard-library calls you would bet the build on are exempt. Anything with a version number attached to its behaviour is not.
+
+## How to report a documentation-derived claim
+
+Name the library, the version if Context7 returned one, and that it came from docs, not a run: "per Context7, `/vercel/next.js@14.0.0`'s middleware API takes X" reads differently from "Next.js middleware takes X", because the first can be checked against a version and the second cannot. If the claim was then verified by running it, say that too, and which one actually settled the question.
+
+## Without Context7
+
+The rule still binds. Read the vendor's own README, changelog or source before writing code against it, the same way this repository's own `AGENTS.md` asks: read the actual API, not a recollection of it. What is not allowed is code written against a remembered shape of a library that was never opened this session.
+
+Source: https://github.com/upstash/context7

package/templates/intermediate/ROUTING.md

@@ -54,6 +54,10 @@ Every number, comparison, complexity or equivalence claim goes through a tool th
 
 One writer per run; every other lane proposes. Search before writing, index in the same pass (`protocols/memory-and-record.md`; companion, optional: obsidian-tc, {{OBSIDIAN_TC_STATUS}}).
 
+## Docs, then prove
+
+A lane's recall of a library's API is a lead, not a verdict, the same as its arithmetic. Pull current, version-specific docs before writing a call against anything you have not confirmed this session (`protocols/docs-then-prove.md`; companion, optional: Context7, {{CONTEXT7_STATUS}}). Then prove the doc was right by running it, the same tool that already owns numbers: codecalc, {{CODECALC_STATUS}}. Where the two disagree, the run wins.
+
 ## Modifier rules
 
 {{PLAN_BIG_LINE}}{{INLINE_THRESHOLD_NOTE}}

package/templates/tools/README.md

@@ -6,5 +6,6 @@ Companion tools: not AIs, but things the AIs call. Each subfolder is written onl
 |---|---|---|
 | `codecalc/` | when codecalc is selected (recommended, default yes) | `CODECALC.md` (install, per-client registration, the skill) and `mcp/` snippets for the agents its own `setup --write` does not cover |
 | `obsidian-tc/` | when obsidian-tc is selected (optional, default no; needs an Obsidian vault, Node 24+, Ollama or a cloud embeddings key) | `OBSIDIAN-TC.md` (what you need first, install, per-agent registration, security posture) and `mcp/` snippets |
+| `context7/` | when context7 is selected (optional, default no; needs a network call, a Node 18+ local alternative, an optional API key) | `CONTEXT7.md` (what you need first, install, per-agent registration, security posture) and `mcp/` snippets |
 
-The rules the tools serve, `protocols/numbers-and-logic.md` and `protocols/memory-and-record.md`, are in `common/` and are written at every level whether or not a tool was selected: the rule binds, the tool makes it cheap to follow. `src/install.js` writes `templates/tools/<id>/` for every selected tool that has a folder here.
+The rules the tools serve, `protocols/numbers-and-logic.md`, `protocols/memory-and-record.md` and `protocols/docs-then-prove.md`, are in `common/` and are written at every level whether or not a tool was selected: the rule binds, the tool makes it cheap to follow. `src/install.js` writes `templates/tools/<id>/` for every selected tool that has a folder here.

package/templates/tools/context7/CONTEXT7.md

@@ -0,0 +1,94 @@
+# Context7: version-aware docs for your agent (optional)
+
+Repo: https://github.com/upstash/context7 · Upstash · MIT · hosted MCP server, or run it yourself with `npx`
+
+**Optional.** Skip this if your agent already opens the real source or docs of anything it calls before writing code against it. The rule it serves, `protocols/docs-then-prove.md`, binds either way.
+
+**Paired with codecalc, not a replacement for it.** Context7 answers "what is this library documented to do, on this version": current docs and code examples, pulled straight into the prompt. codecalc answers "what does this code actually do": it runs the thing. A doc can be stale, a version can drift, a default can change between releases; only a run proves current behaviour. Where the two disagree, the run wins and the source settles it.
+
+## What it gives every agent in this folder
+
+| Need in the protocol | Context7 tool |
+|---|---|
+| find the Context7 id for a library, SDK, API or CLI by name | `resolve-library-id` (MCP) or `ctx7 library <name> <query>` (CLI) |
+| pull current, version-specific docs and code examples before writing a call | `query-docs` (MCP, needs a library id) or `ctx7 docs <libraryId> <query>` (CLI) |
+| skip the library-matching step when you already know the exact package | address it directly, `/org/project` (e.g. `/vercel/next.js`), optionally with `@version` |
+
+Context7 indexes documentation from GitHub, GitLab, Bitbucket, websites, `llms.txt` files, OpenAPI specs and Confluence spaces. It is community-contributed: the upstream disclaimer says it cannot guarantee every project's docs are accurate, complete or current, which is exactly why `protocols/docs-then-prove.md` treats a Context7 answer as a lead codecalc (or your own test run) still has to confirm, never as a verdict.
+
+## What you need first
+
+| Requirement | Why | Notes |
+|---|---|---|
+| **Node.js 18+** | runs the local server or the `ctx7` CLI | only needed for the local (`npx`) connection; the hosted endpoint needs nothing local at all |
+| **A network call to `mcp.context7.com`** | Context7 is a hosted service; there is no fully offline mode | the anonymous rate limit works with no account. Unlike codecalc (offline) and obsidian-tc (local), this tool always leaves the machine |
+| A free **`CONTEXT7_API_KEY`** (optional) | raises the anonymous rate limit | get one at [context7.com/dashboard](https://context7.com/dashboard); it is never pasted into a snippet in `mcp/` (see "Higher rate limits" below) |
+
+## Install
+
+Two ways to connect, remote first (Context7's own documented default, and the one that needs nothing installed). Both connect keyless, at the anonymous rate limit, which is enough to try it:
+
+```bash
+# Remote (recommended): no install. Point your MCP client at the hosted endpoint,
+# https://mcp.context7.com/mcp. No key needed: anonymous requests work at a
+# lower rate limit. OAuth is available where your client supports it
+# (mcp.context7.com/mcp/oauth), as an alternative to an API key, not required either.
+
+# Local alternative: runs the MCP server on your machine over stdio.
+npx -y @upstash/context7-mcp
+
+# Or the one-command setup Context7 itself ships, which authenticates via OAuth,
+# writes an API key, and can install a CLI-based skill instead of MCP:
+npx ctx7 setup
+```
+
+Pinned form, if you want the version this installer was released against: `npx -y @upstash/context7-mcp@{{CONTEXT7_PIN}}`. Drop the pin for latest; `npx` always resolves fresh, so pinning only matters when you want a reproducible version rather than whatever shipped this week.
+
+`npx ctx7 setup` is upstream's own guided installer; it is not run by this installer, only documented here, the same way this project never runs a vendor script for you.
+
+## Register it with your agent (snippets in `mcp/`)
+
+Every snippet below ships **keyless**: the remote ones point at the hosted endpoint with no `Authorization` header at all (Qwen Code's snippet keeps the non-credential `Accept` header upstream itself ships), and the two Zed snippets (one per OS) run the local, version-pinned `npx` server with no key in its `env` block. That is deliberate, not an oversight: see "Higher rate limits" next for why a header is not shipped by default.
+
+| Agent | File to edit | Snippet |
+|---|---|---|
+| Claude Code | its MCP config (`.mcp.json`); needs `"type": "http"` next to `url` or Claude Code skips the server as misconfigured | `mcp/context7.claude-code.mcp.json` |
+| Claude Desktop | no config file: `Settings > Connectors > Add Custom Connector`, name `Context7`, URL `https://mcp.context7.com/mcp` | none, it is a UI step |
+| Cursor | one-click install in the upstream README, or `~/.cursor/mcp.json` | `mcp/context7.mcpServers.json` |
+| VS Code | `.vscode/mcp.json` (key is `servers`, remote type is `http`) | `mcp/context7.vscode.mcp.json` |
+| Zed | `~/.config/zed/settings.json` (key is `context_servers`); upstream ships only a local (`npx`) config for Zed, so this snippet runs the server locally rather than remote. **Windows: use the `.windows` snippet**, see "Local `npx` on Windows" below | macOS/Linux: `mcp/context7.zed.settings.json` · Windows: `mcp/context7.zed.windows.settings.json` |
+| Codex CLI | `~/.codex/config.toml` | `mcp/context7.codex.config.toml` |
+| Antigravity `agy` | its MCP config file | `mcp/context7.agy.mcp_config.json` |
+| Qwen Code | `~/.qwen/settings.json` under `mcpServers`; note the field is `httpUrl`, not `url`, a different shape from every other client here | `mcp/context7.qwen.settings.json` |
+
+### Local `npx` on Windows
+
+On Windows `npx` is a batch file (`npx.cmd`), and a client that spawns `"command": "npx"` directly fails to start it. Context7's own client guide says to wrap it in `cmd` on Windows ([all clients, Windows section](https://context7.com/docs/resources/all-clients)). This only affects the local form: every remote snippet above connects over HTTPS and spawns nothing.
+
+| Where | Use |
+|---|---|
+| Zed on macOS or Linux | `mcp/context7.zed.settings.json` (`"command": "npx"`) |
+| Zed on Windows | `mcp/context7.zed.windows.settings.json` (`"command": "cmd"`, `"args": ["/c", "npx", ...]`) |
+| Any other client, local alternative, on Windows | the same change by hand: `"command": "cmd"` and put `"/c", "npx"` in front of the existing args, e.g. `"args": ["/c", "npx", "-y", "@upstash/context7-mcp@{{CONTEXT7_PIN}}"]` |
+
+Not yet run on a Windows machine by this project; the shape is the vendor's own.
+
+Merge the block; do not replace the file. `mcp/context7.mcpServers.json` (Cursor) and `mcp/context7.claude-code.mcp.json` look alike but are not interchangeable: Claude Code requires the `"type": "http"` field and Cursor's own docs show plain `{"url": ...}` with no `type` at all.
+
+## Higher rate limits (optional key)
+
+Anonymous works. If you hit the rate limit and want a key, add it the correct way for your client, and never as a literal value pasted into any of the snippets above:
+
+- **Codex CLI**: under the `[mcp_servers.context7]` table in `~/.codex/config.toml`, add a `bearer_token_env_var` entry naming the environment variable `CONTEXT7_API_KEY`. Codex reads the token from that variable at connect time and sends it as the `Authorization` header itself; the config file never holds the value ([Codex MCP docs](https://developers.openai.com/codex/mcp)).
+- **Claude Code** (`mcp/context7.claude-code.mcp.json`): add a `headers` object to the `context7` entry with an `Authorization` field whose value is `Bearer` followed by a `${CONTEXT7_API_KEY}` reference. Claude Code expands `${VAR}` references in a remote server's `headers` at load time, and `CONTEXT7_API_KEY` is not one of the credential names it deliberately reads as empty (those are Claude/Anthropic-specific). Set the variable in your environment before launching; an unset variable still loads with the literal, unexpanded reference sent as the header, and Context7 answers every call with "Invalid API key" instead of running anonymously ([Claude Code MCP docs](https://code.claude.com/docs/en/mcp)). That failure, not a missing feature, is why this snippet ships with no header at all.
+- **Claude Desktop**: the Connectors UI has its own key field; use it there rather than editing a file.
+- **Any local `npx` connection** (Zed, or the local alternative for any other client): export `CONTEXT7_API_KEY` in the shell that launches your editor or agent. A spawned stdio child process inherits its parent's environment by default, so `npx -y @upstash/context7-mcp` picks it up with no config edit; this is the same environment variable name Context7's own Docker MCP Toolkit config and its GitHub Copilot integration use to feed the server a key. If your client does not pass its environment through to the child (uncommon), either stay anonymous, or check whether that client's own config format has an `env` block that itself supports an environment-variable reference (Claude Code's does, described above; not every client's does) rather than typing the key in.
+- **Cursor, VS Code, Qwen Code, Antigravity `agy`, or any other client using the `mcpServers.json`/`vscode.mcp.json`/`qwen.settings.json`/`agy.mcp_config.json` snippet**: check that client's own docs for whether it expands an environment-variable reference inside a remote server's `headers` before adding one. This is not confirmed for any of them here. If it does not expand, the literal, unexpanded text becomes the header value and every call fails with "Invalid API key" instead of running anonymously, which is worse than shipping no header at all.
+
+## Security posture, read before you send anything through it
+
+Only the library name and your query text reach Context7's API; your source code is never uploaded. It is still a third-party network call on every lookup, unlike codecalc (offline) and obsidian-tc (local by default): do not route a query that would leak a private project name, an internal library name, or anything else you would not put in a public search box. The docs it indexes are community-contributed, not vetted by Context7 or by this installer; a suspicious or malicious-looking result is reportable upstream from the project's page. An API key raises your rate limit; it is not a secret worth protecting the way a database credential is, but it still never belongs in a committed file, only in your environment.
+
+## Level 3
+
+Runs the same way at any level: the remote endpoint over HTTPS, or the local `npx` server over stdio next to the orchestrator CLI on the box. Nothing about it changes on a box except that the box, not your laptop, is the machine making the network call.

package/templates/tools/context7/mcp/context7.agy.mcp_config.json

@@ -0,0 +1,7 @@
+{
+  "mcpServers": {
+    "context7": {
+      "serverUrl": "https://mcp.context7.com/mcp"
+    }
+  }
+}

package/templates/tools/context7/mcp/context7.claude-code.mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "context7": {
+      "type": "http",
+      "url": "https://mcp.context7.com/mcp"
+    }
+  }
+}

package/templates/tools/context7/mcp/context7.codex.config.toml

@@ -0,0 +1,3 @@
+# Merge into ~/.codex/config.toml
+[mcp_servers.context7]
+url = "https://mcp.context7.com/mcp"

package/templates/tools/context7/mcp/context7.mcpServers.json

@@ -0,0 +1,7 @@
+{
+  "mcpServers": {
+    "context7": {
+      "url": "https://mcp.context7.com/mcp"
+    }
+  }
+}

package/templates/tools/context7/mcp/context7.qwen.settings.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "context7": {
+      "httpUrl": "https://mcp.context7.com/mcp",
+      "headers": { "Accept": "application/json, text/event-stream" }
+    }
+  }
+}

package/templates/tools/context7/mcp/context7.vscode.mcp.json

@@ -0,0 +1,8 @@
+{
+  "servers": {
+    "context7": {
+      "type": "http",
+      "url": "https://mcp.context7.com/mcp"
+    }
+  }
+}

package/templates/tools/context7/mcp/context7.zed.settings.json

@@ -0,0 +1,9 @@
+{
+  "context_servers": {
+    "Context7": {
+      "source": "custom",
+      "command": "npx",
+      "args": ["-y", "@upstash/context7-mcp@{{CONTEXT7_PIN}}"]
+    }
+  }
+}

package/templates/tools/context7/mcp/context7.zed.windows.settings.json

@@ -0,0 +1,9 @@
+{
+  "context_servers": {
+    "Context7": {
+      "source": "custom",
+      "command": "cmd",
+      "args": ["/c", "npx", "-y", "@upstash/context7-mcp@{{CONTEXT7_PIN}}"]
+    }
+  }
+}