@gavin-hu/my-pi-agent 0.20.0 → 0.22.0

package/docs/extensions/plan.md

@@ -8,50 +8,50 @@ executes.
 
 ## Capabilities
 
-Status records what a reader can rely on: **Shipped** is in a tagged release, **Unreleased** is complete in the current tree but not yet tagged, and **Partial** has one released part and one unreleased part. Rows are ordered by user value, highest first.
-
 ### Planning lifecycle
 
-| Capability | How | What you get | Status |
-|---|---|---|---|
-| Read-only planning | `enter_plan_mode`, `/plan`, `Ctrl+Alt+P`, `--plan` | The session keeps only its readers, so the model investigates and proposes without touching the tree. | Shipped |
-| Confirmed model entry | `enter_plan_mode` | The model asks before it takes write access away, and the user answers first. | Shipped |
-| Read-only git shell | `bash` with the read-only git allowlist | Plan mode can inspect `git status`, `diff`, `log`, and `show`; pipes, redirects, and non-git commands are refused. | Shipped |
-| Read-only delegation | `subagent` with forced `readOnly: true` | A delegated agent can read and search but cannot write, edit, or run a shell while the plan is being researched. | Shipped |
-| Absolute-path guard | `path-guard.ts` | A path outside the project is refused unless it is a known plan-safe reader, so planning cannot write through an absolute path. | Shipped |
-| One writable artifact | `write_plan` | The plan lands as markdown under the agent directory, one store per repository, shared by its worktrees. | Shipped |
-| Approval gate | `exit_plan_mode` | The plan is read back and presented; nothing is written until the user approves it. | Shipped |
-| Session goal at approval | `goal` at approval | A `planning` goal is promoted to the plan's objective, and a session with none gets it, without a second dialog; an active goal is left alone. | Shipped |
-| Steps as todos | `exit_plan_mode` | Approval seeds the plan's steps into the todo list, with the verification section as the last item; approving the same plan again replaces the items its earlier approval seeded. | Shipped |
-| Plan kept current | `set_plan_steps` | Ticking a step rewrites its checkbox in the file and its todo item in one call. | Shipped |
-| Stale-step protection | `expected` in `set_plan_steps` | A step whose number moved, is out of range, or no longer matches its text refuses the whole batch instead of ticking the wrong line. | Shipped |
-| Cancel without a plan | `cancel_plan_mode`, `/plan cancel` | Write access returns, and no todo items or goal are recorded. | Shipped |
-| Plans index | `/plan list` | Every saved plan with its title, modified time, and step progress, newest first, under a header naming the store's size and its oldest plan. | Shipped |
-| Plan-store migration | `<repo>/.pi/plans` to the agent-dir store | A store left by an older version is moved in once, with a notice, so worktrees and main see the same index. | Shipped |
-| Instruction-file bootstrap | `/skill:init` | The packaged `init` skill plans and gates a project's `AGENTS.md`, writing only after approval. | Shipped |
-| Branch-following mode | the `plan-mode` session entry | `/resume` and `/tree` restore the mode and its tool set for the branch they land on. | Shipped |
+| Capability | How | What you get |
+|---|---|---|
+| Read-only planning | `plan` action `enter`, `/plan`, `Shift+Tab` (bytefly), `--plan` | The session keeps only its readers, so the model investigates and proposes without touching the tree. |
+| Confirmed model entry | `plan` action `enter` | The model asks before it takes write access away, and the user answers first. |
+| Read-only git shell | `bash` with the read-only git allowlist | Plan mode can inspect `git status`, `diff`, `log`, and `show`; pipes, redirects, and non-git commands are refused. |
+| Read-only delegation | `subagent` with forced `readOnly: true` | A delegated agent can read and search but cannot write, edit, or run a shell while the plan is being researched. |
+| Absolute-path guard | `path-guard.ts` | A path outside the project is refused unless it is a known plan-safe reader, so planning cannot write through an absolute path. |
+| One writable artifact | `plan` action `write` | The plan lands as markdown under the agent directory, one store per repository, shared by its worktrees. |
+| Approval gate | `plan` action `exit` | The plan is read back and presented; nothing is written until the user approves it. |
+| Session goal at approval | `goal` at approval | A `planning` goal is promoted to the plan's objective, and a session with none gets it, without a second dialog; an active goal is left alone. |
+| Steps as todos | `plan` action `exit` | Approval seeds the plan's steps into the todo list, with the verification section as the last item; approving the same plan again replaces the items its earlier approval seeded. |
+| Plan kept current | `plan` action `steps` | Ticking a step rewrites its checkbox in the file and its todo item in one call. |
+| Stale-step protection | `expected` in `plan` action `steps` | A step whose number moved, is out of range, or no longer matches its text refuses the whole batch instead of ticking the wrong line. |
+| Cancel without a plan | `plan` action `cancel`, `/plan cancel` | Write access returns, and no todo items or goal are recorded. |
+| Plans index | `/plan list` | Every saved plan with its title, modified time, and step progress, newest first, under a header naming the store's size and its oldest plan. |
+| Plan-store migration | `<repo>/.pi/plans` to the agent-dir store | A store left by an older version is moved in once, with a notice, so worktrees and main see the same index. |
+| Instruction-file bootstrap | `/skill:init` | The packaged `init` skill plans and gates a project's `AGENTS.md`, writing only after approval. |
+| Branch-following mode | the `plan-mode` session entry | `/resume` and `/tree` restore the mode and its tool set for the branch they land on. |
 
 ### Review
 
 | Capability | How | What you get | Status |
 |---|---|---|---|
-| Review screen | `exit_plan_mode` | A scrollable, themed plan with approve, refine, keep, browser, and exit in the footer. | Shipped |
+| Review screen | `plan` action `exit` | A scrollable, themed plan with approve, refine, keep, browser, and exit in the footer. | Shipped |
 | Browser page | `/plan review`, `w` on the review screen | The plan opens in a local browser as a reading-first page with live section and step progress. | Partial |
 | Approval in the browser | the `/plan review` page's **Approve & run** | The plan is approved without returning to the terminal, and the steps are seeded. | Shipped |
 | Inline comments | the page's `+ Comment`, **Save feedback** | Comments are saved into the plan file as `> [!REVIEW]` lines and returned to the model. | Shipped |
 | Live page | the page's `events` stream, the plan-file poll | An edit made elsewhere repaints every open page without a reload. | Shipped |
-| Changed sections | the `exit_plan_mode` review screen, the `/plan review` outline | After a refinement, only the sections that changed are marked. | Shipped |
+| Changed sections | the `exit` review screen, the `/plan review` outline | After a refinement, only the sections that changed are marked. | Shipped |
+| Block-level change marks | the `/plan review` page's **Changed** view | After a refinement, each block that is new or edited is marked — an inserted step marks itself and leaves the rest of its section alone — and a section that lost blocks says how much shorter it became. **All** / **Changed** / **Comments** switch what the page shows, `v` cycles them, `n`/`N` walk the blocks that carry a comment, and a printed review is always the whole plan. | Unreleased |
+| Settled comments | the page's `Resolve` / `Reopen` on a note you wrote | The note keeps its place, its quote and its history and is written `> [!REVIEW resolved]`, where a later review and the model read it as closed; the panel counts `2 open · 1 resolved`, and every card names who wrote it. | Unreleased |
 | Section navigation | the review screen, `n`/`p` | The screen names the section you are in and jumps between headings. | Shipped |
