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

package/{extensions/file-open/README.md → docs/extensions/file-open.md}

@@ -5,11 +5,19 @@ handler, or reveals it in the file manager. `/open` does it interactively and
 the `open_path` tool does it from a script, both resolving the path against the
 effective working directory.
 
-## Tool rendering
+## Capabilities
 
-How the `open_path` call and its result look in the transcript — the call line as a headline and the body indented under it:
+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.
 
-<img src="../../assets/tools/open_path.png" alt="The open_path tool's call and result, drawn by the generic fallback" width="100%">
+| Capability | How | What you get | Status |
+|---|---|---|---|
+| Native open | `/open`, `open_path` | The file or directory opens in the application the OS associates with its type. | Shipped |
+| Reveal in the file manager | `/open -r`, `open_path` with `reveal: true` | The target is selected in the file manager instead of opened. | Shipped |
+| Working-directory resolution | `/open`, `open_path` | A relative path resolves against the effective working directory, so under [`worktree`](./worktree.md) `/open .` opens the isolated worktree. | Shipped |
+| Codemode-only exposure | `exposure: "codemode"` | The model cannot call `open_path` directly unless a codemode script asks for it; the table does not promise otherwise. | Shipped |
+| Pasted-path cleanup | `/open`, `open_path` | The editor's `@` mention prefix, surrounding quotes, and control characters are stripped before the path is used. | Shipped |
+| Failure reporting | `/open`, `open_path` | A missing path, a launcher that cannot start, and a non-zero exit after a successful start on macOS/Linux are reported. | Shipped |
+| Session-outliving launch | `/open`, `open_path` | The handler runs detached, so the application outlives the Pi session. | Shipped |
 
 ## Quickstart
 
@@ -25,21 +33,6 @@ pi install ./                               # install the package for a user
 /open -r src       reveal src in the file manager
 ```
 
-## What it does
-
-- Opens a file or directory with the OS-native application: `open` on macOS,
-  `explorer` on Windows, `xdg-open` on Linux.
-- Reveals it in the file manager instead with `-r` (or `reveal: true`): `open -R`
-  on macOS, `explorer /select,` on Windows, and the containing directory on
-  Linux, which has no "select" verb.
-- Unwraps the editor's `@` file-mention prefix and surrounding quotes, so
-  `/open @src/app.ts` and `/open @"my file.txt"` both work.
-- Reports a launcher that cannot be started, and (on macOS and Linux) a launcher
-  that exits non-zero because no handler accepted the target.
-- Resolves relative paths against the effective working directory, so under the
-  `worktree` extension `/open .` opens the isolated worktree.
-- Launches the handler detached, so it outlives the Pi session.
-
 ## Commands and flags
 
 ```bash
@@ -55,6 +48,8 @@ needs an interactive terminal UI.
 
 ## Tool
 
+<img src="../../assets/tools/open_path.png" alt="The open_path tool's call and result, drawn by the generic fallback" width="100%">
+
 `open_path` — `exposure: "codemode"`, inactive by default, not read-only,
 open-world (`openWorldHint: true` because it starts an OS process). It is listed
 by the `codemode` tool for a script to call as `tools.open_path(...)`, and an
@@ -106,6 +101,19 @@ JSON, and print modes; a codemode script can call it in any of them. Only the
   non-zero after a successful open, so only a failure to start is reported
   there. Nothing is retried.
 
+## Native handlers
+
+Both surfaces run the same command for a platform; the mode alone chooses
+between open and reveal.
+
+| Platform | Open | Reveal |
+|---|---|---|
+| macOS | `open <path>` | `open -R <path>` |
+| Windows | `explorer <path>` | `explorer /select,<path>` |
+| Linux | `xdg-open <path>` | `xdg-open <dir>` |
+
+Reveal has no native meaning on Linux, so there the containing directory opens.
+
 ## Limitations
 
 - Reveal has no native meaning on Linux, so it opens the containing directory.
@@ -127,7 +135,7 @@ JSON, and print modes; a codemode script can call it in any of them. Only the
 | Command | `/open [path]` and `/open -r [path]`; reports through `ctx.ui.notify`. |
 | State | None persisted, and none needed: every call is independent. |
 | Lifecycle | No `session_start` / `session_shutdown` hooks; the factory holds no long-lived resources. |
