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

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

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

@@ -5,47 +5,51 @@ the background and manage them without blocking the turn. A job starts
 immediately and keeps running across tool calls; poll it, tail its output, wait
 for it, or kill it.
 
-<img src="../../assets/job.png" alt="The /jobs screen: a summary line, the job rows with status glyphs and elapsed times, and the focused job's command, cwd, and last output line" width="100%">
-
+## 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 |
+|---|---|---|---|
+| Background execution | `job` (`start`) | A long build, test suite, server, or watcher keeps running while the turn moves on. | Shipped |
+| Job listing | `job` (`list`), `/jobs` | This session's jobs with status and elapsed time, and a live peer session's tagged `peer`. | Shipped |
+| Polling and waiting | `job` (`status`, `logs`, `wait`) | One call returns a job's status, a bounded output tail, or blocks until it finishes. | Shipped |
+| Stopping jobs | `job` (`kill` with `signal`) | A running job receives `SIGTERM`, `SIGKILL`, or `SIGINT`, and a finished one can be cleared. | Shipped |
+| Selective clear | `job` (`clear` with `id`, `all`) | Clear one finished record by id, or remove running jobs with `all` after a confirmation in the screen. | Shipped |
+| Start deadline | `timeoutMs` on `start` | A job is killed after the requested wall-clock limit instead of running until the session ends. | Shipped |
+| Kill escalation | `killGraceMs` | A kill sends `SIGTERM` first, then `SIGKILL` after the grace period, on a user kill and on shutdown. | Shipped |
+| Stdin driving | `job` (`send` with `input`, `newline`, `eof`) | A line or a bare keystroke reaches a running job started with `stdin: true`, and `eof` closes its input. | Shipped |
+| Rotating logs | `job` (`logs`), `job.maxLogBytes` | stdout and stderr stream to an append-only log that rotates at 8 MiB, so a chatty job cannot fill the disk. | Shipped |
+| Status chips | `job.showStatus` | `▸ N` running and `✗ N` unreported-failure counts in the footer. | Shipped |
+| Completion reporting | `job` (`wake`), `job.wakeOnFinish` | A finished job is reported at the next turn, or triggers one as soon as the agent is idle. | Shipped |
+| Job screen | `/jobs` | Select a job, open its log, kill it, or clear finished ones, with a confirmation on the destructive verbs. | Shipped |
+| Detached lifetime | `job` (`start`, `detached`) | A POSIX job outlives the session and is reattached next time; Windows refuses the detach instead of faking one. | Shipped |
+| Finished-job pruning | `maxJobs` | The registry drops the oldest finished records once the configured count is exceeded. | Shipped |
+| Structured result | tool-result `details` | Every call returns a `JobDetails` record of the job and the action's outcome. | Shipped |
+
+## Quickstart
+
+```bash
+pi --extension ./extensions/job   # load just this extension
+pi -e .                           # load the whole @gavin-hu/my-pi-agent package
+pi install ./                     # install the package
 ```
-pi --extension ./extensions/job    # load just this extension
-pi -e .                            # load the whole @gavin-hu/my-pi-agent package
-pi install ./                      # install the package
+
+```text
+/jobs                             # this session's jobs, and their logs
 ```
 
-## Tool rendering
+The model starts a job with `job start` and collects it with `job status`,
+`job logs`, or `job wait`.
 
-How the `job` call and its result look in the transcript — the call line as a headline and the body indented under it:
+## Tool
 
 <img src="../../assets/tools/job.png" alt="The job tool's result: the call line and an indented body with a finished and a failed job row, each with its status glyph and elapsed time" width="100%">
 