-| Remote review | `exit_plan_mode` on a WeChat turn | The plan file is sent, then one compact prompt to approve, keep planning, or exit. | Shipped |
+| Remote review | `plan` action `exit` on a WeChat turn | The plan file is sent, then one compact prompt to approve, keep planning, or exit. | Shipped |
 
 ### Collaboration
 
-| Capability | How | What you get | Status |
-|---|---|---|---|
-| Shared review | `/plan share`, **Share** | A reviewer link, with a QR a phone can scan, opens the same plan from another machine on this Wi-Fi. | Shipped |
-| One link per teammate | **New link**, **Revoke**, `/plan share stop` | Each teammate holds a link of their own, and one is revoked without disturbing the rest. | Shipped |
-| Two roles | the owner's `token`, a reviewer's link | Only the owner saves, approves, cancels, and manages links; a reviewer reads and comments. | Shipped |
-| Signed comments | the page's `name` control | A reviewer's name binds to her link on its first post, so her notes are hers and the file records who wrote them. | Shipped |
+| Capability | How | What you get |
+|---|---|---|
+| Shared review | `/plan share`, **Share** | A reviewer link, with a QR a phone can scan, opens the same plan from another machine on this Wi-Fi. |
+| One link per teammate | **New link**, **Revoke**, `/plan share stop` | Each teammate holds a link of their own, and one is revoked without disturbing the rest. |
+| Two roles | the owner's `token`, a reviewer's link | Only the owner saves, approves, cancels, and manages links; a reviewer reads and comments. |
+| Signed comments | the page's `name` control | A reviewer's name binds to her link on its first post, so her notes are hers and the file records who wrote them. |
 
 ## Quickstart
 
@@ -64,34 +64,43 @@ pi install ./                      # install the package for a user
 ```text
 /plan                                       # toggle plan mode
 /plan add rate limiting to the public API   # enter plan mode and send the task
+Shift+Tab                                   # toggle too, from bytefly's editor
 ```
 
-The model calls `enter_plan_mode` before a non-trivial task; `/plan` and
-`Ctrl+Alt+P` are the user's own switch.
+The model calls `plan` with action `enter` before a non-trivial task; `/plan` and
+`Shift+Tab` are the user's own switch. Shift+Tab is bytefly's: the editor binds
+it and asks plan through `PLAN_TOGGLE_REQUEST`, so a session that loads `plan`
+without bytefly uses `/plan` (or `--plan`) instead.
 
 ## Tools
 
-How the `write_plan` and `exit_plan_mode` calls and their results look in the transcript — the call line as a headline and the body indented under it:
+One tool with five actions — `enter`, `write`, `exit`, `steps`, `cancel` — because
+the verbs share one domain, the way `board` and `todo` keep theirs in one tool. How
+the `write` and `exit` calls and their results look in the transcript — the call
+line as a headline and the body indented under it:
 
-<img src="../../assets/tools/write_plan.png" alt="The write_plan tool's call and result: the call line and an indented body with the saved plan path and byte count" width="100%">
+<img src="../../assets/tools/plan-write.png" alt="The plan tool's write action: the call line and an indented body with the saved plan path" width="100%">
 
-<img src="../../assets/tools/exit_plan_mode.png" alt="The exit_plan_mode tool's call and result: the call line and an indented body with the approval line and the approved plan preview" width="100%">
+<img src="../../assets/tools/plan-exit.png" alt="The plan tool's exit action: the call line and an indented body with the approval line and the approved plan preview" width="100%">
 
-All five tools are `executionMode: "sequential"` and closed-world. Two are active
-in normal mode and three are `defaultActive: false`, so the plan-mode tool set
-stays small.
+The tool is `executionMode: "sequential"`, closed-world, and active in both modes;
+each action refuses outside its own, so plan mode never has to hide it. Its one
+annotation set is the strictest of the five, because `write` overwrites a plan file
+with `plan_path`; the actions that only change the mode are exempted by the guard
+in `index.ts`, the one place that can still tell them apart, and the policy's
+`isAllowed` stays a statement about files rather than about this tool.
 
-| Tool | Active | Purpose |
+| Action | Active | Purpose |
 |---|---|---|
-| `enter_plan_mode` | normal mode | Ask to enter plan mode; empty schema, confirmed with `ctx.ui.confirm`. |
-| `write_plan` | plan mode | Save the plan: `title` (file-name slug), `content` (full markdown in the documented outline), optional `plan_path` to overwrite a refinement. Returns the absolute path. |
-| `exit_plan_mode` | plan mode | Read the plan file (`plan_path`) and present it for approval. |
-| `cancel_plan_mode` | plan mode | Leave plan mode without a plan file or a review. Empty schema. |
-| `set_plan_steps` | normal mode | Set the checkboxes of the given top-level steps of an approved plan in one write, and their todo items with them. |
+| `enter` | either mode | Ask to enter plan mode; no fields, confirmed with `ctx.ui.confirm`. |
+| `write` | plan mode | Save the plan: `title` (file-name slug), `content` (full markdown in the documented outline), optional `plan_path` to overwrite a refinement. Returns the absolute path. |
+| `exit` | plan mode | Read the plan file (`plan_path`) and present it for approval. |
+| `steps` | normal mode | Set the checkboxes of the given top-level steps of an approved plan in one write, and their todo items with them. |
+| `cancel` | plan mode | Leave plan mode without a plan file or a review. No fields. |
 
-### `enter_plan_mode`
+### `enter`
 
-No parameters. It confirms with `ctx.ui.confirm` before switching the tool set,
+No fields. It confirms with `ctx.ui.confirm` before switching the tool set,
 because the model is changing the mode on the user's behalf; a declined confirm
 answers "stayed in normal mode" and the session keeps write access. Already
 planning, it says so. With no UI it fails with an actionable message instead of
@@ -100,12 +109,12 @@ deciding for the user.
 On a remote turn the confirmation is a short consent sentence in the peer's
 language, and the notice names how to leave.
 
-### `write_plan`
+### `write`
 
 `title` is the file-name slug, `content` the full markdown, and `plan_path`
 overwrites an existing plan when refining. The result carries the absolute path,
-the relative path, and the byte count — the absolute path is what `exit_plan_mode`
-takes.
+the relative path, and the byte count — the absolute path is what `exit` takes. A
+call with neither `title` nor `content` is refused before anything is written.
 
 The file lands in
 `<agent-dir>/plans/<repo-key>/<YYYY-MM-DD-HHmm>-<slug>.md`, keyed by the
@@ -115,8 +124,8 @@ repository the store is `<agent-dir>/plans`. Plans are outside the project, so
 they are never untracked files and never appear in a `rewind` snapshot; a store
 an older version left in `<repo>/.pi/plans` is moved in once, with a notice.
 
-The description documents a canonical outline — a `# <Title>`, then `## Goal`,
-`## Context`, `## Approach`, `## Visual`, `## Steps`, `## Risks`, and
+The tool's description documents a canonical outline — a `# <Title>`, then
+`## Goal`, `## Context`, `## Approach`, `## Visual`, `## Steps`, `## Risks`, and
 `## Verification` — and the model is guided to follow it. Every example in the
 template is the shape wanted rather than a description of it, and each section
 has one job: the goal is one sentence, the context is the facts that force the
@@ -139,7 +148,7 @@ A plan with more than 50 top-level steps in its `Steps` section is refused with
 the cap and the fix named, and nothing is written.
 
 The file is the source of truth. On approval the model follows the plan file's
