model-orchestrator 0.1.34 → 1.0.0

package/docs/how-it-routes.md

@@ -1,60 +1,67 @@
-# How it routes
+# How the model router chooses work
 
-The reasoning behind the lane choice, and the three verifier agents that keep a routed answer honest. Install mechanics are in [install.md](install.md).
+Your agent reads the installed routing rules and chooses a model and tools for each task. A **lane** is a tool or model that can receive work. A **tier** describes model strength and cost: planning model, working model or cheap model. [Installation](install.md) writes the rules for your selection.
 
 ## Routing by role, complexity and stakes
 
-Role picks the agent. Two more inputs move the choice, and they move it in
-different directions, so `TIERS.md` states them separately rather than folding
-them into the role:
+- **Role selects the job:** bulk work, reading, live data, review, finding verification, definition-of-done verification, planning or building.
+- **Complexity sets effort:** a clear transformation and an unresolved architectural choice require different reasoning.
+- **Stakes select the model and reviewer:** security, privacy, data loss and irreversible changes need checks suited to the consequences of a mistake.
+- **Availability limits the choice:** check tools, model names, permissions and remaining headroom before assigning work.
 
-- **Complexity moves the effort.** A worker executing a finished plan needs less
-  reasoning than the reviewer judging its output. When the plan is airtight the
-  spec is carrying the thinking.
-- **Stakes move the tier and the reader.** Security, privacy, data loss and
-  irreversible changes buy the challenge lane, a named check, a rollback path or
-  a human yes. A one-line change to an auth check is simple and high-stakes at
-  the same time, and it is the stakes that decide.
+`aunx route "rename this file"` prints a cheap bulk-work suggestion. `aunx route "design the auth system"` prints a deep-planning suggestion. These are keyword classifications, labelled as suggestions. An unmatched request points to `ROUTING.md` for a decision with the full context.
 
-Stakes means what a mistake would cost: a security hole, leaked personal data,
-lost data, or something you can't undo. Most tasks are low-stakes and route
-normally.
+## Your stack: who does what
 
-The top of the ladder is bought with evidence: a reproduced failure, an
-unresolved checkpoint, an irreversible change. A task that merely feels hard is
-a deep-tier task, not an escalation.
+Each install assigns jobs from the selected AIs' capability facts. The same inputs give the same assignment, stored in `MANIFEST.json` and rendered in the installed README, routing rules and delegation matrix. Selection order breaks ties; a detected binary is an advisory marker and leaves the assignment unchanged.
 
-## A finding is a claim, not a fact
+| Role | Selection rule |
+|---|---|
+| Plan | Prefer the main agent, then the largest known context capacity |
+| Build | Require file writes and main-agent access or a headless runner; prefer the main agent, then project-rule loading and agent definitions |
+| Review | Require a supported runner and a known model family different from the main agent; prefer read-only mode, then billing order |
+| Verify | Use the main agent or a supported runner; prefer a different known model family, then billing order |
+| Research | Require stated live-web access; prefer billing order |
+| Bulk | Require a headless supported runner; prefer billing order, then known input pricing when both options are pay-per-token |
+| Read | Prefer the main agent, then the largest known context capacity |
+| Private | Require a runtime that keeps work on your machine |
+| Fan-out | Show when a selected tool states that one call starts several children; prefer billing order |
+| Long-context | Show when a selected tool's known context capacity exceeds the main agent's; prefer the largest |
 
-Review findings do not go straight to a repair. `finding-verifier` reads the
-cited line, states what would trigger the problem, then hunts for the guard,
-caller or test that makes it impossible, and returns **CONFIRMED**,
-**NOT_REPRODUCED** or **INCONCLUSIVE** per finding. Only CONFIRMED earns a
-change. Use a different model family from the one that produced the finding
-where you have one: a family asked to check its own claim tends to agree with
-itself.
+Billing order is local, free, subscription, then pay-per-token. Unknown prices leave ties in selection order and require checking your provider's rate. Unknown capabilities render as **unverified** and cannot satisfy a role requirement. Two inherited capabilities remain true with **UNVERIFIED against a vendor doc** beside them: Antigravity's fan-out and Grok's live-web tools. Their current vendor behavior needs verification.
 
-## Two more fast-tier checks
+When a separate lane is unavailable, the main agent carries the job at its named tier. Review and private work are exceptions: the table says **none selected**. A fresh-context review on your main agent is a self-check; independent review needs a known different model family. If the main agent's family is unknown, independence is unverified. With no local runtime, keep private work off the selected lanes.
 
-`done-verifier` probes the artifact a tracker item's done-signal names (a file, a commit, a URL, a log line, a count) and returns MET, NOT_MET or UNVERIFIABLE; it never closes or edits anything itself. It carries no file-editing tools, but on claude-code it does carry `Bash` for those probes (`git log`, `grep`, `wc -l`, `test -f`); staying to read-only commands there is a rule in its prompt, not a restriction on the tool grant, and its own description says so. On agy, `commandExecutionPolicy: off` blocks command execution mechanically instead. `reader` is the one that is read-only by tool grant on both: no `Write`, `Edit`, or `Bash`. It reads and digests many files or notes and hands back exactly what the brief asked for, cited by `path:line`; it never classifies, tags or writes, which is what separates it from `bulk-worker`. Both ship in the claude-code and agy agent sets, at the fast tier.
+`aunx route` reads the assigned role from the current manifest, even if you preserve edited routing documents during an upgrade. Pass `--dir PATH` for a custom rules folder. It tries that manifest, then `./ai-orchestrator/MANIFEST.json`, then `./MANIFEST.json`. With no usable manifest it keeps the generic suggestion and adds an install notice. It reads bounded regular JSON files and executes no project code.
 
