kaizen-agent 1.11.0 → 1.12.0

package/README.md

@@ -2,59 +2,55 @@
 <img src="https://raw.githubusercontent.com/hfadhlullah/kaizen/main/assets/banner.png" alt="kaizen" width="760">
 </div>
 
-<p align="center"><i>Your AI agent shows you the plan before it does the work,<br>and a second agent checks what it did.</i></p>
+<p align="center"><b>Stop finding your AI's mistakes next week.</b><br><i>See the plan before it starts. Get a second opinion when it is done.</i></p>
 
 <p align="center">
   <a href="https://github.com/hfadhlullah/kaizen/stargazers"><img alt="stars" src="https://img.shields.io/github/stars/hfadhlullah/kaizen?style=social"></a>
   <a href="https://www.npmjs.com/package/kaizen-agent"><img alt="npm" src="https://img.shields.io/npm/v/kaizen-agent?color=2d50a5&label=npm"></a>
   <a href="https://github.com/hfadhlullah/kaizen/blob/main/LICENSE"><img alt="license" src="https://img.shields.io/npm/l/kaizen-agent?color=2d50a5"></a>
   <img alt="dependencies" src="https://img.shields.io/badge/dependencies-0-2d50a5">
-  <img alt="works with" src="https://img.shields.io/badge/Claude%20Code%20%C2%B7%20Codex%20%C2%B7%20Antigravity-2d50a5">
+  <img alt="works with" src="https://img.shields.io/badge/Claude%20Code%20%C2%B7%20Codex%20%C2%B7%20Antigravity%20%C2%B7%20OpenCode%20%C2%B7%20Cursor%20%C2%B7%20Gemini%20CLI-2d50a5">
 </p>
 
 ---
 
-macOS, Linux, WSL — one paste:
+You ask an AI for something real: a feature, a launch email, a migration plan. It goes
+quiet, then hands you a finished thing. Did it understand you? What did it change? What
+is wrong that you won't notice until next week?
+
+**kaizen adds two checkpoints:**
+
+1. **Before:** you see the plan and say yes or no. Nothing is built until you approve.
+2. **After:** a *second* agent reviews the work. It never saw the first one's reasoning, so it has nothing to defend. It tells you what's wrong, numbered and graded.
+
+You decide what gets fixed.
+
+<p align="center"><img src="https://raw.githubusercontent.com/hfadhlullah/kaizen/main/assets/demo.gif" alt="kaizen shows a plan, you approve, a second agent reports two findings" width="760"></p>
+
+## Install
 
 ```bash
+# macOS · Linux · WSL
 curl -fsSL https://bun.sh/install | bash && ~/.bun/bin/bunx kaizen-agent
 ```
 
-Windows PowerShell — one paste:
-
 ```powershell
+# Windows PowerShell
 irm bun.sh/install.ps1 | iex; & "$env:USERPROFILE\.bun\bin\bunx.exe" kaizen-agent
 ```
 
-Already have Bun? `bunx kaizen-agent`.
-
----
-
-## The problem
-
-You ask an AI to do something real — write the launch email, draft the policy,
-build the feature, plan the migration. It goes quiet, then hands back a finished
-thing.
+Already have Bun? `bunx kaizen-agent`. It sets itself up for every agent you already use.
 
-Now the work is yours. What did it actually change? Did it understand what you
-meant? Is any of it wrong in a way you would only notice next week? And if it
-misread you in the first thirty seconds, everything after that was wasted.
+Then, in any project:
 
-kaizen puts two checkpoints in that gap.
+```
+/kaizen <what you want done>
+```
 
-**Before** it starts, you see a plan and say yes or no. **After** it finishes, a
-second agent — one that never saw the first agent's reasoning, so it has nothing to
-defend — checks the work and tells you what is wrong. You decide what gets fixed.
+That's it. No init and no config.
 
 ## See it
 
-Pick whichever looks like your work. The five stages are identical in all of them —
-what changes is what *done* and *wrong* mean, which kaizen works out from your
-request rather than asking you.
-
-<details open>
-<summary><b>A customer email</b> — pricing change announcement</summary>
-
 ```
 you    /kaizen rewrite the onboarding email — the new pricing starts on the 1st
 
@@ -70,8 +66,6 @@ kaizen Here is the plan.
          2. Add one line on what happens if they do nothing
          3. Keep the existing sign-off and legal footer untouched
 
-       Not doing: touching the pricing page itself — say the word if you want that too.
-
        Approve this plan?                    [ approve ]  [ change something ]
 
 you    approve
@@ -85,71 +79,32 @@ kaizen Done, and reviewed. Two things found:
        Fix them?                             [ both ]  [ just 1 ]  [ leave it ]
 ```
 
-Nobody told the reviewer to look for an untrue claim or a truncated subject line. It
-read the request, concluded this was a customer email, and reviewed it as one.
-
-</details>
+Nobody told the reviewer to hunt for untrue claims. It worked out that this was a customer
+email and reviewed it as one.
 
 <details>
-<summary><b>Code</b> — a bug in checkout</summary>
+<summary><b>Code</b>: a bug in checkout</summary>
 
 ```
 you    /kaizen the discount field lets you enter more than 100%
 
-kaizen Here is the plan.
-
-       This is a bug fix in the checkout code.
-       Done means: a discount above 100 is rejected, and the existing tests still pass.
-       Wrong means: valid discounts stop working.
-
-       What I will do:
-         1. Add a check in apply_discount() — cart.py:9
-         2. Cover it with three tests — 0%, 100%, 101%
-
-       Approve this plan?
-
-you    approve
-
 kaizen Done, and reviewed.
        Verified: ran the suite — 47 passed, 0 failed. Before the change: 44 passed.
 
-       One problem found:
-
        1. cart.py:12  medium  A discount of exactly 100 now returns 0 instead of
                               being rejected. Fix: use > not >=.
 ```
 
-`done` is a passing suite, so the builder has to show the run and its numbers —
-before and after. "It should work" is not accepted in any track.
+"It should work" is never accepted. The builder has to show the run and the numbers.
 
 </details>
 
 <details>
-<summary><b>Marketing</b> — a landing page for a launch</summary>
+<summary><b>Marketing</b>: a landing page for a launch</summary>
 
 ```
 you    /kaizen landing page copy for the Pro tier launch
 
-kaizen Here is the plan.
-
-       This is launch copy aimed at existing free users, not new visitors.
-       Done means: a free user understands what Pro adds and what it costs, and can
-       act without opening another page.
-       Wrong means: an overclaim, a benefit we do not actually ship, or a price that
-       disagrees with billing.
-
-       What I will do:
-         1. Headline and subhead — lead with the one thing free users ask for most
-         2. Four benefits, each tied to a shipped feature
-         3. Price block, pulled from the billing config so it cannot drift
-         4. One CTA, repeated twice
-
-       Out of scope: the pricing page, the in-app upgrade banner.
-
-       Approve this plan?
-
-you    approve
-
 kaizen Done, and reviewed. Three things found:
 
        1. benefits 3   high    "Unlimited exports" — the shipped limit is 500/month.
@@ -157,35 +112,16 @@ kaizen Done, and reviewed. Three things found:
        3. CTA          low     "Get started" appears on the free signup too. Ambiguous.
 ```
 
