model-orchestrator 0.1.4

package/docs/part-1-beginner.md

@@ -0,0 +1,65 @@
+# Part 1 · Beginner: one LLM or agent, routed well
+
+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**.
+
+## 1. Route by capability tier, not model name
+
+| Tier | For | Effort |
+|---|---|---|
+| 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 |
+
+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".
+
+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).
+
+Robustness first, cost second. You split tiers because the split produces better work.
+
+## 2. Classify every task, first match wins
+
+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.
+
+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.
+
+## 3. Gates that can fail
+
+> A gate you cannot fail is not a gate.
+
+"Does this look good?" passes every time. "Name the single biggest risk and the flaw in the request as filed" can come back empty, which is how you know it worked.
+
+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 a named risk and a named flaw. **After it is green:** a fresh context attacks 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.
+
+## 4. Every hand-off carries a brief
+
+A subagent, a fresh chat, a second window holds none of your rules and 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.
+
+## 5. The second pass
+
+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.
+
+## 6. Deep research, single agent
+
+Plan the sub-questions as their own turn and inspect them before spending anything. Sweep. Then a fresh adversarial turn told to attack 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`.
+
+## What the installer gives you at this level
+
+`README.md` (start here) · `ORCHESTRATOR.md` · `TASK_BUNDLE.md` · `protocols/{build-protocol, propagate, gap-analysis, deep-research, numbers-and-logic, memory-and-record}.md` · `CODECALC.md` and `OBSIDIAN-TC.md` with `mcp/` snippets for the companion tools you selected · the loading surface for your primary agent (Claude Code subagents, Antigravity custom agents, a rules-file snippet, or a paste block for a chat app).
+
+## When you have outgrown it
+
+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).

package/docs/part-2-intermediate.md

@@ -0,0 +1,65 @@
+# Part 2 · Intermediate: many AIs, called through their CLIs
+
+Everything in Part 1, plus lanes. One agent stays the orchestrator; every other AI becomes a lane it calls from the terminal.
+
+## 1. Two kinds of lane
+
+**Lane A, subscription CLIs.** Claude Code, Codex, Antigravity, Grok, Hermes. Already paid for, $0 per call, used for interactive and agentic work. **Lane B, metered APIs.** Per token, used for programmatic bulk where a subscription CLI cannot serve. **Local.** A privacy lane, never a cost lane.
+
+Rule: never spend a frontier token on a task a cheap tier finishes correctly. Escalate on signal, not by default. And an external lane must earn the hop with a real strength; when in doubt, stay in-house.
+
+## 2. One job per lane
+
+| Lane | Wins at |
+|---|---|
+| the orchestrator (Claude Code, or whichever you chose) | routes, maps, builds, verifies, records; drives the others as CLIs |
+| Codex | second coder and adversarial auditor: a different model family reading your diff |
+| Antigravity `agy` | deep research sweeps; concurrent fan-out (its subagent call takes an array) |
+| Grok CLI | X and live web reads at $0 (the same search on the API bills per call) |
+| Hermes | the free tier: rough drafts, first-pass summaries, divergent reads, cron jobs |
+| Qwen Code + a cheap metered model | structured bulk output; never anything that cites a line, number or source |
+| Ollama | anything that must not leave the machine |
+
+One driver, no second AI in the mix: the orchestrator invokes the CLIs; it never hands control to another agent.
+
+## 3. Exit 0 is a lie on every lane
+
+Every agent CLI can report success and deliver nothing. `bin/cli-run.mjs` builds the right invocation per lane, reads that lane's **native** terminal event, and exits `10` when a run produced no deliverable, `12` on timeout, `13` when the lane is missing. Byte count is not a check either; a run can emit hundreds of kilobytes and no conclusion. One lane's own success flags lie outright (an upstream 400 reported as success), so its judge reads the two honest signals instead.
+
+Every call goes through it. "This lane is flaky" becomes a query over its log instead of an argument. `node bin/cli-run.mjs --doctor` is the first thing to run after install: enabled lanes, binaries on PATH, and with `--run` a one-word canary per lane.
+
+## 4. Every delegation carries a task bundle, on both surfaces
+
+Subagents and CLI lanes are the same problem: something with none of your rules and broad tool access. The brief (purpose, task class, scope, capabilities, denied actions, conventions, report contract, exit parameters) goes in the prompt or in the file passed to `--brief`. If you can, gate it mechanically: a pre-dispatch hook that refuses a brief missing purpose, denied actions or a report contract.
+
+## 5. Research: three engines, one triager
+
+Fan the same plan to three model families (web sweep, adversarial read, live data), each as one `cli-run` call. The orchestrator opens the primary sources itself, marks every claim, and writes the only durable record. Expect one engine to return confident unsourced numerics; downgrade it. Weight the engines that report their own gaps. Count dispositions, not briefs.
+
+## 6. Gap analysis gets a second family
+
+The second pass is now a different model reading the same artifact, in read-only audit mode. Disagreement between families is the cheapest signal that something is soft.
+
+## 7. The build protocol, bound to lanes
+
+Stage 1 Map: the orchestrator sweeps; CLI lanes critique the map at $0. Stage 2: deep tier, a named risk and a named flaw. Stage 4: scanners on the added lines, fail closed. Stage 5: security-shaped diff → the second coder in read-only audit mode; architecture-shaped → deep tier reviewing build against plan; never both. Two deep checkpoints per build; CLI lanes are uncapped.
+
+## 8. Privacy gate
+
+Name the lanes that never see private notes, client data or personal records. An unnamed bar is not enforced.
+
+## 9. Re-derive every figure a cheap lane returns
+
+Measured on the cheapest metered lane: conclusions right, 0 of 11 line citations correct, fabricated arithmetic attached to true observations. That survives a skim. So a number from a lane is a lead until a tool computes it: [codecalc](https://github.com/The-40-Thieves/codecalc) on the orchestrator's side, registered for Codex, Antigravity and Qwen Code with the snippets in `CODECALC.md`.
+
+## 10. One writer, and a store the lanes can all read
+
+With several lanes proposing, the store is where they meet. obsidian-tc (optional) gives every CLI the same `semantic_search`, `get_backlinks` and compare-and-swap `write_note`, with folder ACLs so a research lane can read what it needs and write nothing. The orchestrator stays the one writer.
+
+## What the installer gives you at this level
+
+Everything from Part 1, plus `ROUTING.md` · `TIERS.md` · `DELEGATION_MATRIX.md` (generated from your selection) · `RESEARCH_TRIAGE.md` · `CLI-RUN.md` · `bin/cli-run.mjs` · `bin/lanes.json`.
+
+## When you have outgrown it
+
+You want the audit to run on a Monday without you, a gateway so nothing but one process holds a key, and a machine that is always on. That is [Part 3](part-3-advanced.md).

package/docs/part-3-advanced.md

@@ -0,0 +1,65 @@
+# Part 3 · Advanced: everything above, plus a virtual machine
+
+A small always-on Linux box owns the schedule. Your laptop stays the interactive driver.
+
+## 1. Only the gateway holds keys
+
+One OpenAI-compatible gateway (LiteLLM) fronts every metered provider. Nothing else on the box holds a credential: not the orchestrator, not a job, not a container. Rotating a key is a change in one place. The gateway binds to loopback or a private mesh, never to the public interface.
+
+Subscription CLIs keep their own sign-in state and stay off the gateway; they are already $0.
+
+## 1b. A subscription is not an API key
+
+The installer asks which metered API keys you hold separately from which CLIs you use. A Claude Code plan gives you `claude`; it does not give you an Anthropic API key, and the gateway only serves what a key unlocks. Gateway lanes and the variable names in `vm/ENVIRONMENT.md` are rendered from the keys, never from the CLI list.
+
+## 2. Bind to aliases, pin the cheapest lane
+
+Each gateway lane is an alias (`bulk-cheap`, `standard`, `deep`, `long-context`, `live-fast`, `local-small`), so a vendor rename is a one-line repoint. Each job is pinned to the cheapest lane that does its work, with a token cap, and climbs the ladder (local → free → cheap → standard → deep) only on failure, low confidence, or an explicit "expensive to get wrong".
+
+## 3. Dispatch on the box
+
+1. Deterministic pre-triage at zero tokens: a keyword table routes the obvious cases.
+2. Judgment dispatch for the rest, by the orchestrator, with a logged reason.
+3. Free lane first.
+4. **Unattended means no human-gated escalation.** An unresolved irreversible call is surfaced and stopped, never executed on a model's confidence.
+5. One writer. Every other engine proposes.
+
+## 4. The weekly gap analysis becomes a job
+
+A timer enumerates live state (gateway lanes, timers, CLI versions), diffs it against the delegation matrix, and lets the free lane draft the report. It catches the dead lane and the silently renamed model. Its "watched by" line starts as `nothing`, and that line is the one that tells you what to build next.
+
+## 5. What runs where
+
+| Surface | Role |
+|---|---|
+| the orchestrator CLI | interactive driver over SSH; dispatch brain for jobs |
+| `cli-run` lanes | the other agent CLIs, headless, signed in by device code |
+| the gateway | every metered provider behind one endpoint |
+| a local runtime | the privacy lane |
+| user-level systemd timers | the schedule |
+
+Headless Linux gotchas the setup script handles: install a keyring or the CLIs re-prompt for auth on every launch; run device-code sign-ins inside `tmux`; invoke CLIs by absolute path from non-login shells.
+
+## 6. Rules that do not bend on a box
+
+- No payment card on any compute lane without a human saying so. Free credit only.
+- Local first; cloud only when local genuinely cannot.
+- Private notes, client data and personal records never go to a third-party bulk lane. Name the barred lanes.
+- Nothing binds to `0.0.0.0`.
+- A secret is never printed, never in argv, never in a file in the repo.
+
+## 7. Every self-running thing gets one document
+
+What and why · trigger · invocation chain · dependencies · reads · writes · **the closed loop (what watches it)** · failure modes · run-and-verify by hand · source of truth. A cold reader must be able to run it, verify it ran, and know who to tell when it breaks, from that one file. An unverified section says UNVERIFIED, never nothing.
+
+## 8. codecalc on the box
+
+Runs as a stdio MCP server next to the orchestrator CLI: offline, no key, nothing to bind. The weekly audit's figures (lane counts, version deltas, spend) are computed there, not estimated by the free lane that drafts the report. See [codecalc](https://github.com/The-40-Thieves/codecalc).
+
+## 9. obsidian-tc on the box
+
+Stdio next to the orchestrator, or the upstream Docker service against a bind-mounted vault. Embeddings on the box's Ollama, so nothing leaves the machine. HTTP transport stays off unless every caller is on the private mesh and auth is on.
+
+## What the installer gives you at this level
+
+Everything from Parts 1 and 2, plus `vm/README.md` · `vm/setup-vm.sh` · `vm/docker-compose.yml` · `vm/gateway.config.yaml` (one lane per provider you selected, keys by name only) · `vm/ENVIRONMENT.md` · `vm/box-CLAUDE.md` · `vm/PRIVACY_GATES.md` · `vm/jobs/` (a weekly audit timer + service, and an index that names what watches each job).

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "model-orchestrator",
+  "version": "0.1.4",
+  "description": "A model orchestrator you can npm run: route every task to the cheapest AI that does it well, across one agent, many CLIs, or a whole virtual machine. Three levels, one installer that asks what you have access to.",
+  "type": "module",
+  "bin": {
+    "model-orchestrator": "bin/cli.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "templates",
+    "docs",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md",
+    "SECURITY.md",
+    "scripts"
+  ],
+  "scripts": {
+    "start": "node bin/cli.js",
+    "test": "node --test",
+    "prepublishOnly": "npm test",
+    "dry-run": "node bin/cli.js --yes --level 2 --ais claude-code,codex,grok --dir ./tmp-dry-run --dry",
+    "gen:catalog": "node scripts/gen-catalog.js"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/aunysillyme/model-orchestrator.git"
+  },
+  "homepage": "https://github.com/aunysillyme/model-orchestrator#readme",
+  "bugs": {
+    "url": "https://github.com/aunysillyme/model-orchestrator/issues"
+  },
+  "keywords": [
+    "ai",
+    "orchestrator",
+    "model-router",
+    "claude-code",
+    "codex",
+    "antigravity",
+    "grok",
+    "ollama",
+    "litellm",
+    "multi-agent",
+    "cli"
+  ],
+  "license": "MIT"
+}

package/scripts/README.md

@@ -0,0 +1,5 @@
+# scripts/
+
+| File | Job |
+|---|---|
+| `gen-catalog.js` | regenerates `docs/catalog.md` from `src/catalog.js`; `npm run gen:catalog`. `test/catalog.test.js` fails if the two disagree. |

package/scripts/gen-catalog.js

@@ -0,0 +1,37 @@
+#!/usr/bin/env node
+// Regenerates docs/catalog.md from src/catalog.js. The test suite checks they agree.
+import { writeFileSync } from 'node:fs';
+import { AIS, LEVELS, TOOLS, npmSpec } from '../src/catalog.js';
+import { readdirSync } from 'node:fs';
+
+export function protocolCount() {
+  return readdirSync(new URL('../templates/common/protocols/', import.meta.url)).filter((f) => f.endsWith('.md') && f !== 'README.md').length;
+}
+
+export function catalogMarkdown() {
+  let md = '# Catalog\n\nGenerated from `src/catalog.js`. Do not hand-edit; `npm run gen:catalog` rewrites it. Protocols shipped at every level: ' + protocolCount() + ' (counted from `templates/common/protocols/`).\n\n## Levels\n\n| Level | Name | Tagline | Gives |\n|---|---|---|---|\n';
+  for (const l of LEVELS) md += `| ${l.id} | ${l.name} | ${l.tagline} | ${l.gives} |\n`;
+  md += '\n## AIs\n\n';
+  for (const a of AIS) {
+    const how = a.install.npm
+      ? '`npm install -g ' + npmSpec(a) + '`'
+      : a.install.script
+        ? 'vendor script (read it first): `' + a.install.script + '`'
+        : a.install.url + (a.install.brew ? ' (or `brew install ' + a.install.brew + '`)' : '');
+    md += `### \`${a.id}\` · ${a.name}\n\n- **Kind:** ${a.kind} · **Access:** ${a.access} · **Lane:** ${a.lane} · **Level:** ${a.minLevel}+\n- **Wins at:** ${a.role}\n- **Install:** ${how}\n- **Sign in:** ${a.auth}\n`;
+    if (a.rulesFile) md += `- **Reads rules from:** \`${a.rulesFile}\`` + (a.agentsDir ? ` · subagents in \`${a.agentsDir}/\`` : '') + '\n';
+    if (a.cliRun) md += '- **cli-run lane:** yes\n';
+    if (a.note) md += `- **Note:** ${a.note}\n`;
+    md += '\n';
+  }
+  md += '## Companion tools\n\n';
+  for (const t of TOOLS) {
+    md += `### \`${t.id}\` · ${t.name}\n\n- **Repo:** ${t.repo}\n- **Gives:** ${t.role}\n- **Install:** \`${t.install}\` (needs ${t.requires})\n- **Registers itself with:** ${t.autoClients.join(', ')}; snippets for the rest are written to \`mcp/\`\n- **Default:** ${t.recommended ? 'selected' : 'not selected'}\n\n`;
+  }
+  return md;
+}
+
+if (process.argv[1] && process.argv[1].endsWith('gen-catalog.js')) {
+  writeFileSync(new URL('../docs/catalog.md', import.meta.url), catalogMarkdown());
+  console.log('docs/catalog.md regenerated');
+}