-steps, and refinements rewrite the same file (`write_plan` with `plan_path`), so
+steps, and refinements rewrite the same file (`write` with `plan_path`), so
 the reviewed artifact is the executed artifact. The text a refinement replaces is
 kept beside it, as a dotfile named for the plan and the revision
 (`.2026-10-26-1008-add-rate-limiting-r001.md`), up to the newest five: that is
@@ -150,9 +159,9 @@ the review never offers it for approval — and a refinement that changed nothin
 keeps nothing, because the copy would be the plan itself. The write's result names
 the revision it kept.
 
-### `exit_plan_mode`
+### `exit`
 
-`plan_path` names the file `write_plan` returned; the tool reads it back and
+`plan_path` names the file `write` returned; the action reads it back and
 presents it for approval. A hand-edited or older file whose step list is over the
 cap is refused before the review screen. The user approves, keeps planning, asks
 for a refinement, or exits plan mode without approving; the last keeps the plan
@@ -172,19 +181,19 @@ the todo list:
 - The plan's `## Verification` section follows as the **last** todo item,
   summarized on one line (`Verify: …`) — a fenced block contributes its
   commands, not its fence lines. It is not a plan step, so it is ticked in the
-  todo list rather than with `set_plan_steps`, and it never counts against the
+  todo list rather than with the `steps` action, and it never counts against the
   50-step cap.
 - A plan without a `Steps` heading keeps the older rule — the shallowest list in
   the document — so prose bullets in a plan that follows the outline never become
   todos, and its verification bullets are already covered.
 - Each seeded item is matched back to its step by text, so ticking a step with
-  `set_plan_steps` completes the item too.
+  `steps` completes the item too.
 - An approval records the step texts it seeded, per plan path, as a `plan-seeded`
-  entry. A plan refined after approval is approved again — `write_plan` needs plan
+  entry. A plan refined after approval is approved again — `write` needs plan
   mode, so a second round is the way back — and that second approval **replaces the
   leftovers its own earlier approval made**: an untouched item whose step was
   renamed or dropped goes, while one somebody started or finished is kept and
-  named, because deleting it would erase work a reader did. `write_plan` says the
+  named, because deleting it would erase work a reader did. `write` says the
   list is stale when it refines a plan that was approved before.
 
 **Goal-aware.** While planning, the injected context restates a pursued session
@@ -196,15 +205,10 @@ the decision. A session with no goal at all is given the same objective, also
 without asking. An `active` or `achieved` goal is never rewritten: a final
 objective is the user's. No path spends a model turn.
 
-### `cancel_plan_mode`
-
-Leaves plan mode without a plan file or a review. Restores write access, records
-no todo items or goal, and keeps any saved plan. Empty schema.
-
-### `set_plan_steps`
+### `steps`
 
 Keep an approved plan current: `plan_path`, plus `updates`, each a 1-based `step`
-in the order `exit_plan_mode` listed, a `status` of `pending` or `completed`, and
+in the order `exit` listed, a `status` of `pending` or `completed`, and
 `expected` — the step's text, so an update whose step number moved is refused
 instead of ticking the wrong line. It is a single all-or-nothing write: a step out
 of range, or an `expected` text that no longer matches the file, refuses every
@@ -213,27 +217,32 @@ marker.
 
 The todo item approval seeded from a step is ticked with it: the file is written
 first and is authoritative, a renamed item is left alone and reported as
-unmatched, and a failed todo write is reported in the result. The tool refuses
-while plan mode is on — refine the plan with `write_plan` instead.
+unmatched, and a failed todo write is reported in the result. The action refuses
+while plan mode is on — refine the plan with `write` instead.
+
+### `cancel`
+
+Leaves plan mode without a plan file or a review. Restores write access, records
+no todo items or goal, and keeps any saved plan. No fields.
 
 ### Transcript
 
-The three tool rows reuse the transcript component, and `exit_plan_mode`
-separates the plan body from its header with a blank line; the collapse hint
-binds to `app.tools.expand` (`ctrl+o` by default).
+The blocks reuse the transcript component, and `exit` separates the plan body from
+its header with a blank line; the collapse hint binds to `app.tools.expand`
+(`ctrl+o` by default).
 
 ```
-enter_plan_mode requested plan mode
+plan enter
 ✓ Plan mode enabled
 ```
 
 ```
-write_plan Add rate limiting
+plan write Add rate limiting
 ✓ Saved plan ~/.pi/agent/plans/a1f9c02/2026-10-09-1809-add-rate-limiting.md
 ```
 
 ```
-exit_plan_mode submitted a plan
+plan exit 2026-10-09-1809-add-rate-limiting
 ✓ Plan approved
 ~/.pi/agent/plans/a1f9c02/2026-10-09-1809-add-rate-limiting.md
 
@@ -247,7 +256,7 @@ exit_plan_mode submitted a plan
 
 | Path | Who starts it | Confirmation |
 |---|---|---|
-| `enter_plan_mode` tool | the model, before a non-trivial task | `ctx.ui.confirm` |
+| `plan` (action `enter`) | the model, before a non-trivial task | `ctx.ui.confirm` |
 | `/plan` | the user | immediate |
 | `/plan <prompt>` | the user, with the task | immediate |
 | `/plan list` | the user, browsing the plans directory | immediate |
@@ -255,7 +264,7 @@ exit_plan_mode submitted a plan
 | `/plan share [stop]` | the user, handing the review to a teammate | immediate |
 | `/plan cancel` | the user, leaving plan mode without approving | immediate |
 | `/skill:init` | the user, creating or updating `AGENTS.md` | enters plan mode; write waits for plan approval |
-| `Ctrl+Alt+P` | the user | immediate |
+| `Shift+Tab` (bytefly) | the user | immediate |
 | `--plan` | the user, at launch | immediate |
 
 `/plan` with no argument toggles plan mode; `/plan <prompt>` enters it (if it is
@@ -267,10 +276,13 @@ already runs read-only:
 ```
 
 `/plan <prompt>` never disables plan mode; only the argument-less `/plan` (or
-`Ctrl+Alt+P`) toggles. Because slash commands go through Pi directly, `/plan` is
-the toggle that works in every terminal (for example Zed's integrated terminal,
-which does not forward `Ctrl+Alt+P`). The footer shows `≡ plan` while plan mode
-is on, and `≡ plan · <plan-file>` once the model has written a plan.
+`Shift+Tab`, through bytefly) toggles. Because slash commands go through Pi
+directly, `/plan` is the toggle that works with or without bytefly. Bytefly's
+footer shows `▶ auto` in accent in its mode segment, and `≡ plan` in warning there
+while plan mode is on; the bar draws that word itself, so the plan file name the
+chip carries never reaches it. `auto` is Pi's default mode — every tool as it ships,
+writes included — so the chip says which mode the session is in, not that a decision
+was taken for you.
 
 `/plan list` walks the plans directory and shows every plan with its title,
 modified time, and step progress, newest first — in the TUI as a docked list
@@ -291,7 +303,7 @@ never swallows one.
 `/plan share` prints the reviewer link and its QR, and `/plan share stop` revokes
 every link; the page's **Share** button does the same. With no browser review open
 it says so and points at `/plan review`. `/plan cancel` leaves plan mode without
-approving, exactly like `cancel_plan_mode`: write access returns and the plan file
+approving, exactly like `cancel`: write access returns and the plan file
 stays for a later review. Both are exact words — `share the tokens` and `cancel
 that idea` stay tasks — as is `list`.
 