-## Pin the route, or know that you did not
+## Verify a review finding
 
-A lane with no `--model`, no `--effort` and no `defaults` entry in
-`bin/lanes.json` runs on **its own config file**, which `cli-run` cannot see. A
-CLI configured months ago at a low reasoning effort keeps auditing at that
-effort while your routing docs describe a second-opinion pass.
+When a review returns a finding, use the assigned verification role to read the cited line, state the trigger and look for a caller, guard or test that disproves it. Where an agent set is installed, `finding-verifier` supplies this prompt. It returns **CONFIRMED**, **NOT_REPRODUCED** or **INCONCLUSIVE**. A confirmed finding gets a repair and a regression check capable of failing before the fix.
+
+Use a different model family for the review when one is available. The build protocol has one audit step: the reviewer checks the build against its scope, while a companion reviewer checks the scope against the user's ask. Fix verification follows the reproduced regression; a second full audit pass is outside that sequence.
+
+## Check completion and digest many files
+
+Use the verification role to probe the artifact named in a definition of done. Where installed, `done-verifier` supplies this prompt and returns MET, NOT_MET or UNVERIFIABLE. On Claude Code it has Bash for read-only probes, so that behavior is instructed by its prompt rather than restricted by the tool grant. It has no file-editing tools. Antigravity's command-execution policy blocks commands for that agent.
+
+The read role digests many files into a cited answer. Where installed, `reader` supplies this prompt; its tool grants contain neither Bash nor file-editing tools. Use the bulk role when the job includes classification or writing.
+
+## Choose and record model and effort
+
+Agent definitions specify planning, working or cheap model tiers and use your plan's configured model. Every current plan mapping is unverified, so generated definitions omit `model:`. Claude Code can use `CLAUDE_CODE_SUBAGENT_MODEL`; a manual `model:` line can pin a verified choice. Antigravity defaults to its inherited model. Support for Claude Code's `xhigh` and `max` effort on every plan is UNVERIFIED.
+
+Probe your vendor's current roster, then request the model and effort the task needs. Replace `<lane>` with a supported CLI named in your stack table. These examples use `--effort`; for a lane whose runner does not support that flag, omit it and configure the model directly:
 
 ```bash
-node bin/cli-run.mjs codex "<prompt>" --model gpt-6-astra --effort high
-node bin/cli-run.mjs --doctor     # prints what each lane is pinned to, and what is not pinned
+aunx cli-run '<lane>' --brief TASK_BRIEF.md --model '<model-id>' --effort high
+# Direct form from the installed rules folder:
+node bin/cli-run.mjs '<lane>' --brief TASK_BRIEF.md --model '<model-id>' --effort high
+aunx cli-run --doctor
+# Direct form: node bin/cli-run.mjs --doctor
 ```
 
-Every run logs the model and effort **requested** and where the request came
-from: `flag`, `lanes.json`, or `lane_default`, on every record including the
-runs that never reached a lane. It does not log an actual. One lane of five
-(grok) reports a model id in its own output and the other four report none, so
-an actual field would be present for one lane and missing for four, and it
-would be a provider-supplied string, which the durable log deliberately never
-holds.
+Explicit flags override defaults in `bin/lanes.json`. Without either, the vendor CLI uses its own configuration. The runner records what was requested and the source of each request: `flag`, `lanes.json` or `lane_default`. These fields describe requested settings; the vendor's own reporting is the place to verify the actual model used.
+
+## Share facts once, then scope each worker
 
+Use `aunx context CONTEXT.md` to scaffold one context file for the run. Use `aunx brief new TASK_BRIEF.md` to quote the ask, name the output, bound edits, list checks and record what the worker has and lacks. Every worker reads the same context file; each brief defines its own section and reports coverage against it.

package/docs/install.md

@@ -2,35 +2,66 @@
 
 Everything the installer asks, writes and accepts as a flag. The short version is in the [README](../README.md).
 
+## Install walkthrough
+
+![Terminal walkthrough of the installer](demo.gif)
+
+This recording shows the published 0.1.x installer. Version 1.0 detects your tools and asks for one confirmation. Companions start unselected, and third-party installation instructions are printed for you to run. Re-record from the published release with `bash scripts/record-demo.sh`.
+
 ## What a run does
 
 
-The installer asks a few things, then writes a folder:
+The installer detects the AI binaries on your PATH, proposes a setup and shows **Your stack: who does what** before writing. The default flow asks exactly one question:
+
+```text
+Write these files?
+[Y/n/e]  (e to change anything above):
+```
 