-The reviewer checked each claim against what actually ships. Finding 2 it refused to
-fix on its own and handed to you — deliberately.
+Every claim is checked against what actually ships.
 
 </details>
 
 <details>
-<summary><b>Research</b> — a decision memo</summary>
+<summary><b>Research</b>: a decision memo</summary>
 
 ```
 you    /kaizen should we move from per-seat to usage-based pricing? write it up
 
-kaizen Here is the plan.
-
-       This is a decision memo for the founders, not a market report.
-       Done means: a recommendation with the reasoning shown, and the case against it
-       stated fairly enough that someone could disagree on the evidence.
-       Wrong means: a conclusion the evidence does not support, or only looking at
-       the data that agrees with it.
-
-       What I will do:
-         1. Pull the last 12 months of seat counts and usage from the billing export
-         2. Model both against actual accounts — who pays more, who pays less
-         3. Name the three accounts that break the model, and by how much
-         4. Recommend, with the strongest argument against it stated first
-
-       Approve this plan?
-
-you    approve
-
 kaizen Done, and reviewed. Two things found:
 
        1. section 3  high    The recommendation rests on 4 accounts out of 60. That
@@ -194,34 +130,16 @@ kaizen Done, and reviewed. Two things found:
                              they are the ones the model treats worst.
 ```
 
-Nothing here was checked for tests or tone. `wrong` was defined as an unsupported
-leap and cherry-picked data, so that is what the reviewer went looking for.
+No tests, no tone check. It looked for unsupported leaps and cherry-picked data.
 
 </details>
 
 <details>