@@ -310,7 +322,7 @@ approval. Its workflow is:
               └─ unavailable/cancelled ──> evidence + assumptions
         └─> draft: new file, exact edits, or an honest no-op
         └─> quality gate
-        └─> write_plan ──> exit_plan_mode
+        └─> plan · write ──> plan · exit
                              ├─ not approved ──> refine the same plan
                              └─ approved ──────> write/edit the target
                                                  └─ read back + quality checklist
@@ -366,9 +378,13 @@ session token, and the owner's token is the one that opened the page.
 | `POST /api/share/revoke?token=…` | owner only: revoke one link by `{ id }`, leaving the others answering |
 | `POST /api/share/stop?token=…` | owner only: revoke every reviewer link |
 
+Every route that reads a body takes JSON and only JSON: a form-encoded, `text/plain`,
+or headerless body is refused `415` before the role check, so a form cannot reach the
+parser even from the page's own origin.
+
 ## Behaviour by mode
 
-The review screen is TUI-only: `exit_plan_mode` opens `PlanViewComponent`, and `w`
+The review screen is TUI-only: `exit` opens `PlanViewComponent`, and `w`
 on it opens the browser review. RPC and other non-interactive runs get no screen.
 
 Dialog-capable non-TUI modes (RPC/WeChat) use one editor prompt instead: on a
@@ -391,10 +407,10 @@ its closing rule on a short terminal.
 Browser review is a local-turn feature: the server binds `127.0.0.1`, so a remote
 (WeChat) turn cannot reach it and `/plan review` there refuses with a notice
 instead of opening a server nobody can use. The browser's **Approve & run** is
-offered only for the review `exit_plan_mode` opens, since only that flow owns
+offered only for the review `exit` opens, since only that flow owns
 leaving plan mode; `/plan review` stays comment-only.
 
-Aborting the turn closes a browser review. `exit_plan_mode` forwards the call's
+Aborting the turn closes a browser review. `exit` forwards the call's
 abort signal to the review server, so an aborted turn returns "not approved"
 and stops listening instead of waiting on a page nobody is watching.
 
@@ -409,7 +425,7 @@ command. The read-only guarantee is layered:
   git commands through `bash` (chained with `&&`/`;`), `powershell` is blocked
   outright, and other mutating tools (worktree mutations, MCP tools) are blocked
   until you exit plan mode. `subagent` stays active but is forced read-only. The
-  only permitted write is the plan control tool `write_plan`, which can only
+  only permitted write is the `plan` tool's `write` action, which can only
   create or overwrite markdown plan files directly inside the plans directory —
   never dotfiles and never through a symlink.
 - **Capability policy.** A tool is allowed only when it is a known structured
@@ -421,18 +437,18 @@ command. The read-only guarantee is layered:
   file path is refused unless it is a known plan-safe reader. `path-guard.ts`
   scans nested arguments and path-shaped values, not just fixed top-level keys.
 - **Control-tool identity.** The `tool_call` guard exempts plan's own tools —
-  `enter_plan_mode`, `cancel_plan_mode`, `write_plan`, and `exit_plan_mode` — only
+  the `plan` tool's `write`, `exit`, and `cancel` actions — only
   when the registered tool is this extension's, matched by source path, so a
   same-named tool from another extension cannot borrow the exemption.
-  `enter_plan_mode` is exempted so a call already in flight when plan mode came on
+  the tool is exempted as a whole, and its `enter` action answers "already"
   is answered with "Already in plan mode" instead of being refused as not
   read-only; the policy still denies it, so it stays hidden while planning.
-- **Contained writes.** `write_plan` only writes markdown non-dotfiles whose
+- **Contained writes.** `write` only writes markdown non-dotfiles whose
   real parent resolves inside the plans directory, and every plan write —
-  create, refine, `set_plan_steps`, browser feedback — goes through a hidden
+  create, refine, `steps`, browser feedback — goes through a hidden
   temp file followed by a rename, so an interrupted write cannot leave a
   truncated plan.
-- **Sanitized model text.** The plan file is model-authored, so `exit_plan_mode`
+- **Sanitized model text.** The plan file is model-authored, so `exit`
   strips control characters from the plan body before rendering it in the
   transcript and in non-TUI notices; a plan file cannot drive the terminal.
 - **Loopback browser review.** The review server binds `127.0.0.1` and requires a
@@ -468,8 +484,19 @@ git diff -- extensions\plan      # allowed: a Windows path separator
 git status && rm -rf x            # blocked: the second segment is not git
 git status | sh                   # blocked: pipes are never allowed
 git diff > out.patch              # blocked: redirection is a write