-1. **Which level?** 1 beginner · 2 intermediate · 3 advanced
-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)
+- **Confirm:** press Enter or `y` to write the displayed files and apply the displayed project activation changes. Existing files changed outside the rules folder get backups. `n` exits without writing.
+- **Edit:** enter `e`, choose one setting and return to the summary. The edit menu includes activation, level, AIs, main agent, companions, paths and plans; level 3 also includes API providers. Turn activation off here or pass `--no-apply`.
+- **No detected tools:** answer "Which AIs do you have access to?" first, then confirm. This path asks two questions.
+- **Defaults:** one selected tool starts at level 1; several tools including a supported worker start at level 2, subject to each tool's minimum level. Level 3 requires an explicit choice. Companions and API providers start unselected.
+- **Main agent:** capability ranking prefers project-rule-loading subagents, then an agent-definition surface, then a CLI with a project rules file. Ties keep selection order.
+- **Overrides:** explicit flags take precedence and appear in the plan. Existing recorded plans and automatic-effort consent survive a rerun.
 
-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).
+The installer never writes a secret, runs no third-party installer, and preserves existing documents by default. `--force` explicitly replaces them. Interactive activation updates the main agent's project rules and supported settings with backups; `--yes` requires `--apply-snippets` for those changes. The summary lists every project file it will change before confirmation.
 
-## Apply Claude Code snippets
+`MANIFEST.json` and `bin/lanes.json` are machine-owned and refreshed on every run. Runtime files upgrade when their content matches the previous installed hash; edited or unverifiable copies stay and are named. `--upgrade-runtime` replaces runtime files only. `--update-docs` applies the same hash check to generated documents, preserving your edits. Docs and protocols go to `--dir` (default `./ai-orchestrator`). Supported subagent definitions and Claude Code hook scripts go to `--project` (default the current directory); their locations appear in the summary.
 