-<summary><b>Operations</b> — a migration runbook</summary>
+<summary><b>Operations</b>: a migration runbook</summary>
 
 ```
 you    /kaizen runbook for moving the database to the new region on Saturday
 
-kaizen Here is the plan.
-
-       This is a runbook someone else executes at 2am, not a description of a plan.
-       Done means: a colleague can follow it start to finish without asking a question.
-       Wrong means: a missing prerequisite, no way back, or a step that silently
-       loses data.
-
-       What I will do:
-         1. Prerequisites, with how to verify each one is true before starting
-         2. Steps in order, each with the exact command and what you should see
-         3. A rollback for every step that changes state
-         4. The point of no return, marked
-
-       Approve this plan?
-
-you    approve
-
 kaizen Done, and reviewed. Two things found:
 
        1. step 7   critical  No rollback after the DNS cutover, and it is not marked
@@ -232,491 +150,53 @@ kaizen Done, and reviewed. Two things found:
 
 </details>
 
-## The board
-
-`kaizen` opens a dashboard; **Board** is the screen where your work lives. Ideas you have
-not started sit on the left, runs sit under the stage they are actually in, and it redraws
-itself as your agents write to disk — a run that moves while you are looking at it moves on
-screen.
-
-```
-  Board   ~/work/acme
-
-  IDEA                     PLANNING              BUILDING           REVIEW          DONE
-  ──────────────────────   ───────────────────   ────────────────   ─────────────   ──────────────
-  › · FAQ page for the     ● q3 board memo       ◐ billing runbook  ● pricing       ○ chapter three
-      pricing change                                                  email
-                                                 ● oauth login                      ○ pricing
-    · onboarding video                                                                research
-      script, two minutes
-
-  ↑↓←→ move     n new  e edit  x reject  d delete  r run     a all projects  q back
-  ● running    ◐ stalled    ◌ starting    ● waiting on you    ○ done    · idea
-```
-
-**Throw an idea in with `n`** and it lands in `<state.dir>/inbox.md`, one line each, in the
-same format a run's backlog already uses. `e` edits, `x` rejects with a reason, `d` deletes.
-
-**`r` starts a run from an idea** — it asks `full` or `lite`, then opens your configured
-agent with the request already typed. The idea retires from the board once a run exists
-that was started from its text, whoever started it, so the same work never appears twice.
-That check spans every project you have opened, because an idea thrown into the global
-inbox becomes a run inside whichever project you launched the agent in.
-
-**The dot is what the run is doing.** `●` cyan is running and `◐` is stalled — kaizen
-records no liveness signal anywhere, so "running" means the run's `state.json` has changed
-in the last half hour. A run whose terminal you closed three days ago shows as stalled,
-which is the distinction the board exists to make. `●` amber, with the name in red, is a
-run that cannot move until you decide something; the legend lists only the states actually
-on screen.
-
-**A run's stage is kaizen's, not yours.** You cannot drag a card between columns — a board
-that could do that would be lying about what happened. The one exception is `x` on a run
-card, which abandons it: the same transition `/kaizen abort` makes, with your reason
-recorded in the run's approval file.
-
-`a` switches between this project and every project kaizen knows about. Below a hundred
-columns the board stacks into a list rather than squeezing five columns into sixty.
+## How it works
 
-### In a browser
-
-```bash
-kaizen web
-```
-
-serves the same board on `http://127.0.0.1:7420/` — loopback only, no account — and
-opens it in a Chromium-family browser as an app window when one is installed, otherwise
-in a tab.
-
-<img src="https://raw.githubusercontent.com/hfadhlullah/kaizen/main/assets/board-web.png" alt="kaizen web board" width="760">
-
-Same columns, same files: an idea added here lands in `inbox.md`, a run
-started here opens your agent in a new terminal exactly as `r` does (a new herdr tab
-or tmux window when one of those is running), and the board
-redraws as your agents write to disk. Mouse first; the TUI's keys still work. Click a card for its plan, review and
-backlog; `⋯` on a card runs, edits, rejects, abandons or archives. `Clear` on Done sends
-every finished run to the archive (`.kaizen/archive.md`, a list, nothing moves), and
-`Archive` in the strip shows what is there, with `Restore` on each card. A finished run in a project with a git remote gets `Commit & push` in its panel: it lists the changed files that run's report names, offers the commit message the builder wrote for the work (the `## Commit` section of its report; a message must start with a type such as `feat:` or `fix:`), commits those files and no others and pushes, and reads `Committed & pushed` afterwards (`Push` alone when the work is already committed). The `Review` tab of such a run, or of one waiting on you at the review, lists the findings with a checkbox each: `Fix all` or `Fix N selected` opens your agent in the project to fix exactly those and recheck them. The gear at the top right holds the browser's theme
-and every `kaizen settings` knob, same rows, same `config.yml`. `--port N` picks a port, `--no-open` just
-serves, the board opens on every project, or on the one picked last time in that browser; `?all=0` in the URL narrows it to the one it was started in. `--daemon` starts the server
-detached so it outlives the terminal (pid kept in `~/.kaizen/web.pid`); `--stop` ends it. `kaizen web --shortcut` adds a launcher
-the OS can find — Spotlight on macOS, the app menu on Linux, a Desktop shortcut on Windows. Each one starts the board in the background (`--daemon`) and opens it; `kaizen web --stop` ends it.
-On Windows `kaizen web` starts in the background unless `--foreground` is given; `kaizen web --stop` ends it.
-
-**A notebook beside the board.** The note icon in the board's header opens
-`/notebook`: markdown notes for the project, kept as plain files in `.kaizen/notes/`
-(folders included, so Obsidian can open the same folder). Notes are edited in place —
-the line you are on shows its markdown, the rest reads typeset, and `/` at the start of a line offers checkboxes, dividers, headings and the other blocks. `[[Other note]]` links
-notes and creates the one that does not exist yet, every note lists what links to it,
-`#tags` filter the list, and a `/` in a note's name puts it in a folder. Notes save as
-you type; a note changed elsewhere since you opened it is never overwritten without
-asking, and a deleted one goes to `.kaizen/notes/.trash/`. Notes link to the board too: `[[run:<id>#finding-2]]`, a tab (`#review`, `#backlog`), a backlog item (`#backlog-3`) or `[[idea:…]]` show as chips that open the board on that item, and a run's Notes tab lists the notes that link to it. The editor is CodeMirror,
-bundled into the package, so the notebook works offline.
-
-**Dictate instead of type.** Every text field on the board — a new idea, its notes, an
-edit, a reject reason, a note on a run — has a mic. Press it, talk, press it again; the
-words land at the caret next to whatever you had typed. Recognition is Whisper running
-inside the page, so audio never leaves your machine. The first press downloads the model
-from huggingface.co and caches it in the browser: `small` by default (about 410 MB,
-accurate across languages); `kaizen settings` → *Dictation model* — or the gear on the
-board — switches to `tiny`, `base`, or `large-v3-turbo` (about 1.5 GB, needs a capable GPU). The transformers.js library itself is fetched from jsDelivr the
-first time you press the mic in a session, so that first press needs the network; the
-model does not download again. Chromium and Edge qualify (Firefox falls back to the
-slower CPU path); a browser without a microphone API or WebAssembly shows no mic.
-
-### Request sources
-
-Requests that already live somewhere else — a team's Google Sheet, a Doc, a shared
-note — do not have to be retyped. The link icon beside the gear opens **Request
-sources**: paste a link, and kaizen reads it at once and adds every request it has not
-seen before to Ideas, each with a note saying where it came from and a *gathered* chip;
-the panel says what came back, or why the link could not be read. In a sheet, the header
-is looked for in the first five rows that hold anything, and a column headed `Request`,
-`Idea`, `Title`, `Task`, `PBI`, `Summary`, `Name`, `Detail`, `Details`, `Description`,
-`Deskripsi`, `Feedback`, `Issue`, `Permintaan` or `Judul` is the request; the other
-cells become its notes. Without such
-a header the request is one column for the whole sheet, the one holding the most text. A row whose `Status` column says `Done`,
-`Finish` or `Finished` is left out, and gathered later if its status changes. A doc or
-a plain-text link gives one idea per line.
-
-Nothing starts on its own: gathered requests sit in Ideas until you press Run.
-Gathering twice adds nothing, and an idea you deleted, edited or rejected does not come
-back. Rewording a row in the source makes it a new request. At most 50 arrive per
-gather; the rest come with the next one.
-
-While the board is running it checks each source every 24 hours — `kaizen settings` →
-*Gather requests*, or the gear, sets `off`, `1h`, `6h` or `24h` — and **Gather now**
-does it on demand. With the board stopped nothing is gathered. From a terminal:
-
-```
-kaizen sources add <link> [label]     kaizen sources        kaizen sources rm <link>
-kaizen gather
-```
-
-Kaizen fetches public `https` links only, with no login and no cookies: share a sheet
-or doc as "anyone with the link can view". A link that needs a sign-in, or a note app
-that only renders in a browser, says so in the panel; run `/kaizen gather` in your
-agent, which reads it with its own access and hands the requests over. Either way what
-a source says is treated as text for an idea, never as instructions. The links live in
-`<state.dir>/sources.json`.
-
-### Mouse
-
-Off by default. Turn it on in `kaizen settings` under `ui.mouse`, and clicking a row or
-card selects it, clicking it again opens or runs it, and the wheel scrolls — on the board,
-the menu, runs, backlog, projects and settings.
-
-It ships off because the trade is real: while the TUI holds the mouse, your terminal cannot
-select text with it, so copying a run id out of the dashboard stops working until you
-leave. Hold **Shift** and drag to select text anyway.
-
-## Install
-
-Kaizen's installer and interactive dashboard require [Bun](https://bun.sh) — it is
-the only prerequisite. Pick your platform:
-
-<details open>
-<summary><b>Windows</b></summary>
-
-In PowerShell:
-
-```powershell
-irm bun.sh/install.ps1 | iex; & "$env:USERPROFILE\.bun\bin\bunx.exe" kaizen-agent
-```
-
-One line, because the shell that just installed Bun does not have it on `PATH` yet;
-the full path sidesteps that. Next time, plain `bunx kaizen-agent`.
-
-Git is not required. Where it is missing, kaizen copies itself into `%USERPROFILE%\kaizen`
-instead of cloning, and `bunx kaizen-agent` is also how you update. Links are made as
-directory junctions and file copies, so no administrator rights or Developer Mode are
-needed. WSL users can follow the Linux instructions instead.
-
-</details>
-
-<details>
-<summary><b>macOS</b></summary>
-
-```bash
-curl -fsSL https://bun.sh/install | bash && ~/.bun/bin/bunx kaizen-agent
-```
-
-Or `brew install oven-sh/bun/bun`, then `bunx kaizen-agent`.
-
-</details>
-
-<details>
-<summary><b>Linux</b></summary>
-
-```bash
-curl -fsSL https://bun.sh/install | bash && ~/.bun/bin/bunx kaizen-agent
-```
-
-The full path is there because the shell that just installed Bun does not have it on
-`PATH` until you open a new one. Next time, plain `bunx kaizen-agent`.
-
-</details>
-
-The installer walks you through where to install, prompts for your workflow preset (`medium`, `low`, or `ultra`), then tells you what to type next. Restart your editor afterwards.
-
-Run from inside a project it asks whether to install globally or for that project
-alone; anywhere else — your home directory, a plain folder, a script — it installs
-globally without asking, since a project install outside a project has nothing to
-belong to.
-
-**It installs for every agent you already have.** The skill folders follow the open
-Agent Skills standard, so the same workflow runs under any of them:
-
-| Agent | Gets | Stages run |
+| | Stage | |
 |---|---|---|