-| Host seams | `resolveEffectiveCwd` and `isExtensionEnabled` (`lib/env.ts`), `stripControlChars` (`lib/format.ts`), `spawn` / `open` / `xdg-open` / `explorer` (via the injected launcher in `open.ts`). |
+| Host seams | `resolveEffectiveCwd` and `isExtensionEnabled` ([`lib/env.ts`](../../lib/env.ts)), `stripControlChars` ([`lib/format.ts`](../../lib/format.ts)), `spawn` / `open` / `xdg-open` / `explorer` (via the injected launcher in [`open.ts`](../../extensions/file-open/open.ts)). |
 | Config | None. |
 
 ## Design notes
@@ -149,7 +157,7 @@ of the model's active tool set unless a script explicitly reaches for it.
 
 | Module | Responsibility |
 |---|---|
-| `index.ts` | The extension factory: registers `open_path` and the `/open` command, resolves the target, and routes a launch failure to `ctx.ui.notify`. |
-| `open.ts` | `normalizeTarget` and `buildCommand` (pure), `resolveTarget` (existence check), and `openTarget` with the injectable launcher, which reports a start failure and a meaningful non-zero exit. |
-| `schema.ts` | `TOOL_NAME`, the TypeBox `parameters` / `outputSchema`, and the `OpenPathArgs` / `OpenPathResult` types. |
-| `extension.test.ts` | The capability suite: normalization, resolution, per-platform commands, the launcher seam, registration, disabling, the tool call, and the command. |
+| [`index.ts`](../../extensions/file-open/index.ts) | The extension factory: registers `open_path` and the `/open` command, resolves the target, and routes a launch failure to `ctx.ui.notify`. |
+| [`open.ts`](../../extensions/file-open/open.ts) | `normalizeTarget` and `buildCommand` (pure), `resolveTarget` (existence check), and `openTarget` with the injectable launcher, which reports a start failure and a meaningful non-zero exit. |
+| [`schema.ts`](../../extensions/file-open/schema.ts) | `TOOL_NAME`, the TypeBox `parameters` / `outputSchema`, and the `OpenPathArgs` / `OpenPathResult` types. |
+| [`extension.test.ts`](../../extensions/file-open/extension.test.ts) | The capability suite: normalization, resolution, per-platform commands, the launcher seam, registration, disabling, the tool call, and the command. |

package/{extensions/file-read/README.md → docs/extensions/file-read.md}

@@ -8,12 +8,29 @@
 the effective working directory with the same symlink-aware guard the built-in
 path tools use.
 
+## 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.
+
+| Capability | How | What you get | Status |
+|---|---|---|---|
+| Document extraction | `read_doc` | Plain text from a document or workbook whose bytes the built-in `read` cannot decode. | Shipped |
+| Paged reading | `read_doc` (`startIndex`, `maxChars`) | A long file arrives in slices, and a truncated result names the offset to ask for next. | Shipped |
+| Workbook text | `read_doc` on `.xlsx` | One `[Sheet]` heading per worksheet followed by tab-separated rows, so the shape of the file survives. | Shipped |
+| Confined reads | `read_doc` | A path outside the effective working directory is refused, symlinks resolved, before any parser runs. | Shipped |
+| Progress and cancellation | `startToolProgress`, the abort signal | A slow extraction shows `Reading... <elapsed>` and can be cancelled instead of looking dead. | Shipped |
+| Bounded extraction | `file-read.maxFileBytes`, `file-read.extractTimeoutMs` | An over-size file or a parser past its deadline fails the read instead of parking the turn. | Shipped |
+| Per-format switches | `file-read.formats` | Any of the six formats can be turned off, and a disabled read names the key that did it. | Shipped |
+| Unsupported-format hint | `read_doc` on another extension | The refusal names the supported formats and the legacy `.xls` conversion hint instead of a generic read error. | Shipped |
+| Lazy parsers | `read_doc` | Only the format you read loads a library, so registration costs nothing at startup. | Shipped |
+| Code-point slicing | `read_doc` (`startIndex`, `maxChars`) | CJK and emoji stay well-formed across a page boundary. | Shipped |
+
 ## Quickstart
 
 ```bash
-pi --extension ./extensions/file-read   # this extension only
-pi -e .                                # the package from this checkout
-pi install ./                          # install the package for a user
+pi --extension ./extensions/file-read   # load just this extension
+pi -e .                                 # load the whole @gavin-hu/my-pi-agent package
+pi install ./                           # install the package
 ```
 
 The extraction libraries are ordinary dependencies, so a normal install brings