+git config --get user.email       # allowed: a read
+git config --add core.hooksPath x # blocked: it writes .git/config
 ```
 
+`git config` reads only. Its flags are an allowlist — `--get`, `--get-all`,
+`--get-regexp`, `--list`, and the modifiers that shape them (`--show-origin`,
+`--show-scope`, `--local`, `--global`, `--null`) — one bare `git config <name>` reads a
+key, and every action that writes is refused by name: `--add`, `--replace-all`, `--unset`,
+`--unset-all`, `--rename-section`, `--remove-section`, `--edit`, or a `<name> <value>`
+pair. A write action used to pass as long as a read flag appeared beside it, so
+`git config --show-scope --replace-all core.fsmonitor /tmp/hook.sh` configured a hook from
+inside a plan and the next `git status` ran it.
+
 A refused shell command explains the fix: the working directory is already the
 project root (so `cd` is unnecessary), and files belong to the `read`, `grep`,
 `find`, and `ls` tools.
@@ -507,7 +534,7 @@ agent file that overrides it.
 
 <img src="../../assets/screens/plan.png" alt="The terminal plan review: a Plan Review title rule, a notice that one section changed since the last review, the plan body with its headings and ◼/◻ task checkboxes, a scroll gauge naming the current section and the visible line range, and the Esc/a/r/w, scroll, and section-jump hints" width="100%">
 
-`exit_plan_mode` opens this screen on the plan file it just wrote. The body is
+`exit` opens this screen on the plan file it just wrote. The body is
 rendered with Pi's own `Markdown` component and `getMarkdownTheme()`, so
 headings, lists, inline code, code blocks, links, and quotes carry the active
 theme's colours; task items get the shared `◼` (done) or `◻` (pending) marker,
@@ -562,6 +589,12 @@ reveals a **+ Comment** action on hover; select
 text first to quote it. **Save feedback** writes the comments into the plan
 file and returns them to the model.
 
+- **A comment can be settled.** **Resolve** (on your own note) keeps it — its place, its
+  quote, its history — and marks it `> [!REVIEW resolved]` in the file, where a later review
+  and the model both read it as closed; **Reopen** puts it back. The panel counts
+  `2 open · 1 resolved`. A note you wrote is labelled **You** on your page and **The owner**
+  on somebody else's, a reviewer's is `@name`, and one sentence beside the facts says what
+  **Approve & run** and **Save feedback** each do.
 - **Shared theme.** The page uses the same Bytefly tokens, base rules, and
   syntax-token colours as `file-browse` (`lib/web/`), follows the system light/dark
   preference until the header toggle sets an explicit choice, and remembers that
@@ -629,7 +662,7 @@ file and returns them to the model.
   Stripping is fence-aware: a `> [!REVIEW]` line inside a code block is
   documentation, not feedback. The file is the only copy of a saved comment; the
   ones this tab has not saved yet live in its own `sessionStorage` and nowhere else.
-- **A revision keeps the review.** `write_plan` passes the file it is replacing
+- **A revision keeps the review.** `write` passes the file it is replacing
   through `carryFeedback`, which re-attaches each comment by the strongest evidence
   that survived: the anchored block's text, per occurrence, so a plan that repeats
   a step keeps the comments apart; then the block whose wording still overlaps it —
@@ -654,14 +687,15 @@ file and returns them to the model.
   save that carries no comments asks for nothing, so the review screen comes back
   instead. `/plan review` sends them as a user message (a plan-mode revision or a
   plain update, depending on the mode).
-- **Loopback first, tokenized.** The server binds `127.0.0.1`, carries a random
-  per-session token in the URL, rejects a `Host` header it was not bound on,
-  refuses a cross-origin POST, serves only `GET`, `HEAD`, and `POST`, and caps the
-  request body. Sharing adds a second listener (below); it never widens the first. A save or cancel
-  resolves the session only after its HTTP response is delivered, so the browser
-  never sees a false "Failed to fetch". The last bound port is remembered per
-  plan, so reviewing the same plan again reuses the origin (and the browser's
-  saved theme with it). It is closed on the owner's save or cancel, on the owner's
+- **Loopback first, tokenized.** The review mounts `/plan/<id>` on the session's one
+  server, which binds `127.0.0.1`; the URL carries a random per-session token, a `Host`
+  header the server was not bound on is rejected, a cross-origin POST is refused, only
+  `GET`, `HEAD`, and `POST` are served, and the request body is capped. Sharing asks that
+  mount for one LAN listener (below); it never widens the loopback socket. A save or
+  cancel resolves the session only after its HTTP response is delivered, so the browser
+  never sees a false "Failed to fetch". The prefix is the review's, on the session's one
+  origin, so the browser's saved theme survives a review. It is closed on the owner's
+  save or cancel, on the owner's
   page going away, or on `session_shutdown`; a reload reconnects inside that grace,
   so refreshing or reloading a conflicted page does not end the review. A
   reviewer's tab opening or closing is not the review's lifetime.
@@ -741,13 +775,13 @@ both.
   keeps no registry, so it sees an external edit or a hand-copied plan
   immediately; it lists a file over the 256 KiB plan limit without reading it,
   and does not index the agent directory's plans while a worktree is active.
-- Approval tracks at most 50 steps: `write_plan` refuses a larger plan, and
-  `exit_plan_mode` refuses to present one, so no reviewed step is silently
+- Approval tracks at most 50 steps: `write` refuses a larger plan, and
+  `exit` refuses to present one, so no reviewed step is silently
   dropped. A step longer than 200 characters is shortened in the todo list and
   the approval listing — a display rule only, because the plan file always keeps
   the full text.
 - The todo item for a step is matched by its text. An item renamed after
-  approval no longer matches, so `set_plan_steps` leaves it alone and says so in
+  approval no longer matches, so `steps` leaves it alone and says so in
   its result; the plan file is still updated.
 - Browser review needs a local browser: the server is loopback-only, so a remote
   turn cannot drive it.
@@ -766,14 +800,24 @@ both.
   refuses a file it did not render (`409`). It is a poll rather than a file
   watcher, so a change on a filesystem that reports nothing at all is still seen
   at the next request, because every page read re-compares the file.
+- **A settled note is a flag in the marker.** `> [!REVIEW resolved]` (and
+  `moved resolved`) is read as open when absent; a build from before this one does not know
+  the flag and shows the marker line as body text, so a file reviewed on both sides of the
+  upgrade reads differently there.
 - A shared review holds at most eight links. Each is a live bearer credential, so
   a ninth is refused with the cap named rather than minted.
+- **One tool means one filter.** Pi's per-tool filter is all-or-nothing, so a
+  session that disables `plan` loses every action with it, and plan mode
+  force-activates the tool while it is on (and puts the user's set back when it
+  ends). `rewind` also snapshots a run at the tool's first call rather than at
+  the first real write, because one annotation set cannot say that `enter` writes
+  nothing; it is still one snapshot per run, of the same tree.
 
 ## Non-goals
 
 - **Not a sandbox.** Extensions share Pi's OS permissions.
 - **No progress tracker of record.** `todo` owns completion state; the plan
-  file only mirrors it (`set_plan_steps`), and plan mode does not read completion
+  file only mirrors it (`steps`), and plan mode does not read completion
   back out.
 - **No auto-execution.** Approval hands control back to the model.
 
@@ -781,10 +825,11 @@ both.
 
 | Integration point | How |
 |---|---|
-| Tools | `enter_plan_mode` (active; `readOnlyHint: true`), `write_plan` (`defaultActive: false`; `readOnlyHint: false`, `destructiveHint: true`), `exit_plan_mode` (`defaultActive: false`; `readOnlyHint: true`), `cancel_plan_mode` (`defaultActive: false`; `readOnlyHint: true`), `set_plan_steps` (active; `readOnlyHint: false`, `idempotentHint: true`). All five are `executionMode: "sequential"` and closed-world, and the read-only policy default-denies `set_plan_steps` while planning. Each returns typed `details` (`EnterPlanModeDetails`, `WritePlanDetails`, `ExitPlanModeDetails`, `CancelPlanModeDetails`, `SetPlanStepsDetails`), and `ExitPlanModeDetails` carries the review's `annotations` when a browser approval or save supplied comments; no `outputSchema`/`structuredContent`. |
-| Commands and flags | `/plan` (toggle, or enter and send a task), `/plan list` (plans index), `/plan review [path]` (browser review), `/plan share [stop]` (reviewer link), `/plan cancel` (leave without approving), `/skill:init` (skill-backed `AGENTS.md` bootstrap), `--plan` launch flag, `Ctrl+Alt+P` shortcut. |
+| Tools | one `plan` tool, active in both modes, with five actions: `enter`, `write`, `exit`, `steps`, `cancel`. It is `executionMode: "sequential"`, closed-world, and carries one annotation set — `readOnlyHint: false`, `destructiveHint: true`, `idempotentHint: false` — because `write` overwrites a plan file: the actions that only change the mode are exempted by the guard in `index.ts`, the only place that can tell them apart. Each action returns typed `details` discriminated by `action` (`EnterPlanModeDetails`, `WritePlanDetails`, `ExitPlanModeDetails`, `CancelPlanModeDetails`, `SetPlanStepsDetails`); a refusal carries `RefusedPlanDetails` (`refused`, `error`) and no action's state; no `outputSchema`/`structuredContent`. |
+| Commands and flags | `/plan` (toggle, or enter and send a task), `/plan list` (plans index), `/plan review [path]` (browser review), `/plan share [stop]` (reviewer link), `/plan cancel` (leave without approving), `/skill:init` (skill-backed `AGENTS.md` bootstrap), `--plan` launch flag. `Shift+Tab` is bytefly's editor chord, not a registered shortcut: `app.thinking.cycle` is reserved, so the editor requests a toggle over the event bus instead. |
 | State | Enabled flag and the tools it hid persisted with `pi.appendEntry("plan-mode", { enabled, removed })`, and each review's baseline persisted with `pi.appendEntry("plan-baseline", { path, sections })` as one digest per heading section; both rebuilt from `ctx.sessionManager.getBranch()`, so `/resume` and `/tree` restore the mode and the changed markers of the branch they land on. Plan writes a goal only at approval, through `ctx.executeTool("goal", { objective })` when the `goal` tool is registered: a `planning` goal is promoted to the plan's `## Goal`, a session with none is given the same objective, and an `active`/`achieved` goal is left alone — no path asks first. A review that shows the same content appends nothing. The last plan path lives in runtime memory for the footer chip, and a bare `/plan review` falls back to the newest plan file in the directory. |