-| Claude Code | Skills, the three stage agents, the slash commands | Each as its own subagent |
-| Codex | Skills | Sequentially, one session |
-| Antigravity | Skills | Parallel agents where available, else sequentially |
-| OpenCode, Cursor, Gemini CLI | Skills | Sequentially, one session |
-
-An agent counts as present if it has a config directory or a command on your PATH.
-Only what is already there is touched — installing does not create `~/.opencode` for
-someone who does not use OpenCode. Install again after adding an agent and it picks
-the new one up.
-
-**No agent yet?** kaizen does nothing on its own — it is a workflow an agent runs.
-If none is found, the installer says so and offers the list above, opening the
-install page for whichever you pick. Install it, run `kaizen` again, and carry on.
-
-The stage agents and slash commands are Claude Code's own formats and are not copied
-elsewhere; under the others you invoke the skill by name. `.kaizen/` is plain files
-either way, so a run started in one tool can be finished in another.
-
-Run `kaizen` anytime to open the terminal dashboard:
-
-```
-  ⠀⠀⠀⣰⠖⠾⣟⣛⠋⢉⣩⠽⢛⡽⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀
-  ⠀⠀⢰⢻⠀⠀⢀⡬⠟⠉⢀⠴⠋⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀
-  ⠀⢠⠇⣾⡠⠞⢩⠤⢄⡚⣁⣀⣀⣀⢀⣠⠤⡄⠀⠀⠀⠀⠀⠀    █ █  ▄▀█  █  ▀▀█  █▀▀  █▄ █
-  ⢠⣏⠔⣫⣀⡤⢸⠀⠀⠉⠁⠀⠀⠈⠉⠀⠀⡇⠀⠀⠀⠀⠀⠀    █▀▄  █▀█  █   ▄▀  ██▄  █ ▀█
-  ⢾⠥⢾⡅⢧⠀⢸⠃⡤⠖⠢⡀⢀⠔⠲⢤⠘⡇⠀⠀⣀⣀⠀⠀    █ █  █ █  █  █▄▄  █▄▄  █  █
-  ⠀⠀⠈⣇⠈⢠⣫⠞⠀⠘⢱⢣⡜⡎⠃⠀⠳⣝⡄⢠⠇⢻⢉⣷
-  ⠀⠀⠀⠘⢆⠀⠑⢦⣀⡀⠈⠓⠚⠁⢀⣀⣤⣊⣠⢾⡀⢠⣿⠃    0.7.2   plan · approve · build · review
-  ⠀⠀⠀⠀⠈⠓⢄⠀⠀⠉⣉⣭⣭⣉⠉⠀⠈⢀⣠⢔⡩⠥⢥⡀    ~/Projects/app
-  ⠀⠀⠀⠀⠀⠀⢠⡇⠀⡞⠁⠀⠀⠈⢳⠀⢰⣍⣠⠚⠧⡀⠀⡷    Claude Code, Codex, Antigravity, OpenCode, Gemini CLI
-  ⠀⠀⠀⠀⠀⠀⠸⡇⠀⣇⠀⠀⠀⠀⣸⠀⢠⡏⠀⠀⢀⣳⠞⠁
-  ⠀⠀⠀⠀⠀⠀⠀⠳⣀⣨⠥⠤⠶⠾⣅⣀⠞⠉⠉⠉⠉⠀⠀⠀
-
-  ╭─ Runs ──────────────────────────────────╮ ╭─ Backlog — 4 open ──────────────────────────╮
-  │ ● fix-discount       waiting on you     │ │ cart.py:12    low   use > not >=            │
-  │ ● cache-headers      in review          │ │ headline      med   legal review            │
-  │ ● 3 done                                │ │ … 2 more                                    │
-  ╰─────────────────────────────────────────╯ ╰─────────────────────────────────────────────╯
-
-  › All projects        every project kaizen knows about
-    Runs
-    Backlog
-    Settings
-    Upgrade
-    Quit
-```
-
-It monitors your runs and backlog across all your projects without having to open an agent.
-Installing puts the `kaizen` command on your PATH, so updating later is:
-
-```bash
-kaizen upgrade
-```
-
-That pulls the latest workflow, relinks anything new, and clears the installer cache
-`bunx` keeps — which is what otherwise leaves you on an old version without saying
-so. `bunx kaizen-agent upgrade` does the same thing if you would rather not have the
-command. `kaizen --version` prints what is installed; `bunx kaizen-agent --version`
-prints what npm has.
+| 1 | **Plan** | Reads your request, writes a plan. Changes nothing. |
+| 2 | **You approve** | Say yes, or say what to change. |
+| 3 | **Build** | Does the work, then *proves* it: runs the tests, checks each claim, walks each step. |
+| 4 | **Review** | A fresh agent checks the work and lists what's wrong. |
+| 5 | **Fix** | Serious findings get fixed and rechecked. The rest comes to you, never silently dropped. |
 
-Then, in any project, just ask for something:
+## Why people use it
 
-```
-/kaizen <what you want done>
-```
+- **It isn't just for code.** Emails, docs, runbooks, research. kaizen works out what *done* and *wrong* mean for each request, so a book chapter is never reviewed for race conditions.
+- **The reviewer has nothing to defend.** It starts cold, sees only the plan and the result, and finds what the builder talked itself past.
+- **A board for all your work.** Run `kaizen` in a terminal, or `kaizen web` in the browser. Ideas, plans, builds and reviews across every project, updating live. Start a run, approve or revise a plan, answer its questions, pick which findings to fix, then commit and push, all without opening a terminal.
+- **Requests come to you.** Paste a Google Sheet or Doc link and every request in it lands on the board as an idea.
+- **Notes and voice, offline.** A markdown notebook beside the board, plus dictation on every field. Whisper runs in the page, so audio never leaves your machine.
+- **Plain files, any agent.** Every run is a folder of markdown in `.kaizen/`. Start in Claude Code, finish in Codex, Antigravity, OpenCode, Cursor or Gemini CLI.
 
-The first run sets the project up on its own — a `.kaizen/` folder holding the run's
-files. Nothing to initialise by hand. (`/kaizen-init` exists if you want to do it
-ahead of time, and the installer offers it for the project you install from.)
-
-Setup also adds a short section to the project's `CLAUDE.md`, so you can stop typing
-`/kaizen` entirely — ask for something the normal way and work worth a plan goes
-through the stages on its own. It draws the line at work worth a plan: a change
-across more than one file, anything with a migration or a rollback, a document
-someone else will act on. Questions and one-line fixes are answered, not staged.
-Delete that section to go back to `/kaizen` being explicit.
-
-That is the whole thing. Everything below is detail.
-
-## How a run goes
-
-| | Stage | What happens |
-|---|---|---|
-| 1 | **Plan** | Reads your request and the existing material, writes a plan. Changes nothing. |
-| 2 | **You approve** | You see the plan and the work list. Say yes, or say what to change. |
-| 3 | **Build** | Does the work, then proves it — runs the tests, checks the claim against its source, walks the steps — and records what actually came back. |
-| 4 | **Review** | A different agent, which never saw stage 3's reasoning, checks the work and lists what is wrong, numbered and graded. |
-| 5 | **Fix** | Serious findings get fixed and re-checked, up to a limit. Anything left over is handed to you, never quietly dropped. |
-
-Each stage runs as its own agent with a clean slate, and writes a file before the
-next one starts. That is what makes stage 4 worth anything: a reviewer that watched
-itself do the work will defend it.
-
-Stage 3 is the one you can move. Set `build.executor` to `inline` and the agent you
-are already talking to does the work — you watch each step and can interrupt — or
-leave it as `subagent` and it is handed off and reported back, which keeps your
-conversation short and is the only workable choice on a big run. Set it to `ask` to
-be offered the choice each time you approve a plan. Stage 4 does not move: the
-reviewer is a separate agent either way, because that is the whole reason its
-findings are worth reading.
-
-## How it knows what kind of work this is
-
-kaizen is not a software workflow. The same five stages hold for a book chapter, a
-launch email, a migration runbook, or a research memo — what changes is what
-*deliverable*, *done*, and *wrong* mean.
-
-Each run works that out for itself — its **track** — by answering three questions
-from your request:
-
-- **What is the deliverable?** A merged change, a chapter, a landing page, a runbook.
-- **What counts as done?** Tests pass. The chapter reads end to end. A colleague can
-  follow the runbook unaided.
-- **What would make it wrong?** A security hole. A claim that is not true. A step
-  that silently loses data.
-
-The third answer is what the reviewer becomes. A reviewer hunting race conditions in
-a book manuscript is worse than no reviewer at all, and the track is what prevents
-it. You are never asked to categorise your own request — it reads the request and
-tells you what it concluded, so you correct a sentence instead of filling in a form.
+<img src="https://raw.githubusercontent.com/hfadhlullah/kaizen/c858bb6d666a65780d09c06032c8819489b87da5/assets/board.png" alt="kaizen web board" width="760">
 
 ## Commands
 