-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.
+Every non-dry install runs a compact local health check. The final **What's left for you** section lists remaining actions, such as sign-ins or a chat app's paste step, and says when nothing remains. The generated `README.md` explains activation for the selected main agent and level. [Uninstall](#uninstall) removes recorded activation changes as well as unedited managed files.
 
-- **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.
+The manifest's `roles` assignment is refreshed on every run. If a changed assignment leaves edited documents in place, the installer names that difference: `aunx route` uses the current manifest while those documents retain your edits. Use `--update-docs` to regenerate unchanged managed documents.
+
+## Project activation
+
+Interactive installs apply activation by default as part of the one confirmation. Turn it off with `--no-apply` or the edit screen. Headless `--yes` preserves 0.1.x behavior: add `--apply-snippets` to apply activation; without it, project rules and settings remain untouched.
+
+- **Rules:** the catalog selects the main agent's project rules file: `CLAUDE.md`, `AGENTS.md`, `GEMINI.md` or `QWEN.md`. A block between `<!-- model-orchestrator:start -->` and `<!-- model-orchestrator:end -->` is created or replaced in place, keeping every byte outside it. Incomplete or duplicate markers are refused before writing.
+- **Hooks:** a Claude Code main agent gets its generated hooks merged into `.claude/settings.json`, preserving existing keys and hooks. A command with the same arguments already present in that event is kept once. Invalid JSON exits 2, names the file and writes nothing.
+- **Companions:** a Claude Code main agent gets selected tools registered in the project's `.mcp.json` when activation is enabled. Existing settings and server names stay; a conflicting server entry becomes a printed step. Other main agents retain manual registration steps because the catalog has no verified project config target for them. `obsidian-tc` also needs your actual configuration path. No global config is changed.
+- **Backups:** existing files changed during application get sibling `<name>.bak-YYYYMMDDTHHMMSS` backups, including generated files replaced on a rerun. Each path is printed; unchanged and newly created files need no backup. Existing backups are preserved.
+- **Preview:** `--dry` and `--dry-run` list the proposed writes and backups without changing files or running the health check. For a headless activation preview, pass `--yes --apply-snippets --dry` with your selection and paths.
+- **Manual surfaces:** a chat app keeps one paste step. A main agent without a catalog-supported project rules file keeps its instruction step. `--no-apply` leaves the relevant rules, hook and companion merge steps in the final list.
+- **Removal:** the manifest records the applied block and added hook and MCP entries. Uninstall removes unchanged owned entries and preserves surrounding content, existing entries and backups. Edited owned content is kept and named for review.
 
 ```bash
 npx model-orchestrator --yes --level 2 --ais claude-code,codex --primary claude-code --project . --dir ./ai-orchestrator --apply-snippets
 ```
 
+## Health check and sign-in
+
+Every non-dry install runs the existing runner's `--doctor` presence check automatically, with no network or prompt sent. A missing CLI is reported alongside its installation command; the installer never runs that command. `--doctor --run` remains an explicit live check through your own vendor sign-ins.
+
+Sign-in status is checked only when the catalog records a reliable command. Codex uses `codex login status`; a confirmed session removes its sign-in from **What's left for you**, and a confirmed sign-out prints a direct "sign in to Codex" step. Claude Code uses `claude auth status` and trusts only a confirmed sign-in the same way, but never a confirmed sign-out: an author-machine probe found a working, signed-in session that still reports a JSON sign-out, so any result other than a confirmed sign-in keeps the conditional "if you have not signed in yet" step for Claude Code. Every other CLI gets that same conditional step followed by its sign-in instruction. The installer never runs a login flow.
+
+Start a fresh agent session in the displayed project to load the installed rules. For a later presence check, use `aunx cli-run --doctor`, or at level 2 and up `node ./ai-orchestrator/bin/cli-run.mjs --doctor` with your chosen rules path.
+
 ## Plans and automatic effort
 
-State known subscription plans with `--plans codex=pro-20x,agy=ultra-5x`. The generated guidance uses plan headroom to allocate volume only. It never changes capability or independent-review rules. `--effort-auto` is explicit consent to set `auto` only for selected high or max headroom CLI lanes. Auto chooses medium below 4,000 prompt characters and high otherwise, never higher. A codex audit is always high. Name `xhigh` explicitly for security-critical or irreversible work.
+State known subscription plans with `--plans codex=pro-20x,agy=ultra-5x`, or choose subscription plans from the edit menu. The generated guidance uses plan headroom to allocate volume only. Every catalog plan currently has an unverified model mapping, so agent definitions omit `model:` and use your tool's configuration. Probe the available models before dispatching work. Claude Code also honors `CLAUDE_CODE_SUBAGENT_MODEL`; a manual `model:` line can set a verified choice. Plan support for `xhigh` and `max` effort remains UNVERIFIED.
+
+`--effort-auto` is explicit consent to set `auto` only for selected high or max headroom CLI lanes. Auto chooses medium below 4,000 prompt characters and high otherwise, never higher. An audit lane may impose its own effort floor; check its configuration. Name `xhigh` explicitly for security-critical or irreversible work. The default install skips plan and effort questions; choosing plans in the edit menu enables the effort choice in that same step.
 ## The two folders every run writes to
 
 An install has two targets, and a scripted run should set both.
@@ -38,26 +69,45 @@ 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 or apply with `--apply-snippets`. |
+| `--project` | the current directory | the main agent's supported subagent definitions: `.claude/agents/` for Claude Code or `.agents/agents/` for Antigravity; Claude Code's hook scripts in `.claude/hooks/`. With activation enabled, the catalog-supported rules file, Claude Code's `.claude/settings.json` and selected companion entries in its `.mcp.json` are merged with backups. |
 
-`--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.
+`--project` defaulting to the current directory is the one that surprises people: run the command from your home folder with Claude Code as the main agent 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
+## Headless installation
+
+`--yes` requires both `--level` and `--ais`, giving scripted installs an explicit selection. It never prompts and applies project activation only with `--apply-snippets`. Detection-based inference applies to the interactive flow. All existing flags remain available, including `--primary`, `--tools`, `--plans`, `--apis`, `--no-tools` and `--no-install`.
 
 ```bash
 # 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,context7 to choose.
+# Companions default to none, including with --yes.
+# Add --tools codecalc,obsidian-tc,context7 to write their guides and snippets.
 
 npx model-orchestrator --yes --level 3 --ais claude-code,codex,agy,grok,hermes,qwen,ollama --apis anthropic,openrouter --dry   # print the plan, write nothing
 npx model-orchestrator --yes --level 2 --ais claude-code,codex --project ~/my-app --dir ~/my-app/ai-orchestrator --no-tools  # subagents into ~/my-app/.claude/agents
 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
 ```
 
+## Upgrading from 0.1.x
+
+Use the same project and rules folder as your existing install. Preview first:
+
+```bash
+npx model-orchestrator@1 --yes --level 2 --ais claude-code,codex --primary claude-code --project . --dir ./ai-orchestrator --update-docs --dry
+```
+
+- **Documents:** `--update-docs` replaces only files matching their recorded installed hashes. The former brief filename migrates to `TASK_BRIEF.md` when unedited. An edited legacy brief stays and is named so you can move your changes deliberately.
+- **Runtime:** unchanged managed runtime files upgrade automatically. Use `--upgrade-runtime` when you intend to replace an edited runtime; it leaves document edits alone.
+- **Companions:** existing codecalc guides and snippets stay managed. New installs select none unless you pass `--tools`. `--uninstall` still removes companion files only when unedited.
+- **Activation:** interactive reruns apply the main agent's catalog-supported project rules and settings with backups; turn this off with `--no-apply`. Headless reruns require `--apply-snippets` for activation changes.
+- **Compatibility:** every 0.1.x installer flag remains accepted. `--no-tools` and `--no-install` remain accepted for older scripts.
+- **Verification:** remove `--dry` to apply. The health check runs automatically; start a fresh agent session to load the updated rules.
+
+The installer writes its own files and the displayed project activation changes. Missing selected CLIs and companions appear in one **Install these yourself** block with official commands and links.
+
 ## Uninstall
 
 Use the same `--dir` and `--project` paths you installed with. The uninstall reads `MANIFEST.json` under `--dir` and checks every recorded path before removing any file.
@@ -71,42 +121,94 @@ npx model-orchestrator --uninstall --dir ./ai-orchestrator --project ./my-app
 
 - **Unedited files:** removed when their content hash matches the manifest.
 - **Edited files:** kept and listed by path, with the manifest retained so you can review them.
+- **Applied activation:** an unchanged recorded rules block and the exact hook or MCP entries added by the installer are removed. Existing entries and surrounding content stay. An edited owned entry stays and is named; the manifest remains for a later retry.
+- **Backups:** existing project files changed during cleanup get backups. Timestamped backups stay for a reviewed restore.
 - **Other files:** anything outside the manifest stays, including your own files in shared `.claude/agents/` and `.claude/hooks/` folders.
 - **Directories:** removed only when the manifest records that the installer created them and they are empty after removal. Older manifests leave directories in place because they carry no directory ownership record.
 - **Manifest:** removed last, only when every managed file has been removed.
 - **Path safety:** an absolute path, traversal entry, or symlink is refused before any removal. Entries must stay inside their declared `--dir` or `--project` root.
+- **Global configuration:** installation and uninstall refuse home-level agent rules and global agent folders such as `~/.claude` and `~/.codex`. Choose a project directory below your home folder for project activation.
 - **Missing manifest:** exits 2 and names the expected `MANIFEST.json` path.
 - **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`. 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.
+Manually pasted activation from an older install has no ownership record, so the command prints its cleanup steps. Applied blocks use `<!-- model-orchestrator:start -->` and `<!-- model-orchestrator:end -->`. Review any retained entry or backup before changing it so later edits survive.
 
 ## What gets written (level 3, everything)
 
+The tree shows the activation alternatives. Each install writes the main agent's snippet and its supported agent set; companion files appear when selected. Paths beginning with `<project>/` are relative to `--project`, separate from the rules folder.
+
 ```
 ai-orchestrator/
   README.md                 start here, written for your level and your AIs
   ORCHESTRATOR.md           single-agent routing rules (level 1)
-  TASK_BUNDLE.md            the brief every delegation carries
-  protocols/                build-protocol · propagate · gap-analysis · deep-research · numbers-and-logic · memory-and-record · docs-then-prove
+  TASK_BRIEF.md            the brief every delegation carries
+  CONTEXT.md               shared facts every delegation reads
+  ACCEPTANCE_CHECKS.json   executable acceptance checks
+  DECISIONS.md             the decision log: Did / Why / Serves / Rejected
+  protocols/                acceptance-checks · build-protocol · context-file · decision-log · deep-research · docs-then-prove · gap-analysis · memory-and-record · numbers-and-logic · propagate
   CODECALC.md  OBSIDIAN-TC.md  CONTEXT7.md  mcp/   companion-tool install docs + per-agent registration snippets (if selected)
-  <project>/.claude/agents/ one per tier plus finding-verifier, done-verifier, reader, at the PROJECT root (if Claude Code is primary)
-  <project>/.claude/hooks/  route-gate.mjs (UserPromptSubmit) + subagent-context.mjs (SubagentStart) + route-metrics.mjs (all five: see "Measuring routing" below), Claude Code only
-  CLAUDE.snippet.md         the block to paste into your CLAUDE.md
-  settings.hooks.snippet.json  the hooks block to merge into .claude/settings.json (Claude Code only)
+  CLAUDE.snippet.md         rules block for CLAUDE.md (Claude Code main agent)
+  settings.hooks.snippet.json  hooks for .claude/settings.json (Claude Code main agent)
+  GEMINI.snippet.md         rules block for GEMINI.md (Antigravity main agent)
+  AGENTS.snippet.md         rules block for AGENTS.md (Codex main agent)
+  QWEN.snippet.md           rules block for QWEN.md (Qwen Code main agent)
+  PASTE-INTO-YOUR-AGENT.md  paste into instructions (main agent with no project rules file)
   ROUTING.md                multi-lane decision tree (level 2+)
   TIERS.md  DELEGATION_MATRIX.md  RESEARCH_TRIAGE.md  CLI-RUN.md
-  bin/cli-run.mjs  bin/lanes.json          (node bin/cli-run.mjs --doctor is the smoke test)
+  bin/cli-run.mjs  bin/lanes.json          (aunx cli-run --doctor, or node bin/cli-run.mjs --doctor)
   vm/                       gateway config, compose, box rules, privacy gates, jobs/ (level 3)
+
+<project>/.claude/agents/  Claude Code main agent's subagent set
+<project>/.claude/hooks/   route-gate.mjs, subagent-context.mjs, route-metrics.mjs (Claude Code main agent)
+<project>/.agents/agents/  Antigravity main agent's custom agent set
 ```
 
+## Project commands (`aunx`)
+
+Install the command with `npm install -g model-orchestrator`, then run these from your project. `aunx` without a subcommand accepts the installer flags.
+
+| Command | Result |
+|---|---|
+| `aunx cli-run --doctor` | Check selected CLIs; add `--run` for live vendor canaries |
+| `aunx route-metrics --summary` | Summarize your local routing history |
+| `aunx brief` | Print the task brief template |
+| `aunx brief new TASK_BRIEF.md` | Scaffold a task brief |
+| `aunx context CONTEXT.md` | Scaffold a shared context file |
+| `aunx checks ACCEPTANCE_CHECKS.json` | Scaffold executable acceptance checks |
+| `aunx checks run ACCEPTANCE_CHECKS.json` | Execute trusted check commands; exit 1 on any failure |
+| `aunx route [--dir PATH] "rename this file"` | Print the role, assigned AI, tier, effort and reason from your manifest |
+
+`aunx cli-run` uses the packaged runner by default; pass `--dir PATH` to use that project's own installed runner under `PATH/bin/` instead, and `aunx` prints the runner path it is using. Review check commands before running them: they execute with your shell permissions.
+
+`aunx route` reads `MANIFEST.json` first under `--dir`, then under `./ai-orchestrator`, then in the current folder. It reads regular JSON files of at most 1 MiB, refuses symlinks and executes no project code. A missing or invalid manifest gives the generic suggestion plus an install notice.
+
+## Installer operation
+
+The installer creates routing instructions and activates the supported project surfaces so you can start using them from a fresh agent session.
+
+| Part | Operation |
+|---|---|
+| Trigger | Run `model-orchestrator`, `npx model-orchestrator` or `aunx` without a subcommand. The installer is a one-off command, with no schedule. |
+| Invocation chain | `bin/cli.js` parses flags, detects tools, plans files and activation, shows the summary, obtains the interactive confirmation, writes the plan, runs the presence check and prints remaining actions. `--yes` skips confirmation; `--dry` stops before writes and checks. |
+| Dependencies | Node 18 or newer; writable chosen target folders. Vendor CLIs and companions are detected locally and installed by you. |
+| Reads | Catalog and templates, CLI presence, the previous manifest, existing project rules and settings, and reliable catalog-listed sign-in status. |
+| Writes | Managed files under `--dir` and `--project`, the displayed project activation merges, ownership records in the manifest, and sibling backups for changed existing files. |
+| Closed loop | The terminal reports written, preserved and applied files, health results and remaining actions. Nothing watches a completed install or retries it automatically. Start a fresh agent session to check that it loads the rules. |
+| Failure modes | Invalid flags, refused paths, malformed activation markers or invalid JSON exit 2 before application. A missing CLI or unconfirmed sign-in is reported for manual setup. Edited managed files or activation entries are kept and named. Report a reproducible installer failure with its command and exit code to the repository's issue tracker. |
+| Run and verify | Preview the headless example above with `--dry`; remove `--dry` to apply. Check the marked rules block, Claude Code's hook settings when selected, and the printed health result. Run `npm test` from the source checkout for fixture checks; use `aunx cli-run --doctor --run` only when you choose a live vendor check. |
+| Source of truth | `bin/cli.js` owns the flow, `src/catalog.js` owns host capabilities, `src/install.js` owns planning and writes, `src/apply-snippets.js` and `src/apply-companions.js` own activation merges, `src/postinstall.js` owns presence and sign-in checks, and `src/uninstall.js` reads the manifest to remove owned content. |
+
+The automatic presence check proves that configured binaries can be found. It does not prove authentication, a live response or that a new agent session loaded the rules; those checks require the corresponding vendor session.
+
 ## Repo layout
 
 | Folder | What |
 |---|---|
-| [`bin/`](bin/README.md) | `cli.js` (the installer) and `cli-run.mjs` (the lane runner) |
-| [`src/`](src/README.md) | the catalog, the pure planner, detection, rendering |
-| [`templates/`](templates/README.md) | everything the installer can write, by level, plus `tools/` for companions |
-| [`docs/`](docs/README.md) | the three parts and the catalog |
-| [`plugin/`](plugin/README.md) | the Claude Code plugin, generated from `templates/` by `npm run gen:plugin`; `.claude-plugin/marketplace.json` at the root lists it |
-| [`test/`](test/README.md) | `npm test`: judges proven to go red, catalog integrity, planner, end-to-end install in a temp dir; `.github/workflows/test.yml` runs it on Ubuntu, macOS and Windows, Node 18/20/22 |
+| [`bin/`](../bin/README.md) | `cli.js` (the installer), `aunx.js` (the CLI entry point) and `cli-run.mjs` (the lane runner) |
+| [`src/`](../src/README.md) | the catalog, the pure planner, detection, rendering |
+| [`templates/`](../templates/README.md) | everything the installer can write, by level, plus `tools/` for companions |
+| [`docs/`](../docs/README.md) | the three parts and the catalog |
+| [`plugin/`](../plugin/README.md) | the Claude Code plugin, generated from `templates/` by `npm run gen:plugin`; `.claude-plugin/marketplace.json` at the root lists it |
+| [`proof/`](../proof/README.md) | the measured numbers behind the README's claims: method, sample size, date and expiry |
+| [`test/`](../test/README.md) | `npm test`: judges proven to go red, catalog integrity, planner, end-to-end install in a temp dir; `.github/workflows/test.yml` runs it on Ubuntu, macOS and Windows, Node 18/20/22 |

package/docs/part-1-beginner.md

@@ -1,71 +1,63 @@
-# Part 1 · Beginner: one LLM or agent, routed well
+# Part 1: route work inside one agent
 
-You do not need five vendors to orchestrate. You need three things inside the one agent you already have: **tiers**, **task classes**, and **gates that can fail**.
+Start with the agent or chat app you already use. The installer gives it task classes, model tiers and checks it can apply before calling another tool.
 
-## 1. Route by capability tier, not model name
+## Choose a tier for the job
 
-| Tier | For | Effort |
+| Tier | Job | Effort guidance |
 |---|---|---|
-| deep | ambiguous planning, architecture, strategy, root-cause debugging, anything expensive to get wrong | highest |
-| standard | writing code, reviewing code, executing a known plan, synthesizing research | high |
-| fast | classifying, extracting, formatting, bulk summaries | low |
+| Planning model | Ambiguous requirements, architecture and root-cause analysis | Increase reasoning for the unresolved decisions |
+| Working model | Build a scoped change, review code, synthesize research | Match effort to complexity and consequences |
+| Cheap model | Classify, extract, format and digest many files | Keep routine work bounded |
 
-If your agent exposes model choice (Claude Code, Codex, Antigravity), map the tiers to its strongest, everyday and cheapest models. If it does not (a chat app), the tiers become **how hard you ask it to think**: a deep task gets a planning turn before anything is written; a fast task gets "table, one row per item, no commentary".
+Map tiers to the models your agent actually exposes. With a chat app, use the same categories to decide whether the next turn needs a plan, an execution step or a short structured answer.
 
-Three cost levers, always together: tier (price per token), token discipline (how many tokens: read only what you will touch, never re-read, deliverables not narration), effort (how hard each call thinks).
+The installer detects available tools, shows the proposed setup and asks for one confirmation. With no detected tool, choose your AIs first. Level 1 includes a **Your stack: who does what** table in its README and a summary in `ORCHESTRATOR.md`. The main agent carries eligible jobs; review and private work remain **none selected** unless the stack meets their separate requirements. [Assignment rules](how-it-routes.md#your-stack-who-does-what).
 
-And three inputs into the choice, not one. **Role** picks the agent. **Complexity** moves the effort: a worker executing a finished plan needs less reasoning than the reviewer judging its output, so when the plan is airtight the spec is carrying the thinking. **Stakes** move the tier and who reads the result: security, privacy, data loss and irreversible changes are the four worth naming, because none of their failures can be fixed by editing the code afterwards. A one-line change to an auth check is simple and high-stakes at once, and it is the stakes that decide.
+Role selects the job. Complexity sets effort. Security, privacy, data loss and irreversible changes affect which model and reviewer can safely handle it. Check the current tool and model roster before deciding.
 
-Robustness first, cost second. You split tiers because the split produces better work.
+## Classify a task
 
-## 2. Classify every task, first match wins
+The installed decision tree covers bulk work, reading many files, live data, review, verification of findings, definition-of-done checks, ambiguous planning and builds. `aunx route "rename this file"` gives a keyword-based suggestion; the agent applies the full rules to the task's context.
 
-1. Bulk and mechanical → fast.
-2. Needs live data → standard, with tools. Freshness comes from tools, not from a bigger model, and anything a search returns is a lead, not a fact.
-3. Review without changing → standard, read-only, findings ranked by severity.
-4. Ambiguous, strategic, expensive to get wrong → deep, then hand the plan down.
-5. Everything else that changes files → do it directly at standard. Bounded sub-parts can go down a tier; the main build never goes to a fresh context whole.
+When a worker fails, inspect the evidence and choose the next action explicitly. A reproducible problem can justify a stronger model or more capable tools. A simple lookup belongs with a reader or a direct tool call.
 
-Modifiers: plan big, execute small · never silently retry a failed attempt at the same tier (escalate once and say so; two consults that do not unstick it means stop and ask) · de-escalate when a request sounds deep but is a lookup.
+## Build from checks to verified use
 
-## 3. Gates that can fail
+The build protocol starts by quoting the request and assigning acceptance checks. It probes available tools, tests uncertain assumptions, orders work by dependencies and collects one context file. An Assign step chooses the worker by reasoning fit, permissions, context capacity and headroom.
 
-> A gate you cannot fail is not a gate.
+After the build, use a known different model family to review the final merged artifact. A companion reviewer checks the scope against the original ask in the same audit step. When the stack has one family, a fresh-context review is a self-check; record that independent review is unavailable. Findings get reproduced before repair, and each fix gets a regression that can fail. Release means the change is in use on named surfaces, with live behavior checked and a rollback identified.
 
-"Does this look good?" passes every time. "Name what is most likely to go wrong, and what the request as filed missed" can come back empty, which is how you know it worked.
+The mechanical audit-skip conditions are documented in `protocols/build-protocol.md`. They are evaluated together against the diff. The process uses one audit pass, with regression checks for its fixes.
 
-Every build gets two checkpoints. **Before writing:** you map what it touches and what could break, then ask the deep tier on the finished map for one named weak spot and one gap in the request. **After it is green:** a fresh context challenges it (bad input, failing dependency, drift from the plan), allowed to answer CLEAN, every finding reproduced before it reaches you. Then the ship, with a rollback named and an explicit yes. Then the loud negative: re-check the old name everywhere and expect zero.
+## Give each worker a task brief
 
-## 4. Every hand-off carries a brief
+```bash
+aunx context CONTEXT.md
+aunx brief new TASK_BRIEF.md
+aunx checks ACCEPTANCE_CHECKS.json
+```
 
-A subagent, a fresh chat, a second window may hold none of your rules, and that is the default to assume. The one documented exception is a Claude Code subagent: it loads the project's CLAUDE.md hierarchy at start, so it keeps the standing rules, just not this task's scope. Either way, it reads an unspecified edge as an open one. The brief: purpose, task class, granted scope, capabilities, denied actions, conventions it does not have, report contract (what was not done, what is unverified), exit parameters (when to stop, and what to return if it hits the bound). Absence is denial.
+The context file carries verified facts once. The task brief quotes the ask and names scope, files, non-goals, interfaces to preserve, available and missing tools, checks, measurements, order of work and a coverage-table report. A worker gets the same task boundaries whether it is a subagent or a separate CLI.
 
-## 5. The second pass
+Claude Code subagents load the project's instruction hierarchy. A separate CLI or chat window may need those instructions supplied explicitly. Probe what the worker receives and include the missing context.
 
-After anything comprehensive, a fresh turn that hunts for what is **missing**, not what is present. Every clause of the ask maps to a step; every step maps to a clause. A clause with no step is dropped scope; a step with no clause is invented scope. Say both.
+## Compute, record and verify with your tools
 
-## 6. Deep research, single agent
+- **Numbers:** use a calculator or execution tool for figures someone will act on. codecalc is an optional companion.
+- **Notes:** search before writing, keep the index accurate and use one writer. A notes folder works; obsidian-tc adds search and controlled writes.
+- **APIs:** read current official documentation and test the call. Context7 can retrieve the documentation when available.
+- **Decisions:** record Did / Why / Serves / Rejected when choosing between approaches. Keep evidence and operational consequences in the record.
 
-Plan the sub-questions as their own turn and inspect them before spending anything. Sweep. Then a fresh second-opinion turn told to question the premise. Plant one deliberately wrong figure and see whether it corrects it. Mark every claim CONFIRMED / DISAGREEMENT / REPORTED / UNVERIFIED. Agreement is weak evidence; disagreement is the signal.
-
-## 7. Numbers and logic are computed, never guessed
-
-The one thing tiers and gates cannot fix: a model confident about `0.1 + 0.2` does not feel uncertain, it feels finished. So any figure someone will act on, any comparison you state, any complexity or equivalence claim goes through a tool that computes. The companion for that is [codecalc](https://github.com/The-40-Thieves/codecalc): exact arithmetic, a sandboxed code runner in 31 languages, an SMT logic checker, and proofs that a port or an optimization preserved behaviour. One command registers it with Claude Code, Claude Desktop, Cursor, VS Code or Zed. Without it the rule still binds; use anything that calculates.
-
-Logic flow follows the same rule. Reasoning scaffolds help models with no native reasoning mode and add nothing to ones that already think first. The authorising evidence is the computed outcome, never the thought log.
-
-## 8. Memory and record
-
-Every protocol ends in a write. Search before you write (duplicates are how a store starts lying), correct the folder index in the same pass, one writer per session, mark inferred content as inferred. The optional companion for that is [obsidian-tc](https://github.com/The-40-Thieves/obsidian-tc), a governed MCP server over an Obsidian vault: hybrid search, backlinks, compare-and-swap writes, folder ACLs. It needs an Obsidian vault, Node 24+ or Bun, and Ollama or a cloud embeddings key, so it is off by default; without it the rule still binds against a notes folder and `grep`.
-
-## 9. Docs, then prove
-
-A model's recall of a library's API is training data, not a live source; it goes stale the moment the vendor ships a release it never saw. Before writing code against a library, SDK, API or CLI you have not confirmed this session, pull current, version-specific docs; then a run, not the doc, is what proves the code behaves that way. The optional companion is [Context7](https://github.com/upstash/context7) (Upstash): it hands the agent current, version-aware documentation and code examples on request, hosted or run locally with `npx`. It pairs with codecalc rather than replacing it: Context7 says what the code is supposed to do, codecalc's run says what it actually does, and the run wins where they disagree. It needs a network call (there is no offline mode), so it is off by default; without it the rule still binds, read the vendor's own docs or source by hand.
+Every protocol names the fallback when its optional companion is absent. [Companion setup](companions.md).
 
 ## What the installer gives you at this level
 
-`README.md` (start here) · `ORCHESTRATOR.md` · `TASK_BUNDLE.md` · `protocols/{build-protocol, propagate, gap-analysis, deep-research, numbers-and-logic, memory-and-record, docs-then-prove}.md` · `CODECALC.md`, `OBSIDIAN-TC.md` and `CONTEXT7.md` with `mcp/` snippets for the companion tools you selected · the loading surface for your primary agent (Claude Code subagents, Antigravity custom agents, a rules-file snippet, or a paste block for a chat app).
+- **Rules:** `ORCHESTRATOR.md` and the loading surface for your main agent.
+- **Briefs:** `TASK_BRIEF.md`, a context-file template and acceptance-check template.
+- **Protocols:** building, context, acceptance checks, decisions, propagation, gap analysis, research, calculation, notes and documentation verification.
+- **Optional tools:** setup guides and MCP snippets only for companions you select.
 
-## When you have outgrown it
+## Add a second model family
 
-You keep wanting a second model family to read your diff, a $0 lane for bulk, or a live-data lane your primary does not have. That is [Part 2](part-2-intermediate.md).
+When a task would benefit from another model's review or a CLI with different tools, move to [Part 2](part-2-intermediate.md).