-## What it does
-
-- Registers one model-callable tool, `job`, with actions `start`, `list`,
-  `status`, `logs`, `send`, `kill`, `wait`, and `clear`.
-- Shows this session's jobs, and — tagged `peer` — a live peer session's, so two
-  Pi sessions on one repo can see each other's builds; the peer's rows are
-  read-only on the screen.
-- Runs each command in its own process group, streaming stdout and stderr to an
-  append-only log file under `~/.pi/agent/jobs/<project>/`. A segment rotates
-  to `<id>.log.1` at `maxLogBytes` (8 MiB by default), so a chatty job cannot
-  fill the disk, and `logs` reads across the boundary.
-- Feeds a running job input when it was started with `stdin: true`: `send`
-  writes a line (or a bare keystroke) to its stdin, and `eof: true` closes it, so
-  a REPL, a debugger prompt, or a `read` can be driven without a TTY.
-- Shows a `▸ N` running status chip and a separate `✗ N` unreported-failure
-  chip for this session's jobs, plus a `/jobs` screen for selecting, tailing,
-  killing, and clearing.
-- Reports finished jobs to the model at the start of the next turn, or — for
-  jobs started with `wake: true` — by triggering one turn as soon as the agent is
-  idle, including right after a running turn settles.
-- Kills session-owned jobs on shutdown so no process is left behind; on POSIX,
-  start a job with `detached: true` to keep it running and reattach next session.
-  A detached job points its own output straight at its log file, so it keeps
-  logging after this process ends. Windows has neither a process group to leave
-  nor a shell `EXIT` trap, so it refuses the detach instead of faking one.
-
-## Tool
+`job` — `executionMode: "sequential"`, `readOnlyHint: false`,
+`destructiveHint: true`, `idempotentHint: false`, `openWorldHint: true`. One
+tool with eight actions: `start` returns immediately with an id, and the rest
+act on it.
 
 | Field | Value |
 |---|---|
@@ -147,20 +151,27 @@ job status j1
 ✓ j1 tests · exit 0 · 12.0s
 ```
 
-### Command: `/jobs`
+## Commands
 
 `/jobs` opens an interactive list in the TUI, and prints a text summary
-elsewhere. The list shows the jobs this session started, a dead session's
-records adopted into it, and a live peer session's jobs tagged `peer`. On
-the screen: `↑`/`↓` or `j`/`k` select, `PgUp`/`PgDn` page, `Home`/`End` jump,
-`Enter`/`l` opens the log pane, `d` (or `K`) kills the selected running job,
-`x` clears finished jobs, `Esc`/`q` closes. `d` and `x` ask for a `y`/`N`
-confirmation before acting, so a stray key cannot kill a build; when `x` would
-drop an unreported result, the prompt says how many. A `d` on a finished job (or
-an `x` with nothing finished) says so instead of doing nothing. Another
-session's row opens its log but is otherwise left alone: `d` answers
-`j9 is another session's job; not killed.`, and `x` counts and clears only this
-session's finished jobs. In the log pane,
+elsewhere.
+
+<img src="../../assets/screens/job.png" alt="The /jobs screen: a summary line, the job rows with status glyphs and elapsed times, and the focused job's command, cwd, and last output line" width="100%">
+
+| Command | What it does |
+|---|---|
+| `/jobs` | Show and manage background jobs: an interactive list in the TUI, a text summary elsewhere. |
+
+The list shows the jobs this session started, a dead session's records adopted
+into it, and a live peer session's jobs tagged `peer`. On the screen: `↑`/`↓` or
+`j`/`k` select, `PgUp`/`PgDn` page, `Home`/`End` jump, `Enter`/`l` opens the log
+pane, `d` (or `K`) kills the selected running job, `x` clears finished jobs,
+`Esc`/`q` closes. `d` and `x` ask for a `y`/`N` confirmation before acting, so a
+stray key cannot kill a build; when `x` would drop an unreported result, the
+prompt says how many. A `d` on a finished job (or an `x` with nothing finished)
+says so instead of doing nothing. Another session's row opens its log but is
+otherwise left alone: `d` answers `j9 is another session's job; not killed.`,
+and `x` counts and clears only this session's finished jobs. In the log pane,
 `↑`/`↓`, `PgUp`/`PgDn`, `Home`/`End`, and `g`/`G` scroll; the view follows the
 tail until you scroll up, and `Esc`/`Backspace`/`q` returns to the list. The
 pane's subheader names the job's log file, notes when only a bounded tail is
@@ -172,8 +183,7 @@ chips count only this session's. Running jobs come first, then recent finished
 ones, and a focused detail pane follows (command, cwd, outcome, the owner when
 it is another session, and the last output line). Selection is tracked by job
 id, so the live re-sort cannot move the cursor or switch the open log out from
-under the user.
-Any dock screen (`/todos`, `/jobs`, `/rewind`, or the
+under the user. Any dock screen (`/todos`, `/jobs`, `/rewind`, or the
 `question` questionnaire) hides the above-editor goal/todo rails for its
 lifetime and restores them on close.
 
@@ -185,8 +195,9 @@ notifications instead.
 
 ## Configuration
 
-The `job` section of the shared `bytefly.json` (global document, then project
-document, project wins):
+The keys live in the `job` section of the shared `bytefly.json`; resolution rules
+are in
+[`../configuration.md`](../configuration.md#job--background-jobs).
 
 | Key | Default | Meaning |
 |---|---|---|