@illuminis/comprism 0.1.0

package/LICENSE

@@ -0,0 +1,15 @@
+Copyright (c) 2026 illuminis AI, LLC. All rights reserved.
+
+This software is proprietary and confidential. It is distributed so that
+authorized users may install and run it as published. No license is granted to
+copy, modify, distribute, sublicense, sell, or create derivative works from it,
+and no rights are granted by implication, estoppel, or otherwise.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+Contact: legal@illuminis.ai

package/README.md

@@ -0,0 +1,281 @@
+# `@illuminis/comprism` - the CompletionPrism Companion
+
+The half of CompletionPrism that runs on your machine. It sits between the tool
+you already use and the AI provider, records what finishing your work actually
+cost, and changes nothing about what your tool does.
+
+```bash
+npm install && npm run build
+
+export ANTHROPIC_API_KEY=...      # or OPENAI_API_KEY
+node out/cli.js setup
+node out/cli.js session
+node out/cli.js report
+```
+
+## The coding agent
+
+`comprism agent` is a coding agent in your terminal. It reads your project,
+changes files, runs commands, runs your tests, and shows you every change before
+it makes it.
+
+```bash
+npm install -g @illuminis/comprism
+comprism login                    # once, per machine
+cd ~/your-project
+comprism agent "the tests are failing, work out why and fix it"
+```
+
+**What makes it different from the others.** Every step is routed to whichever
+model finishes the work for least, and it can change its mind between one step
+and the next. The receipt at the end says what the job actually cost.
+
+```
+  /Users/you/your-project  23 actions available
+  step 1  claude-sonnet-5  $0.02  5.0s
+  ok   run_tests   425ms
+  step 2  claude-sonnet-5  $0.02  3.0s
+  ok   read_file parser.js
+  ok   edit_file parser.js
+  step 3  claude-sonnet-5  $0.02  3.3s
+  ok   run_tests   262ms
+
+Done
+  6 steps  .  6 actions  .  $0.14  .  tests passed
+```
+
+### How much it is allowed to do
+
+Four settings, and the safe one is the default. Nothing is automatic unless you
+choose it.
+
+| `--mode` | What it may do |
+|---|---|
+| `read_only` | Look at the project and answer questions. Change nothing |
+| `approve_writes` | **The default.** Show you every change before making it |
+| `auto_edit` | Change files freely. Ask before running anything |
+| `full_auto` | Get on with it. Publishing and installing packages are still confirmed |
+
+Some things no setting unlocks: force pushing, rewriting history, downloading a
+script and running it, anything that touches your credentials, and deploying to
+production. Those are yours to do.
+
+### Before you let it change anything
+
+```bash
+comprism agent --plan "rename the parser module and update every caller"
+```
+
+It reads what it needs, tells you what it would do, and changes nothing. The
+cheapest moment to disagree with an agent is before it starts.
+
+### While it is running
+
+- **Ctrl+C** stops the job. It does not kill the command line tool, and it does
+  not leave the job running on the server.
+- **Type anything** and it joins the next step, so you can correct course without
+  starting again.
+
+### Taking a job back
+
+Every change is copied before it is made. Open the job in the portal and undo it,
+and the files go back to exactly the bytes they started with. Where a job also
+ran a command, the undo says so plainly rather than claiming to have reversed it.
+
+### Carrying on tomorrow
+
+```bash
+comprism agent --resume <job-id> "also add a test for the empty case"
+```
+
+It continues the conversation rather than starting a new one, so it already knows
+what it read and decided.
+
+### In a script, or in continuous integration
+
+```bash
+comprism agent --yes --mode auto_edit "run the linter and fix what it reports"
+echo $?     # 0 if it finished, non-zero if it did not
+```
+
+With no terminal attached nobody can be asked anything, so anything that would
+need an approval is **refused** rather than assumed. A script that needs to change
+files says so by choosing a mode that allows it.
+
+### Which model
+
+By default, whichever finishes each step for least. Pin one when you want to
+decide yourself:
+
+```bash
+comprism agent --model gpt-5 "..."          # or any model your account can reach
+comprism agent --max-spend 2.00 "..."       # stop here rather than running on
+```
+
+Four providers are wired: Anthropic, OpenAI, Google and xAI. Which ones you can
+reach depends on the keys on your account.
+
+### Requirements
+
+Node 22 or newer, and a workspace you have signed in to with `comprism login`.
+
+---
+
+## Instrument a tool you already use
+
+```bash
+node out/cli.js proxy
+export ANTHROPIC_BASE_URL=http://127.0.0.1:8787
+```
+
+Requests are forwarded to the provider byte for byte. Your key is forwarded,
+never read or stored. Unset the variable and we are gone, with nothing to undo.
+
+## Whose Anthropic account pays
+
+Yours, on every surface. How it gets there differs by one thing only: whether the
+surface can carry a credential.
+
+| How you work | Where the key comes from | Stored anywhere? |
+|---|---|---|
+| `comprism session`, `comprism proxy`, or an IDE pointed at your workspace | this machine, per request | no |
+| The developer API and the SDKs | the `X-Anthropic-Key` header, per request | no |
+| Claude Desktop and claude.ai | your workspace's own stored key | yes, encrypted, and only this one |
+
+The third row is the exception and it is a protocol limit rather than a choice:
+an MCP connector reaches the server with no channel for a provider credential, so
+answering those prompts at all means the workspace holding a key. A workspace
+that holds none gets its connector answers refused - never billed to illuminis.
+
+```bash
+node out/cli.js key            # whose account pays, here and in your workspace
+node out/cli.js key push       # send this machine's key, for the connector surface
+node out/cli.js key clear      # take it back out
+```
+
+`push` is the one command that deliberately sends a provider key anywhere. It
+sends the key this machine already resolves, over TLS, to the workspace you are
+signed in to; Anthropic validates it before it is stored; nothing is written to
+disk here either way. An administrator can do the same in the app, under Policy
+and Data Controls.
+
+## The stats footer
+
+Through the proxy there is no result object and no widget area: the client
+renders the message body and nothing else. So a finished Anthropic answer comes
+back with two extra lines under it.
+
+```
+The GCD of 1071 and 462 is 21.
+
+---
+**$0.038 saved** vs Claude Opus 5 · *Claude Haiku 4.5 · 12,614 tokens · 0.0s*
+```
+
+**How it works.** On the way out, the footer is wrapped in an HTML comment pair
+(`<!--cp-meta-->` … `<!--/cp-meta-->`) that renders as nothing. On a streamed
+response it arrives as one more text content block - `content_block_start`,
+`content_block_delta`, `content_block_stop` at the next free index - emitted
+after the provider's last block and before the terminating `message_delta`. On a
+non-streamed one it is spliced in as a text block after the last existing text
+block. Either way the provider's own bytes are forwarded unchanged; the footer is
+added, never merged.
+
+On the way back in, every previously injected footer is cut out of the request by
+sentinel before it reaches the provider. So the model never sees one, never
+learns to imitate the format, and nobody pays context for the same footer twice.
+Stripping is idempotent and runs whether or not injection is switched on.
+
+**It is never allowed to cost you an answer.** If anything in the footer path
+throws, the provider's response passes through completely unmodified and the
+failure is logged rather than shown. Nothing is added at all when the turn ends
+in a tool call, a refusal, a truncation, an error event, an empty response, or a
+model with no published price.
+
+```bash
+node out/cli.js footer            # what it is doing now
+node out/cli.js footer off        # byte-faithful in both directions
+node out/cli.js footer on
+```
+
+### Configuring pricing, the baseline and the template
+
+Everything lives under `footer` in `~/.comprism/config.json`:
+
+```json
+{
+  "footer": {
+    "enabled": true,
+    "template": "compact",
+    "baselineModel": "claude-opus-5",
+    "pricing": {
+      "claude-haiku-4-5": { "inPerMTok": 0.8, "outPerMTok": 4.0 }
+    }
+  }
+}
+```
+
+`baselineModel` is what the saving is measured against: the one capable model a
+company would have mandated for everything. It is named in the footer itself,
+because "$0.038 saved" is a claim nobody can check and "$0.038 saved vs Claude
+Opus 5" is one they can. When the routed model costs the same or more, no
+dollar figure is shown at all - never a negative one.
+
+`pricing` overrides the published catalog per model, for tenants whose
+contracted rate is not list price. `inPerMTok` and `outPerMTok` are required;
+`cacheReadPerMTok` and `cacheWritePerMTok` are optional and default to the
+provider's published multipliers of the input price (0.1x and 1.25x). A model in
+neither the catalog nor this table is unpriced, and an unpriced turn gets no
+footer rather than a guessed one.
+
+`template` is one of:
+
+| Template | Hero |
+|---|---|
+| `compact` | this turn's saving, with the baseline named |
+| `cumulative` | everything saved since the recorder started, then this turn |
+| `detailed` | this turn's saving, plus the in / out / cached token split |
+
+To add another, extend `renderFooter` in `src/footer.ts` and the `FooterTemplate`
+union in `src/types.ts`. Keep it to a divider and one line: the footer exists to
+punctuate an answer, not to compete with it.
+
+### The known constraint
+
+The client renders markdown in the message body and offers no other surface, so
+that is the whole design space. No panel, no badge, no hover, no color beyond
+what bold and italic give. Anything richer belongs in the portal, which is why
+the footer stays deliberately small.
+
+## What it records, and what it refuses to
+
+Under `~/.comprism/`, mode 700, append-only:
+
+| File | One row per |
+|---|---|
+| `ledger.jsonl` | provider call: model, tokens, cost, latency, finish reason |
+| `decisions.jsonl` | decision point: what was known and chosen, **never edited** |
+| `sessions.json` | working session: the shape of each turn, not its words |
+
+Never written, anywhere: your prompts, the responses, or your API keys. A request
+is identified by the sha256 of its normalized text and nothing else. Turning text
+storage on is an explicit tenant decision; everything here works without it.
+
+## The estimator is present and inert
+
+With no evidence, the estimator returns "no recommendation, insufficient
+evidence", records why, and the request proceeds untouched. It never invents a
+number. Selection arrives with the model program, through the same interface,
+and nothing upstream of it changes.
+
+## The gate
+
+```bash
+npm run gate
+```
+
+Runs the frozen spec's Phase 1 acceptance list: one ledger row per call, decision
+ids resolving, remediation on all three weak conditions, a caller override
+dispatching exactly one model, the canaries for request text and keys, ledger
+durability under a mid-write kill, and `report` reconciling to the ledger.
+Eighteen checks. All of them must pass before anything here is committed.