-| Command | What it does |
+| Command | |
 |---|---|
 | `/kaizen <request>` | Start a run |
-| `/kaizen-plan <request>` | Plan only — stop before anything is built |
-| `/kaizen-auto <request>` | No approval stops; report at the end |
-| `/kaizen-lite <request>` | Every stage in this session — cheap, and the reviewer has seen the work |
-| `/kaizen-full <request>` | Every stage its own cold agent — the independent review |
+| `/kaizen-plan <request>` | Plan only |
+| `/kaizen-auto <request>` | No stops; report at the end |
+| `/kaizen-lite <request>` | Every stage in this session: cheaper |
+| `/kaizen-full <request>` | Every stage its own cold agent: the independent review |
 | `/kaizen-review [target]` | Review something that already exists |
-| `/kaizen-status` | What is waiting on you, in flight, done |
-| `/kaizen-approve` | Approve whatever the run is waiting on |
-| `/kaizen-reject <reason>` | Send it back with a reason, or kill the run |
-| `/kaizen-run` | Carry on with an approved plan |
-| `/kaizen-backlog` | Everything noticed but not done, across all runs |
-| `/kaizen-abort` | Abandon the current run |
-| `/kaizen-gather` | Read the request sources kaizen cannot read by itself into Ideas |
-| `kaizen sources [add\|rm <link>]` | In a terminal: list, add or remove request sources |
-| `kaizen gather` | In a terminal: check every source now and add new requests to Ideas |
-| `/kaizen-config` | Show this project's settings and change them |
-| `/kaizen-init` | Set up the current project — optional, the first run does it |
+| `/kaizen-approve` · `/kaizen-reject <reason>` | Answer whatever the run is waiting on |
+| `/kaizen-run` · `/kaizen-abort` | Carry on with an approved plan, or drop the run |
+| `/kaizen-status` · `/kaizen-backlog` | What's waiting, in flight, done, or left over |
+| `/kaizen-gather` | Pull new requests from your sources onto the board |
+| `/kaizen-config` | Change this project's settings |
 | `/kaizen-help` | The full card |
 
