model-orchestrator 0.1.31 → 0.1.33

package/CHANGELOG.md

@@ -4,6 +4,24 @@ All notable changes to this project are documented here. The format follows [Kee
 
 ## [Unreleased]
 
+## [0.1.33] - 2026-09-24
+
+### Added
+
+- **Opt-in snippet application.** `--apply-snippets` applies a replaceable Claude Code rules block and merges hooks with timestamped backups, validation before writes, dry-run previews and manual uninstall guidance. ([#41](https://github.com/aunysillyme/model-orchestrator/issues/41))
+- **Model orchestrator or a model proxy.** README and `llms.txt` explain the request layer, when to pick each approach and how they compose. ([#44](https://github.com/aunysillyme/model-orchestrator/issues/44))
+
+### Fixed
+
+- **Selected lane guidance.** Delegation rows and related cost and research advice render from selected catalog lane categories, keeping absent categories out of active picks. ([#42](https://github.com/aunysillyme/model-orchestrator/issues/42))
+- **Rules folder relocation.** Project-contained snippets use relative paths; external rules paths carry relocation guidance. Installer hooks that read rules honour `MODEL_ORCHESTRATOR_RULES_DIR`, and the generated README names the path case. ([#43](https://github.com/aunysillyme/model-orchestrator/issues/43))
+
+## [0.1.32] - 2026-09-23
+
+### Changed
+
+- **README shows what the install gives you, not a file dump.** The 50-line dry-run file list under the demo became a six-row table naming each part and what it does for you; the preview command stays, and the full file list is one link away in `docs/install.md`.
+
 ## [0.1.31] - 2026-09-23
 
 ### Added
@@ -427,7 +445,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.31...HEAD
+[Unreleased]: https://github.com/aunysillyme/model-orchestrator/compare/v0.1.33...HEAD
+[0.1.33]: https://github.com/aunysillyme/model-orchestrator/compare/v0.1.32...v0.1.33
+[0.1.32]: https://github.com/aunysillyme/model-orchestrator/compare/v0.1.31...v0.1.32
 [0.1.31]: https://github.com/aunysillyme/model-orchestrator/compare/v0.1.30...v0.1.31
 [0.1.30]: https://github.com/aunysillyme/model-orchestrator/compare/v0.1.29...v0.1.30
 [0.1.29]: https://github.com/aunysillyme/model-orchestrator/compare/v0.1.28...v0.1.29

package/README.md

@@ -14,66 +14,25 @@ npx model-orchestrator
 
 <img src="docs/demo.gif" alt="A terminal running npx model-orchestrator with --dry: it prints the level, the AIs detected, both target folders and all 38 files it would write, then says nothing was written." width="100%" />
 
-A few questions, then 38 files for a three-AI setup. The same plan as text (paths shown relative to the project folder):
+A few questions, then it writes the setup for the AIs you picked. For Claude Code, Codex and Grok that is 38 files:
 
-```text
-Plan
-  level    2 Intermediate
-  access   claude-code, codex, grok
-  primary  claude-code
-  tools    codecalc
-  plans    none stated
-  folder   ./ai-orchestrator
-  project  . (8 subagents + 3 hooks go here)
-  files    38
-  - README.md
-  - TASK_BUNDLE.md
-  - protocols/README.md
-  - protocols/build-protocol.md
-  - protocols/deep-research.md
-  - protocols/docs-then-prove.md
-  - protocols/gap-analysis.md
-  - protocols/memory-and-record.md
-  - protocols/numbers-and-logic.md
-  - protocols/propagate.md
-  - ORCHESTRATOR.md
-  - [project] .claude/agents/builder.md
-  - [project] .claude/agents/bulk-worker.md
-  - [project] .claude/agents/code-reviewer.md
-  - [project] .claude/agents/deep-planner.md
-  - [project] .claude/agents/done-verifier.md
-  - [project] .claude/agents/finding-verifier.md
-  - [project] .claude/agents/live-researcher.md
-  - [project] .claude/agents/reader.md
-  - CLAUDE.snippet.md
-  - [project] .claude/hooks/route-gate.mjs
-  - [project] .claude/hooks/subagent-context.mjs
-  - [project] .claude/hooks/route-metrics.mjs
-  - settings.hooks.snippet.json
-  - CODECALC.md
-  - mcp/agy.mcp_config.json
-  - mcp/codex.config.toml
-  - mcp/mcpServers.json
-  - mcp/vscode.mcp.json
-  - mcp/zed.settings.json
-  - CLI-RUN.md
-  - DELEGATION_MATRIX.md
-  - RESEARCH_TRIAGE.md
-  - ROUTING.md
-  - TIERS.md
-  - bin/cli-run.mjs
-  - bin/lanes.json
-  - MANIFEST.json
-
---dry: nothing written.
-```
+| Part | What it does for you |
+|---|---|
+| `ROUTING.md`, `TIERS.md`, `DELEGATION_MATRIX.md` | tell your agent which model or CLI handles each kind of task, and at what effort |
+| `TASK_BUNDLE.md` and `protocols/` | the brief every hand-off carries, plus build, research, audit and record-keeping steps |
+| 8 subagents in `.claude/agents/` | builder, planner, reviewer, researcher, bulk worker, reader and two verifiers, each with its own tools |
+| 3 hooks in `.claude/hooks/` | put the routing table in front of your agent on every prompt and every subagent start, and log where work went |
+| `bin/cli-run.mjs` | calls Codex, Grok and the other CLIs, and counts a run as done only when it returns a result |
+| `mcp/` and `CODECALC.md` | ready-to-paste configs for the companion tools you chose |
 
-Run it yourself, in any folder:
+Preview it in any folder, nothing is written:
 
 ```bash
 npx model-orchestrator --yes --level 2 --ais claude-code,codex,grok --primary claude-code --dir ./ai-orchestrator --project . --dry
 ```
 
+Every file, folder by folder: [docs/install.md](docs/install.md#what-gets-written-level-3-everything).
+
 The recording above comes from the published package under `asciinema`, rendered with `agg`: `bash scripts/record-demo.sh`.
 
 - **What it is:** routing rules, subagent definitions and a CLI lane runner (`cli-run`) for the AI tools you already pay for.
@@ -81,6 +40,16 @@ The recording above comes from the published package under `asciinema`, rendered
 - **Use it when:** you run more than one model or agent and want the expensive tier kept for planning and judgment.
 - **For agents:** [`llms.txt`](llms.txt) summarizes the package and links every doc; [`AGENTS.md`](AGENTS.md) has the headless commands.
 
+## Model orchestrator or a model proxy
+
+An HTTP proxy or gateway such as LiteLLM, Portkey, OpenRouter or claude-code-router
+swaps the model per request underneath the agent.
+model-orchestrator is an installer that writes routing rules, subagents, hooks
+and a lane runner above the request layer for the coding agents and subscription CLIs you already pay for.
+Pick a proxy for request-level model routing and a shared API entry point.
+Pick model-orchestrator for task delegation across your agents, tiers and CLIs.
+They compose: your agent follows the installed rules, and a proxy can route its API requests underneath.
+
 ## After you install
 
 For the Claude Code setup above, follow the activation summary from the project folder:
@@ -89,6 +58,8 @@ For the Claude Code setup above, follow the activation summary from the project
 2. **Hooks:** merge `ai-orchestrator/settings.hooks.snippet.json` into `.claude/settings.json` (create it if missing).
 3. **Smoke test:** run `node ./ai-orchestrator/bin/cli-run.mjs --doctor` to check the enabled lanes. Add `--run` to send each lane one tiny prompt.
 
+Add `--apply-snippets` to apply the rules and hooks steps for a Claude Code primary. It is off by default. The installer replaces one marked block in `CLAUDE.md`, preserves the surrounding bytes, and merges hooks while keeping existing settings and avoiding duplicate commands with the same arguments. Existing files changed by the run get timestamped backups beside them (`<name>.bak-YYYYMMDDTHHMMSS`); every backup path is printed. Preview with `--apply-snippets --dry-run`. Invalid settings JSON stops the run before any writes. Other primaries get the snippet name to paste by hand.
+
 Run `claude` from the project folder to load the subagents. Follow the sign-in and companion-tool steps printed for your selection; the same steps are saved in `ai-orchestrator/README.md`.
 
 A real call through the lane runner, captured from a fresh install on 2026-09-23 (Codex CLI 0.154.0). Your agent sends a small read to Codex at low effort, and `cli-run` prints one status line with the route it used:

package/bin/cli.js

@@ -2,7 +2,7 @@
 // model-orchestrator installer.
 // Asks which level you want and which AIs you have access to, then writes the
 // matching files into a folder. It never writes a secret, never runs a vendor
-// shell script, and never overwrites a file you already have unless --force.
+// shell script. Existing documents are preserved unless an update is requested.
 
 import { stdin, stdout } from 'node:process';
 import { makeAsker } from '../src/prompt.js';
@@ -18,13 +18,14 @@ import { planFiles, writeFiles, resolveSelection, resolveTools, resolveApis, dir
 // shell, or fall back to the escaped cmd.exe path it also provides.
 import { windowsSpawnPlan } from './cli-run.mjs';
 import { uninstallFiles } from '../src/uninstall.js';
+import { assertSnippetPrimary, planSnippetApplication } from '../src/apply-snippets.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
 // turn a dry run into a real one.
 const SPEC = {
   level: 'value', ais: 'value', primary: 'value', dir: 'value', project: 'value', tools: 'value', apis: 'value', plans: 'value',
-  yes: 'bool', force: 'bool', dry: 'bool', 'dry-run': 'bool', uninstall: 'bool', 'no-install': 'bool', 'no-tools': 'bool', 'no-apis': 'bool', 'effort-auto': 'bool', 'upgrade-runtime': 'bool', 'update-docs': 'bool', list: 'bool', help: 'bool', h: 'bool', version: 'bool', v: 'bool'
+  'apply-snippets': 'bool', yes: 'bool', force: 'bool', dry: 'bool', 'dry-run': 'bool', uninstall: 'bool', 'no-install': 'bool', 'no-tools': 'bool', 'no-apis': 'bool', 'effort-auto': 'bool', 'upgrade-runtime': 'bool', 'update-docs': 'bool', list: 'bool', help: 'bool', h: 'bool', version: 'bool', v: 'bool'
 };
 export function parseArgs(argv) {
   const out = {};
@@ -112,6 +113,7 @@ Flags
   --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
+  --apply-snippets   apply Claude Code rules and hooks with timestamped backups (opt-in)
   --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
                      when they cannot be verified as untouched; documents are still kept
@@ -193,6 +195,7 @@ async function main() {
     console.log(dry ? 'Uninstall preview (--dry): nothing changed.' : 'Uninstall complete.');
     for (const action of actions) console.log(action);
     console.log('\nManual steps: remove the pasted model-orchestrator block from CLAUDE.md and its merged hook entries from .claude/settings.json. Keep your other rules and hooks.');
+    console.log(`Applied rules use <!-- model-orchestrator:start --> and <!-- model-orchestrator:end -->. Backups stay beside the originals: ${join(project, 'CLAUDE.md.bak-YYYYMMDDTHHMMSS')} and ${join(project, '.claude', 'settings.json.bak-YYYYMMDDTHHMMSS')}. Review backups before restoring them; later edits may need to be kept.`);
     console.log('For another primary agent, remove its pasted activation block from its rules file.');
     return;
   }
@@ -366,7 +369,10 @@ async function main() {
   }
 
   // 5. Plan
-  const files = planFiles({ level, selected, primary, dir, project, tools, apis, plans, effortAuto });
+  const applySnippets = flag('apply-snippets');
+  if (applySnippets) assertSnippetPrimary(primary);
+  const files = planFiles({ level, selected, primary, dir, project, tools, apis, plans, effortAuto, applySnippets });
+  if (applySnippets) files.push(...planSnippetApplication({ primary, project, files }));
   const lvl = LEVELS.find((l) => l.id === level);
   const agentFiles = files.filter((f) => f.root === 'project');
   const projectKinds = [
@@ -384,6 +390,12 @@ async function main() {
   }
   if (flag('dry') || flag('dry-run')) {
     for (const f of files) console.log('  - ' + (f.root === 'project' ? '[project] ' : '') + f.rel);
+    if (applySnippets) {
+      const preview = writeFiles(files, { dir, project, dry: true, force: flag('force'), upgradeRuntime: flag('upgrade-runtime'), updateDocs: flag('update-docs'), prevManifest: prev, backupExisting: true });
+      for (const path of preview.written) console.log('  would write ' + path);
+      for (const path of [...preview.skipped, ...preview.conflicts, ...preview.unverifiable, ...preview.docsConflict, ...preview.docsUnverifiable]) console.log('  would keep ' + path);
+      for (const path of preview.backups) console.log('  would back up ' + path);
+    }
     console.log('\n--dry: nothing written.');
     rl && rl.close();
     return;
@@ -405,7 +417,7 @@ async function main() {
 
   let written, skipped, upgraded, conflicts, unverifiable, docsUpdated, docsConflict, docsUnverifiable;
   try {
-    ({ written, skipped, upgraded, conflicts, unverifiable, docsUpdated, docsConflict, docsUnverifiable } = writeFiles(files, { dir, project, force: flag('force'), upgradeRuntime: flag('upgrade-runtime'), updateDocs: flag('update-docs'), prevManifest: prev }));
+    ({ written, skipped, upgraded, conflicts, unverifiable, docsUpdated, docsConflict, docsUnverifiable } = writeFiles(files, { dir, project, force: flag('force'), upgradeRuntime: flag('upgrade-runtime'), updateDocs: flag('update-docs'), prevManifest: prev, backupExisting: applySnippets, onBackup: (path) => console.log('  backup ' + path) }));
   } catch (e) {
     if (e && e.code === 'PREFLIGHT') bad(e.message);
     throw e;
@@ -479,7 +491,7 @@ 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. The generated
   // README renders this same array, so the two surfaces cannot disagree (#20).
-  const steps = activationSteps({ level, selected, primary, tools, dir, project });
+  const steps = activationSteps({ level, selected, primary, tools, dir, project, applySnippets });
   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).`);
@@ -498,5 +510,5 @@ function isEntryPoint() {
 }
 if (isEntryPoint()) main().catch((e) => {
   console.error('model-orchestrator: ' + (e && e.message ? e.message : e));
-  process.exit(e && ['EOF', 'UNINSTALL'].includes(e.code) ? 2 : 1);
+  process.exit(e && ['EOF', 'UNINSTALL', 'PREFLIGHT'].includes(e.code) ? 2 : 1);
 });

package/docs/install.md

@@ -11,7 +11,22 @@ The installer asks a few things, then writes a folder:
 2. **Which AIs do you have access to?** (it marks the ones already on your PATH)
 3. **Which one is your primary agent?** (the one that runs the system)
 
-It never writes a secret, never runs a vendor shell script for you, and never overwrites a document you already have unless you pass `--force`. Two exceptions, both stated when they happen: `MANIFEST.json` and `bin/lanes.json` are machine-owned and rewritten on every run so a changed selection applies; runtime files (`cli-run`, the audit job, compose, gateway config, setup script) are upgraded when the installed copy matches the hash a previous run recorded, kept and reported as a conflict when you edited them, and kept as unverifiable when no manifest exists (`--upgrade-runtime` replaces runtime files only). The same hash rule is available for documents on request: `--update-docs` regenerates the documents a previous run wrote and nobody edited, so a changed selection reaches `ROUTING.md` and the delegation matrix without `--force`; edited documents are kept and named. Docs and protocols go to `--dir` (default `./ai-orchestrator`); subagent definitions (and, on Claude Code, three hook scripts) go to the project root your agent runs from (`--project`, default the current directory), because that is the only place Claude Code and Antigravity read them. It ends with an activation summary: what to copy where, which sign-ins, and one smoke command. Use `--uninstall` to remove unedited managed files, then remove your manually merged activation entries. See [Uninstall](#uninstall).
+It never writes a secret, never runs a vendor shell script for you, and preserves existing documents by default. `--force` explicitly replaces them; `--apply-snippets` opts into the backed-up activation merge described below. Two exceptions, both stated when they happen: `MANIFEST.json` and `bin/lanes.json` are machine-owned and rewritten on every run so a changed selection applies; runtime files (`cli-run`, the audit job, compose, gateway config, setup script) are upgraded when the installed copy matches the hash a previous run recorded, kept and reported as a conflict when you edited them, and kept as unverifiable when no manifest exists (`--upgrade-runtime` replaces runtime files only). The same hash rule is available for documents on request: `--update-docs` regenerates the documents a previous run wrote and nobody edited, so a changed selection reaches `ROUTING.md` and the delegation matrix without `--force`; edited documents are kept and named. Docs and protocols go to `--dir` (default `./ai-orchestrator`); subagent definitions (and, on Claude Code, three hook scripts) go to the project root your agent runs from (`--project`, default the current directory), because that is the only place Claude Code and Antigravity read them. It ends with an activation summary: what to copy where, which sign-ins, and one smoke command. Use `--uninstall` to remove unedited managed files, then remove your manually merged activation entries. See [Uninstall](#uninstall).
+
+## Apply Claude Code snippets
+
+Pass `--apply-snippets` with a Claude Code primary to apply both activation snippets. The flag is off by default; other primaries exit 2 and name the snippet to paste by hand.
+
+- **Rules:** create `CLAUDE.md` if missing, or insert a block between `<!-- model-orchestrator:start -->` and `<!-- model-orchestrator:end -->`. Reruns replace that block in place, keeping every byte outside it. Incomplete or duplicate markers are refused before writing.
+- **Settings:** create `.claude/settings.json` if missing, or merge the generated hooks while preserving existing keys and hooks. A command with the same arguments already present in that event is kept once. Unparseable JSON exits 2, names the file, and writes nothing anywhere.
+- **Backups:** every existing file changed during an apply run gets a sibling `<name>.bak-YYYYMMDDTHHMMSS`, including generated files replaced on a rerun. Each path is printed. New and unchanged activation files need no backup; existing backups are preserved.
+- **Preview:** `--apply-snippets --dry` and `--apply-snippets --dry-run` list writes, kept files and backup paths without changing the filesystem.
+- **Activation:** the summary reports the applied rules and hooks, then lists sign-ins and verification. Start a fresh Claude Code session to verify the instructions loaded.
+- **Revert:** uninstall leaves the marked block, settings and backups in place and names them in its manual steps. Review a backup before restoring it so later edits survive.
+
+```bash
+npx model-orchestrator --yes --level 2 --ais claude-code,codex --primary claude-code --project . --dir ./ai-orchestrator --apply-snippets
+```
 
 ## Plans and automatic effort
 
@@ -23,10 +38,12 @@ 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. Claude Code also gets three hook scripts in `.claude/hooks/`, wired by a settings snippet you merge yourself. |
+| `--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. Claude Code also gets three hook scripts in `.claude/hooks/`, wired by a settings snippet you merge yourself or apply with `--apply-snippets`. |
 
 `--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 the subagent and hook 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.
 
+Rules inside the project use project-relative snippet paths, so moving the whole project preserves them. Rules outside the project use absolute paths and carry a relocation note. After moving those rules, re-run the installer or set `MODEL_ORCHESTRATOR_RULES_DIR` for the installed rule-reading hooks, and update your agent instruction paths. An absolute override names the new folder; a relative override is relative to `CLAUDE_PROJECT_DIR`. `route-metrics` reads no rules and keeps its home-directory log. The separately installed Claude Code plugin keeps its existing default-path lookup.
+
 ## Non-interactive
 
 ```bash
@@ -62,7 +79,7 @@ npx model-orchestrator --uninstall --dir ./ai-orchestrator --project ./my-app
 - **Target paths:** `--dir` and `--project` must match the installation paths in the manifest. A mismatch exits 2 before removal.
 - **Preview:** `--dry` (or `--dry-run`) lists the planned removals and writes nothing.
 
-The command prints the remaining manual steps: remove the pasted model-orchestrator block from `CLAUDE.md` and its merged hook entries from `.claude/settings.json`. Keep your other rules and hooks. With another primary agent, remove its pasted activation block from the corresponding rules file.
+The command prints the remaining manual steps: remove the pasted model-orchestrator block from `CLAUDE.md` and its merged hook entries from `.claude/settings.json`. Applied blocks use `<!-- model-orchestrator:start -->` and `<!-- model-orchestrator:end -->`. Timestamped `CLAUDE.md.bak-*` and `.claude/settings.json.bak-*` backups stay beside the originals for a reviewed restore. Keep your other rules and hooks. With another primary agent, remove its pasted activation block from the corresponding rules file.
 
 ## What gets written (level 3, everything)
 

package/llms.txt

@@ -8,6 +8,8 @@ Levels: 1 beginner (one agent or chat app), 2 intermediate (several agent CLIs,
 
 Claude Code plugin: `/plugin marketplace add aunysillyme/model-orchestrator`, then `/plugin install model-orchestrator@model-orchestrator`. It installs the two read-only hooks (`route-gate`, `subagent-context`) and eight subagents; the routing rules still come from `npx model-orchestrator`, and the routing log (`route-metrics.mjs`) is npm-only.
 
+Pick a model proxy (LiteLLM, Portkey, OpenRouter, claude-code-router) for per-request model routing underneath an agent; pick model-orchestrator for installed routing rules, subagents, hooks and a lane runner for coding agents and subscription CLIs. They compose.
+
 ## Docs
 
 - [README](https://github.com/aunysillyme/model-orchestrator/blob/main/README.md): what it is, a real dry-run plan, the levels, the AIs, the principles

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "model-orchestrator",
-  "version": "0.1.31",
+  "version": "0.1.33",
   "description": "Model orchestrator for Claude Code, Codex, Antigravity (Google): routing rules so small work goes to cheap tiers and fewer tokens go to frontier models.",
   "type": "module",
   "bin": {

package/src/README.md

@@ -5,6 +5,7 @@
 | `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. `activationSteps()` and `snippetFor()` live here so the terminal summary and the generated README render the same list. `subagentsLoadRules(primary)` gates every delegate-by-default render var (builder-by-default wording, the route-gate table, the inline-threshold note) on the one verified premise: a claude-code subagent loads CLAUDE.md. |
+| `apply-snippets.js` | validates the two Claude Code activation targets before any writes, builds a replaceable marked block and merges hook entries. `writeFiles` applies these opt-in entries with backups and rollback; they stay outside the uninstall manifest. |
 | `plugin.js` | the plan for the Claude Code plugin bundle in `plugin/`: `planPluginFiles()` renders the claude-code agents and the two read-only hooks from the same templates `install.js` uses, with plugin render vars (the installer's default rules paths, the setup hint for a project with no rules) instead of per-install ones. Pure; `scripts/gen-plugin.js` writes it and `test/plugin.test.js` checks the committed copy. |
 | `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/apply-snippets.js

@@ -0,0 +1,81 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { preflight, snippetFor } from './install.js';
+
+export const START = '<!-- model-orchestrator:start -->';
+export const END = '<!-- model-orchestrator:end -->';
+const object = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
+const refuse = (message) => Object.assign(new Error(message), { code: 'PREFLIGHT' });
+
+function mergeHooks(settings, incoming, path) {
+  if (!object(settings) || (settings.hooks !== undefined && !object(settings.hooks))) {
+    throw refuse(`${path}: expected a JSON object with an optional hooks object`);
+  }
+  const hooks = { ...settings.hooks };
+  for (const [event, groups] of Object.entries(incoming)) {
+    const existing = hooks[event] === undefined ? [] : hooks[event];
+    if (!Array.isArray(existing) || existing.some((group) => !object(group) || !Array.isArray(group.hooks))) {
+      throw refuse(`${path}: hooks.${event} must contain hook groups`);
+    }
+    // A hook only counts as wired under the same matcher: the same command under a
+    // narrower matcher never fires for the tools the snippet's group targets.
+    const key = (group, hook) => JSON.stringify([group.matcher ?? '', hook.command, hook.args || []]);
+    const seen = new Set(existing.flatMap((group) => group.hooks.filter(object).map((hook) => key(group, hook))));
+    const added = [];
+    for (const group of groups) {
+      const missing = group.hooks.filter((hook) => {
+        if (seen.has(key(group, hook))) return false;
+        seen.add(key(group, hook));
+        return true;
+      });
+      if (missing.length) added.push({ ...group, hooks: missing });
+    }
+    hooks[event] = [...existing, ...added];
+  }
+  return { ...settings, hooks };
+}
+
+function markedContent(original, snippet, path) {
+  const start = original.indexOf(START);
+  const end = original.indexOf(END);
+  const block = Buffer.from(`${START}\n${snippet.trimEnd()}\n${END}`);
+  if (start === -1 && end === -1) {
+    const separator = original.length && original.at(-1) !== 10 ? '\n\n' : original.length ? '\n' : '';
+    return Buffer.concat([original, Buffer.from(separator), block, Buffer.from('\n')]);
+  }
+  if (start < 0 || end < start || original.indexOf(START, start + START.length) !== -1 || original.indexOf(END, end + END.length) !== -1) {
+    throw refuse(`${path}: expected one matching ${START} / ${END} block`);
+  }
+  return Buffer.concat([original.subarray(0, start), block, original.subarray(end + Buffer.byteLength(END))]);
+}
+
+export function assertSnippetPrimary(primary) {
+  if (primary?.id !== 'claude-code') {
+    throw refuse(`--apply-snippets requires claude-code as primary; paste ${snippetFor(primary) || 'PASTE-INTO-YOUR-AGENT.md'} by hand`);
+  }
+}
+
+// Read and validate both user files before the installer writes anything.
+// These entries deliberately stay outside the uninstall manifest.
+export function planSnippetApplication({ primary, project, files }) {
+  assertSnippetPrimary(primary);
+  const targets = ['CLAUDE.md', join('.claude', 'settings.json')];
+  const problems = preflight(targets.map((rel) => ({ rel })), project);
+  if (problems.length) throw refuse(problems.join('; '));
+  const settingsPath = join(project, targets[1]);
+  const priorSettings = existsSync(settingsPath) ? readFileSync(settingsPath) : null;
+  let settings = {};
+  if (priorSettings) {
+    try { settings = JSON.parse(priorSettings.toString('utf8')); }
+    catch { throw refuse(`${settingsPath}: invalid JSON; nothing written`); }
+  }
+  const incoming = JSON.parse(files.find((f) => f.rel === 'settings.hooks.snippet.json').content);
+  const merged = mergeHooks(settings, incoming.hooks, settingsPath);
+  const rulesPath = join(project, targets[0]);
+  const priorRules = existsSync(rulesPath) ? readFileSync(rulesPath) : null;
+  const snippet = files.find((f) => f.rel === 'CLAUDE.snippet.md').content;
+  return [
+    { rel: targets[0], original: priorRules, content: markedContent(priorRules || Buffer.alloc(0), snippet, rulesPath) },
+    { rel: targets[1], original: priorSettings, content: priorSettings && JSON.stringify(settings) === JSON.stringify(merged) ? priorSettings : JSON.stringify(merged, null, 2) + '\n' }
+  ].map((file) => ({ ...file, root: 'project', mode: 0o644, applySnippet: true }));
+}

package/src/catalog.js

@@ -8,6 +8,7 @@
 //   bin        binary to look for on PATH, or null
 //   access     'subscription' ($0 per call on a plan you already pay for), 'metered' (per token), 'free', 'local'
 //   lane       'A' = subscription CLI, 'B' = metered API, 'local' = stays on the machine
+//   laneCategories  routing capabilities used to filter generated lane advice
 //   role       the one job it wins at in a multi-AI stack
 //   minLevel   1 beginner, 2 intermediate, 3 advanced
 //   install    { npm: pkg } for a global npm install the installer may run after you say yes,
@@ -88,6 +89,7 @@ export const AIS = [
   },
   {
     id: 'codex',
+    laneCategories: ['second-coder'],
     name: 'Codex CLI (OpenAI, ChatGPT plan)',
     vendor: 'OpenAI',
     kind: 'agent-cli',
@@ -110,6 +112,7 @@ export const AIS = [
   },
   {
     id: 'agy',
+    laneCategories: ['fan-out', 'largest-context'],
     name: 'Antigravity CLI `agy` (Google AI plan)',
     vendor: 'Google',
     kind: 'agent-cli',
@@ -134,6 +137,7 @@ export const AIS = [
   },
   {
     id: 'grok',
+    laneCategories: ['live-data'],
     name: 'Grok CLI (xAI, X Premium)',
     vendor: 'xAI',
     kind: 'agent-cli',
@@ -156,6 +160,7 @@ export const AIS = [
   },
   {
     id: 'hermes',
+    laneCategories: ['free'],
     name: 'Hermes Agent (Nous Research)',
     vendor: 'Nous Research',
     kind: 'agent-cli',
@@ -173,6 +178,7 @@ export const AIS = [
   },
   {
     id: 'qwen',
+    laneCategories: ['cheapest-metered'],
     name: 'Qwen Code CLI (Alibaba, provider-agnostic)',
     vendor: 'Alibaba',
     kind: 'agent-cli',
@@ -191,6 +197,7 @@ export const AIS = [
   },
   {
     id: 'ollama',
+    laneCategories: ['local'],
     name: 'Ollama (local models)',
     vendor: 'Ollama',
     kind: 'local',

package/src/install.js

@@ -161,6 +161,30 @@ export function auditLane(selected) {
 // recommend a command its own lanes.json disables.
 export function laneVars(selected) {
   const has = (id) => selected.some((a) => a.id === id);
+  const categories = new Set(selected.flatMap((a) => a.laneCategories || []));
+  const supplies = (category) => categories.has(category);
+  const picks = [
+    ['cheapest-metered', 'Bulk classify / extract / summarize, data may leave the machine', 'the cheapest metered lane, then the fast tier', 'use the selected bulk lane and verify its output'],
+    ['local', 'Bulk work on data that must stay local', 'the local lane', 'a privacy lane; route here for confinement'],
+    ['fan-out', 'Many independent items each needing its own agent turn', 'a concurrent fan-out lane', 'one call, N children, on a subscription'],
+    ['live-data', 'Live web or social reads', 'the live-data CLI', 'subscription-covered; the same search on the API bills per call'],
+    ['second-coder', 'Code review, no changes', 'standard tier, or the second-coder CLI', 'a different model family catches what one misses'],
+    ['second-coder', 'Second-opinion audit of a security-shaped diff', 'the second-coder CLI in read-only audit mode', 'a second family challenges, the orchestrator reproduces'],
+    [null, 'Deep architecture / planning', 'deep tier', 'expensive to get wrong'],
+    [null, 'Well-specified execution', 'the orchestrator', 'execution does not need the top tier'],
+    ['largest-context', 'Long-document analysis', 'the largest-context lane, or caching on the primary', 'window size vs re-query cost'],
+    [null, 'Routing decisions themselves', 'the cheapest lane you have, or none', 'spend only the tokens the routing decision needs'],
+    ['free', 'Rough drafts, divergent reads, first-pass summaries', 'the free tier', '$0, and disagreement with the primary is information'],
+    ['cheapest-metered', 'Anything citing a line, a number, or a source', 'the cheapest metered lane with a full verification pass', 'verify every supporting number and citation']
+  ].filter(([category]) => !category || supplies(category)).map(([, ...row]) => row);
+  const cost = [
+    'Prompt caching everywhere it fits: frozen prefix first, volatile text last.',
+    'Cascade: cheapest capable tier first, escalate on signal.',
+    ...(supplies('cheapest-metered') ? ['Batch APIs where the selected provider supports them, for work that can wait.'] : []),
+    ...(supplies('free') ? ['A free model for routing decisions.'] : []),
+    'Effort and reasoning knobs before model swaps; often the bigger lever.',
+    'Alias-based config so a vendor rename is a one-line repoint.'
+  ];
   const enabled = selected.filter((a) => a.cliRun).map((a) => a.id);
   const cr = (id) => '`cli-run ' + id + '`';
   const step0 = [];
@@ -193,6 +217,16 @@ export function laneVars(selected) {
   if (has('hermes')) run.push('node bin/cli-run.mjs hermes --brief "$BRIEF" --timeout 900 > research/out-hermes.md');
   if (has('qwen')) run.push('node bin/cli-run.mjs qwen  --brief "$BRIEF" --timeout 900 > research/out-qwen.md');
   return {
+    TASK_LANES_TABLE: table(picks, ['Task type', 'Pick', 'Why']),
+    COST_PLAYBOOK: cost.map((line, i) => `${i + 1}. ${line}`).join('\n'),
+    FAN_OUT_ADVICE: supplies('fan-out') ? ' Many independent items each needing its own agent turn → the selected concurrent fan-out lane.' : '',
+    METERED_CITATION_NOTE: supplies('cheapest-metered') ? " A lane's figure is re-derived before it is repeated: verify every supporting number and citation from the cheapest metered lane." : '',
+    RESEARCH_SELECTION_ADVICE: enabled.length >= 2
+      ? 'Send the same PLAN to your selected CLI lanes, preferring different model families. Run each through `cli-run` so a run that produced nothing exits 10 and is treated as a missing engine.'
+      : 'Use the primary agent for the sweep, then a fresh-context second-opinion turn. Add CLI lanes from different model families for independent research passes.',
+    GAP_ANALYSIS_LANE: supplies('second-coder')
+      ? 'a **different model family** reading the same artifact. Use the selected second-opinion coder lane in read-only mode; verify each finding before acting.'
+      : 'a fresh-context second pass reading the same artifact. Use a different model family when one is available; verify each finding before acting.',
     LANE_STEP0: step0.length ? step0.map((l) => '   - ' + l).join('\n') : '   - none selected yet: every task stays on your primary agent\'s tiers until you add a lane (re-run the installer with more AIs)',
     STAGE1_LANES: stage1.length ? '; ' + stage1.join(', ') : '',
     ATTACK_LANE: has('codex') ? '`cli-run codex --audit` (a second model family in a read-only sandbox)' : 'code-reviewer at deep tier, in a fresh context told to challenge and allowed to answer CLEAN',
@@ -366,15 +400,17 @@ export function activationSteps(opts) {
   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)`);
+  if (opts.applySnippets) steps.push(`applied ${join(dirAbs, snippet)} to the model-orchestrator marked block in ${join(projectAbs, 'CLAUDE.md')}`);
+  else 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`);
   // Only claude-code ships hooks (route-gate, subagent-context): the wiring
-  // lives in a snippet, never written into a settings.json the user already has.
-  if (subagentsLoadRules(primary)) steps.push(`merge the hooks in ${join(dirAbs, 'settings.hooks.snippet.json')} into ${join(projectAbs, '.claude', 'settings.json')} (create it if missing) to wire the route-gate, subagent-context and route-metrics hooks`);
+  // lives in a snippet, applied only when the user opts in.
+  if (opts.applySnippets) steps.push(`applied hooks to ${join(projectAbs, '.claude', 'settings.json')}, preserving existing settings and hooks`);
+  else if (subagentsLoadRules(primary)) steps.push(`merge the hooks in ${join(dirAbs, 'settings.hooks.snippet.json')} into ${join(projectAbs, '.claude', 'settings.json')} (create it if missing) to wire the route-gate, subagent-context and route-metrics hooks`);
   for (const a of selected.filter((a) => a.bin && a.kind === 'agent-cli')) steps.push(`sign in to ${a.name}: ${a.auth}`);
   // A local runtime has a bin but no sign-in, so the agent-cli loop above skips it
   // and before this it appeared in no ordered list at any level (#26).
@@ -442,9 +478,12 @@ function vars(opts) {
   let rulesPath = relative(projectAbs, dirAbs).split(sep).join(posix.sep);
   if (rulesPath === '') rulesPath = '.';
   else if (rulesPath.startsWith('..')) rulesPath = dirPosix; // outside the project: absolute is the only honest path
+  const rulesPathNote = rulesPath === dirPosix
+    ? 'Moved the folder? Re-run the installer or set MODEL_ORCHESTRATOR_RULES_DIR to the rules folder for the hooks, and update the paths in your agent instructions.'
+    : '';
   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 });
+  const steps = activationSteps({ level, selected, primary, tools, dir: opts.dir, project: opts.project, applySnippets: opts.applySnippets });
   const proofs = proofSteps({ level, primary });
   const routingFile = level >= 2 ? 'ROUTING.md' : 'ORCHESTRATOR.md';
   // The path route-gate.mjs and subagent-context.mjs resolve at runtime,
@@ -463,18 +502,32 @@ function vars(opts) {
   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}\``);
+  whereThingsWent.push(rulesPathNote
+    ? '- Rules location: absolute, because this folder is outside the project. ' + rulesPathNote
+    : '- Rules location: project-relative, so moving the project and its rules folder together preserves the paths.');
   return {
     ...laneVars(selected),
     ACTIVATION_STEPS: steps.map((st, i) => `${i + 1}. ${st}`).join('\n'),
     PROOF_STEPS: proofs.map((st, i) => `${i + 1}. ${st}`).join('\n'),
-    LOAD_IT: readsProjectRules
+    LOAD_IT: opts.applySnippets
+      ? 'The installer applied the generated rules to the model-orchestrator marked block in `CLAUDE.md` and merged the hooks into `.claude/settings.json`. Existing files changed by this run have timestamped backups beside them; their paths were printed in the terminal.'
+      : 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.',
+    CLAUDE_SNIPPET_INTRO: opts.applySnippets
+      ? '# Model orchestrator activation\n\nThe installer applied these rules to the marked block in `CLAUDE.md` at your project root.'
+      : "# Add this to your project's CLAUDE.md\n\nCopy the block below into `CLAUDE.md` at your project root (create the file if it does not exist). The installer did not modify any file you already had.",
+    CLAUDE_HOOKS_ACTIVATION: opts.applySnippets
+      ? 'The installer merged the hook entries into `.claude/settings.json` to wire all three in.'
+      : 'Merge `settings.hooks.snippet.json`, written next to this file, into `.claude/settings.json` to wire all three in.',
     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,
+    RULES_PATH_NOTE: rulesPathNote,
+    RULES_PATH_NOTE_COMMENT: rulesPathNote ? '// ' + rulesPathNote : '',
+    RULES_DIR_OVERRIDE_JS: 'process.env.MODEL_ORCHESTRATOR_RULES_DIR',
     ROUTING_FILE: level >= 2 ? 'ROUTING.md' : 'ORCHESTRATOR.md',
     PROJECT_DIR: projectAbs,
     AGENTS_DIR: primary && primary.agentsDir ? join(projectAbs, primary.agentsDir) : 'none (your primary agent has no subagent folder)',
@@ -587,8 +640,7 @@ export function planFiles(opts) {
     add('CLAUDE.snippet.md', render(readFileSync(join(TEMPLATES, 'agents', 'snippets', 'claude-code.md'), 'utf8'), v));
     // Delegate-by-default hooks (0.1.15), claude-code only: route-gate.mjs (UserPromptSubmit)
     // and subagent-context.mjs (SubagentStart) live where Claude Code looks for
-    // project hooks; the wiring snippet is a document the user merges in, never
-    // written into a settings.json they already have.
+    // project hooks; the wiring snippet is merged by hand or with --apply-snippets.
     add(join('.claude', 'hooks', 'route-gate.mjs'), render(readFileSync(join(TEMPLATES, 'agents', 'snippets', 'route-gate.mjs'), 'utf8'), v), 0o755, 'project');
     add(join('.claude', 'hooks', 'subagent-context.mjs'), render(readFileSync(join(TEMPLATES, 'agents', 'snippets', 'subagent-context.mjs'), 'utf8'), v), 0o755, 'project');
     // route-metrics.mjs (0.1.16), claude-code only: five events (UserPromptSubmit,
@@ -810,6 +862,15 @@ export function writeFiles(files, opts) {
     if (!groups[k].length) continue;
     problems.push(...preflight(groups[k], roots[k]).map((p) => (k === 'project' ? `[project] ${p}` : p)));
   }
+  if (!problems.length) {
+    for (const f of files.filter((file) => file.applySnippet)) {
+      const abs = resolve(roots[f.root], f.rel);
+      const current = existsSync(abs) ? readFileSync(abs) : null;
+      if (current === null ? f.original !== null : !Buffer.isBuffer(f.original) || !current.equals(f.original)) {
+        problems.push(`${abs}: changed since snippet planning; re-run the installer`);
+      }
+    }
+  }
   if (problems.length) {
     const e = new Error('refusing to write:\n  ' + problems.join('\n  '));
     e.code = 'PREFLIGHT';
@@ -823,6 +884,7 @@ export function writeFiles(files, opts) {
   const docsUpdated = [];   // --update-docs: documents regenerated because the installed copy was an untouched generated one
   const docsConflict = [];  // --update-docs: documents kept because you edited them
   const docsUnverifiable = []; // --update-docs: documents kept because there is no manifest to compare against
+  const backups = [];
   const created = [];
   // Only directories actually created by this install are owned. Preserve the
   // previous inventory on reruns; legacy manifests deliberately own none.
@@ -851,7 +913,11 @@ export function writeFiles(files, opts) {
         const label = (k === 'project' ? '[project] ' : '') + f.rel.split(sep).join('/');
         const key = label;
         const cls = k === 'dir' ? fileClass(f.rel) : 'document';
-        if (exists && !force) {
+        if (exists && f.applySnippet && Buffer.from(f.content).equals(readFileSync(abs))) {
+          skipped.push(label);
+          continue;
+        }
+        if (exists && !force && !f.applySnippet) {
           if (cls === 'document') {
             // Documents are the user's. Without --update-docs they are never touched.
             // With it, the same hash rule the runtime class uses applies: regenerate
@@ -911,6 +977,17 @@ export function writeFiles(files, opts) {
           }
           content = JSON.stringify(m, null, 2) + '\n';
         }
+        if (exists && opts.backupExisting) {
+          let stamp = Date.now();
+          let backup;
+          do {
+            backup = abs + '.bak-' + new Date(stamp).toISOString().replace(/[-:]/g, '').slice(0, 15);
+            stamp += 1000;
+          } while (existsSync(backup));
+          if (!dry) writeFileSync(backup, readFileSync(abs), { flag: 'wx', mode: statSync(abs).mode & 0o777 });
+          backups.push(backup);
+          if (!dry) opts.onBackup?.(backup);
+        }
         if (!dry) {
           if (exists) originals.set(abs, { content: readFileSync(abs), mode: statSync(abs).mode });
           const missingDirectories = [];
@@ -933,7 +1010,7 @@ export function writeFiles(files, opts) {
           }
           writeFileSync(abs, content, { flag: exists ? 'w' : 'wx' });
           if (!exists) created.push(abs);
-          chmodSync(abs, f.mode);
+          if (!exists || !f.applySnippet) chmodSync(abs, f.mode);
         }
         written.push(label);
       }
@@ -956,7 +1033,7 @@ export function writeFiles(files, opts) {
     }
     throw e;
   }
-  return { written, skipped, upgraded, conflicts, unverifiable, docsUpdated, docsConflict, docsUnverifiable };
+  return { written, skipped, upgraded, conflicts, unverifiable, docsUpdated, docsConflict, docsUnverifiable, backups };
 }
 
 export function resolveSelection(ids) {

package/src/plugin.js

@@ -32,6 +32,9 @@ export const HAND_OWNED = ['README.md', 'hooks/hooks.json'];
 export function pluginVars() {
   return {
     PRIMARY_NAME: 'Claude Code',
+    RULES_PATH_NOTE_COMMENT: '',
+    // Plugin hooks retain their existing project-root-only environment access.
+    RULES_DIR_OVERRIDE_JS: "''",
     RULES_FILE_REL: DEFAULT_RULES.join(' or '),
     RULES_FILE_REL_JSON: JSON.stringify(DEFAULT_RULES[0] + ' (' + DEFAULT_RULES[1] + ' on a level 1 install)'),
     TASK_BUNDLE_REL_JSON: JSON.stringify(DEFAULT_TASK_BUNDLE),

package/src/uninstall.js

@@ -1,6 +1,6 @@
 import { closeSync, constants, fstatSync, lstatSync, openSync, readFileSync, readdirSync, rmdirSync, unlinkSync } from 'node:fs';
 import { createHash } from 'node:crypto';
-import { isAbsolute, join, relative, resolve, sep, win32 } from 'node:path';
+import { basename, dirname, isAbsolute, join, relative, resolve, sep, win32 } from 'node:path';
 import { dirProblems, realRoot } from './install.js';
 
 const hash = (bytes) => createHash('sha256').update(bytes).digest('hex');
@@ -112,6 +112,18 @@ export function uninstallFiles({ dir, project, dry = false }) {
   }
 
   const actions = [];
+  const backupTargets = [...files, manifest];
+  if (data.primary === 'claude-code') backupTargets.push(entry('[project] CLAUDE.md', roots), entry('[project] .claude/settings.json', roots));
+  for (const item of backupTargets) {
+    const parent = dirname(item.abs);
+    if (!inspect({ root: item.root, abs: parent, directory: true })) continue;
+    const prefix = basename(item.abs) + '.bak-';
+    for (const name of readdirSync(parent).sort()) {
+      if (name.startsWith(prefix) && /^\d{8}T\d{6}$/.test(name.slice(prefix.length))) {
+        actions.push('  keep backup ' + join(parent, name));
+      }
+    }
+  }
   const pending = [];
   let edited = false;
   for (const item of files) {

package/templates/agents/snippets/claude-code.md

@@ -1,11 +1,10 @@
-# Add this to your project's CLAUDE.md
-
-Copy the block below into `CLAUDE.md` at your project root (create the file if it does not exist). The installer did not modify any file you already had.
+{{CLAUDE_SNIPPET_INTRO}}
 
 ```markdown
 ## Model orchestrator
 
 Routing rules live in `{{RULES_PATH}}/{{ROUTING_FILE}}`. Read them before any build task. Quick version, first match wins:
+{{RULES_PATH_NOTE}}
 
 1. Bulk, mechanical, many similar items -> bulk-worker (fast tier).
 2. Needs live data -> live-researcher (standard tier + tools).
@@ -28,6 +27,6 @@ Numbers, comparisons, complexity and equivalence claims go through codecalc (or
 Anything durable is searched for before it is written and its folder index is corrected in the same pass; one writer per run: `{{RULES_PATH}}/protocols/memory-and-record.md`.
 ```
 
-Subagents were written to `{{AGENTS_DIR}}` (the project root, which is where Claude Code reads project-level agents; `--project` changes it). Run `claude` from `{{PROJECT_DIR}}` and they are available as {{AGENTS_LIST_LINE}}.
+Subagents were written to `.claude/agents/` under the project root, which is where Claude Code reads project-level agents (`--project` selects that root). Run `claude` from your project root and they are available as {{AGENTS_LIST_LINE}}.
 
-Three hooks were written to `{{AGENTS_DIR}}/../hooks/` (`.claude/hooks/`): `route-gate.mjs` injects the routing table on every prompt, `subagent-context.mjs` reminds a spawned subagent where the rules and the task-bundle format live, and `route-metrics.mjs` appends each turn's route marker and subagent dispatch to a local `route-metrics.jsonl` log (read it with `node .claude/hooks/route-metrics.mjs --summary`). Merge `settings.hooks.snippet.json`, written next to this file, into `.claude/settings.json` to wire all three in.
+Three hooks were written to `.claude/hooks/` under the project root: `route-gate.mjs` injects the routing table on every prompt, `subagent-context.mjs` reminds a spawned subagent where the rules and the task-bundle format live, and `route-metrics.mjs` appends each turn's route marker and subagent dispatch to a local `route-metrics.jsonl` log (read it with `node .claude/hooks/route-metrics.mjs --summary`). {{CLAUDE_HOOKS_ACTIVATION}}

package/templates/agents/snippets/generic.md

@@ -6,6 +6,7 @@ Your agent, {{PRIMARY_NAME}}, reads `{{PRIMARY_RULES_FILE}}` from the project ro
 ## Model orchestrator
 
 Routing rules live in `{{RULES_PATH}}/{{ROUTING_FILE}}`. Read them before any build task.
+{{RULES_PATH_NOTE}}
 
 Route by capability tier, first match wins: bulk and mechanical -> fast tier · needs live data -> standard tier with tools · review without changing -> standard, read-only · ambiguous or expensive to get wrong -> deep tier, then hand the plan down · everything else -> build it directly at standard tier.
 

package/templates/agents/snippets/route-gate.mjs

@@ -12,7 +12,7 @@
 // a full read of an arbitrarily large or non-regular file), and never
 // executes anything it reads. See docs/audit-brief.md for the security notes.
 import { statSync, openSync, readSync, closeSync, realpathSync } from 'node:fs';
-import { join, isAbsolute } from 'node:path';
+import { join, isAbsolute, basename } from 'node:path';
 
 // One template, two renders. The installer renders a one-element list from
 // the level and directory the user chose: a level 1 install points it at
@@ -22,6 +22,7 @@ import { join, isAbsolute } from 'node:path';
 // render from, so it lists the installer's default locations and reads the
 // first one that exists.
 const RULES_CANDIDATES = {{RULES_CANDIDATES_JSON}};
+{{RULES_PATH_NOTE_COMMENT}}
 const RULES_FILE_REL = RULES_CANDIDATES.join(' or ');
 // Empty in an installer render, whose rules file was written by the same run.
 // The plugin renders a next step for a project that has no rules yet, so a
@@ -68,6 +69,8 @@ function projectRoot() {
 }
 
 function resolveRulesPath(rel, root) {
+  const override = {{RULES_DIR_OVERRIDE_JS}};
+  if (override) return isAbsolute(override) ? join(override, basename(rel)) : root ? join(root, override, basename(rel)) : null;
   if (isAbsolute(rel)) return rel;
   return root ? join(root, rel) : null;
 }

package/templates/agents/snippets/route-metrics.mjs

@@ -34,6 +34,8 @@ import {
 import { join } from 'node:path';
 import { homedir } from 'node:os';
 
+// Telemetry has no rules lookup: MODEL_ORCHESTRATOR_RULES_DIR changes the
+// two context hooks, while metrics keep their existing home-directory log.
 const HOME_DIR = join(homedir(), '.ai-orchestrator');
 const LOG_FILE = join(HOME_DIR, 'route-metrics.jsonl');
 const STATE_DIR = join(HOME_DIR, 'route-metrics.state');

package/templates/agents/snippets/subagent-context.mjs

@@ -11,14 +11,22 @@
 // Fail-open by design: a miss here is a stray context string, not a gate.
 // This script always exits 0, never executes anything it reads, and never
 // blocks on stdin past a short bound (see drainStdin below).
-import { isAbsolute } from 'node:path';
+import { isAbsolute, join, basename } from 'node:path';
 
 // Rendered at install time so a --dir outside the project still names an
 // honest path rather than a hardcoded one.
-const RULES_FILE_REL = {{RULES_FILE_REL_JSON}};
-const TASK_BUNDLE_REL = {{TASK_BUNDLE_REL_JSON}};
+{{RULES_PATH_NOTE_COMMENT}}
+const RULES_FILE_REL = {{RULES_DIR_OVERRIDE_JS}}
+  ? {{RULES_CANDIDATES_JSON}}.map(rulesPath).join(' or ')
+  : {{RULES_FILE_REL_JSON}};
+const TASK_BUNDLE_REL = rulesPath({{TASK_BUNDLE_REL_JSON}});
 const STDIN_DRAIN_MS = 250; // hard cap: never let an open, never-closed stdin pipe hold this hook open
 
+function rulesPath(baked) {
+  const override = {{RULES_DIR_OVERRIDE_JS}};
+  return override ? join(override, basename(baked)) : baked;
+}
+
 const additionalContext = [
   'SUBAGENT CONTEXT (model-orchestrator).',
   'Routing rules: ' + RULES_FILE_REL + (isAbsolute(RULES_FILE_REL) ? '.' : ' (relative to the project root).'),

package/templates/common/protocols/deep-research.md

@@ -33,9 +33,9 @@ Agreement is weak evidence. Disagreement is the signal.
 
 You still get the shape. Run PLAN as its own turn and inspect it before spending anything. Run the sweep. Then run a **fresh-context second-opinion turn** with a brief that says "question the premise; list what this report would get wrong if its sources were stale". Plant one deliberately wrong figure in the brief and see whether it corrects it: if it does not, its confirmations are worth less than they look. Mark every claim.
 
-## Level 2 and up: three engines, one triager
+## Level 2 and up: selected engines, one triager
 
-Fan out the same PLAN to three different model families through their CLIs (a web-sweep lane, a second-opinion-read lane, a live-data lane). Run them through `cli-run` so a run that produced nothing is caught as `rc=10` rather than read as an empty finding. The orchestrator triages: it opens the primary sources itself, marks each claim, and writes the brief. Only the orchestrator writes the durable record; every other engine proposes.
+{{RESEARCH_SELECTION_ADVICE}} The orchestrator triages: it opens the primary sources itself, marks each claim, and writes the brief. Only the orchestrator writes the durable record; every other engine proposes.
 
 Known failure shape: one engine will return confident unsourced numerics and claim full coverage. Downgrade those to hypothesis. The engines that report their own gaps honestly are the ones to weight.
 

package/templates/common/protocols/gap-analysis.md

@@ -14,7 +14,7 @@ Verification asks "is what I did correct?". Gap analysis asks "what did I not do
 ## Who runs it
 
 - **Level 1 (one agent):** the same agent, in a fresh turn, with a brief that says "you are looking for what is missing; do not re-verify what is present". Fresh context matters more than a different model.
-- **Level 2 and up:** a **different model family** reading the same artifact. Disagreement between two families is the cheapest available signal that something is soft. The second-opinion coder lane (read-only mode) is the natural fit.
+- **Level 2 and up:** {{GAP_ANALYSIS_LANE}}
 - **Level 3:** make it recurring. A weekly audit job enumerates live state (lanes, jobs, services, model lists), diffs it against the plan, and files a report. It catches the dead lane and the silently renamed model nobody noticed.
 
 ## The second half: analyze, compare, suggest

package/templates/intermediate/DELEGATION_MATRIX.md

@@ -12,20 +12,7 @@ Generated {{DATE}} from the AIs you said you have: `{{AI_IDS}}`.
 
 ## Task → lane
 
-| Task type | Pick | Why |
-|---|---|---|
-| Bulk classify / extract / summarize, data may leave the machine | the cheapest metered lane, then the fast tier | cost gap is an order of magnitude; batch APIs add more |
-| Bulk work on data that must stay local | the local lane | a privacy lane, never a cost lane; route here for confinement, not to save money |
-| Many independent items each needing its own agent turn | a concurrent fan-out lane | one call, N children, on a subscription |
-| Live web or social reads | the live-data CLI | subscription-covered; the same search on the API bills per call |
-| Code review, no changes | standard tier, or the second-coder CLI | a different model family catches what one misses |
-| Second-opinion audit of a security-shaped diff | the second-coder CLI in read-only audit mode | Claude writes, a second family challenges, the orchestrator reproduces |
-| Deep architecture / planning | deep tier | expensive to get wrong |
-| Well-specified execution | the orchestrator | execution does not need the top tier |
-| Long-document analysis | the largest-context lane, or caching on the primary | window size vs re-query cost |
-| Routing decisions themselves | the cheapest lane you have, or none | never spend deep tokens deciding not to use deep |
-| Rough drafts, divergent reads, first-pass summaries | the free tier | $0, and disagreement with the primary is information |
-| Anything citing a line, a number, or a source | never the cheapest metered lane without a full verification pass | measured: conclusions right, every supporting number invented |
+{{TASK_LANES_TABLE}}
 
 ## Install and sign-in
 
@@ -33,12 +20,7 @@ Generated {{DATE}} from the AIs you said you have: `{{AI_IDS}}`.
 
 ## Cost playbook
 
-1. Prompt caching everywhere it fits: frozen prefix first, volatile text last.
-2. Cascade: cheapest capable tier first, escalate on signal.
-3. Batch APIs for anything not latency-sensitive.
-4. A free or local model for routing decisions.
-5. Effort and reasoning knobs before model swaps; often the bigger lever.
-6. Alias-based config so a vendor rename is a one-line repoint.
+{{COST_PLAYBOOK}}
 
 ## Privacy gate
 

package/templates/intermediate/RESEARCH_TRIAGE.md

@@ -1,6 +1,6 @@
 # RESEARCH_TRIAGE.md: engines in parallel, one triager
 
-The deep-research lane at level 2: fan the same plan out to different model families through their CLIs, then triage against primary sources you open yourself.
+{{RESEARCH_SELECTION_ADVICE}} Then triage against primary sources you open yourself.
 
 Your `cli-run` lanes: {{CLI_RUN_LANES}} ({{RESEARCH_ENGINES}} research engine(s) below). Everything in this file was rendered from that selection; a lane that is not listed is not one you have.
 
@@ -19,7 +19,7 @@ BRIEF=research/brief.md      # purpose, sub-questions, source standard, report c
 {{RESEARCH_RUN}}
 ```
 
-Then the orchestrator reads the three outputs, opens every primary source that carries a decision, and writes one dated brief with marks: **CONFIRMED** (two engines + primary source) · **DISAGREEMENT** (both readings kept) · **REPORTED** (someone's own post, quoted not trusted) · **UNVERIFIED**.
+Then the orchestrator reads the available outputs, opens every primary source that carries a decision, and writes one dated brief with marks: **CONFIRMED** (two engines + primary source) · **DISAGREEMENT** (both readings kept) · **REPORTED** (someone's own post, quoted not trusted) · **UNVERIFIED**.
 
 ## Triage discipline
 

package/templates/intermediate/ROUTING.md

@@ -18,7 +18,7 @@ Rule of thumb: never spend a frontier token on a task a cheap tier finishes corr
 
 0. **Is there a cheaper or better external lane for this?** Check `DELEGATION_MATRIX.md`. Your enabled lanes, every one called through `bin/cli-run.mjs`:
 {{LANE_STEP0}}
-1. **Bulk and mechanical?** → fast tier{{BULK_LANE}}. Many independent items each needing its own agent turn → a concurrent fan-out lane if you have one.
+1. **Bulk and mechanical?** → fast tier{{BULK_LANE}}.{{FAN_OUT_ADVICE}}
 1a. **Reading or digesting many files or notes, not writing?** → reader. Different from a bulk pass: reader reports, it does not classify, tag or transform.
 2. **Needs live data?** → {{LIVE_LANE}} standard tier with web tools.
 3. **Reviewing without changing?** → standard tier read-only. Security-critical → {{ATTACK_LANE}}.
@@ -48,7 +48,7 @@ Caps: two deep-tier checkpoints per build. CLI lanes are $0 and do not count.
 
 ## Numbers and logic
 
-Every number, comparison, complexity or equivalence claim goes through a tool that computes (`protocols/numbers-and-logic.md`; companion: codecalc, {{CODECALC_STATUS}}). A lane's figure is re-derived before it is repeated: the cheapest metered lane measured 0 of 11 line citations correct while its conclusions were right.
+Every number, comparison, complexity or equivalence claim goes through a tool that computes (`protocols/numbers-and-logic.md`; companion: codecalc, {{CODECALC_STATUS}}).{{METERED_CITATION_NOTE}}
 
 ## Memory and record