package/out/agent/command.d.ts

@@ -0,0 +1,86 @@
+import { type JobResult } from "./session";
+export interface AgentArgs {
+    request: string[];
+    /** Start it and hand the terminal back. See `runDetached` for what this can
+     *  and cannot do. */
+    background?: boolean;
+    mode?: string;
+    plan?: boolean;
+    /** The person read the plan and said build it. Changes to files in this
+     *  project then happen without being asked about one at a time. Commands and
+     *  publishing are still asked about. */
+    approvePlan?: boolean;
+    model?: string;
+    /** Run `model` and nothing else, whatever the router would prefer. */
+    pin?: boolean;
+    maxSpend?: number;
+    /** `--allow "python3 grade.py"`, repeatable. Exact commands, pre approved. */
+    allow?: string[];
+    yes?: boolean;
+    resume?: string;
+    /**
+     * Go without the code map for this job, whatever the company setting says.
+     *
+     * Two people need it and both are legitimate. The corpus study, because a run
+     * with a map and a run without one are two different quantities and averaging
+     * them would flatter whichever arm happened to have one. And anybody who
+     * suspects the map and wants the files read directly.
+     */
+    noMap?: boolean;
+    /** The job this question follows on from, so the agent knows what was
+     *  already said. Not the same as `resume`, which re-enters a job that stopped
+     *  part way; this is the ordinary next question in a conversation. */
+    continuesJob?: string;
+    cwd?: string;
+    /**
+     * Ask the person a yes or no question.
+     *
+     * Supplied by a caller that already owns the keyboard, so a session and the
+     * agent never open two readers on it. Two readers divide the typing between
+     * them and the second one reads nothing, which is how a request to run a
+     * command inside a session came back refused with nobody having declined it.
+     *
+     * Absent, the agent opens its own reader exactly as it always has, which is
+     * what the standalone command wants.
+     */
+    confirm?: (question: string) => Promise<boolean>;
+    /**
+     * Files already uploaded, to be put in front of this question.
+     *
+     * Ids, never contents: the file was read by the server when it was attached,
+     * and what it holds is text with a half-hour life. Sending the bytes again
+     * here would be sending them twice and storing them nowhere useful.
+     */
+    attachments?: string[];
+    /**
+     * Handed a way to stop the job, as soon as there is one to stop.
+     *
+     * For a caller that owns the keyboard and therefore also owns Ctrl+C. This
+     * command stops a job on its own SIGINT handler, and a caller holding a
+     * readline interface never lets that handler fire, so without this the job
+     * carried on after the person asked to leave and the session closed reporting
+     * a cost of nothing on work it had already paid for.
+     */
+    /** Handed the controls the moment the job starts: stop it, or say something
+     *  to it while it runs. A caller that owns the keyboard needs both, because
+     *  a person watching a job go the wrong way at step three should be able to
+     *  correct it rather than stop it and start again. */
+    onStarted?: (controls: {
+        cancel: () => void;
+        steer: (text: string) => void;
+    }) => void;
+    /**
+     * Told what the job cost, once it has finished.
+     *
+     * The command itself only needs an exit code, so that is still what this
+     * returns. A session running several jobs needs the figures as well, to keep
+     * a running total: without them it showed every session as zero spent and
+     * zero saved, which is the one number this product cannot get wrong.
+     *
+     * Not called when the job never started, because there is nothing to add.
+     */
+    onFinished?: (result: JobResult) => void;
+}
+export declare function runAgent(args: AgentArgs): Promise<number>;
+/** The help text. Written to be read by somebody who has not read anything else. */
+export declare const AGENT_HELP: string;