@@ -23,31 +40,15 @@ tool directly:
 ```jsonc
 { "path": "docs/spec.pdf" }
 { "path": "docs/spec.pdf", "startIndex": 40000, "maxChars": 40000 }
-{ "path": "report.xlsx" }
 ```
 
-## What it does
-
-- Extracts plain text from `.pdf`, `.docx`, `.doc`, `.odt`, `.rtf`, and `.xlsx`
-  files for the model to read.
-- Pages long files: when output is truncated, call again with the `startIndex`
-  named in the note.
-- Slices by code point, so CJK and emoji stay well-formed.
-- Reads only inside the effective working directory, resolving symlinks so a
-  link cannot escape it.
-- Loads a format's parser only when that format is actually read, so registration
-  costs nothing at startup.
-
 ## Tool
 
-`read_doc` — direct exposure, active by default, read-only, closed-world
-(no network).
-
-How the call and its result look in the transcript — the call line as a headline
-and the body indented under it:
-
 <img src="../../assets/tools/read_doc.png" alt="The read_doc tool's result: the call line and an indented body with the file path, format, size, and the extracted text preview" width="100%">
 
+`read_doc` — direct exposure, active by default, read-only, closed-world (no
+network). It takes one file and returns that file's text.
+
 | Parameter | Type | Meaning |
 |---|---|---|
 | `path` | string, required, 1–4096 chars | Path to a `.pdf`, `.docx`, `.doc`, `.odt`, `.rtf`, or `.xlsx`, relative to the working directory (or absolute inside it). |
@@ -74,14 +75,8 @@ the text says what the file was.
 
 Errors are thrown for: a missing or non-file path, a path outside the root, an
 unsupported extension (with a targeted hint for legacy `.xls`), a disabled
-format, an over-size file, and a parser that rejects the file. The extension
-installs nothing.
-
-## Behaviour by mode
-
-The tool behaves identically in `tui`, RPC, JSON, and print modes; it has no
-widgets or status output. `renderCall` / `renderResult` affect only the
-interactive transcript (and HTML exports).
+format, an over-size file, and a parser that rejects the file. No external
+executable is installed.
 
 The call line carries the path (`~`-shortened, OSC-8 linked when the terminal
 supports it) and any paging options. The result line drops the path — it is
@@ -117,11 +112,18 @@ applied, so the theme's own ANSI codes stay intact. A host-rejected call (a
 permission block, a validation failure) renders its own message through the same
 sanitized error path.
 
+## Behaviour by mode
+
+The tool behaves identically in `tui`, RPC, JSON, and print modes; it has no
+widgets or status output. `renderCall` / `renderResult` affect only the
+interactive transcript (and HTML exports).
+
 ## Configuration
 