-| Entry requests | `pi.events` channel `PLAN_ENTER_REQUEST` from `lib/plan-entry.ts`: the `goal` workflow asks, with the shared consent sentence, and plan enables the mode on the caller's context without a second dialog. Subscribed on `session_start`, released on `session_shutdown`. |
+| Entry requests | `pi.events` channels from `lib/plan-entry.ts`: `PLAN_ENTER_REQUEST` (the `goal` workflow asks, with the shared consent sentence, and plan enables the mode on the caller's context without a second dialog) and `PLAN_TOGGLE_REQUEST` (bytefly's Shift+Tab asks to flip it and gets the state back). Both share one `PlanModeRequest` payload and `isPlanExtensionLoaded`. Subscribed on `session_start`, released on `session_shutdown`. |
+| `board` while planning | The board is one action-shaped tool, so its annotation cannot say it reads: plan mode reads the action instead, through `lib/policy.ts`'s `isBoardRead` and `lib/board/actions.ts`'s table. The refusal is built by `boardWriteRefusal` in that same module — the board's words, because the sentence names the board's order: claim a card before you plan, and record its plan once it is approved. |
 | Hooks | `tool_call` blocks non-read-only calls and forces `subagent` read-only; `before_agent_start` injects the hidden `[PLAN MODE ACTIVE]` context, with a pursued session goal read from the branch through `lib/goal-state.ts`; `context` keeps only the newest plan context while enabled and drops stale ones otherwise. |
 | Lifecycle | `session_start`/`session_tree` restore state; `session_shutdown` clears the footer status and closes any browser review server. |
 
@@ -792,16 +837,16 @@ both.
 
 - **Consent is one dialog, whichever extension asks.** The goal workflow offers
   plan mode as a phase of the goal, but a command context cannot call
-  `enter_plan_mode` (`ExtensionCommandContext` has no `executeTool`). So the
+  the `plan` tool (`ExtensionCommandContext` has no `executeTool`). So the
   consent sentence left `policy.ts` for `lib/plan-entry.ts`, and the entry itself
   is a `pi.events` request: the asker shows the question, plan enables silently
-  with the asker's context. `enter_plan_mode` keeps its own confirm, using the
+  with the asker's context. The tool's `enter` action keeps its own confirm, using the
   same sentence, so the model-initiated path is unchanged and the two texts
   cannot drift. A request that nobody answers resolves `false` rather than
   hanging, so `goal` loaded alone still works.
 - **One review loop owns the human gate.** `review.ts` asks however the session
   is attached — TUI screen, dialog plus editor, remote file plus digest, or
-  browser — and returns one `ReviewDecision`, so `exit_plan_mode` and
+  browser — and returns one `ReviewDecision`, so `exit` and
   `/plan review` no longer carry two copies of the browser lifecycle and the
   tool's own `for(;;)` with a `continue` per outcome. The loop also owns the
   baseline rule (mark what the screen showed, after it showed it) and forwards
@@ -809,9 +854,11 @@ both.
 - **Two tools, not one.** `EnterPlanMode`/`ExitPlanMode` are a pair: entering is
   consent to explore read-only, exiting is consent to act. A single toggle tool
   cannot express "the model wants to plan but the user declines".
-- **User entry is instant, model entry confirmed.** `/plan`, `Ctrl+Alt+P`, and
-  `--plan` are the user's own action and take effect at once; `enter_plan_mode`
-  changes the mode on the user's behalf, so it confirms first.
+- **User entry is instant, model entry confirmed.** `/plan`, `Shift+Tab`, and
+  `--plan` are the user's own action and take effect at once; the `enter` action
+  changes the mode on the user's behalf, so it confirms first. Shift+Tab travels
+  through bytefly's editor and `PLAN_TOGGLE_REQUEST`, so the mode stays owned by
+  `plan` even when the key is pressed in another extension's surface.
 - **Review the file, decide in a screen.** The plan is a file, so it is the
   artifact already on screen. `ctx.ui.confirm()` is a non-scrollable selector
   that pushes buttons off-screen for a long plan, so the TUI gets a scrollable
@@ -819,7 +866,7 @@ both.
   renders the body with Pi's `Markdown` component so the plan reads like any
   other markdown in the app; the plan text is sanitized before it reaches the
   renderer, so only the theme's own ANSI survives.
-- **`write_plan` is the only write.** It is not the builtin `write`, so the
+- **`write` is the only write.** It is not the builtin `write`, so the
   capability policy and path backstop stay intact; a `plan_path` must name a
   markdown non-dotfile whose real parent resolves inside the plans directory,
   so symlinks and the directory's own `.gitignore` are never writable targets.
@@ -842,7 +889,7 @@ both.
   authoritative, so a failed nested write is reported in the result text — once
   one artifact has changed there is no previous state to hand back.
 - **A cap is enforced where it can still be fixed.** Both refusal points —
-  `write_plan` and `exit_plan_mode` — sit before the write and before the review,
+  `write` and `exit` — sit before the write and before the review,
   because those are the moments the model can still regroup the steps. A note on
   a successful write would arrive after the file existed and the review had
   already listed every step, which is exactly when the overflow becomes lost
@@ -856,7 +903,7 @@ both.
   a session entry rather than the previous text, so the markers survive a resume
   without copying the plan file into the branch, and the reader and the writer
   share one normalization so a tab cannot read as a change.
-- **The outline guides, it does not enforce.** `write_plan` documents the
+- **The outline guides, it does not enforce.** `write` documents the
   canonical shape in its description and stores whatever markdown it is given;
   no section is required and nothing is rewritten. The description names the two
   headings that do carry behavior — `Steps` is what approval reads as steps, and
@@ -868,7 +915,7 @@ both.
   source-line map, so `tui.ts` splits the body at its headings and renders each
   section separately. That gives exact offsets for the current-section label and
   `n`/`p`; the single-section case is byte-for-byte the old render.
-- **`set_plan_steps` is a second contained write.** It changes only the named
+- **`steps` is a second contained write.** It changes only the named
   steps' checkboxes, in an existing markdown plan inside the plans directory
   (`isContainedPlan`), in a single all-or-nothing write — refusing every entry
   if any step is out of range or an entry's `expected` text no longer matches —
@@ -925,20 +972,21 @@ both.
 
 | File | Responsibility |
 |---|---|
-| `index.ts` | Wiring: tools, command, flag, shortcut, events, context injection. |
-| `types.ts` | `PlanModeEntry`, `EnterPlanModeDetails`, `WritePlanDetails`, `ExitPlanModeDetails`, `CancelPlanModeDetails`, `SetPlanStepsDetails`. |
+| `index.ts` | Wiring: tools, command, flag, events, context injection. |
+| `types.ts` | `PLAN_ACTIONS`, `PlanModeEntry`, the five action `details` types and their `PlanDetails` union, and `RefusedPlanDetails`. |
 | `policy.ts` | Plan mode's read-only policy, the shared prompt summary, and the bash-refusal guidance. |
 | `git-bash.ts` | `checkReadOnlyGit`: the pure allowlist that restricts `bash` to read-only git commands. |