package/out/agent/command.js

@@ -0,0 +1,259 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AGENT_HELP = void 0;
+exports.runAgent = runAgent;
+/**
+ * `comprism work` — the coding agent, from a terminal.
+ *
+ * Specification: docs/modules/CODING_AGENT_BUILD_SPECIFICATION.md, register
+ * items A6 (interactive), A7 (scriptable), C14 (resume) and L2 (how to install
+ * it).
+ *
+ * ## Two shapes, one session
+ *
+ * With a person at the keyboard, approvals are asked, Ctrl+C stops the run
+ * rather than killing the process, and anything typed while it works joins the
+ * next step.
+ *
+ * With `--yes` or no terminal attached, nobody is asked anything. The
+ * permission mode has to have settled it in advance, and an action that would
+ * need an approval is refused rather than assumed. **Silence is never consent**:
+ * a script that needs to change files says so by choosing a mode that allows it.
+ */
+const fs = __importStar(require("fs"));
+const readline = __importStar(require("readline"));
+const connection_1 = require("../lib/connection");
+const session_1 = require("./session");
+const ui = __importStar(require("./render"));
+/** The WebSocket the session needs is a global from Node 22.
+ *
+ *  Checked here with a message somebody can act on. Without it the failure is
+ *  `WebSocket is not defined` from inside a library, which reads as a broken
+ *  install rather than an old runtime. */
+function requireWebSocket() {
+    if (typeof globalThis.WebSocket === "function")
+        return true;
+    process.stderr.write(ui.red("  This needs Node 22 or newer.") +
+        ui.dim(`  You are on ${process.version}. Upgrade Node and try again.\n`));
+    return false;
+}
+const MODES = ["read_only", "approve_writes", "auto_edit", "full_auto"];
+/**
+ * Start a job, hand the terminal back, and keep working.
+ *
+ * Specification register item C15.
+ *
+ * **What this honestly is, and is not.** The job continues without somebody
+ * watching it, and it writes to a log they can follow or ignore. The machine has
+ * to stay on, because the actions run HERE: reading and changing files is done
+ * by this process on this disk, and no amount of server-side cleverness moves
+ * that. A laptop that goes to sleep pauses the job, and the job says so when it
+ * wakes.
+ *
+ * Anything needing an approval is refused rather than waited on, for the same
+ * reason `--yes` refuses: nobody is there, and treating silence as consent would
+ * let a job change files nobody ever saw. So a background job is only useful in
+ * a permission mode that settles it in advance, and the command says so rather
+ * than letting somebody find out an hour later.
+ */
+async function runDetached(args) {
+    const { spawn } = await Promise.resolve().then(() => __importStar(require("child_process")));
+    const os = await Promise.resolve().then(() => __importStar(require("os")));
+    const pathMod = await Promise.resolve().then(() => __importStar(require("path")));
+    const mode = args.mode ?? "approve_writes";
+    if (mode === "approve_writes" || mode === "read_only") {
+        process.stderr.write(ui.red("  A background job cannot ask you anything, so in this mode it "
+            + "would refuse every change.\n")
+            + ui.dim("  Use --mode auto_edit or --mode full_auto, or run it in the "
+                + "foreground.\n"));
+        return 1;
+    }
+    const logPath = pathMod.join(os.tmpdir(), `comprism-agent-${Date.now()}.log`);
+    const log = fs.openSync(logPath, "a");
+    // Detached, with its own process group, so closing the terminal does not take
+    // the job with it. `unref` is what actually lets this process exit.
+    const child = spawn(process.execPath, [
+        process.argv[1] ?? "", "agent",
+        ...args.request,
+        "--mode", mode, "--yes",
+        ...(args.model ? ["--model", args.model] : []),
+        ...(args.pin ? ["--pin"] : []),
+        ...(args.maxSpend ? ["--max-spend", String(args.maxSpend)] : []),
+        ...(args.allow ?? []).flatMap((c) => ["--allow", c]),
+        ...(args.cwd ? ["--cwd", args.cwd] : []),
+    ], { detached: true, stdio: ["ignore", log, log], env: { ...process.env, NO_COLOR: "1" } });
+    child.unref();
+    process.stdout.write(ui.green(`  Started in the background as process ${child.pid}.\n`)
+        + ui.dim(`  Follow it:  tail -f ${logPath}\n`)
+        + ui.dim("  It keeps working while you do something else. This machine has "
+            + "to stay awake: the files are here, so the work is too.\n"));
+    return 0;
+}
+async function runAgent(args) {
+    if (!requireWebSocket())
+        return 1;
+    if (args.background)
+        return runDetached(args);
+    const connection = (0, connection_1.readConnection)();
+    if (!connection?.url) {
+        process.stderr.write(
+        // The command named here MUST be one this tool actually has. It said
+        // `comprism login`, which has never existed, so the one instruction a
+        // brand new user is given was a dead end.
+        ui.red("  Not signed in.") +
+            ui.dim("  Run `comprism login` first.\n"));
+        return 1;
+    }
+    // The machine credential, not the session token. The session token belongs to
+    // a browser sign-in and is short lived; this is the long-lived credential
+    // minted for this laptop, listed in the portal beside every other machine and
+    // revocable on its own. A job running for twenty minutes must not stop
+    // because a browser session expired somewhere else.
+    const credential = connection.workspaceKey;
+    if (!credential) {
+        process.stderr.write(ui.red("  This machine has no workspace key.") +
+            ui.dim("  Run `comprism connect` again to mint one.\n"));
+        return 1;
+    }
+    const root = fs.realpathSync(args.cwd ?? process.cwd());
+    const mode = args.mode ?? "approve_writes";
+    if (!MODES.includes(mode)) {
+        process.stderr.write(ui.red(`  ${mode} is not a permission mode.`) +
+            ui.dim(`  One of: ${MODES.join(", ")}\n`));
+        return 1;
+    }
+    const request = args.request.join(" ").trim();
+    if (!request && !args.resume) {
+        process.stderr.write(ui.dim("  Say what you want done.\n"));
+        return 1;
+    }
+    // Headless when asked for, and also when there is no terminal at all: piped
+    // into a script, nobody is there to answer an approval, and pretending
+    // otherwise would hang the pipeline until it timed out.
+    const headless = Boolean(args.yes) || !process.stdin.isTTY;
+    const session = new session_1.TerminalSession({
+        baseUrl: connection.url,
+        credential,
+        root,
+        permissionMode: mode,
+        planOnly: Boolean(args.plan),
+        planApproved: Boolean(args.approvePlan),
+        model: args.model,
+        pinModel: Boolean(args.pin),
+        maxSpendUsd: args.maxSpend,
+        approvedCommands: args.allow ?? [],
+        attachmentIds: args.attachments ?? [],
+        headless,
+        confirm: args.confirm,
+        resumeJobId: args.resume,
+        continuesJob: args.continuesJob,
+        withoutMap: Boolean(args.noMap),
+    });
+    // Ctrl+C stops the JOB, not the process. Killing the process would leave the
+    // job running on the server with nothing watching it, and whatever the agent
+    // had started on this machine would carry on unsupervised.
+    const onInterrupt = () => session.cancel();
+    process.on("SIGINT", onInterrupt);
+    args.onStarted?.({
+        cancel: () => session.cancel(),
+        steer: (text) => session.steer(text),
+    });
+    // Anything typed while it works. Not a prompt, deliberately: the run is
+    // printing, and a prompt competing with it for the same lines is unreadable.
+    //
+    // Skipped entirely when the caller lent us a keyboard. The whole point of
+    // `confirm` is that one component owns the terminal; opening a reader here as
+    // well would put the same two owners back on it by another door, and the
+    // caller is the one already reading what gets typed.
+    let steering = null;
+    if (!headless && !args.confirm) {
+        steering = readline.createInterface({ input: process.stdin, terminal: false });
+        steering.on("line", (line) => {
+            const text = line.trim();
+            if (text)
+                session.steer(text);
+        });
+    }
+    try {
+        const result = await session.run(request);
+        args.onFinished?.(result);
+        // A shell needs to know whether it worked. Anything other than finishing
+        // cleanly is a non-zero exit, so `comprism work ... && next-thing` behaves
+        // the way a person expects.
+        return result.outcome === "finished" ? 0 : 1;
+    }
+    catch (err) {
+        process.stderr.write(ui.red(`  ${err.message}\n`));
+        return 1;
+    }
+    finally {
+        process.off("SIGINT", onInterrupt);
+        steering?.close();
+    }
+}
+/** The help text. Written to be read by somebody who has not read anything else. */
+exports.AGENT_HELP = `
+${ui.bold("comprism work")} — a coding agent in your terminal
+
+  comprism work "add a test for the parser and make it pass"
+
+${ui.bold("What it does")}
+  Reads your project, changes files, runs commands and runs your tests, and
+  shows you every change before it makes it. Each step is routed to whichever
+  model finishes the work for least, and the receipt at the end says what it
+  cost.
+
+${ui.bold("Options")}
+  --mode <mode>      read_only, approve_writes (default), auto_edit, full_auto
+  --plan             work out what it would do and change nothing
+  --approve-plan     you read the plan and want it built. Files change without
+                     being asked about one at a time; commands still ask
+  --model <id>       tell it which model you are running, so the receipt can
+                     price the saving against it. It may still move you up
+  --pin              run --model and nothing else, whatever it would prefer
+  --max-spend <usd>  stop at this much rather than running on
+  --allow "<cmd>"    approve one exact command up front, repeatable. The only
+                     way an unattended run can verify its own work
+  --yes              never ask; anything needing approval is refused instead
+  --background       start it and get your terminal back; it keeps working
+  --resume <job>     carry on from a job you already started
+  --cwd <path>       work in this folder rather than the current one
+  --no-map           do not use the code map for this job; read the files
+
+${ui.bold("While it runs")}
+  Ctrl+C stops the job. Anything you type joins the next step, so you can
+  correct it without starting again.
+`;