model-orchestrator 0.1.10 → 0.1.12

package/CHANGELOG.md

@@ -4,6 +4,31 @@ All notable changes to this project are documented here. The format follows [Kee
 
 ## [Unreleased]
 
+## [0.1.12] - 2026-09-08
+
+Five issues from one first-run walkthrough of 0.1.11 (#20 to #24). Every one of them is the same failure: a page describing an install that did not happen. Each fix removes the second copy of a fact rather than correcting it.
+
+### Fixed
+
+- **The generated README no longer describes a different install from the one the terminal just printed** (#20). The activation list existed twice: once as an array built in `bin/cli.js`, once as prose in `templates/common/README.md` that assumed a chat app. A level 2 Claude Code install was told, on the page it was pointed at, to paste `PASTE-INTO-YOUR-AGENT.md`, a file that run never wrote, and a level 1 chat install was told its rules file was `your agent's instructions file`, a leftover placeholder. `activationSteps()` and `snippetFor()` now live in `src/install.js` and both surfaces render the same array, so the page can only ever name the file that was written. A test renders every level against every possible primary and fails if the README omits a printed step or names any other agent's snippet.
+- **A chat install no longer claims a project root it never created** (#21). Level 1 with a chat app writes no project files, and the README still printed `--project` as "where your agent reads rules and subagents" next to "subagent definitions: none". It now says there is no project root and why. A CLI primary that reads a rules file but gets no subagent folder (codex, qwen) keeps its project path and gains the missing half: whether this run created that folder.
+- **The chat activation line is a sentence again** (#22). It read `paste ... into Claude app or claude.ai (chat only, no CLI)'s custom instructions or Project`: the catalog's disambiguating note sat inside a possessive. Chat entries in the catalog now carry `chatName` and `chatSurface`, and the line reads `open the Claude app or claude.ai and paste the block in <path> into its custom instructions or a Project`. The catalog note stays where it is useful, in the picker list.
+- **"Built against" and "pinned to" are one number per lane, by construction** (#23). The README's compatibility table was hand-written and the installer's npm pins were edited separately, so a user comparing them found claude at 2.1.226 and 2.1.260, codex at 0.153.4 and 0.153.2, with no rule for which to trust. `builtAgainst` in `src/catalog.js` is now the single source: `npm run gen:catalog` renders the README table from it, the npm pin **is** that value wherever a lane installs from npm, and the tests fail if the table drifts, if a pin disagrees with its `builtAgainst`, or if a recorded fixture's vendor version disagrees with either. The pins moved to the exercised versions rather than the table moving to the pins, because the exercised version is the one with evidence behind it.
+- **The README stops pinning a release tag the registry has moved past** (#23). The GitHub one-liner still said `#v0.1.7` while npm served 0.1.11. It now points at main, says where the tags are, and a test fails on any `#vX.Y.Z` in the README that is not this package's own version.
+- **The documented example sets both write targets** (#24). The first non-interactive example set `--dir` and left `--project` at the current directory, so a copied command run from a home folder dropped five agent files into it. Both flags are now set in the example, a table explains what lands where and why `--dir` defaults to a folder named for its contents, and the installer prints a line when `--project` was left at the default and subagent files are going there. A test fails on any documented `--yes` example that sets one target and not the other.
+- **Privacy describes what actually runs** (#24). It claimed the only network step was an `npm install -g` you approve, when the thing the user runs is `npx` (a download in itself) and the installer under `--yes` prints vendor install commands without running them. Both are now stated, along with `--yes` selecting the recommended companion tool unless `--no-tools` is passed.
+
+### Changed
+
+- Vendor CLI pins move to the versions this release was exercised against: `@anthropic-ai/claude-code@2.1.226`, `@openai/codex@0.153.4`, `@qwen-code/qwen-code@0.22.3`. A pin is a floor, not a ceiling: newer versions may work, and the table exists so a lane that breaks after a vendor upgrade has something to compare against.
+- `npm run gen:catalog` now regenerates two surfaces, `docs/catalog.md` and the README vendor table between its `vendor-table` markers.
+
+## [0.1.11] - 2026-09-07
+
+### Fixed
+
+- **The cost claim the audit rejected was still live in three places outside the README.** #11 asked for the opening promise to be narrowed, and 0.1.2 narrowed it in `README.md` only. "Route every task to the cheapest AI that does it well" survived in `package.json`'s `description`, which is what **npm search results show**, in the repository's GitHub description, which is what **GitHub search shows**, and in the installer's own banner, printed to **every user on every run**. All three now say what the package generates instead of what it guarantees: "Routing instructions and a CLI runner for your AI tools." The cheapest-capable-lane *guidance* in the docs and templates is untouched; that is the product's advice, not a promise about what the code enforces.
+
 ## [0.1.10] - 2026-09-07
 
 Closes the last two verification items on #11. Both had been described as needing vendor sign-ins or infrastructure that was not available. Both turned out to be doable with what was already here, and doing them found a real defect.
@@ -160,7 +185,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.7...HEAD
+[Unreleased]: https://github.com/aunysillyme/model-orchestrator/compare/v0.1.12...HEAD
+[0.1.12]: https://github.com/aunysillyme/model-orchestrator/compare/v0.1.11...v0.1.12
+[0.1.11]: https://github.com/aunysillyme/model-orchestrator/compare/v0.1.10...v0.1.11
 [0.1.10]: https://github.com/aunysillyme/model-orchestrator/compare/v0.1.9...v0.1.10
 [0.1.9]: https://github.com/aunysillyme/model-orchestrator/compare/v0.1.8...v0.1.9
 [0.1.8]: https://github.com/aunysillyme/model-orchestrator/compare/v0.1.7...v0.1.8

package/README.md

@@ -10,7 +10,7 @@ Built from a working system, not a diagram: the routing rules, the protocols and
 npx model-orchestrator
 ```
 
-That runs the latest published release from the npm registry. To run a specific release or the current main straight from GitHub: `npx github:aunysillyme/model-orchestrator#v0.1.7` (drop `#v0.1.7` for main).
+That runs the latest published release from the npm registry, and `npx model-orchestrator --version` prints which one you got. To run the current main straight from GitHub instead: `npx github:aunysillyme/model-orchestrator`. Add `#vX.Y.Z` for one specific release; the tags are on the [releases page](https://github.com/aunysillyme/model-orchestrator/releases), so this page never pins a number the registry has moved past.
 
 The installer asks a few things, then writes a folder:
 
@@ -56,13 +56,29 @@ An orchestrator routes work. It does not make a model stop guessing numbers, and
 
 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).
 
+## The two folders every run writes to
+
+An install has two targets, and a scripted run should set both.
+
+| Flag | Default | What lands there |
+|---|---|---|
+| `--dir` | `./ai-orchestrator` | the docs, protocols and (level 2+) `bin/cli-run.mjs`. Named after what it contains, not after this package, so a project can hold one without looking like a checkout of it. Pass `--dir ./model-orchestrator` if you prefer the package name. |
+| `--project` | the current directory | the subagent definitions, and the rules file your agent reads. Only Claude Code (`.claude/agents/`) and Antigravity (`.agents/agents/`) get files here, because that is the only place those CLIs look. |
+
+`--project` defaulting to the current directory is the one that surprises people: run the command from your home folder with Claude Code as the primary and five agent files land in your home folder. The installer prints the resolved project path in the plan and says when you left it at the default. Set it.
+
 ## Non-interactive
 
 ```bash
-npx model-orchestrator --yes --level 2 --ais claude-code,codex,grok --primary claude-code --dir ./ai-orchestrator
+# both targets set: docs in ./ai-orchestrator, subagents into ./my-app/.claude/agents
+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.
+
 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  # subagents into ~/my-app/.claude/agents
-npx model-orchestrator --yes --level 2 --ais claude-code,codex,grok --primary claude-code --update-docs   # added a lane: regenerate the docs you never edited
+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
+npx model-orchestrator --yes --level 2 --ais claude-code,codex,grok --primary claude-code --dir ./ai-orchestrator --project . --update-docs   # added a lane: regenerate the docs you never edited
 ```
 
 ## What gets written (level 3, everything)
@@ -114,17 +130,23 @@ If you need a property in the third row to be enforced, that is a router, a poli
 
 The lane wiring and the output judges were written against these versions, which are the ones this release was exercised on:
 
-| Lane | Vendor | Version this release was built against |
-|---|---|---|
-| `claude` | Anthropic | 2.1.226 |
-| `codex` | OpenAI | codex-cli 0.153.4 |
-| `agy` | Google | 1.1.27 |
-| `grok` | xAI | 1.0.5 |
-| `hermes` | Nous Research | 0.20.0 |
-| `qwen` | Alibaba | 0.22.3 |
-| `ollama` | local | 0.33.3 |
+<!-- vendor-table:start -->
 
-Recorded on 2026-09-06 from the maintainer's own installs, by running each CLI's own version flag. Nothing here is pinned: these CLIs ship breaking flag changes on their own schedules, so a newer version may work perfectly, or may change a flag the generated wiring passes. When a lane starts failing after a vendor upgrade, compare against this table first.
+| Lane | Vendor | Version this release was built against | Where that number is proved |
+|---|---|---|---|
+| `claude` | Anthropic | 2.1.226 | the npm pin the installer writes, `@anthropic-ai/claude-code@2.1.226` |
+| `codex` | OpenAI | 0.153.4 | `test/fixtures/codex-0.153.4.jsonl`, a recorded run |
+| `agy` | Google | 1.1.27 | `test/fixtures/agy-1.1.27.jsonl`, a recorded run |
+| `grok` | xAI | 1.0.5 | `test/fixtures/grok-1.0.5.json`, a recorded run |
+| `hermes` | Nous Research | 0.20.0 | `test/fixtures/hermes-0.20.0.txt`, a recorded run |
+| `qwen` | Alibaba | 0.22.3 | `test/fixtures/qwen-0.22.3-nokey.json`, a recorded run |
+| `ollama` | Ollama | 0.33.3 | the pinned image the level 3 box runs, `ollama/ollama:0.33.3` |
+
+Generated from `src/catalog.js` by `npm run gen:catalog`; `npm test` fails if this table and the catalog disagree. Fixtures were captured 2026-09-06.
+
+<!-- vendor-table:end -->
+
+One number per lane, and it is the same number the installer pins: where a lane installs from npm, `builtAgainst` in the catalog *is* the pin, so "built against" and "pinned to" can never be two answers. That pin is a floor, not a ceiling: these CLIs ship breaking flag changes on their own schedules, so a newer version may work perfectly, or may change a flag the generated wiring passes. When a lane starts failing after a vendor upgrade, compare against this table first.
 
 **The live canary runs on your machine, with your credentials.** That is what `node bin/cli-run.mjs --doctor --run` is: it sends every enabled lane one tiny prompt through your own sign-ins and reports `canary ok` or `canary FAILED rc=` per lane. Run it after install, and again after any vendor upgrade.
 
@@ -144,7 +166,12 @@ It deliberately does not run in this repository's CI. A canary is only meaningfu
 
 Node 18 or newer. No dependencies. Works on macOS and Linux; the level 3 box templates assume Ubuntu. Windows is untested: `cli-run` ends a lane's process tree there with `taskkill`, but nothing in CI runs on Windows, so treat it as unsupported until someone reports otherwise.
 
-**Privacy.** The installer makes no network call of its own and sends no telemetry; the only network activity is the `npm install -g` you approve per package. `cli-run` talks to nothing but the vendor CLI you name.
+**Privacy.** The installer sends no telemetry and makes no network call of its own once it is running. Two things around that are worth being exact about:
+
+- `npx model-orchestrator` is itself a download: npm fetches this package from the registry before any of it runs. `npm install -g model-orchestrator` once, then run `model-orchestrator`, if you would rather that happen exactly one time.
+- A missing vendor CLI is *printed*, not installed. In an interactive run the installer offers to run one pinned `npm install -g` per package and only runs the ones you answer yes to; with `--yes` or `--no-install` it answers no for you and prints the command instead. Vendor shell installers (Antigravity, Grok) are only ever printed, alongside the `curl … | less` you would use to read one before running it.
+
+`cli-run` talks to nothing but the vendor CLI you name.
 
 ## Contributing
 

package/bin/cli.js

@@ -10,7 +10,7 @@ import { spawnSync } from 'node:child_process';
 import { resolve, join } from 'node:path';
 import { which } from '../src/detect.js';
 import { AIS, LEVELS, TOOLS, PROVIDERS, aisForLevel, agentCandidates, byId, npmSpec } from '../src/catalog.js';
-import { planFiles, writeFiles, resolveSelection, resolveTools, resolveApis, dirProblems, readManifest, MACHINE_OWNED, RUNTIME, GENERATOR_VERSION } from '../src/install.js';
+import { planFiles, writeFiles, resolveSelection, resolveTools, resolveApis, dirProblems, readManifest, activationSteps, MACHINE_OWNED, RUNTIME, GENERATOR_VERSION } from '../src/install.js';
 
 // One strict parse. Unknown flags, missing values and duplicates are usage
 // errors (exit 2) before anything is planned, so a typo like --dryy can never
@@ -88,7 +88,7 @@ if (flag('help') || flag('h')) {
 Usage
   npx model-orchestrator                      interactive
   npx model-orchestrator --list               show the AI catalog and exit
-  npx model-orchestrator --yes --level 2 --ais claude-code,codex,grok [--primary claude-code] [--dir ./ai-orchestrator]
+  npx model-orchestrator --yes --level 2 --ais claude-code,codex,grok [--primary claude-code] [--dir ./ai-orchestrator] [--project .]
 
 Flags
   --level 1|2|3      1 beginner (one agent), 2 intermediate (many CLIs), 3 advanced (plus a VM)
@@ -98,7 +98,8 @@ Flags
   --apis a,b         level 3 only: metered API keys you HOLD (anthropic,openai,google,xai,openrouter); --no-apis for none.
                      Asked separately from the CLIs because a subscription is not an API key.
   --dir path         where to write the docs and protocols (default ./ai-orchestrator)
-  --project path     the project root your agent runs from; subagent definitions go here (default: current directory)
+  --project path     the project root your agent runs from; subagent definitions go here (default: current directory,
+                     so set it: a run from your home folder otherwise drops the subagent files there)
   --yes              skip confirmations
   --force            overwrite every file that already exists, documents included
   --upgrade-runtime  replace the runtime files (cli-run, the audit job, compose, gateway config, setup script) even
@@ -139,7 +140,10 @@ function bad(msg) {
 }
 
 async function main() {
-  console.log('\nmodel-orchestrator\nRoute every task to the cheapest AI that does it well.\n');
+  // Says what this generates, not what it guarantees. The old line promised
+  // routing this package does not perform: lane choice is an instruction an
+  // agent follows, never something enforced here (#11).
+  console.log('\nmodel-orchestrator\nRouting instructions and a CLI runner for the AIs you actually have.\n');
 
   // 1. Level
   let level = Number(opt('level'));
@@ -268,6 +272,9 @@ async function main() {
   const lvl = LEVELS.find((l) => l.id === level);
   const agentFiles = files.filter((f) => f.root === 'project');
   console.log(`\nPlan\n  level    ${lvl.id} ${lvl.name}\n  access   ${selected.map((a) => a.id).join(', ')}\n  primary  ${primary ? primary.id : 'none'}\n  tools    ${tools.map((t) => t.id).join(', ') || 'none'}` + (level >= 3 ? `\n  api keys ${apis.map((p) => p.id).join(', ') || 'none'}` : '') + `\n  folder   ${dir}\n  project  ${project}${agentFiles.length ? ' (' + agentFiles.length + ' subagent files go here)' : ''}\n  files    ${files.length}`);
+  if (agentFiles.length && !opt('project')) {
+    console.log(`\nNote: --project was not given, so the ${agentFiles.length} subagent file(s) go to the current directory (${project}). Pass --project to put them somewhere else.`);
+  }
   if (level >= 2 && !selected.some((a) => a.cliRun)) {
     console.log('\nWarning: no executable lanes selected; delegation is inactive. Use level 1 for a single-agent setup, or add a supported CLI. Doctor will exit 13 until a lane is enabled.');
   }
@@ -362,16 +369,9 @@ async function main() {
   }
 
   // 7. Activation summary: writing the folder is half the job. Say exactly what
-  // turns it on, in order, with one command that proves it.
-  const snippet = files.find((f) => /\.snippet\.md$|^PASTE-INTO-YOUR-AGENT\.md$/.test(f.rel));
-  const steps = [];
-  if (snippet && primary && primary.rulesFile) steps.push(`copy the block in ${join(dir, snippet.rel)} into ${join(project, primary.rulesFile)} (create it if missing)`);
-  else if (snippet) steps.push(`paste ${join(dir, snippet.rel)} into ${primary.name}'s custom instructions or Project`);
-  if (primary && primary.agentsDir) steps.push(`subagents are in ${join(project, primary.agentsDir)}; run ${primary.bin} from ${project} to pick them up`);
-  for (const a of selected.filter((a) => a.bin && a.kind === 'agent-cli')) steps.push(`sign in to ${a.name}: ${a.auth}`);
-  for (const t of tools) steps.push(`${t.id}: ${t.install}`);
-  if (level >= 2) steps.push(`smoke test: node ${join(dir, 'bin', 'cli-run.mjs')} --doctor   (add --run to send each lane one tiny prompt)`);
-  if (level >= 3) steps.push(`box: read ${join(dir, 'vm', 'README.md')}; keys named in vm/ENVIRONMENT.md go in your secrets manager, never a file`);
+  // turns it on, in order, with one command that proves it. The generated
+  // README renders this same array, so the two surfaces cannot disagree (#20).
+  const steps = activationSteps({ level, selected, primary, tools, dir, project });
   console.log('\nTo activate, in order:');
   steps.forEach((st, i) => console.log(`  ${i + 1}. ${st}`));
   console.log(`\nStart here: ${join(dir, 'README.md')} (written for level ${level} and the AIs you picked).`);

package/docs/catalog.md

@@ -16,18 +16,20 @@ Generated from `src/catalog.js`. Do not hand-edit; `npm run gen:catalog` rewrite
 
 - **Kind:** agent-cli · **Access:** subscription · **Lane:** A · **Level:** 1+
 - **Wins at:** orchestrator: routes, maps, builds, verifies, records
-- **Install:** `npm install -g @anthropic-ai/claude-code@2.1.260`
+- **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/`
+- **Built against:** 2.1.226 (the same number the npm pin uses)
 
 ### `codex` · Codex CLI (OpenAI, ChatGPT plan)
 
 - **Kind:** agent-cli · **Access:** subscription · **Lane:** A · **Level:** 1+
 - **Wins at:** second coder and adversarial auditor (a different model family reading your diff)
-- **Install:** `npm install -g @openai/codex@0.153.2`
+- **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
+- **Built against:** 0.153.4 (the same number the npm pin uses)
 
 ### `agy` · Antigravity CLI `agy` (Google AI plan)
 
@@ -37,6 +39,7 @@ Generated from `src/catalog.js`. Do not hand-edit; `npm run gen:catalog` rewrite
 - **Sign in:** 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
+- **Built against:** 1.1.27
 - **Note:** Gemini CLI was retired by Google in June 2026. agy is the successor. Do not install `gemini`.
 
 ### `grok` · Grok CLI (xAI, X Premium)
@@ -46,6 +49,7 @@ Generated from `src/catalog.js`. Do not hand-edit; `npm run gen:catalog` rewrite
 - **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
+- **Built against:** 1.0.5
 
 ### `hermes` · Hermes Agent (Nous Research)
 
@@ -54,15 +58,17 @@ Generated from `src/catalog.js`. Do not hand-edit; `npm run gen:catalog` rewrite
 - **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
 
 ### `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
-- **Install:** `npm install -g @qwen-code/qwen-code@0.23.0`
+- **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.
 - **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.
 
 ### `ollama` · Ollama (local models)
@@ -71,6 +77,7 @@ Generated from `src/catalog.js`. Do not hand-edit; `npm run gen:catalog` rewrite
 - **Wins at:** the privacy lane: anything that must never leave the machine. Not a cost lane.
 - **Install:** https://ollama.com/download (or `brew install ollama`)
 - **Sign in:** none
+- **Built against:** 0.33.3
 
 ### `claude-app` · Claude app or claude.ai (chat only, no CLI)
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "model-orchestrator",
-  "version": "0.1.10",
-  "description": "A model orchestrator you can npm run: route every task to the cheapest AI that does it well, across one agent, many CLIs, or a whole virtual machine. Three levels, one installer that asks what you have access to.",
+  "version": "0.1.12",
+  "description": "Routing instructions and a CLI runner for your AI tools. One installer asks what you have access to and generates a matching setup, from one chat app to several agent CLIs or a virtual machine.",
   "type": "module",
   "bin": {
     "model-orchestrator": "bin/cli.js"
@@ -46,7 +46,12 @@
     "ollama",
     "litellm",
     "multi-agent",
-    "cli"
+    "cli",
+    "llm",
+    "agents",
+    "subagents",
+    "qwen",
+    "mcp"
   ],
   "author": "aunysillyme (https://github.com/aunysillyme)",
   "license": "MIT"

package/scripts/README.md

@@ -2,4 +2,4 @@
 
 | File | Job |
 |---|---|
-| `gen-catalog.js` | regenerates `docs/catalog.md` from `src/catalog.js`; `npm run gen:catalog`. `test/catalog.test.js` fails if the two disagree. |
+| `gen-catalog.js` | regenerates `docs/catalog.md` AND the vendor compatibility table in `README.md` (between the `vendor-table` markers) from `src/catalog.js`; `npm run gen:catalog`. `test/catalog.test.js` fails if either generated surface disagrees with the catalog. |

package/scripts/gen-catalog.js

@@ -1,7 +1,8 @@
 #!/usr/bin/env node
-// Regenerates docs/catalog.md from src/catalog.js. The test suite checks they agree.
-import { writeFileSync } from 'node:fs';
-import { AIS, LEVELS, TOOLS, npmSpec } from '../src/catalog.js';
+// Regenerates docs/catalog.md and the README's vendor compatibility table from
+// src/catalog.js. The test suite checks they agree, so neither can drift (#23).
+import { writeFileSync, readFileSync } from 'node:fs';
+import { AIS, LEVELS, TOOLS, IMAGES, npmSpec } from '../src/catalog.js';
 import { readdirSync } from 'node:fs';
 
 export function protocolCount() {
@@ -21,6 +22,7 @@ export function catalogMarkdown() {
     md += `### \`${a.id}\` · ${a.name}\n\n- **Kind:** ${a.kind} · **Access:** ${a.access} · **Lane:** ${a.lane} · **Level:** ${a.minLevel}+\n- **Wins at:** ${a.role}\n- **Install:** ${how}\n- **Sign in:** ${a.auth}\n`;
     if (a.rulesFile) md += `- **Reads rules from:** \`${a.rulesFile}\`` + (a.agentsDir ? ` · subagents in \`${a.agentsDir}/\`` : '') + '\n';
     if (a.cliRun) md += '- **cli-run lane:** yes\n';
+    if (a.builtAgainst) md += `- **Built against:** ${a.builtAgainst}` + (a.install.npm ? ' (the same number the npm pin uses)' : '') + '\n';
     if (a.note) md += `- **Note:** ${a.note}\n`;
     md += '\n';
   }
@@ -31,7 +33,45 @@ export function catalogMarkdown() {
   return md;
 }
 
+export const VENDOR_TABLE_START = '<!-- vendor-table:start -->';
+export const VENDOR_TABLE_END = '<!-- vendor-table:end -->';
+
+export function fixtureManifest() {
+  return JSON.parse(readFileSync(new URL('../test/fixtures/manifest.json', import.meta.url), 'utf8'));
+}
+
+// The compatibility table in README.md. Every number comes from `builtAgainst`
+// in src/catalog.js, which is also the npm pin where there is one, so "built
+// against" and "pinned to" are the same number by construction (#23).
+export function vendorTableMarkdown() {
+  const fx = fixtureManifest();
+  const byLane = Object.fromEntries(fx.fixtures.map((f) => [f.lane, f]));
+  let md = VENDOR_TABLE_START + '\n\n| Lane | Vendor | Version this release was built against | Where that number is proved |\n|---|---|---|---|\n';
+  for (const a of AIS) {
+    if (!a.bin || !a.builtAgainst) continue;
+    const proof = byLane[a.id]
+      ? '`test/fixtures/' + byLane[a.id].file + '`, a recorded run'
+      : a.install.npm
+        ? 'the npm pin the installer writes, `' + npmSpec(a) + '`'
+        : a.id === 'ollama'
+          ? 'the pinned image the level 3 box runs, `' + IMAGES.ollama + '`'
+          : "the maintainer's own install";
+    md += `| \`${a.bin}\` | ${a.vendor} | ${a.builtAgainst} | ${proof} |\n`;
+  }
+  md += `\nGenerated from \`src/catalog.js\` by \`npm run gen:catalog\`; \`npm test\` fails if this table and the catalog disagree. Fixtures were captured ${fx.capturedAt}.\n\n` + VENDOR_TABLE_END;
+  return md;
+}
+
+export function readmeWithVendorTable(current) {
+  const a = current.indexOf(VENDOR_TABLE_START);
+  const b = current.indexOf(VENDOR_TABLE_END);
+  if (a === -1 || b === -1) throw new Error('README.md has no vendor-table markers');
+  return current.slice(0, a) + vendorTableMarkdown() + current.slice(b + VENDOR_TABLE_END.length);
+}
+
 if (process.argv[1] && process.argv[1].endsWith('gen-catalog.js')) {
   writeFileSync(new URL('../docs/catalog.md', import.meta.url), catalogMarkdown());
-  console.log('docs/catalog.md regenerated');
+  const readmeUrl = new URL('../README.md', import.meta.url);
+  writeFileSync(readmeUrl, readmeWithVendorTable(readFileSync(readmeUrl, 'utf8')));
+  console.log('docs/catalog.md and the README vendor table regenerated');
 }

package/src/README.md

@@ -4,6 +4,6 @@
 |---|---|
 | `catalog.js` | the single list of levels and AIs. Add an AI here and the prompts, docs tables, delegation matrix, gateway config and installer all pick it up. Nothing else lists AIs. |
 | `detect.js` | PATH lookup for a binary, plus the few places vendor installers drop binaries without touching PATH. No shell-outs. |
-| `install.js` | pure planner: turns (level, selection, primary) into a list of files to write, rendering templates and computing every generated table. `writeFiles` is the only thing that touches disk. |
+| `install.js` | pure planner: turns (level, selection, primary) into a list of files to write, rendering templates and computing every generated table. `writeFiles` is the only thing that touches disk. `activationSteps()` and `snippetFor()` live here so the terminal summary and the generated README render the same list. |
 | `prompt.js` | line-buffered questions for the interactive path; piped answers are queued, EOF mid-prompt aborts instead of confirming a write. |
 | `render.js` | `{{KEY}}` substitution. Throws on an unknown key, so a template typo fails the test suite instead of shipping a literal placeholder. |

package/src/catalog.js

@@ -17,6 +17,16 @@
 //   rulesFile  the instructions file that agent reads from a project root, if any
 //   agentsDir  where that agent keeps project-level subagent definitions, if any
 //   cliRun     true when bin/cli-run.mjs has a judge for this lane
+//   builtAgainst  the vendor version this release's lane wiring and judges were
+//              exercised against. ONE number per lane: the README compatibility
+//              table is generated from it, and where install.npm exists the pin
+//              IS this number, so "built against" and "pinned to" cannot drift
+//              into two answers (#23). Lanes with a recorded fixture are
+//              cross-checked against test/fixtures/manifest.json by the tests.
+//   chatName   chat apps only: the app's name in a sentence, without the
+//              "(chat only, no CLI)" catalog note, so the activation line stays
+//              a sentence you can read once (#22)
+//   chatSurface chat apps only: where the pasted block goes in that app
 
 export const LEVELS = [
   {
@@ -53,7 +63,8 @@ export const AIS = [
     lane: 'A',
     role: 'orchestrator: routes, maps, builds, verifies, records',
     minLevel: 1,
-    install: { npm: '@anthropic-ai/claude-code', pin: '2.1.260' },
+    install: { npm: '@anthropic-ai/claude-code', pin: '2.1.226' },
+    builtAgainst: '2.1.226',
     auth: 'run `claude` once and sign in with your Anthropic account',
     rulesFile: 'CLAUDE.md',
     agentsDir: '.claude/agents',
@@ -70,7 +81,8 @@ export const AIS = [
     lane: 'A',
     role: 'second coder and adversarial auditor (a different model family reading your diff)',
     minLevel: 1,
-    install: { npm: '@openai/codex', pin: '0.153.2' },
+    install: { npm: '@openai/codex', pin: '0.153.4' },
+    builtAgainst: '0.153.4',
     auth: '`codex login` (add `--device-auth` on a machine with no browser)',
     rulesFile: 'AGENTS.md',
     agentsDir: null,
@@ -87,6 +99,7 @@ export const AIS = [
     role: 'deep research sweeps and concurrent fan-out (its subagent call takes an array)',
     minLevel: 1,
     install: { script: 'https://antigravity.google/cli/install.sh' },
+    builtAgainst: '1.1.27',
     auth: 'first run opens a device-code sign-in with your Google account',
     rulesFile: 'GEMINI.md',
     agentsDir: '.agents/agents',
@@ -105,6 +118,7 @@ export const AIS = [
     role: 'X and live web reads at no per-call cost (its search tools bill on the API, not on the CLI)',
     minLevel: 1,
     install: { script: 'https://x.ai/cli/install.sh' },
+    builtAgainst: '1.0.5',
     auth: '`grok login` (add `--device-auth` on a headless machine)',
     rulesFile: null,
     agentsDir: null,
@@ -121,6 +135,7 @@ export const AIS = [
     role: 'the free tier: rough drafts, first-pass summaries, cheap divergent reads, cron jobs on a box',
     minLevel: 2,
     install: { url: 'https://github.com/NousResearch/hermes-agent' },
+    builtAgainst: '0.20.0',
     auth: '`hermes auth add <provider>` per provider; its own fallback chain handles outages',
     rulesFile: null,
     agentsDir: null,
@@ -136,7 +151,8 @@ export const AIS = [
     lane: 'B',
     role: 'cheapest metered bulk lane for structured output; never for anything that cites a line, a number or a source',
     minLevel: 2,
-    install: { npm: '@qwen-code/qwen-code', pin: '0.23.0' },
+    install: { npm: '@qwen-code/qwen-code', pin: '0.22.3' },
+    builtAgainst: '0.22.3',
     auth: 'a provider key in an environment variable, named (not stored) in ~/.qwen/settings.json. There is no free Qwen cloud tier any more.',
     rulesFile: 'QWEN.md',
     agentsDir: null,
@@ -154,6 +170,7 @@ export const AIS = [
     role: 'the privacy lane: anything that must never leave the machine. Not a cost lane.',
     minLevel: 2,
     install: { url: 'https://ollama.com/download', brew: 'ollama' },
+    builtAgainst: '0.33.3',
     auth: 'none',
     rulesFile: null,
     agentsDir: null,
@@ -171,6 +188,8 @@ export const AIS = [
     minLevel: 1,
     install: { url: 'https://claude.ai' },
     auth: 'sign in',
+    chatName: 'the Claude app or claude.ai',
+    chatSurface: 'custom instructions or a Project',
     rulesFile: null,
     agentsDir: null,
     cliRun: false
@@ -187,6 +206,8 @@ export const AIS = [
     minLevel: 1,
     install: { url: 'https://chatgpt.com' },
     auth: 'sign in',
+    chatName: 'ChatGPT',
+    chatSurface: 'custom instructions or a Project',
     rulesFile: null,
     agentsDir: null,
     cliRun: false
@@ -203,6 +224,8 @@ export const AIS = [
     minLevel: 1,
     install: { url: 'https://gemini.google.com' },
     auth: 'sign in',
+    chatName: 'the Gemini app',
+    chatSurface: 'saved instructions or a Gem',
     rulesFile: null,
     agentsDir: null,
     cliRun: false

package/src/install.js

@@ -193,6 +193,38 @@ export function laneVars(selected) {
   };
 }
 
+// Which activation file this primary gets. ONE decision, read by three
+// surfaces: planFiles writes the file, vars() names it in the generated README,
+// and bin/cli.js prints it in the terminal. Before 0.1.12 the README hardcoded
+// PASTE-INTO-YOUR-AGENT.md and named it for CLI installs that never got one (#20).
+export function snippetFor(primary) {
+  if (!primary) return null;
+  return primary.rulesFile ? primary.rulesFile.replace(/\.md$/, '.snippet.md') : 'PASTE-INTO-YOUR-AGENT.md';
+}
+
+// The activation list, in order. The terminal prints this array at the end of a
+// run and the generated README renders the same array, so the page cannot
+// describe a different first step from the one the user just read (#20).
+export function activationSteps(opts) {
+  const { level, selected = [], primary } = opts;
+  const tools = opts.tools || [];
+  const dirAbs = resolve(opts.dir || 'ai-orchestrator');
+  const projectAbs = resolve(opts.project || process.cwd());
+  const snippet = snippetFor(primary);
+  const steps = [];
+  if (snippet && primary.rulesFile) steps.push(`copy the block in ${join(dirAbs, snippet)} into ${join(projectAbs, primary.rulesFile)} (create it if missing)`);
+  // A chat app has no possessive that survives its catalog note: "Claude app or
+  // claude.ai (chat only, no CLI)'s custom instructions" was the sentence this
+  // replaces (#22).
+  else if (snippet) steps.push(`open ${primary.chatName || primary.name} and paste the block in ${join(dirAbs, snippet)} into its ${primary.chatSurface || 'custom instructions'}`);
+  if (primary && primary.agentsDir) steps.push(`subagents are in ${join(projectAbs, primary.agentsDir)}; run ${primary.bin} from ${projectAbs} to pick them up`);
+  for (const a of selected.filter((a) => a.bin && a.kind === 'agent-cli')) steps.push(`sign in to ${a.name}: ${a.auth}`);
+  for (const t of tools) steps.push(`${t.id}: ${t.install}`);
+  if (level >= 2) steps.push(`smoke test: node ${join(dirAbs, 'bin', 'cli-run.mjs')} --doctor   (add --run to send each lane one tiny prompt)`);
+  if (level >= 3) steps.push(`box: read ${join(dirAbs, 'vm', 'README.md')}; keys named in vm/ENVIRONMENT.md go in your secrets manager, never a file`);
+  return steps;
+}
+
 function vars(opts) {
   const { level, selected, primary } = opts;
   const tools = opts.tools || [];
@@ -206,8 +238,28 @@ function vars(opts) {
   if (rulesPath === '') rulesPath = '.';
   else if (rulesPath.startsWith('..')) rulesPath = dirAbs; // outside the project: absolute is the only honest path
   const pinOf = (id) => (toolById[id] && toolById[id].pin) || 'latest';
+  const snippet = snippetFor(primary);
+  const steps = activationSteps({ level, selected, primary, tools, dir: opts.dir, project: opts.project });
+  // Only claude-code and agy put files under the project root. A chat primary
+  // puts nothing there, so naming a project root would name a folder this run
+  // never created (#21).
+  const writesProject = !!(primary && primary.agentsDir);
+  const readsProjectRules = !!(primary && primary.rulesFile);
+  const whereThingsWent = [`- This folder: \`${dirAbs}\``];
+  if (writesProject) whereThingsWent.push(`- Project root (where your agent reads rules and subagents): \`${projectAbs}\``, `- Subagent definitions: \`${join(projectAbs, primary.agentsDir)}\``);
+  else if (readsProjectRules) whereThingsWent.push(`- Project root (where ${primary.name} reads \`${primary.rulesFile}\`): \`${projectAbs}\`` + (existsSync(projectAbs) ? '' : ' (this run wrote nothing there; create the folder before you copy the snippet in)'), '- Subagent definitions: none, this agent has no subagent folder');
+  else whereThingsWent.push('- Project root: none. A chat app reads pasted instructions, not files, so this install wrote nothing to a project folder.', '- Subagent definitions: none');
+  whereThingsWent.push(`- The rules path your snippets use: \`${rulesPath}\``);
   return {
     ...laneVars(selected),
+    ACTIVATION_STEPS: steps.map((st, i) => `${i + 1}. ${st}`).join('\n'),
+    LOAD_IT: readsProjectRules
+      ? `${primary.name} reads its rules from \`${primary.rulesFile}\` in the project root. The installer wrote \`${snippet}\` next to this README; copy its contents into \`${join(projectAbs, primary.rulesFile)}\`, creating that file if it does not exist. Nothing was appended to a file you already had.`
+      : snippet
+        ? `${primary.name} has no project rules file, so the rules travel by paste. The installer wrote \`${snippet}\` next to this README; open ${primary.chatName || primary.name} and paste its contents into ${primary.chatSurface || 'custom instructions'}. Nothing was appended to a file you already had.`
+        : 'No primary agent was selected, so no activation file was written. Re-run the installer and pick one.',
+    CHAT_UPLOAD_NOTE: primary && primary.kind === 'chat' ? ' A chat app cannot open a local path: upload or paste any protocol file you want it to read.' : '',
+    WHERE_THINGS_WENT: whereThingsWent.join('\n'),
     RULES_PATH: rulesPath,
     ROUTING_FILE: level >= 2 ? 'ROUTING.md' : 'ORCHESTRATOR.md',
     PROJECT_DIR: projectAbs,

package/templates/common/README.md

@@ -13,13 +13,18 @@ Companion tools:
 
 This folder gives your agent routing instructions and, at level 2+, a runner for explicitly selected CLI lanes. The agent chooses the tier or lane; the runner does not automatically compare prices or choose a model.
 
-## Your first task
+## Activate it
 
-1. Activate the snippet using the instructions below. For a chat app, paste the block in `PASTE-INTO-YOUR-AGENT.md`; upload any full protocols you want it to read because local paths alone do not share files.
-2. Start a fresh agent session and ask: "Read the orchestrator instructions. Quote the routing rule you will use, then sort pear, apple, banana alphabetically. Name the tier and whether you delegated."
-3. Expect the fast tier and `apple, banana, pear`. If the agent cannot quote the routing rule, check the snippet location or chat instructions before continuing. This is a manual activation check, not proof that every future task follows the rules.
-4. At level 2+, run `node bin/cli-run.mjs --doctor` from this folder. It checks binary presence, not authentication or loaded instructions. `--doctor --run` additionally uses a little quota to test live responses. No enabled lanes means delegation is inactive.
-5. To test a real output contract, choose an enabled lane from `bin/lanes.json` and run `node bin/cli-run.mjs <lane> 'Return only {"sorted":["apple","banana","pear"]}' --expect-json`. This uses quota. Expect JSON and exit 0; inspect the array yourself. A non-JSON response exits 10, a missing binary exits 13, and an authentication failure reports the vendor error. The explicit lane tests execution; your primary agent still makes delegation decisions.
+These are the same steps, in the same order, that the installer printed in your terminal.{{CHAT_UPLOAD_NOTE}}
+
+{{ACTIVATION_STEPS}}
+
+## Then prove it took
+
+1. Start a fresh agent session and ask: "Read the orchestrator instructions. Quote the routing rule you will use, then sort pear, apple, banana alphabetically. Name the tier and whether you delegated."
+2. Expect the fast tier and `apple, banana, pear`. If the agent cannot quote the routing rule, check the snippet location or chat instructions before continuing. This is a manual activation check, not proof that every future task follows the rules.
+3. At level 2+, run `node bin/cli-run.mjs --doctor` from this folder. It checks binary presence, not authentication or loaded instructions. `--doctor --run` additionally uses a little quota to test live responses. No enabled lanes means delegation is inactive.
+4. To test a real output contract, choose an enabled lane from `bin/lanes.json` and run `node bin/cli-run.mjs <lane> 'Return only {"sorted":["apple","banana","pear"]}' --expect-json`. This uses quota. Expect JSON and exit 0; inspect the array yourself. A non-JSON response exits 10, a missing binary exits 13, and an authentication failure reports the vendor error. The explicit lane tests execution; your primary agent still makes delegation decisions.
 
 ## What is in this folder
 
@@ -38,9 +43,9 @@ This folder gives your agent routing instructions and, at level 2+, a runner for
 
 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.
 
-## Load it into your agent
+## Where the rules load from
 
-For a CLI primary, the project rules file is `{{PRIMARY_RULES_FILE}}`. Chat apps use pasted instructions instead. The installer wrote a snippet file next to this README (`*.snippet.md`, or `PASTE-INTO-YOUR-AGENT.md` for a chat app). Copy its contents into that file, or paste it into the agent's custom instructions. Nothing was appended to a file you already had.
+{{LOAD_IT}}
 
 ## The three rules that carry everything
 
@@ -50,10 +55,7 @@ For a CLI primary, the project rules file is `{{PRIMARY_RULES_FILE}}`. Chat apps
 
 ## Where things went
 
-- This folder: `{{INSTALL_DIR}}`
-- Project root (where your agent reads rules and subagents): `{{PROJECT_DIR}}`
-- Subagent definitions: `{{AGENTS_DIR}}`
-- The rules path your snippets use: `{{RULES_PATH}}`
+{{WHERE_THINGS_WENT}}
 
 ## Uninstall