-## What it writes
-
-Everything a run knows lives in files next to the work, not in a chat window:
-
-```
-.kaizen/
-  memory.md             # what past reviews learned about this project
-  runs/2026-09-07-onboarding-email/
-    00-request.md       # what you asked, word for word
-    01-plan.md          # the plan you approved
-    02-approval.md      # what you decided, and why
-    03-impl.md          # what changed, and the proof it works
-    04-review.md        # findings, numbered and graded
-    06-backlog.md       # what was noticed but not done
-```
-
-Plain files, so you can read them, commit them, and pick a run back up tomorrow —
-or in another tool. kaizen also runs under Codex and Antigravity, and a run started
-in one can be finished in another. See [adapters.md](https://github.com/hfadhlullah/kaizen/blob/main/skills/kaizen/adapters.md).
-
-## Settings
-
-`~/.kaizen/config.yml` — one file, every project. The three worth knowing:
-
-| Setting | Default | Meaning |
-|---|---|---|
-| `mode` | `approve` | `approve` stops for you; `auto` never does; `plan-only` stops after the plan |
-| `runner` | `full` | `full` gives each stage its own agent, so the reviewer never saw the work — several times the cost. `lite` runs every stage here, at about the cost of doing it by hand |
-| `build.executor` | `subagent` | Who does the work: a separate agent, `inline` in the current one, or `ask` each time |
-| `auto_fix.min_severity` | `high` | Findings this bad or worse get fixed without asking |
-| `approvals.plan` | `true` | Stop and show the plan before anything is built |
-| `ui.mouse` | `false` | Click to select, click again to act; while on, the terminal cannot select text |
-| `subagents.model` | `inherit` | Model the stage subagents run on: `inherit`, `opus`, `sonnet`, `haiku` (Claude Code only) |
-| `agent.<cmd>.model`, `agent.<cmd>.effort` | — | Model/effort the board launches a session with, per tool: `claude`, `codex`, `agy`, `opencode`, `gemini`. Model names are the tool's own (`agy models`) |
-| `subagents.effort` | `inherit` | Reasoning effort for the stage subagents: `inherit`, `low`, `medium`, `high` (Claude Code only) |
-
-```bash
-kaizen settings
-```
-
-opens a full-screen browser over the whole file — arrows to move and change, every
-change written as you make it, esc to close:
-
-```
-  kaizen settings   ~/.kaizen/config.yml
-
-  › preset                         medium
-    mode                           approve
-    runner                         full
-    build.executor                 subagent
-    approvals.plan                 true
-    approvals.review               false
-    auto_fix.enabled               true
-    auto_fix.min_severity          high
-    auto_fix.max_iterations        2
-    ...
-
-  Quick preset — low: inline & manual, medium: balanced, ultra: autonomous subagents
-
-  ↑↓ move · ←→ change · esc close     saved preset = medium
-```
-
-One project can differ: put a `.kaizen/config.yml` in it with just the keys to
-override, and it wins there while everything else follows the global file.
-It edits each line in place, so the comment above every key survives. `/kaizen-config`
-does the same thing from inside your agent if you would rather not leave it. Everything is also
-in [`config.default.yml`](https://github.com/hfadhlullah/kaizen/blob/main/skills/kaizen/config.default.yml),
-with a comment on each key, if you would rather edit the file.
-
-## Under the hood
-
-- [`SKILL.md`](https://github.com/hfadhlullah/kaizen/blob/main/skills/kaizen/SKILL.md) — how the workflow behaves
-- [`spec.md`](https://github.com/hfadhlullah/kaizen/blob/main/skills/kaizen/spec.md) — the tool-neutral contract every stage follows
-- [`adapters.md`](https://github.com/hfadhlullah/kaizen/blob/main/skills/kaizen/adapters.md) — running it under Codex or Antigravity
-
-<details>
-<summary>Installer flags, updating, and installing without bun</summary>
-
-| Flag | Effect |
-|---|---|
-| *(none)* | Ask when standing in a project, otherwise install globally |
-| `--global` | Globally, no question asked |
-| `--project` | Into the current directory only |
-| `--check` | Report what is linked, exit non-zero if anything is missing |
-| `--force` | Replace a real file sitting where a link belongs |
-| `--preset <name>` | Pre-select workflow preset (`low`, `medium`, or `ultra`) |
-| `--yes` | Take every default, ask nothing |
-| `--verbose` | List every link instead of a one-line summary |
-| `upgrade` | Pull, relink, and clear the installer cache. No prompts. |
-| `uninstall` | Remove the links, the clone, and the launcher. Asks whether to keep your runs and settings. The clone goes only when it is `~/kaizen`, cloned from kaizen's repository, with no local changes; any other `KAIZEN_HOME` is kept and named. |
-| `uninstall --purge` | The same, and delete `~/.kaizen` and this project's `.kaizen/` too. |
-| `settings` | Open the settings browser for the nearest `.kaizen/`. Also `config`. |
-
-Uninstalling works the same on Linux, macOS and Windows — `kaizen uninstall`, or
-`bunx kaizen-agent uninstall` when the command itself is already gone. It offers three
-answers — keep your runs and settings, remove everything, or cancel — and takes the
-first without asking when the output is not a terminal. It lists what it removed and what it kept; the `## Kaizen workflow` line in each project's `CLAUDE.md` is left for
-you to delete, since you may have edited around it.
-
-A global install also writes `~/.local/bin/kaizen` (`kaizen.cmd` in bun's bin
-directory on Windows), a two-line launcher pointing at
-the clone, so `kaizen upgrade` works from anywhere. It tells you if that directory is
-not on your PATH. `uninstall` removes it; `--project` installs skip it.
-
-Re-running is safe: correct links are left alone.
-
-`bunx` extracts a package once and reuses it without re-resolving, so a plain
-`bunx kaizen-agent` can keep running an old installer even after a new one is
-published. `upgrade` clears that copy, so the next run resolves fresh. The workflow
-itself — skills, agents, commands — comes from the clone and updates on any run.
-
-To work on kaizen itself, install from your own checkout so the links point at it:
-
-```bash
-git clone https://github.com/hfadhlullah/kaizen.git ~/kaizen
-cd ~/kaizen && bun run cli/install.ts
-```
-
-Without bun:
-
-```bash
-mkdir -p ~/.claude/skills ~/.claude/agents ~/.claude/commands
-ln -s ~/kaizen/skills/kaizen ~/.claude/skills/kaizen
-ln -s ~/kaizen/skills/kaizen-help ~/.claude/skills/kaizen-help
-for f in ~/kaizen/agents/kaizen-*.md; do ln -s "$f" ~/.claude/agents/"$(basename "$f")"; done
-for f in ~/kaizen/commands/kaizen-*.md; do ln -s "$f" ~/.claude/commands/"$(basename "$f")"; done
-```
-
-</details>
-
-## Reporting a bug
+In a terminal: `kaizen` (dashboard), `kaizen web` (board), `kaizen settings`, `kaizen upgrade`.
 
-```
-kaizen issue [what happened]
-```
+## Learn more
 
-Opens kaizen's GitHub bug form with your machine filled in: kaizen version, OS, arch,
-CPU, RAM, bun version, terminal. The board does the same from *Report an issue* in its
-footer, and every error it shows carries a *Report* link with the error already in the
-form. Your home folder is written as `~`; no hostname or username is included. Nothing
-is sent until you read it and press Submit on GitHub. `kaizen issue --env` only prints
-the details.
+- **[The guide](https://github.com/hfadhlullah/kaizen/blob/main/docs/guide.md)**: the board, request sources, notebook, settings, installer flags, uninstall
+- [`spec.md`](https://github.com/hfadhlullah/kaizen/blob/main/skills/kaizen/spec.md): the contract every stage follows
+- [`adapters.md`](https://github.com/hfadhlullah/kaizen/blob/main/skills/kaizen/adapters.md): running outside Claude Code, with Codex and Antigravity as the worked examples. OpenCode, Cursor and Gemini CLI load the same skill folder
+- Found a bug? `kaizen issue`, or *Report an issue* on the board, opens a GitHub bug form with your system details filled in. Nothing is sent until you press Submit on GitHub.
 
 ## License
 
-MIT. *Kaizen (改善) is Japanese for continuous improvement — small changes, checked
-as you go.*
+MIT. *Kaizen (改善) is Japanese for continuous improvement: small changes, checked as you go.*

package/agents/kaizen-planner.md

@@ -165,10 +165,15 @@ Write `01-plan.md` with exactly these sections:
 - **Track** — one or two sentences opening the plan: what kind of work this is, the
   deliverable, what done means, what wrong means. Stated as your reading of the
   request, so it can be corrected in a breath.
-- **Framing** — the problem in your own words: what is wrong now, what would be true
-  instead, and why it matters. Then the approach you chose, and the alternatives you
-  rejected with one line each on why. This section is what the human checks first; if
-  your restatement is off, everything after it is off too.
+- **Framing** — the problem in your own words, as short labelled bullets, not a
+  paragraph: **Problem** (what is wrong now, as the user meets it), **Fix** (what will
+  be true instead, and the approach you chose), **Rejected** (each alternative, one
+  line on why). This section is what the human checks first; if your restatement is
+  off, everything after it is off too.
+- **Work list** — the plan in plain bullets, one line per thing that will actually be
+  done, no jargon. It sits right after Framing and is shown again right before the
+  builder starts, so write it for someone who has not read the rest of the plan. Five
+  bullets is usually plenty; if it needs fifteen, the run is too big.
 - **Goal** — one paragraph in the user's terms describing what will be true when done.
 - **Scope** — bullets for what is included, then an explicit **Not included** list.
 - **Reuse** — existing material to build on: `path:line` for code, a section or page
@@ -182,10 +187,6 @@ Write `01-plan.md` with exactly these sections:
   it unaided for a runbook. Real and checkable, never a placeholder.
 - **Risks** — what could break, what is irreversible, what needs a backup or
   migration first. Call out anything touching data, auth, or production config.
-- **Work list** — the plan in plain bullets, one line per thing that will actually be
-  done, no jargon. This is shown to the user right before the builder starts, so
-  write it for someone who has not read the rest of the plan. Five bullets is usually
-  plenty; if it needs fifteen, the run is too big.
 - **Open questions** — every assumption that survived your analysis. Leave the list
   empty only if it genuinely is.
 
@@ -210,6 +211,13 @@ Write `01-plan.md` with exactly these sections:
   run's backlog, so write each as a standalone one-liner that still makes sense read
   months later with no plan around it.
 
+Write Track, Framing, Work list, Goal, Scope, Risks and Out of scope suggestions for a
+person deciding whether to approve, often on a narrow panel: everyday words, short
+sentences, one idea per bullet, things named by what the user sees rather than by
+function, file, CSS value or gate id. Code names, `path:line` and gate ids belong in
+Reuse, Steps and Verification, where the builder and reviewer need them exact. If a
+sentence only makes sense to someone who has read the code, it is in the wrong section.
+
 ## The goals are the user's, the solution is yours
 
 Expanding a one-liner into a clear problem statement is your job. Deciding what is

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kaizen-agent",
-  "version": "1.11.0",
+  "version": "1.12.0",
   "description": "Staged workflow for AI agents — code, writing, research, operations: plan, human approval, build, independent review, bounded fix loop.",
   "type": "module",
   "bin": {

package/skills/kaizen/SKILL.md

@@ -108,6 +108,17 @@ worth two more stages to confirm a one-line message now reads correctly. A findi
 `high` or above pulls the run back onto the full path whatever its size, since that
 severity is the loop's whole reason for existing.
 
+**Trivial changes take the direct path.** Where the request is one obvious change with
+nothing to decide — a typo, a label, a one-line copy or config tweak — a plan is longer
+than the work and a review re-reads what the user is about to look at anyway. Write
+`00-request.md`, build straight away, write `03-impl.md`, and stop at
+`stage: "review"`, `awaiting: "approvals.review"`: the user checks the result and
+approves it or says what to change. No `01-plan.md`, no plan approval, no
+`04-review.md` — the user's check is the review. Never the direct path for money, data,
+a migration, security, anything hard to undo, or a request with an open question; in
+`plan-only`, `auto`, or `/kaizen full`; or when in doubt. Work that turns out bigger
+mid-build stops and goes back to a plan.
+
 This is a judgement, not a threshold to enforce: fifty lines that change how money is
 rounded are not a small change. Say which path you took and why, in one line, when the
 run starts.

package/skills/kaizen/spec-build.md

@@ -9,6 +9,11 @@ builder's contract. The planner and reviewer do not read it.
 **Agent:** builder. **Input:** `01-plan.md`, `02-approval.md`, the track.
 **Output:** the deliverable itself, plus `03-impl.md`.
 
+On the direct path (see `spec.md`, Stage 0) there is no plan: the input is
+`00-request.md`, and the request is the scope. If the work turns out to need a
+decision, more than the one obvious change, or anything the direct path excludes,
+stop and send the run back to `stage: "plan"`.
+
 The builder produces whatever the track's deliverable is — code, a chapter, the
 campaign copy, the runbook — and nothing else.
 

package/skills/kaizen/spec-main.md

@@ -84,12 +84,15 @@ subagents at all.
 
 ## Final approval
 
-Controlled by `approvals.review`, skipped in `auto`.
+Controlled by `approvals.review`, skipped in `auto`. A direct-path run always stops here,
+whatever `approvals.review` says: the user's check is its only review.
 
 Report: what was built, verification results, findings fixed, findings still open,
 and anything the builder noted as out of scope. Where the run used `runner: lite`, say
 so in that report — the reviewer saw the work, and nobody should read a same-session
-review as an independent one because the output looked the same. Then stop. Committing, pushing, or
+review as an independent one because the output looked the same. Where the run took
+the direct path, say there was no plan and no review: the user's check is the review.
+Then stop. Committing, pushing, or
 opening a pull request happens only if the user asks.
 
 **Open findings are offered by number.** List them with the reviewer's numbering

package/skills/kaizen/spec-plan.md

@@ -44,10 +44,17 @@ scope suggestions* for a separate decision.
 
 The planner reads code but writes none. Its plan must contain:
 
-0. **Framing** — the problem in the planner's own words: what is wrong now, what
-   would be true instead, why it matters, the approach chosen, and the alternatives
-   rejected with a reason each. The human checks this first; a wrong restatement
-   makes everything after it wrong.
+0. **Framing** — the problem in the planner's own words, as a few short labelled
+   bullets rather than a paragraph: **Problem** (what is wrong now, as the user meets
+   it), **Fix** (what will be true instead, and the approach), **Rejected** (each
+   alternative with its reason, one line), then the track in one line. The human
+   checks this first; a wrong restatement makes everything after it wrong.
+
+   Right below it, the **Work list**: plain bullets, one line per thing that will
+   actually be done, written for someone who has not read the rest of the plan.
+   Five bullets is usually plenty. It sits second so the reader learns what will
+   happen before the detail; the plan approval shows it verbatim and the builder
+   tracks progress against it.
 1. **Goal** — one paragraph, in the user's terms, on what will be true when done.
 2. **Scope** — what is included, and an explicit *not included* list. The second list
    is what prevents the builder from wandering.
@@ -115,12 +122,22 @@ installs packages.
 fix loop reads it again per iteration, so a line written once is read five or six
 times. Sections 3 to 6 — the material to reuse, the file manifest, the steps, the
 verification — earn their length: they are what stop every later stage searching the
-material again, and cutting them costs more than it saves. Sections 0, 1, 8 and 10 are
-read once by a human at the approval and should be as short as they can be and still
-be correct: a paragraph of framing, a paragraph of goal, the risks that are real, the
+material again, and cutting them costs more than it saves. Sections 0 (Framing and the
+Work list), 1, 8 and 10 are read once by a human at the approval and should be as
+short as they can be and still be correct: a few labelled lines of framing, a short
+work list, a paragraph of goal, the risks that are real, the
 questions that are open. An alternative rejected gets a line saying what and why, not
 a case against it.
 
+**Write the parts a person reads for a person.** Framing, the Work list, Goal, Scope,
+Risks and Out of scope suggestions are read by someone deciding whether to approve,
+often on a narrow panel. Write them in everyday words: short sentences, one idea per
+bullet, things named by what the user sees ("the chat bubble", "the Plan tab") rather
+than by function, file, CSS value or gate id. Code names, `path:line` and gate ids
+belong in Reuse, the File manifest, Steps and Verification, where the builder and
+reviewer need them exact. If a sentence only makes sense to someone who has read the
+code, it is in the wrong section.
+
 A plan whose framing is longer than its steps is a plan that spent the run's budget
 explaining itself.
 
@@ -133,8 +150,8 @@ Controlled by `approvals.plan` (default on), skipped in `auto`.
 Present to the user, in this order:
 
 1. The track, the goal, and the top risk — a few lines, not the whole plan file.
-2. **The work list**, verbatim from the plan: plain bullets of what will actually be
-   done. This is the last thing the user sees before anything is produced, so it must
+2. **The work list**, verbatim from the plan, where it sits right after Framing:
+   plain bullets of what will actually be done. This is the last thing the user sees before anything is produced, so it must
    be readable on its own, without the plan's reasoning around it.
 3. The open questions, **as a pick list** — see below.
 

package/skills/kaizen/spec.md

@@ -5,7 +5,8 @@ follow this document; only the way stages are dispatched differs per tool. If an
 adapter and this file disagree, this file wins.
 
 A stage may only start when the previous stage's artifact exists on disk and the approval
-between them, if enabled, has been resolved.
+between them, if enabled, has been resolved. The one exception is the direct path
+(see *Stage 0*), which skips the plan and the review on purpose.
 
 ---
 
@@ -108,7 +109,10 @@ write, refreshed on every later one.
 `stage` takes exactly one of five words, and boards key their columns on them:
 `plan`, `build`, `review`, `done`, `abandoned`. Set it when the stage starts —
 `build` before the builder touches anything, `review` before the reviewer reads — as
-its own write, not tacked onto a longer command that may not finish. Any other word
+its own write, not tacked onto a longer command that may not finish. Fixing findings
+is building and a recheck is reviewing, whoever runs them and whether the loop or the
+user picked the findings: `build` with `iteration` raised and `awaiting: null` before
+each iteration's first edit, `review` before its recheck reads. Any other word
 (`implement`, `fix`, `building`) is unknown to every reader and shows as still planning.
 
 `awaiting` is `null` or the config key of the approval being waited on —
@@ -131,6 +135,16 @@ the config said the day someone came back to it.
 If the request remains ambiguous enough that a plan would be guesswork, ask now. One
 round of questions here is cheaper than a rejected plan.
 
+**The direct path.** Where the request is one obvious change with nothing to decide —
+a typo, a label, a one-line copy or config tweak — and being wrong is cheap and
+visible, intake may skip the plan and the review: say so in one line, set
+`stage: "build"`, build against `00-request.md`, write `03-impl.md`, then set
+`stage: "review"`, `awaiting: "approvals.review"` and stop for the user to check the
+result. No `01-plan.md` or `04-review.md` is written, and no `02-approval.md` unless
+the user revises at that stop. Never for money, data, a migration, security, anything
+hard to undo, or a request with an open question; never in `plan-only` or `auto`
+mode or under `runner: full`; and when in doubt, not.
+
 ---
 
 ## Stage files

package/web/board.html

@@ -210,7 +210,7 @@ aside .foot .more .menu-pop{left:0;right:auto;top:auto;bottom:calc(100% + 4px)}.
 .srow .hint{grid-column:1;margin:0;font-size:12px;color:var(--dim);line-height:1.45;max-width:46ch}
 .srow input.sel{width:170px}
 .fpick{display:inline-flex;gap:6px;align-items:center}
-.srow[hidden],.sg[hidden],.sjump button[hidden]{display:none}
+.srow[hidden],.yolo[hidden],.sg[hidden],.sjump button[hidden]{display:none}
 /* search and section chips: pinned to the top of the panel while the rows scroll under it */
 .sq{position:sticky;top:-24px;z-index:1;background:var(--bg-2);padding:24px 0 12px;margin:-24px 0 4px;border-bottom:1px solid var(--line)}.sq input{width:100%;max-width:none}.sq+.sg{margin-top:16px}
 .sjump{display:flex;flex-wrap:wrap;gap:6px;margin-top:10px}.sjump button{padding:3px 10px;border:1px solid var(--line);border-radius:var(--r-pill);font-size:12px;color:var(--dim)}.sjump button:hover{background:var(--hover);color:var(--ink)}
@@ -232,7 +232,9 @@ aside .foot .more .menu-pop{left:0;right:auto;top:auto;bottom:calc(100% + 4px)}.
 .toast.on{opacity:1}
 .toast.on.rep{pointer-events:auto}.toast a{color:inherit;margin-left:8px;text-decoration:underline;text-underline-offset:2px}
 .help{position:fixed;inset:0;z-index:12;display:none;align-items:center;justify-content:center;background:color-mix(in srgb,var(--bg) 60%,transparent);backdrop-filter:blur(3px)}
-.help.on{display:flex}.help div{background:var(--bg-2);border:1px solid var(--line);border-radius:var(--r);padding:24px 28px;line-height:2.2;box-shadow:var(--shadow-2)}
+.help.on{display:flex}.help div{background:var(--bg-2);border:1px solid var(--line);border-radius:var(--r);padding:24px 28px;box-shadow:var(--shadow-2)}
+.help p{margin:0 0 16px;color:var(--dim)}.help dl{display:grid;grid-template-columns:auto 1fr;gap:10px 20px;align-items:center;margin:0}.help dt{display:flex;gap:6px;justify-content:flex-end}.help dd{margin:0}
+.help kbd{font:12px/1 ui-monospace,monospace;padding:4px 7px;border:1px solid var(--line);border-bottom-width:2px;border-radius:var(--r-s);background:var(--bg);color:var(--ink-hi)}
 /* request sources: cards, status badges, top bar, and add-box */
 .src-topbar{display:flex;justify-content:space-between;align-items:center;padding:10px 14px;background:var(--bg);border:1px solid var(--line);border-radius:var(--r);margin:14px 0 16px;gap:12px}
 .src-topbar .meta{display:flex;flex-direction:column;gap:2px}
@@ -346,8 +348,8 @@ aside .foot .more .menu-pop{left:0;right:auto;top:auto;bottom:calc(100% + 4px)}.
 </aside>
 <div class="toast" id="toast" role="status"></div>
 <div class="help" id="help"><div>
-Optional. Everything here is also a button.<br>
-<kbd>←↓↑→</kbd><kbd>hjkl</kbd>move between cards<br><kbd>Enter</kbd>open<br><kbd>←→</kbd><kbd>hl</kbd>tabs, in an open run<br><kbd>↑↓</kbd><kbd>jk</kbd>scroll, in an open run<br><kbd>n</kbd>new idea<br><kbd>e</kbd>edit<br><kbd>x</kbd>reject / abandon<br><kbd>r</kbd>run<br><kbd>a</kbd>all projects<br><kbd>Esc</kbd>close<br><kbd>?</kbd>this list</div></div>
+<p>Optional. Everything here is also a button.</p>
+<dl><dt><kbd>←↓↑→</kbd><kbd>hjkl</kbd></dt><dd>move between cards</dd><dt><kbd>Enter</kbd></dt><dd>open</dd><dt><kbd>←→</kbd><kbd>hl</kbd></dt><dd>tabs, in an open run</dd><dt><kbd>↑↓</kbd><kbd>jk</kbd></dt><dd>scroll, in an open run</dd><dt><kbd>n</kbd></dt><dd>new idea</dd><dt><kbd>e</kbd></dt><dd>edit</dd><dt><kbd>x</kbd></dt><dd>reject / abandon</dd><dt><kbd>r</kbd></dt><dd>run</dd><dt><kbd>a</kbd></dt><dd>all projects</dd><dt><kbd>Esc</kbd></dt><dd>close</dd><dt><kbd>?</kbd></dt><dd>this list</dd></dl></div></div>
 
 <script>
 // The page never touches the filesystem. Everything comes from /state and the run
@@ -747,7 +749,7 @@ async function openRun(c,refresh,again){
 // run last moved: the same approval reached again after a revise is a new question.
 // The footer's More menu is a <details>: close it on a click anywhere else.
 document.addEventListener("click",e=>{for(const d of document.querySelectorAll(".more[open]"))if(!d.contains(e.target))d.open=false});
-const APPROVAL={"approvals.plan":"The plan is ready. Read it in the Plan tab, then approve or send it back.","approvals.review":"The work is reviewed. Approve to finish it, or revise with what to change."},decided=new Set(),answer=c=>key(c)+":"+c.awaiting+":"+c.moved;
+const APPROVAL={"approvals.plan":"The plan is ready. Read it in the Plan tab, then approve or send it back.","approvals.review":"The work is ready to check. Approve to finish it, or revise with what to change."},decided=new Set(),answer=c=>key(c)+":"+c.awaiting+":"+c.moved;
 async function decide(c,b,why,answers){b.disabled=true;askNotify();const r=await post("/decide",{dir:c.state,id:c.id,awaiting:c.awaiting,...(why===undefined?{}:{why}),...(answers?{answers}:{})});
  // A failed send keeps the footer, and with it a typed comment.
  if(!r.ok){b.disabled=false;return}