-| `plans.ts` | Plan-file store: slug/stamp naming, directory resolution (repository, active worktree, or agent directory), containment, `write`/`setSteps`/`saveFeedback`, and `read`/`latest`. |
+| `plans.ts` | Plan-file store: slug/stamp naming, the store's directory (`<agent-dir>/plans/`, keyed by the repository, unkeyed outside git, through `lib/plans/paths.ts`), `write`/`setSteps`/`saveFeedback`, and `read`/`latest`. |
+| `lib/plans/paths.ts` | Where a plan lives, and which paths are one: `plansDir` for `<agent-dir>/plans/` (keyed by the repository, unkeyed outside it), the markdown/non-dotfile name rule, symlink-safe containment, and `resolvePlanArg`. Shared with `board`, which records the file a card is executed against. |
 | `plan-files.ts` | How a plan file reaches the disk: `writeAtomic` (a dotfile temp, then a rename, so a crash cannot truncate the plan a review is reading) and `keepRevision`, which keeps the text a refinement replaces beside it, numbered, up to the newest five. |
 | `todos.ts` | Approval-time todo merge (pure): the last list replayed from the branch, and the merge of the plan's steps into it with the cap respected. |
 | `steps.ts` | Plan-document structure: the outline, step extraction and the `Steps`-section scope, the plan's own goal (`goalSection`), and the checkbox edit. |
 | `sections.ts` | The one fence-aware heading scan: `extractSections`, `sectionKeys` (the key that tells two identically titled sections apart), and the `HEADING` / `FENCE` / `normalizeHeadingText` vocabulary `blocks.ts` reads a heading through. |
 | `format.ts` | Pure result/approval text: the plan preview, the step-cap diagnosis, step labels, the merge summary, and the verification note. |
 | `plan-text.ts` | The plan text a review shows and compares: `sanitizePlanText`, the one normalization both sides use, the per-section `sectionDigests`, and `changedSections`, which hands each section back with its flag. |
-| `runtime.ts` | Enabled state, tool gating, persistence (mode and review baseline), control-tool identity, footer status. |
-| `tools.ts` | Registration entry: composes the five tool registrations in the order the session sees them. |
-| `tools/` | One module per tool (`enter.ts`, `write.ts`, `exit.ts`, `cancel.ts`, `steps.ts`), plus `todo-seed.ts` (the two nested `todo` writes) and `nested.ts` (reading a nested result). |
+| `runtime.ts` | Enabled state, tool gating, persistence (mode and review baseline), the `plan` tool's identity and its place in the active set, footer status. |
+| `tools.ts` | The one registration: the flat action schema, the dispatch over the five actions, and the call and result blocks they draw. |
+| `tools/` | One module per action (`enter.ts`, `write.ts`, `exit.ts`, `cancel.ts`, `steps.ts`), each exporting its `execute`/`call`/`text` seam; plus `refusal.ts` (the one rejected-call shape), `todo-seed.ts` (the two nested `todo` writes) and `nested.ts` (reading a nested result). |
 | `review.ts` | The review gate: one decision from the TUI screen, a dialog, or the browser, the shared browser lifecycle, and the "mark what was shown" baseline rule. |
 | `review-prompt.ts` | Pure rendering and parsing for the compact remote review: one action table behind both the prompt and the reply parser. |
 | `commands.ts` | `/plan` (enter, optional task), `/plan review [path]`, `/plan list`, `/plan share [stop]`, and `/plan cancel`. |
@@ -946,14 +994,18 @@ both.
 | `plan-index.ts` | `/plan list`: the notice text and the docked index screen (store size and oldest plan, title, step progress, age, focused path; Enter reviews). |
 | `blocks.ts` | Source-line block model (fence-aware headings, paragraphs, list items, code, quotes, tables, rules, blanks), and `contentBlockAt`: the block with content a comment beside blank space belongs to. |
 | `feedback.ts` | Comment codec: authored markers, `stripFeedback`, `readFeedback`/`parseFeedback` (body, blocks, and comments out of one parse), `formatFeedback` (writer-scoped), `displayFeedback`, `carryFeedback`, `feedbackSummary`, and payload validation. |
-| `web.ts` | `createPlanWebReview`: the review session (per-token roles, the change stream, the plan-file poll, the body cap, settle-after-flush, abort) over `lib/http`'s one loopback server. |
+| `review-lazy.ts` | The review gate behind a dynamic import: `reviewPlan` and `runBrowserReview` load `review.ts` (and its TUI screen) on the first review, so registration, `/plan cancel`, and the tool schemas never do. The decision and baseline types live here, where a type import costs nothing. |
+| `web-lazy.ts` | The review behind `lib/lazy`: `NO_SERVER_DEPS`, and the proxy `/plan` and the tools share, so `web.ts` loads on the first review and shutdown closes only an opened one |
+| `web.ts` | `createPlanWebReview`: the review session (per-token roles, the change stream, the plan-file poll, the body cap, settle-after-flush, abort) over `lib/http`'s one loopback server, and the router wiring — the island is `web-payload.ts` and the writes are `web-write.ts`. |
 | `web-tokens.ts` | The token table: the role each token names, the collision rule that keeps two roles off one token, and the names the other live links have bound. |
 | `web-streams.ts` | The event streams: who is listening, what a frame is addressed to, and the closed-tab grace that ends the review when the owner's page goes away. |
 | `web-router.ts` | Pure request handler: token role, `Host` allowlist, origin, and method checks through one POST-and-role guard, then the page, comment, owner-save, approve, cancel, and the four share routes. |