package/src/README.md

@@ -0,0 +1,9 @@
+# src/
+
+| File | Job |
+|---|---|
+| `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. |
+| `prompt.js` | line-buffered questions for the interactive path; piped answers are queued, EOF mid-prompt aborts instead of confirming a write. |
+| `render.js` | `{{KEY}}` substitution. Throws on an unknown key, so a template typo fails the test suite instead of shipping a literal placeholder. |

package/src/catalog.js

@@ -0,0 +1,277 @@
+// The single source the installer, the docs and the generated files all read.
+// Add an AI here and every level picks it up. Nothing else lists AIs.
+//
+// Fields
+//   id         stable key used in --ais and in generated files
+//   name       what the prompt shows
+//   kind       'agent-cli' (a terminal agent), 'chat' (a chat app, no CLI), 'local' (a local model runtime)
+//   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
+//   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,
+//              { script: url } for a vendor shell installer the installer only PRINTS, never runs,
+//              { url } for a download page
+//   auth       how you sign in, always the vendor's own flow, never a key typed into this tool
+//   rulesFile  the instructions file that agent reads from a project root, if any
+//   agentsDir  where that agent keeps project-level subagent definitions, if any
+//   cliRun     true when bin/cli-run.mjs has a judge for this lane
+
+export const LEVELS = [
+  {
+    id: 1,
+    key: 'beginner',
+    name: 'Beginner',
+    tagline: 'one LLM or agent, routed well',
+    gives: 'tiers, task classification, every protocol, one agent set up to follow them'
+  },
+  {
+    id: 2,
+    key: 'intermediate',
+    name: 'Intermediate',
+    tagline: 'several LLMs and agents, called through their CLIs',
+    gives: 'everything in Beginner plus cli-run, a delegation matrix, task bundles and three-engine research triage'
+  },
+  {
+    id: 3,
+    key: 'advanced',
+    name: 'Advanced',
+    tagline: 'everything above, plus a virtual machine that runs it unattended',
+    gives: 'everything in Intermediate plus a gateway config, scheduled jobs, a dispatch layer and privacy gates for a box'
+  }
+];
+
+export const AIS = [
+  {
+    id: 'claude-code',
+    name: 'Claude Code (Anthropic)',
+    vendor: 'Anthropic',
+    kind: 'agent-cli',
+    bin: 'claude',
+    access: 'subscription',
+    lane: 'A',
+    role: 'orchestrator: routes, maps, builds, verifies, records',
+    minLevel: 1,
+    install: { npm: '@anthropic-ai/claude-code', pin: '2.1.260' },
+    auth: 'run `claude` once and sign in with your Anthropic account',
+    rulesFile: 'CLAUDE.md',
+    agentsDir: '.claude/agents',
+    cliRun: false,
+    models: { deep: 'opus', standard: 'sonnet', fast: 'haiku' }
+  },
+  {
+    id: 'codex',
+    name: 'Codex CLI (OpenAI, ChatGPT plan)',
+    vendor: 'OpenAI',
+    kind: 'agent-cli',
+    bin: 'codex',
+    access: 'subscription',
+    lane: 'A',
+    role: 'second coder and adversarial auditor (a different model family reading your diff)',
+    minLevel: 1,
+    install: { npm: '@openai/codex', pin: '0.153.2' },
+    auth: '`codex login` (add `--device-auth` on a machine with no browser)',
+    rulesFile: 'AGENTS.md',
+    agentsDir: null,
+    cliRun: true
+  },
+  {
+    id: 'agy',
+    name: 'Antigravity CLI `agy` (Google AI plan)',
+    vendor: 'Google',
+    kind: 'agent-cli',
+    bin: 'agy',
+    access: 'subscription',
+    lane: 'A',
+    role: 'deep research sweeps and concurrent fan-out (its subagent call takes an array)',
+    minLevel: 1,
+    install: { script: 'https://antigravity.google/cli/install.sh' },
+    auth: 'first run opens a device-code sign-in with your Google account',
+    rulesFile: 'GEMINI.md',
+    agentsDir: '.agents/agents',
+    cliRun: true,
+    models: { deep: 'pro', standard: 'flash', fast: 'flash' },
+    note: 'Gemini CLI was retired by Google in June 2026. agy is the successor. Do not install `gemini`.'
+  },
+  {
+    id: 'grok',
+    name: 'Grok CLI (xAI, X Premium)',
+    vendor: 'xAI',
+    kind: 'agent-cli',
+    bin: 'grok',
+    access: 'subscription',
+    lane: 'A',
+    role: 'X and live web reads at no per-call cost (its search tools bill on the API, not on the CLI)',
+    minLevel: 1,
+    install: { script: 'https://x.ai/cli/install.sh' },
+    auth: '`grok login` (add `--device-auth` on a headless machine)',
+    rulesFile: null,
+    agentsDir: null,
+    cliRun: true
+  },
+  {
+    id: 'hermes',
+    name: 'Hermes Agent (Nous Research)',
+    vendor: 'Nous Research',
+    kind: 'agent-cli',
+    bin: 'hermes',
+    access: 'free',
+    lane: 'A',
+    role: 'the free tier: rough drafts, first-pass summaries, cheap divergent reads, cron jobs on a box',
+    minLevel: 2,
+    install: { url: 'https://github.com/NousResearch/hermes-agent' },
+    auth: '`hermes auth add <provider>` per provider; its own fallback chain handles outages',
+    rulesFile: null,
+    agentsDir: null,
+    cliRun: true
+  },
+  {
+    id: 'qwen',
+    name: 'Qwen Code CLI (Alibaba, provider-agnostic)',
+    vendor: 'Alibaba',
+    kind: 'agent-cli',
+    bin: 'qwen',
+    access: 'metered',
+    lane: 'B',
+    role: 'cheapest metered bulk lane for structured output; never for anything that cites a line, a number or a source',
+    minLevel: 2,
+    install: { npm: '@qwen-code/qwen-code', pin: '0.23.0' },
+    auth: 'a provider key in an environment variable, named (not stored) in ~/.qwen/settings.json. There is no free Qwen cloud tier any more.',
+    rulesFile: 'QWEN.md',
+    agentsDir: null,
+    cliRun: true,
+    note: 'Its own success flags lie on API failures. cli-run checks the two honest signals for you.'
+  },
+  {
+    id: 'ollama',
+    name: 'Ollama (local models)',
+    vendor: 'Ollama',
+    kind: 'local',
+    bin: 'ollama',
+    access: 'local',
+    lane: 'local',
+    role: 'the privacy lane: anything that must never leave the machine. Not a cost lane.',
+    minLevel: 2,
+    install: { url: 'https://ollama.com/download', brew: 'ollama' },
+    auth: 'none',
+    rulesFile: null,
+    agentsDir: null,
+    cliRun: false
+  },
+  {
+    id: 'claude-app',
+    name: 'Claude app or claude.ai (chat only, no CLI)',
+    vendor: 'Anthropic',
+    kind: 'chat',
+    bin: null,
+    access: 'subscription',
+    lane: 'chat',
+    role: 'single-agent use through Projects and custom instructions',
+    minLevel: 1,
+    install: { url: 'https://claude.ai' },
+    auth: 'sign in',
+    rulesFile: null,
+    agentsDir: null,
+    cliRun: false
+  },
+  {
+    id: 'chatgpt-app',
+    name: 'ChatGPT (chat only, no CLI)',
+    vendor: 'OpenAI',
+    kind: 'chat',
+    bin: null,
+    access: 'subscription',
+    lane: 'chat',
+    role: 'single-agent use through custom instructions and Projects',
+    minLevel: 1,
+    install: { url: 'https://chatgpt.com' },
+    auth: 'sign in',
+    rulesFile: null,
+    agentsDir: null,
+    cliRun: false
+  },
+  {
+    id: 'gemini-app',
+    name: 'Gemini app (chat only, no CLI)',
+    vendor: 'Google',
+    kind: 'chat',
+    bin: null,
+    access: 'subscription',
+    lane: 'chat',
+    role: 'single-agent use through Gems and saved instructions',
+    minLevel: 1,
+    install: { url: 'https://gemini.google.com' },
+    auth: 'sign in',
+    rulesFile: null,
+    agentsDir: null,
+    cliRun: false
+  }
+];
+
+// Companion tools: not AIs, but things the AIs call. Asked about separately.
+export const TOOLS = [
+  {
+    id: 'codecalc',
+    name: 'codecalc (calculator, code runner, logic checker for your agent)',
+    repo: 'https://github.com/The-40-Thieves/codecalc',
+    role: 'exact arithmetic, code execution in 31 languages, SMT logic checks, complexity and equivalence proofs; offline, no key, no telemetry',
+    install: "uvx 'codecalc[full]' setup --write",
+    pin: '0.5.0',
+    requires: 'uv (https://docs.astral.sh/uv/) and Python 3.10+',
+    autoClients: ['Claude Code', 'Claude Desktop', 'Cursor', 'VS Code', 'Zed'],
+    recommended: true,
+    optionalNote: 'Optional. Needs Python 3.10+ and uv. Everything else runs offline.'
+  },
+  {
+    id: 'obsidian-tc',
+    name: 'obsidian-tc (governed memory: an agent-ready MCP server over an Obsidian vault)',
+    repo: 'https://github.com/The-40-Thieves/obsidian-tc',
+    role: 'durable memory and record for your agents: hybrid retrieval (BM25 + dense + link graph), backlinks, compare-and-swap writes with a confirmation gate, folder ACLs, a poison scan on inferred writes; 163 tools, local by default',
+    install: 'npm install -g obsidian-tc && obsidian-tc /path/to/your/vault',
+    pin: '1.26.0',
+    requires: 'an Obsidian vault folder (the Obsidian app itself is only needed for live plugin bridges); Node 24+ or Bun 1.1+ (stricter than this installer); Ollama with `nomic-embed-text` for local embeddings, or a cloud embeddings key; the Local REST API plugin only for bridge tools',
+    autoClients: ['Cursor', 'VS Code'],
+    recommended: false,
+    optionalNote: 'Optional and heavier than codecalc. Skip it if you do not keep notes in Obsidian. AGPL-3.0.'
+  }
+];
+export const toolById = Object.fromEntries(TOOLS.map((t) => [t.id, t]));
+
+// Metered API providers for the level 3 gateway. Separate from the AI list on
+// purpose: a Claude Code subscription is not an Anthropic API key, and a user
+// can truthfully have one without the other. Only NAMES of variables live here.
+export const PROVIDERS = [
+  { id: 'anthropic', name: 'Anthropic API', envName: 'ANTHROPIC_API_KEY', lanes: [['standard', 'anthropic/claude-sonnet-5'], ['deep', 'anthropic/claude-opus-5']] },
+  { id: 'openai', name: 'OpenAI API', envName: 'OPENAI_API_KEY', lanes: [['second-opinion', 'openai/gpt-5.6-terra']] },
+  { id: 'google', name: 'Google Gemini API', envName: 'GEMINI_API_KEY', lanes: [['long-context', 'gemini/gemini-3.1-pro']] },
+  { id: 'xai', name: 'xAI API', envName: 'XAI_API_KEY', lanes: [['live-fast', 'xai/grok-4.1-fast']] },
+  { id: 'openrouter', name: 'OpenRouter (many cheap models, one key)', envName: 'OPENROUTER_API_KEY', lanes: [['bulk-cheap', 'openrouter/qwen/qwen3.7-flash']] }
+];
+export const providerById = Object.fromEntries(PROVIDERS.map((p) => [p.id, p]));
+
+// Container image pins for the level 3 templates. Bump deliberately; a
+// reviewed box should not change underneath the user on a restart.
+export const IMAGES = {
+  litellm: 'ghcr.io/berriai/litellm:v1.99.1',
+  ollama: 'ollama/ollama:0.33.3'
+};
+
+export const byId = Object.fromEntries(AIS.map((a) => [a.id, a]));
+
+// The ONE place an npm install spec is built. Interactive install, the printed
+// fallback command, the install table and the box script all call this, so
+// two users on two paths get the same version.
+export function npmSpec(a) {
+  if (!a.install || !a.install.npm) return null;
+  return a.install.npm + (a.install.pin ? '@' + a.install.pin : '');
+}
+
+export function aisForLevel(level) {
+  return AIS.filter((a) => a.minLevel <= level);
+}
+
+export function agentCandidates(selected) {
+  // Which of the selected AIs can be the single primary agent at level 1.
+  return selected.filter((a) => a.kind === 'agent-cli' || a.kind === 'chat');
+}

package/src/detect.js

@@ -0,0 +1,26 @@
+import { accessSync, statSync, constants } from 'node:fs';
+import { delimiter, join } from 'node:path';
+import { homedir } from 'node:os';
+
+// PATH lookup plus the handful of places vendor installers drop binaries
+// without touching PATH. Never a shell function, never a shell out.
+// A directory with the binary's name is not a binary (X_OK passes on
+// searchable directories), so the candidate must be a regular file.
+export function which(bin) {
+  if (!bin) return null;
+  const home = homedir();
+  const searchPath = process.env['PATH'] || '';
+  const dirs = searchPath.split(delimiter).filter(Boolean);
+  dirs.push(join(home, '.local', 'bin'), join(home, '.grok', 'bin'), join(home, '.npm-global', 'bin'));
+  for (const d of dirs) {
+    const p = join(d, bin);
+    try {
+      if (!statSync(p).isFile()) continue;
+      accessSync(p, constants.X_OK);
+      return p;
+    } catch {
+      /* keep looking */
+    }
+  }
+  return null;
+}