-The `file-read` section of the shared `bytefly.json`, loaded from
-`~/.pi/agent/bytefly.json` then `<cwd>/.pi/bytefly.json` (project wins), each
-merged over the defaults and clamped:
+The keys live in the `file-read` section of the shared `bytefly.json`; resolution
+rules are in
+[`../configuration.md`](../configuration.md#file-read--document-and-spreadsheet-extraction).
+Each value is merged over the defaults and clamped:
 
 | Key | Default | Clamp | Meaning |
 |---|---|---|---|
@@ -163,16 +165,17 @@ reads only `file-read`, and `bun run config:migrate` renames an existing
 
 ## Extraction
 
-Each extractor builds a plain-text document from the format's bytes:
+Each extractor builds a plain-text document from the format's bytes. Every
+format is enabled by default; `file-read.formats` turns one off.
 
-| Format | Library | Output normalization |
-|---|---|---|
-| PDF | `unpdf` (`extractText`, `mergePages: true`) | Every page in reading order, pages separated by a blank line. No OCR: a scanned or image-only PDF yields little or no text. |
-| DOCX | `mammoth` (`extractRawText`) | The body story, paragraphs separated by blank lines. Headers, footers, footnotes, and comments are not included. |
-| DOC | `word-extractor` (OLE body) | The classic Word body story. |
-| ODT | `fflate` + `fast-xml-parser` | `content.xml` is unzipped and walked: paragraphs and headings are lines, table cells are tab-separated, and `text:s` / `text:tab` / `text:line-break` become their whitespace. |
-| RTF | `rtf-parser` | Paragraphs are flattened to their span text; formatting is dropped. |
-| XLSX | `exceljs` | One `[Sheet]` heading per non-empty worksheet, then tab-separated rows. Dates and numbers use the workbook's displayed text; formulas show their computed value. Cell formatting is dropped. |
+| Format | Extensions | Library | Output normalization |
+|---|---|---|---|
+| PDF | `.pdf` | `unpdf` (`extractText`, `mergePages: true`) | Every page in reading order, pages separated by a blank line. No OCR: a scanned or image-only PDF yields little or no text. |
+| DOCX | `.docx` | `mammoth` (`extractRawText`) | The body story, paragraphs separated by blank lines. Headers, footers, footnotes, and comments are not included. |
+| DOC | `.doc` | `word-extractor` (OLE body) | The classic Word body story. |
+| ODT | `.odt` | `fflate` + `fast-xml-parser` | `content.xml` is unzipped and walked: paragraphs and headings are lines, table cells are tab-separated, and `text:s` / `text:tab` / `text:line-break` become their whitespace. |
+| RTF | `.rtf` | `rtf-parser` | Paragraphs are flattened to their span text; formatting is dropped. |
+| XLSX | `.xlsx` | `exceljs` | One `[Sheet]` heading per non-empty worksheet, then tab-separated rows. Dates and numbers use the workbook's displayed text; formulas show their computed value. Cell formatting is dropped. |
 
 The tool is pageable across the whole extracted text, so a word-processing
 document or a workbook is read in the same `startIndex` / `maxChars` way as a PDF.
@@ -181,17 +184,6 @@ Each call is bounded by `extractTimeoutMs` (30 s by default). A parser that
 outlasts the deadline is abandoned — the read fails with the limit named, and a
 late result is discarded — so a pathological file cannot park the turn.
 
-## Supported formats
-
-| Format | Extensions | Extractor | Enabled by default |
-|---|---|---|---|
-| PDF | `.pdf` | `unpdf` | yes |
-| DOCX | `.docx` | `mammoth` | yes |
-| DOC | `.doc` | `word-extractor` | yes |
-| ODT | `.odt` | `fflate` + `fast-xml-parser` | yes |
-| RTF | `.rtf` | `rtf-parser` | yes |
-| XLSX | `.xlsx` | `exceljs` | yes |
-
 ## Adding a format
 
 The format table in `formats.ts` is the single source of truth; the handler,
@@ -208,7 +200,7 @@ config defaults, and error listing all derive from it.
 3. Add a `ReadFormat` entry to `FORMATS` and widen the `id` union.
 4. Add the new extractor to `extract/extract.test.ts` with a real minimal
    fixture, and extend `tool.test.ts` for format selection and config.
-5. Add a row to the tables above.
+5. Add a row to the format table above.
 
 `tool.ts`, `paging.ts`, and the config normalizer need no changes.
 
@@ -318,4 +310,4 @@ builds a genuine PDF, DOCX, and ODT; XLSX is written with `exceljs`; legacy `.do
 reads the committed `files/legacy.doc`), so the libraries are exercised, not
 stubbed. `tool.test.ts` injects fake extractors for behavioural cases and reads a
 real PDF and a real `.doc` end to end; `test/helpers/fixtures/file-read.ts`
-provides the scratch root and an escape symlink.
+provides the scratch root and an escape symlink.

package/{extensions/goal/README.md → docs/extensions/goal.md}

@@ -1,7 +1,27 @@
 # goal — a persistent session objective for Pi
 
 A single high-level objective for the session, kept visible and restated before
-every turn. The goal is the *what*; the [`todo`](../todo/) list is the *how*.
+every turn. The goal is the *what*; the [`todo`](./todo.md) list is the *how*.
+
+## 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.
+
+| Capability | How | What you get | Status |
+|---|---|---|---|
+| Goal recording | `goal`, `/goal set`, `/goal raw`, `/goal clear` | The objective is replaced whole, cleared by an empty value, and recorded verbatim when you ask for it. | Shipped |
+| Phase tracking | `goal`, `/goal done` | The goal is `planning`, `active`, or `achieved`, and only the workflow can open a draft. | Shipped |
+| Plan-first question | `goal`, `/goal <prompt>`, `/goal raw` | One dialog decides whether a new goal enters plan mode before it is pursued. | Shipped |
+| Plan-mode allowlist | `goal` in plan mode | The model can record or update the objective while plan mode keeps the rest of the session read-only. | Shipped |
+| Plan-phase settlement | `planning` goal, `exit_plan_mode` | Leaving plan mode without approval makes the draft `active`; approving the plan writes its `## Goal` into it. | Shipped |
+| Understanding loop | `/goal <prompt>`, `/goal set`, `/goal edit` | A typed goal is restated, questioned when it is unclear, and confirmed in the editor before it is recorded. | Shipped |
+| Goal rail | the `Goal · active · …` widget, the `achieved` key | The objective stays one line above the editor while it is pursued. | Shipped |
+| Per-turn restatement | the `[SESSION GOAL]` reminder | The model reads the pursued objective before each turn, without it entering the transcript. | Shipped |
+| Open-list check | `goal`, `/goal done` | Completing the goal names the todo items the list still has open. | Shipped |
+| Branch-following state | tool-result `details`, the `goal` session entry | The goal survives `/resume` and `/tree`, and abandoned branches never leak in. | Shipped |
+| Command help | `/goal help`, `/goal -h`, `/goal --help` | The verb list and the usage of each form, without changing the goal. | Shipped |
+
+## Quickstart
 
 ```bash
 pi --extension ./extensions/goal    # load just this extension
@@ -9,86 +29,29 @@ pi -e .                             # load the whole @gavin-hu/my-pi-agent packa
 pi install ./                       # install the package
 ```
 
-## Tool rendering
+```text
+/goal                               # show the goal, or the usage when none is set
+/goal Refactor the parser to support streaming input
+```
 
-How the `goal` call and its result look in the transcript — the call line as a headline and the body indented under it:
+The model records the same objective with `goal`; the model-facing tool never
+runs the understanding loop.
 
-<img src="../../assets/tools/goal.png" alt="The goal tool's result: the call line and an indented body with the Goal header and the objective body" width="100%">
+## Tool
 
-## What it does
-
-- Registers one model-callable tool, `goal`, that records the session
-  objective. Send the complete objective every call; an empty objective clears
-  it.
-- Tracks the goal's **phase**, not a flag: `planning` while a plan is being
-  designed, `active` once the objective is final, `achieved` when it is done.
-  A model-issued call may only send `active` or `achieved`, so one call can never
-  claim a plan that does not exist.
-- **Asks once whether to plan first** when a new goal is recorded: accepting
-  enters plan mode and stores the objective as `planning`, declining stores it
-  `active`. The `plan` extension owns the mode; the question and its consent
-  sentence come from `lib/plan-entry.ts`, the same ones `enter_plan_mode` shows,
-  so the user answers once. The question is skipped for an update to a goal that
-  is already pursued, without a dialog UI, or when `plan` is not loaded.
-- **Settles a draft whose plan never arrived.** If plan mode is left without an
-  approved plan — the toggle, the shortcut, a resumed branch — the `planning`
-  goal becomes `active` with its own wording on the next observation, so the
-  phase can never get stuck. Approval is different: `plan` sets the goal from the
-  plan's own `## Goal` section (see the [`plan`](../plan/) docs).
-- Achieves a goal over an open list knowingly: completing it while the branch's
-  todo list still has open items names the count in the result (`1 todo item is
-  still open…`), so the model closes the *how* instead of declaring the *what*
-  done over an unfinished list; `/goal done` appends the same sentence to its
-  notice. The count is read from the branch through `lib/todo-state.ts`; the
-  structured result is unchanged.
-- Shows a persistent one-line rail above the editor whenever a goal exists,
-  label-first to match the [`todo`](../todo/) widget, pinned at the top of the
-  `Goal / Todos` stack when both are loaded:
-
-  ```
-  Goal · active · Refactor the parser to support streaming input and ship it …
-  ```
-
-  Once achieved the goal is hidden from the widget by default, matching a
-  completed todo list; the transcript keeps the record. Set `achieved: "show"`
-  in the `goal` section of `bytefly.json` to keep drawing the dimmed line
-  instead.
-
-- Restates a **pursued** goal to the model before each turn (an invisible
-  `[SESSION GOAL]` message) — `planning` and `active` alike, so a plan is designed
-  against the objective — and stops once it is achieved.
-- Stores tool-set goals in tool-result `details` and command-set goals as a
-  `goal` session entry, so either way the goal follows the active session branch
-  and survives `/resume` and `/tree` — a `planning` draft included, since it is
-  written the same way. Abandoned branches never leak into the current goal.
-- Understands the goal before recording it: `/goal <prompt>` asks the session
-  model to restate the goal as it understands it and, when it cannot yet, to ask
-  up to three questions — which the command asks directly through host dialogs
-  (`select` / `input`). The answers are carried into the editor under the
-  restatement, below a `--- notes (not saved) ---` line, so accepting the
-  restatement as-is records the goal alone; folding an answer into the sentence
-  above the line keeps it. `/goal set
-  <prompt>` reuses the loop but records without starting a turn, `/goal edit`
-  changes the current goal in place, and `/goal raw <prompt>` records the typed
-  words verbatim. The loop is best-effort and needs a dialog UI plus a model; the
-  `goal` tool stays the silent setter.
+<img src="../../assets/tools/goal.png" alt="The goal tool's result: the call line and an indented body with the Goal header and the objective body" width="100%">
 
-## Tool
+`goal` — `exposure: "direct"` (the default), `executionMode: "sequential"`,
+read-write, closed-world, idempotent. It is a whole-goal replacement: the model
+sends the complete objective and the previous goal is discarded.
 
-`goal` is a whole-goal replacement tool. It declares an `outputSchema` and
-returns matching `structuredContent` (`{ goal, action, error? }`, with
-`goal: null` after a clear), so codemode/scripts can read the goal as data.
+| Parameter | Type | Meaning |
+|---|---|---|
+| `objective` | string, required | The complete objective, one line. Pass `""` to clear. |
+| `status` | `active` \| `achieved` | `achieved` completes the goal; `active` records a final objective; omit it to let the workflow ask whether to plan first. `planning` is the workflow's to set; a call cannot. |
 
-| Field | Value |
-|---|---|
-| `name` | `goal` |
-| `objective` | The complete objective, one line. Pass `""` to clear. |
-| `status` | `achieved` completes the goal; `active` records a final objective; omit it to let the workflow ask whether to plan first. `planning` is the workflow's to set; a call cannot. |
-| `exposure` | `direct` (default). |
-| `executionMode` | `sequential` — calls share the in-memory goal. |
-| `annotations` | `idempotentHint: true` (a snapshot write), not read-only. |
-| `outputSchema` | `GoalResult` — `{ goal, action, error? }`, also returned as `structuredContent`. |
-| `promptGuidelines` | Carry the when-to-use rule and the mark-achieved-with-a-blank-objective rule; the replacement/clear semantics live in the description. |
+Result (`details` / `structuredContent`): `{ goal, action, error? }`, with
+`goal: null` after a clear.
 
 Validation (a violation returns an error result and leaves the goal unchanged):
 a known `status`, an objective of at most 2000 characters, and a non-blank
@@ -109,19 +72,22 @@ whether the todos were written by the model, by `/todos`, or by an approved
 plan. It is text only: `details`, `structuredContent`, and the transcript header
 are unaffected.
 
-`goal` is allowlisted in `plan-mode` (alongside `todo`), so the model can record
-or update the objective during read-only exploration without leaving plan mode.
-Plan mode also reads the goal: it restates a pursued one in its injected context,
-it promotes a `planning` goal when a plan is approved, and it offers to record the
-plan's `## Goal` when the session has none (`lib/goal-state.ts` is the reader). An
-`active` or `achieved` goal — a final objective — is never rewritten by an
-approval.
+The transcript result is the status header alone, directly under the call line
+that names the objective:
+
+```
+goal → set: Refactor the parser to support streaming input
+  Goal · active
+```
+
+The renderer reuses the slot's component (`context.lastComponent`) rather than
+rebuilding it each render.
 
-### `/goal` command
+## Commands
 
 The command has no tool result, so it persists each change as a `goal` custom
 entry; `reconstructGoal` replays both entry kinds in branch order through
-`lib/goal-state.ts`, so its readers agree.
+`lib/goal-state.ts`, so its readers agree. `/goal` completes each verb.
 
 | Command | What it does |
 |---|---|
@@ -134,50 +100,28 @@ entry; `reconstructGoal` replays both entry kinds in branch order through
 | `/goal clear` | Clear the goal. |
 | `/goal help` (or `-h` / `--help`) | Show the command usage. |
 
-`/goal <prompt>` runs the loop only when a dialog UI and a session model are
-present (TUI or RPC). In print and JSON mode the typed text is set and run
-unchanged. A plain-text clarifier reply is treated as a restatement, so a model
-that ignores the JSON instruction still works; a failed, timed-out, or unusable
-comprehension notices the user and keeps the typed text; and a dismissed
-question or editor cancels the command, changing nothing. The questions are asked
-one at a time with `ctx.ui.select` (for a question with options) and
-`ctx.ui.input` (for a free-form one); the command never calls
-`ask_user_question`. A bare `/goal set` and `/goal edit` need a dialog UI —
-without one they show the usage instead. `/goal raw` never needs one for the
-words, but the plan question does need a dialog: both run variants ask it only
-where a dialog UI exists, and record `active` otherwise. The record-only paths
-never ask; a goal recorded while plan mode is already on is still a draft
-(`planning`), because that is what it is.
+The questions and the confirm step are host dialogs, forwarded by RPC, so the
+loop needs one; in print and JSON mode the typed text is set and run unchanged.
+A dismissed question or editor cancels the command, changing nothing. The
+[`plan`](./plan.md) extension owns plan mode, so the plan question is skipped
+when it is not loaded, and a bare `/goal set` shows the usage instead of an
+editor when there is no dialog UI.
 
 ## Behaviour by mode
 
 The tool works in every mode. The persistent widget requires interactive
 (`tui`) mode; the reminder and the `/goal` command work everywhere. The
-`/goal <prompt>` runs the loop: its model call uses a cancellable `tui` spinner
-in interactive mode and runs directly in RPC; the questions and the confirm step
-are host dialogs, forwarded by RPC. In print and JSON mode the loop is skipped
-and the typed text is sent. The plan question is a host dialog too, so it is
-asked only in TUI and RPC, and skipped when the `plan` extension is not loaded.
-The widget is always a single line; the transcript result is the status header
-alone, directly under the call line that names the objective:
-
-```
-goal → set: Refactor the parser to support streaming input
-  Goal · active
-```
-
-The renderer reuses the slot's component (`context.lastComponent`) rather than
-rebuilding it each render. A `planning` goal shows the same rail with a warning
-status word and is restated; achieved goals are hidden from the widget by
-default (restore the dimmed line with `achieved: "show"`), and they are no
-longer restated to the model. While a dock screen is open (`/todos`, `/jobs`,
-`/rewind`, or the `question` questionnaire), the rail is hidden and
+`/goal <prompt>` comprehension call uses a cancellable `tui` spinner in
+interactive mode and runs directly in RPC. When a goal exists, the widget is
+always a single line above the editor; while a dock screen is open (`/todos`,
+`/jobs`, `/rewind`, or the `question` questionnaire), the rail is hidden and
 returns on close.
 
 ## Configuration
 
 The widget presentation is configurable from the `goal` section of the shared
-`bytefly.json` (global document, then project document, project wins):
+`bytefly.json`; resolution rules are in
+[`../configuration.md`](../configuration.md#goal--the-goal-widget).
 
 | Key | Default | Meaning |
 |---|---|---|
@@ -186,6 +130,53 @@ The widget presentation is configurable from the `goal` section of the shared
 Malformed documents and invalid values are ignored, and goal behavior never
 depends on config.
 
+## Plan entry
+
+A new goal's phase is decided once, with one dialog. Accepting enters plan mode
+and stores the objective as `planning`, so a plan can be designed against it;
+declining stores it `active`, the final objective. The question is skipped for
+an update to a goal that is already pursued, without a dialog UI, and when
+`plan` is not loaded. The question and its consent sentence come from
+`lib/plan-entry.ts`, the same ones `enter_plan_mode` shows, so the user answers
+once.
+
+A draft whose plan never arrived is settled rather than stranded. If plan mode is
+left without an approved plan — the toggle, the shortcut, a resumed branch — the
+`planning` goal becomes `active` with its own wording on the next observation, so
+the phase can never get stuck. Approval is different: `plan` sets the goal from
+the plan's own `## Goal` section (see the [`plan`](./plan.md) docs), and only a
+`planning` goal is eligible, so a final objective is the user's.
+
+`goal` is allowlisted in `plan-mode` (alongside `todo`), so the model can record
+or update the objective during read-only exploration without leaving plan mode.
+Plan mode also reads the goal: it restates a pursued one in its injected context,
+it promotes a `planning` goal when a plan is approved, and it offers to record the
+plan's `## Goal` when the session has none (`lib/goal-state.ts` is the reader). An
+`active` or `achieved` goal — a final objective — is never rewritten by an
+approval.
+
+## The understanding loop
+
+`/goal <prompt>` asks the session model to restate the goal as it understands it
+and, when it cannot yet, to ask up to three questions, which the command asks
+directly through host dialogs (`select` / `input`). The answers are carried into
+the editor under the restatement, below a `--- notes (not saved) ---` line, so
+accepting the restatement as-is records the goal alone; folding an answer into
+the sentence above the line keeps it. `/goal set <prompt>` reuses the loop but
+records without starting a turn, and `/goal raw <prompt>` records the typed words
+verbatim.
+
+The loop is best-effort and needs a dialog UI plus a model. A plain-text clarifier
+reply is treated as a restatement, so a model that ignores the JSON instruction
+still works; a failed, timed-out, or unusable comprehension notices the user and
+keeps the typed text. The questions are asked one at a time with `ctx.ui.select`
+(for a question with options) and `ctx.ui.input` (for a free-form one); the
+command never calls `ask_user_question`. `/goal raw` never needs a dialog for the
+words, but the plan question does: both run variants ask it only where a dialog
+UI exists, and record `active` otherwise. The record-only paths never ask, and a
+goal recorded while plan mode is already on is still a draft (`planning`), because
+that is what it is. The `goal` tool stays the silent setter.
+
 ## Non-goals
 
 - No multiple or nested goals — one objective per session.
@@ -246,19 +237,12 @@ depends on config.
   record and stops the reminder, which a single empty-clear cannot express.
 - **The command runs the understanding loop.** `/goal <prompt>` is the
   user-driven path: one comprehension call (`clarify-prompt.ts` + `clarify.ts`)
-  returns `{ understood, goal, questions }`. An understood goal opens a prefilled
-  `ctx.ui.editor`, then `pi.sendUserMessage` sets and runs it. A not-understood
-  goal has its questions asked through host dialogs, and its answers ride into
-  the editor as `Also:` notes below a sentinel line that is cut away on save:
-  no second model call rewrites the goal, so the user is the one who folds an
-  answer into the sentence, above the line, when they want it kept.
-  `/goal set`
-  reuses the loop but skips the send; a bare `/goal set` or `/goal edit` opens
-  the editor prefilled with the current goal; and `/goal raw` skips the loop
-  entirely. The loop is best-effort (a failure keeps the typed text) and a
-  dismissed dialog cancels the command, so nothing is half-applied. No
-  conversation history is sent: the model must not invent scope the user did not
-  state. The `goal` tool remains the model's setter, with no comprehension loop.
+  returns `{ understood, goal, questions }`. No second model call rewrites the
+  goal, so the user is the one who folds an answer into the sentence, above the
+  sentinel line, when they want it kept; and no conversation history is sent, so
+  the model cannot invent scope the user did not state. The loop is best-effort
+  and a dismissed dialog cancels the command, so nothing is half-applied. The
+  `goal` tool remains the model's setter, with no comprehension loop.
 - **State in `details` and a custom entry.** A `goal` tool call stores the goal
   in its result's `details`; the `/goal` command appends a `goal` custom entry
   (`pi.appendEntry`). `reconstructGoal` reads the branch through