-| `web-page.ts` | The review page shell (header, reading progress, review facts, section outline, shortcut sheet, approve confirmation, share and name dialogs), its data island, and inline CSS. |
+| `web-page.ts` | The review page shell (header, reading progress, review facts, section outline, shortcut sheet, approve confirmation, share and name dialogs) and inline CSS. |
+| `web-payload.ts` | The page's data island: `ReviewPageData` and `reviewPageData`, which builds every fact the browser renders — the blocks, the stored comments, the outline and its change marks, the step progress, the highlighted code, the caps, and who is asking — from one read of the plan, with no server or socket in sight. |
+| `web-write.ts` | The review's two write paths over the plan store: `saveOwnerAnnotations` (the owner's save, which returns the plan it wrote) and `postReviewerAnnotations` (a reviewer's post, signed and scoped to its link), sharing one 404/409 check so a comment can never land beside text nobody read. |
 | `web-share.ts` | Pure sharing rules: the reachable LAN addresses from an injected snapshot, one tokenized URL, the link table (mint, find, revoke, list, state) with its cap, and the reasons a share is unavailable. |
 | `web-share-session.ts` | The shared listener: its bound address, the link table over the session's tokens, `ShareState`, and invite/revoke/stop/close, injected with the request handler, role map, and frame hooks. |
-| `web-keys.ts` | The client's keyboard as typed source (`WEB_KEYS_JS`): `handleKey` — Esc peels the composer before closing, a field and the shortcut sheet own their keys, and `s` is the write the page offers — and `rememberSelection`, which keeps the text a reader selected as the next comment's quote. |
+| `web-keys.ts` | The client's keyboard as typed source (`WEB_KEYS_JS`), and the one table the page's keys come from: `webKeys()` gives each binding its keys, the shortcut sheet's sentence, the sidebar hint's words and whether the page offers it — a function rather than a constant, because the bundle carries a body and `String()` of a table would drop the closures — read by `handleKey` (Esc peels the composer before closing, a field and the sheet own their keys, `s` is the write the page offers) and by the sheet and hint line the page renders; plus `rememberSelection`, which keeps the text a reader selected as the next comment's quote, and the `keyRows`/`surfaceOf` the handler and the page's own sheet both read, spliced with them for the same reason. |
 | `web-settle.ts` | The client's settlement as typed source (`WEB_SETTLE_JS`): `submitAnnotations` — one POST shape whose 409 disables the writes, offers a reload and says the server's own sentence — and the four ways a review ends, of which only the owner's save, approve and close settle it. |
 | `web-plan.ts` | The client's frame as typed source (`WEB_PLAN_JS`, `renderPlanFrame`): it draws every block and its comment rail, then puts the reader back — focus only when it was inside the plan, the active block in place rather than by scrolling. Reads arrive as getters, mutations leave as callbacks, so the bundle keeps every variable. |
 | `web-composer.ts` | The client's composer lifecycle as typed source (`WEB_COMPOSER_JS`): `closeComposer` (over one `ComposerDeps` the client builds where the state is), `reopenComposer` for the draft a reload interrupted, and `commentOnActive`, which returns the index so the client keeps its one `activeIndex`. |
@@ -962,7 +1014,7 @@ both.
 | `web-client.ts` | The `/client.js` source: the composition root, and nothing else by decision — the element handles, the state each rule is handed, one zero-argument adapter per rule, the listeners that attach them, the `EventSource` that keeps a tab's presence known, and the boot order. Every rule it used to hold lives in the `web-*.ts` modules below, where it can be typed and driven. |
 | `web-comments.ts` | The client's comment half: selection quotes, the composer, authored cards and who may edit them, delete-with-undo. |
 | `web-collab.ts` | The client's collaboration half: the link list with copy and per-link revoke, the reviewer's name, and the island refetch a stream frame triggers. |
-| `web-markdown.ts` | The client's document half: `safeHref` and the inline/table/code/list rendering (interpolated into `web-client.ts`). |
+| `web-markdown.ts` | The client's block half: tables, fenced code, headings, quotes, and lists, with each block's text handed to the shared `renderInline` from `lib/web/markdown.ts` (interpolated into `web-client.ts`). |
 | `web-chrome.ts` | The client's chrome half: the state chip, the status line, the header, and reading progress (interpolated into `web-client.ts`). |
 | `web-outline.ts` | The client's outline as typed source (`WEB_OUTLINE_JS`): `sectionFor` — the last heading at or before a line — `renderOutline`, which builds the list and hands back the counters it made, `observeSections`, which watches the blocks and returns the one watcher the client keeps, and `renderFacts`, which paints the step progress and counts each comment under its heading. |
 | `path-guard.ts` | Recursive path-argument detection for the read-only backstop. |
@@ -973,7 +1025,7 @@ both.
 | [`../../lib/qr.ts`](../../lib/qr.ts) | QR matrix, terminal half-blocks, and inline SVG for the share link (shared with `wechat`). |
 | [`../../lib/http/`](../../lib/http/) | The one loopback server entry, the bind, `Host` allowlist, header sets, and response kit both browser surfaces serve through. |
 | [`../../lib/web/index.ts`](../../lib/web/index.ts) | Shared Bytefly web brand system: tokens, base rules, `tok-*` colors, layout, the bootstrap, the toggle wiring, the shortcut sheet (`keysSheet`, `keysDialogScript`), and shared markup. |
-| [`../../lib/http/index.ts`](../../lib/http/index.ts) | Loopback HTTP layer shared with `file-browse`: the page policy and header sets, `ServeResponse`, the request-envelope helpers, bind/respond/close. |
+| [`../../lib/http/index.ts`](../../lib/http/index.ts) | The served-page kit shared with `file-browse`: the page policy and header sets, `ServeResponse`, the request-envelope helpers, bind/respond/close. Reached from the handler that serves a page; the mount contract is the leaf [`mount.ts`](../../lib/http/mount.ts). |
 | `../../lib/policy.ts` | Shared read-only capability policy (default-deny + `readOnlyHint`). |
 | `../../lib/tui/chrome.ts` | Shared screen header, viewport-row helper, and styled key-hint footer. |
 
@@ -983,21 +1035,27 @@ both.
 bun test extensions/plan
 ```
 
-Twelve co-located suites, declared in `test/suite-manifest.ts`:
+Thirteen co-located suites, declared in `test/suite-manifest.ts`:
 
-- `plans.test.ts` — the plan-file store: naming, directory resolution, atomic
-  writes, `read`/`latest`/`index`, containment, `setSteps`, `saveFeedback`, and
-  step extraction.
+- `plans.test.ts` — the plan-file store: naming, the store's directory, atomic
+  writes, `read`/`latest`/`index`, `setSteps`, `saveFeedback`, and step extraction;
+  the location and path rules it runs through (`plansDir`, `plansDirFor`, the name
+  rule, symlink-safe containment) are `lib/plans/paths.ts` and its own suite.
 - `feedback.test.ts` — the comment codec: authored markers, stripping and
   parsing, who a reviewer's write is signed by, carrying feedback onto a
   revision, and displaying stored comments.
-- `tools.test.ts` — registration and all five tools, the approval merge into
+- `tools.test.ts` — all five actions against a real plan store, the approval merge into
   `todo`, the session goal, and the call/result renderings.
+- `tool-registration.test.ts` — the registration itself: the flat action schema,
+  the strictest-of-five annotations, and the refusal each action gives when it
+  needs a field or runs outside its mode.
 - `review-prompt.test.ts` — the compact remote prompt and its reply parser
   against one action table.
-- `web.test.ts` — the browser review: the comment codec, the router, the page
-  roles and page shell, the client script, the stream, the plan-file poll, the
-  share rules, and a real loopback session.
+- `web-*.test.ts` — the browser review, one capability per suite: the comment
+  codec and the router (`web-router`), the page roles and its shell (`web-page`),
+  the client script's rules (`web-client`, `web-outline`, `web-composer`,
+  `web-settlement`), the stream and the plan-file poll (`web-stream`), the
+  loopback session (`web-session`), and the share rules (`web-shared-review`).
 - `web-behaviour.test.ts` — the served review, driven in a real browser through
   the router: the blocks and the plan's name, a block's comment control opening the
   composer with Escape peeling it before the review, a stored comment in its block's
@@ -1006,9 +1064,9 @@ Twelve co-located suites, declared in `test/suite-manifest.ts`:
 - `web-share.test.ts` — the LAN address selector, `shareUrl`, the link table with
   its cap, and the reasons a share is unavailable.
 - `commands.test.ts` — `/plan review`, `/plan list`, `/plan share`, and the one
-  review gate shared by `exit_plan_mode` and the browser, including the abort and
+  review gate shared by `exit` and the browser, including the abort and
   baseline rules.
-- `runtime.test.ts` — tool gating, persistence and status, control-tool identity,
+- `runtime.test.ts` — tool gating, persistence and status, the `plan` tool's identity,
   the review baseline, branch restore, the read-only git allowlist, and the
   path-argument scan.
 - `tui.test.ts` — the review screen at fixed widths: Markdown body, scrolling,
@@ -1016,6 +1074,5 @@ Twelve co-located suites, declared in `test/suite-manifest.ts`:
   refine editor, and the changed-section markers.
 - `sections.test.ts` — the fence-aware scan: heading shape, fences, the preamble,
 source lines and levels, and the occurrence key.
-- `extension.test.ts` — the Pi wiring: registration, the entry request, the
-  session lifecycle, the tool-call guard, injected context, the command, and the
-  shortcut.
+- `extension.test.ts` — the Pi wiring: registration, the enter and toggle requests,
+  the session lifecycle, the tool-call guard, injected context, and the command.