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

package/docs/extensions/check.md

@@ -8,22 +8,20 @@ framework, or CI system.
 
 ## 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 |
-|---|---|---|---|
-| Plan-mode refusal | `/check`, the read-only policy | Plan mode refuses a check because tests still write caches, snapshots, or generated files; approve the plan first. | Shipped |
-| Single active run | `run_check`, `/check` | A second run is refused with the corrective action while one process is active, instead of starting a parallel check. | Shipped |
-| Supervised run | `/check`, `run_check` | One process per command, with a wall-clock timeout, a bounded log, and `Esc` to cancel the process tree. | Shipped |
-| Command detection | a project manifest, `check.command` | The project's test, lint, and typecheck commands are found without configuration, with a shell command override. | Shipped |
-| Target selection | `/check` with a target, `run_check.target` | Run `test`, `lint`, `typecheck`, or `all`; `all` is the default. | Shipped |
-| Structured failures | `run_check` | The model gets `path`, `line`, `column`, `test`, `message`, and `command` instead of a wall of log text. | Shipped |
-| Failure list | `/check` | A navigable list with a detail view for the focused failure, drawn from a source excerpt or the bounded tail. | Shipped |
-| Rerun from the list | `r` in the failure list | Rerun the same check after reading a failure; `Enter` opens its detail and `Esc` closes. | Shipped |
-| Live run screen | `/check` | A scrolling tail that repaints while the command runs, so a silent compiler still shows progress. | Shipped |
-| Capped transcript | `run_check` | One status summary and at most five failure rows, expanded with `ctrl+o` to the model's 20-failure cap. | Shipped |
-| Headless report | `/check`, `run_check` | RPC, JSON, and print sessions post the summary plus the failure list, with no screen. | Shipped |
-| Honest fallback | `/check`, `run_check` | An unparsed failure names the exit status and the last output lines, never an invented location. | Shipped |
+| Capability | How | What you get |
+|---|---|---|
+| Plan-mode refusal | `/check`, the read-only policy | Plan mode refuses a check because tests still write caches, snapshots, or generated files; approve the plan first. |
+| Single active run | `run_check`, `/check` | A second run is refused with the corrective action while one process is active, instead of starting a parallel check. |
+| Supervised run | `/check`, `run_check` | One process per command, with a wall-clock timeout, a bounded log, and `Esc` to cancel the process tree. |
+| Command detection | a project manifest, `check.command` | The project's test, lint, and typecheck commands are found without configuration, with a shell command override. |
+| Target selection | `/check` with a target, `run_check.target` | Run `test`, `lint`, `typecheck`, or `all`; `all` is the default. |
+| Structured failures | `run_check` | The model gets `path`, `line`, `column`, `test`, `message`, and `command` instead of a wall of log text. |
+| Failure list | `/check` | A navigable list with a detail view for the focused failure, drawn from a source excerpt or the bounded tail. |
+| Rerun from the list | `r` in the failure list | Rerun the same check after reading a failure; `Enter` opens its detail and `Esc` closes. |
+| Live run screen | `/check` | A scrolling tail that repaints while the command runs, so a silent compiler still shows progress. |
+| Capped transcript | `run_check` | One status summary and at most five failure rows, expanded with `ctrl+o` to the model's 20-failure cap. |
+| Headless report | `/check`, `run_check` | RPC, JSON, and print sessions post the summary plus the failure list, with no screen. |
+| Honest fallback | `/check`, `run_check` | An unparsed failure names the exit status and the last output lines, never an invented location. |
 
 ## Quickstart
 
@@ -252,7 +250,7 @@ never turned into an invented location.
 | `source.ts` | Guarded source excerpt around a failure's `path:line`. |
 | `runtime.ts` | Planning, sequencing, aggregation, live lines, cancel/shutdown. |
 | `format.ts` | Summary, failure rows, source-excerpt/detail text, model report. |
-| `tui.ts` | `CheckRunComponent` (a live tail) and `CheckResultComponent` (a `DockListScreen` over the failures). |
+| `view/check-screens.ts` | `CheckRunComponent` (a live tail) and `CheckResultComponent` (a `DockListScreen` over the failures), loaded on first use. |
 | `tools.ts` | `run_check` schema, registration, the running partial result, and the call/result renderers. |
 | `render.ts` | The transcript result block: status summary, capped failure rows, tail fallback. |
 | `commands.ts` | `/check`, target parsing, completions, TUI/headless flow. |

package/docs/extensions/context.md

@@ -7,20 +7,18 @@ untouched.
 
 ## 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 |
-|---|---|---|---|
-| Window headline | `/context` | Pi's own estimate: tokens, window, percentage, free space, and the auto-compaction threshold with the headroom left before it. | Shipped |
-| Composition breakdown | `/context` | Where the window went — system prompt, active tool definitions, the conversation by role, injected pack context, summaries, and shell output. | Shipped |
-| Guarded compaction | `/context compact [instructions]`, `c` on the screen | Compact from the report without interrupting a streaming turn or a running compaction. | Shipped |
-| Compact result | `/context compact` result | The before and after token counts are reported, so the effect of the compaction is visible. | Shipped |
-| Honest drift | `/context` | The difference between Pi's total and the composition estimate, named instead of hidden by forcing the parts to add up. | Shipped |
-| Compaction history | `/context` | How many compactions the branch has, what the newest one cut from and to, and what its summary costs. | Shipped |
-| Largest messages | `/context` | The five largest single messages, so a report that is mostly one tool result says so. | Shipped |
-| Gauge rendering | the `/context` screen | The window and composition bars show ten or eight cells, colored by role, instead of leaving the reader to infer the shape. | Shipped |
-| Pending total | `/context` after a compaction | The report shows a pending total instead of a fabricated estimate while Pi recalculates the window. | Shipped |
-| Mode coverage | `/context` | A scrollable screen in the TUI, the same facts as plain text in `rpc`, `json`, and `print`. | Shipped |
+| Capability | How | What you get |
+|---|---|---|
+| Window headline | `/context` | Pi's own estimate: tokens, window, percentage, free space, and the auto-compaction threshold with the headroom left before it. |
+| Composition breakdown | `/context` | Where the window went — system prompt, active tool definitions, the conversation by role, injected pack context, summaries, and shell output. |
+| Guarded compaction | `/context compact [instructions]`, `c` on the screen | Compact from the report without interrupting a streaming turn or a running compaction. |
+| Compact result | `/context compact` result | The before and after token counts are reported, so the effect of the compaction is visible. |
+| Honest drift | `/context` | The difference between Pi's total and the composition estimate, named instead of hidden by forcing the parts to add up. |
+| Compaction history | `/context` | How many compactions the branch has, what the newest one cut from and to, and what its summary costs. |
+| Largest messages | `/context` | The five largest single messages, so a report that is mostly one tool result says so. |
+| Gauge rendering | the `/context` screen | The window and composition bars show ten or eight cells, colored by the row's category — the same hue in the composition table and in the largest-message list — instead of leaving the reader to infer the shape. |
+| Pending total | `/context` after a compaction | The report shows a pending total instead of a fabricated estimate while Pi recalculates the window. |
+| Mode coverage | `/context` | A scrollable screen in the TUI, the same facts as plain text in `rpc`, `json`, and `print`. |
 
 ## Quickstart
 
@@ -83,6 +81,28 @@ first reply, when Pi's fallback leaves the prompt and the tools out. Each bar
 rounds to the nearest cell, so a bar sits within half a cell of the percentage
 printed beside it; the percentage itself is exact.
 
+## The table is a chart
+
+A row's bar and its percentage wear the hue of its category, and the
+largest-message list uses the same table, so a tool result is one colour wherever
+it appears. A hue identifies; it never judges — the gauge is the only verdict on
+the screen, and the footer's feedback line is the transient one. Labels, token
+counts, and notes stay in the body, secondary, and faint roles, so the text still
+reads on its own and the colour repeats an order the row already has.
+
+| Category | Hue | Bucket ids |
+|---|---|---|
+| System prompt | blue (`hue1`) | `system` |
+| Tool definitions | purple (`hue2`) | `tools` |
+| User messages | pink (`hue3`) | `user` |
+| Assistant | green (`hue4`) | `assistant` |
+| Tool results | amber (`hue5`) | `toolResults`, the `tool result` rows |
+| Everything else | neutral (`meta`, children `faint`) | injected context and its children, summaries, shell output |
+
+A category with no entry — an injected type, a role a future Pi adds — reads
+neutral rather than borrowing a hue, so the coloured rows always mean the five
+categories above.
+
 | Row | Source |
 |---|---|
 | Headline (`tokens`, `percent`) | `ctx.getContextUsage()`: the last valid provider usage plus Pi's estimate of the messages after it. `tokens` is `null` between a compaction and the next successful reply, because the last usage describes the pre-compaction context. |
@@ -175,7 +195,7 @@ printed beside it; the percentage itself is exact.
 | `collect.ts` | The host boundary: one read of usage, prompt, tools, settings, projection, and branch. |
 | `report.ts` | The pure builder: composition, reserve resolution, compaction history, largest messages. |
 | `format.ts` | The plain-text report for non-TUI modes. |
-| `tui.ts` | `ContextComponent`: gauge, rows, scroll, confirmation, feedback. |
+| `view/context-report.ts` | `ContextComponent`: gauge, rows, scroll, confirmation, feedback, loaded on first use. |
 | `types.ts` | `ContextInputs`, `ContextReport`, buckets, and the host types named through `ReturnType<…>`. |
 
 ## Testing

package/docs/extensions/file-browse.md

@@ -12,30 +12,28 @@ the shared loopback layer plus one small vanilla script.
 
 ## 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 |
-|---|---|---|---|
-| One-command browsing | `/browse` | The server starts at the effective working directory, prints its URL, and opens the browser. | Shipped |
-| Read-only serving | `/browse` | Nothing is edited or written, and the server binds `127.0.0.1` only. | Shipped |
-| Two-pane page | `/`, `/browse[/<rel>]` | A collapsible tree beside the current folder's listing, with the tree, filter, and quick-open trigger pinned in their own pane. | Shipped |
-| File previews | `/view/<rel>` | Text, rendered Markdown, image thumbnails, and download cards for binary or over-size files, each with a per-language icon. | Shipped |
-| Quick open | `/`, `Ctrl/Cmd+K`, `/api/files` | A fuzzy path finder over the tree opens a file without walking the tree. | Shipped |
-| Git diff view | `/diff`, `/diff/<rel>` | A change overview and one file's unified diff, scoped to `head`, `staged`, or `worktree`. | Shipped |
-| Live status | `/events`, the `◉ live` chip | An open page keeps its branch, change markers, and footer up to date without a reload. | Shipped |
-| Reload hint | `/api/dir-rev`, `⟳ reload` | A page whose folder gained or lost a file offers a reload control instead of changing its rows. | Shipped |
-| Terminal session chip | `browse` status key | The terminal footer shows `◉ <port>` while the page is served, so the session names its live server. | Shipped |
-| Listing controls | the `Name`, `Size`, and `Modified` headers | The current folder sorts by name, size, or modified time, directories first, and the choice is remembered per browser. | Shipped |
-| Keyboard navigation | the tree's keymap, `?` | The tree is one tab stop with arrow, fold, and open keys; a shortcut sheet lists the page's own keys. | Shipped |
-| Diff hunk navigation | `n`/`p` in `/diff` | Jump between changed hunks without scrolling the whole file. | Shipped |
-| Fold and expand all | the `fold all` control | Collapse or expand the whole tree in one click. | Shipped |
-| Reading progress | `browse-progress` hairline | A long directory or diff read shows how much has loaded, and printing hides the indicator. | Shipped |
-| Printing | `@media print` styles | The page prints without the toolbar, progress hairline, or other screen-only chrome. | Shipped |
-| Syntax highlighting | `/view/<rel>`, `/view/<rel>?raw=1` | Supported code files show keywords, strings, numbers, and comments in colour in both themes; other text stays plain. | Shipped |
-| Markdown preview | `/view/<rel>`, `/view/<rel>?raw=1` | A README renders as headings, lists, tables, code, and links, with a one-click raw view. | Shipped |
-| Copy and wrap | the page toolbar, `y`, `u` | Copy a file's path or contents or a `path:12-30` line reference, and toggle line wrapping for text and raw views. | Shipped |
-| Theme toggle | the header button, `/theme.js` | Dark and light palettes, following the system until an explicit choice is remembered per browser. | Shipped |
-| Idle stop and port reuse | `/browse stop`, the session port | The server stops when idle and reuses its port for the next session instead of leaking listeners. | Shipped |
+| Capability | How | What you get |
+|---|---|---|
+| One-command browsing | `/browse` | The server starts at the effective working directory, prints its URL, and opens the browser; every later `/browse` opens the page it already serves. |
+| Read-only serving | `/browse` | Nothing is edited or written, and the server binds `127.0.0.1` only. |
+| Two-pane page | `/files/`, `/files/browse[/<rel>]` | A collapsible tree beside the current folder's listing, with the tree, filter, and quick-open trigger pinned in their own pane. |
+| File previews | `/view/<rel>` | Text, rendered Markdown, image thumbnails, and download cards for binary or over-size files, each with a per-language icon. |
+| Quick open | `/files/`, `Ctrl/Cmd+K`, `/files/api/files` | A fuzzy path finder over the tree opens a file without walking the tree. |
+| Git diff view | `/diff`, `/diff/<rel>` | A change overview and one file's unified diff, scoped to `head`, `staged`, or `worktree`. |
+| Live status | `/events`, the `◉ live` chip | An open page keeps its branch, change markers, and footer up to date without a reload. |
+| Reload hint | `/api/dir-rev`, `⟳ reload` | A page whose folder gained or lost a file offers a reload control instead of changing its rows. |
+| The session's page port | `serve`'s `◉ <port>` chip | The footer names the one port every page of the session answers on, this one included. |
+| Listing controls | the `Name`, `Size`, and `Modified` headers | The current folder sorts by name, size, or modified time, directories first, and the choice is remembered per browser. |
+| Keyboard navigation | the tree's keymap, `?` | The tree is one tab stop with arrow, fold, and open keys; a shortcut sheet lists the page's own keys. |
+| Diff hunk navigation | `n`/`p` in `/diff` | Jump between changed hunks without scrolling the whole file. |
+| Fold and expand all | the `fold all` control | Collapse or expand the whole tree in one click. |
+| Reading progress | `browse-progress` hairline | A long directory or diff read shows how much has loaded, and printing hides the indicator. |
+| Printing | `@media print` styles | The page prints without the toolbar, progress hairline, or other screen-only chrome. |
+| Syntax highlighting | `/view/<rel>`, `/view/<rel>?raw=1` | Supported code files show keywords, strings, numbers, and comments in colour in both themes; other text stays plain. |
+| Markdown preview | `/view/<rel>`, `/view/<rel>?raw=1` | A README renders as headings, lists, tables, code, and links, with a one-click raw view. |
+| Copy and wrap | the page toolbar, `y`, `u` | Copy a file's path or contents or a `path:12-30` line reference, and toggle line wrapping for text and raw views. |
+| Theme toggle | the header button, `/theme.js` | Dark and light palettes, following the system until an explicit choice is remembered per browser. |
+| Idle stop and prefix reuse | `/browse stop`, the idle grace | The page gives its prefix back when nobody is reading it, so a closed tab never holds the session's server. |
 
 ## Quickstart
 
@@ -66,33 +64,33 @@ selects the root.
 
 - The root is the effective cwd, so an active `worktree` session serves the
   worktree. `<path>` must resolve inside it.
-- The port is fixed for the session: the first `/browse` picks a random port
-  in `4780`–`5779` and every later `/browse` in that session reuses it, so the
-  URL stays stable across roots and restarts. Set `"port"` to pin an explicit
-  port; a busy port is reported, not silently changed.
-- Starting while already running with the same root reprints the URL without
-  restarting; a different root (or a changed pinned port) restarts the server.
+- The port is the project's: `serve` hashes the repository key into `4780`–`5779`
+  (and `serve.port` pins it), so the origin stays stable across roots and restarts. A
+  busy pinned port is reported, not silently changed.
+- Starting while already running with the same root opens that page again and
+  reprints its URL, without restarting the server; a different root restarts the page.
+  With `autoOpen` off, the second `/browse` only reprints the URL.
 - The server is closed when its last page has been gone for ten seconds, so
   closing the browser window ends the session's browse server and `/browse`
-  starts it again on the same port. A reload or a new tab inside that grace keeps
+  starts it again on the session's port. A reload or a new tab inside that grace keeps
   it. `session_shutdown` closes it too, and `/browse stop` closes it at once.
 
 ## Routes
 
 | Route | Result |
 |---|---|
-| `/`, `/browse[/<rel>]` | tree + directory listing |
-| `/view/<rel>` | tree + file page (text, Markdown, image, binary, or over-size) |
-| `/view/<rel>?raw=1` | raw Markdown/text source instead of the rendered view |
-| `/raw/<rel>` | raw bytes, streamed; downloads and image sources |
-| `/diff[?mode=head\|staged\|worktree]` | changed-file overview with `--stat` |
-| `/diff/<rel>[?mode=…]` | one file's unified diff |
-| `/api/tree?path=<rel>` | JSON children for lazy tree expansion |
-| `/api/files?q=<query>` | JSON fuzzy path matches for the quick-open palette |
-| `/api/dir-rev?path=<rel>` | JSON listing revision for the reload check |
-| `/events` | Server-Sent Events stream of `status` frames for the open page |
-| `/app.js` | the first-party client script |
-| `/theme.js` | the pre-paint theme bootstrap |
+| `/files/`, `/files/browse[/<rel>]` | tree + directory listing |
+| `/files/view/<rel>` | tree + file page (text, Markdown, image, binary, or over-size) |
+| `/files/view/<rel>?raw=1` | raw Markdown/text source instead of the rendered view |
+| `/files/raw/<rel>` | raw bytes, streamed; downloads and image sources |
+| `/files/diff[?mode=head\|staged\|worktree]` | changed-file overview with `--stat` |
+| `/files/diff/<rel>[?mode=…]` | one file's unified diff |
+| `/files/api/tree?path=<rel>` | JSON children for lazy tree expansion |
+| `/files/api/files?q=<query>` | JSON fuzzy path matches for the quick-open palette |
+| `/files/api/dir-rev?path=<rel>` | JSON listing revision for the reload check |
+| `/files/events` | Server-Sent Events stream of `status` frames for the open page |
+| `/files/app.js` | the first-party client script |
+| `/files/theme.js` | the pre-paint theme bootstrap |
 
 ## Configuration
 
@@ -102,8 +100,7 @@ global document then project document, project wins — are in
 
 | Key | Default | Meaning |
 |---|---|---|
-| `port` | `0` | `0` picks one random port fixed for the session; a positive value pins it. |
-| `autoOpen` | `true` | Open the browser on start; `false` for headless. |
+| `autoOpen` | `true` | Open the browser on start and on every later `/browse`; `false` for headless. |
 | `maxFileBytes` | `1048576` | Larger files show a download card only. |
 | `maxThumbBytes` | `5242880` | Larger images get an icon, not a thumbnail. |
 | `maxTextLines` | `5000` | Rendered lines before truncation. |
@@ -342,12 +339,11 @@ old and new sides for `lib/highlight`.
 
 ## Live status
 
-While a server is running, the extension publishes a two-tone `◉ <port>` chip
-(a green circle-dot and a blue port) under the shared `browse` status key. The
-[`bytefly`](./bytefly.md) extension routes it to line 1's right zone, after
-`⎇ branch` and `⑂ worktree` and in the same run as the board page's port chip;
-it is cleared on stop and on `session_shutdown`. The chip is session-local: it
-reflects only this session's server, with no cross-session sharing.
+The page answers at `/files` on the session's one server, so the footer's one
+`◉ <port>` chip is the session's, not this page's: [`serve`](./serve.md) publishes it
+while anything is mounted, and [`bytefly`](./bytefly.md) routes it to line 1's right
+zone, after `⎇ branch` and `⑂ worktree`. It is cleared when the session's server closes,
+so a session with no page open shows nothing at all.
 
 The page has its own live status, which is what a left-open tab reads. A `◉ live`
 chip beside `read-only` says whether status is flowing (green), still
@@ -452,22 +448,20 @@ stops at the first difference because the control, not the checker, is the fix.
 | Integration point | How |
 |---|---|
 | Command | `/browse` registers a single command from the factory; no tools are exposed. |
-| State | The running server, its root, and the session port live in a module-local closure; nothing is persisted and no session entries are written. |
+| State | The running mount, its root, and the session id live in a module-local closure; nothing is persisted and no session entries are written. The port is `serve`'s, not this extension's. |
 | Lifecycle | The factory opens no socket; the server is created on `/browse` and closed idempotently by `/browse stop`, by `session_shutdown`, and once its last page has been gone for the idle grace, which also ends every attached status stream. |
 
 ## Design notes
 
 - **Lifecycle.** `/browse` resolves `resolveEffectiveCwd(ctx.cwd)`, loads config,
-  selects the port, parses args, and `await createFileServer(...)`: `realpath`
-  the root, bind `127.0.0.1`, await `listening`, return `{ url, port, root,
-  close }`. The port is chosen once for the session: a pinned config `port`
-  wins, otherwise a random port is drawn and cached after the first successful
-  bind, so later starts reuse it (a conflict is reported and the next `/browse`
-  rolls another). `/browse stop` and `session_shutdown` await the idempotent
-  `close()`; `session_shutdown` also clears the cached port. The page is the
-  server's only reader, so the channel reports the last page's departure after
-  `IDLE_STOP_MS` and the command closes the server and clears the chip — the
-  cached port survives, so the next `/browse` binds the same one.
+  parses args, and mounts the page through `requestMount`: `realpath` the root, claim
+  `/files` on the session's server, return `{ url, port, root, close }`. The
+  port belongs to `serve` — `serve.port` pins the session's origin — so nothing here
+  picks or retries one. `/browse stop` and `session_shutdown` await the idempotent
+  `close()`, which gives the prefix back. The page is the mount's only reader, so the
+  channel reports the last page's departure after `IDLE_STOP_MS` and the command
+  releases the prefix — and the session's port is `serve`'s, remembered per session,
+  so the next `/browse` answers on the same origin.
 - **Pure routing.** `handleRequest(context, method, rawUrl, headers)` validates
   method and `Host`, parses the URL, matches a route, and runs every path
   through `paths.ts`. It returns a plain `ServeResponse`, so routing is tested
@@ -529,7 +523,7 @@ stops at the first difference because the control, not the checker, is the fix.
 | `view/diff-html.ts` | The unified-diff body: the gutter, the sign, the hunk sections, and per-hunk highlighting |
 | `transport/router.ts` | Pure request handler: routes, the `/raw` sandbox policy, and the error page |
 | `transport/server.ts` | This extension's routes over `lib/http`'s loopback server: the request count, the stream cap, and the idle policy |
-| [`../../lib/http/index.ts`](../../lib/http/index.ts) | Loopback HTTP layer shared with `plan`: one server entry (`serveLoopback`), page/script/JSON/event-stream headers, `ServeResponse`, the request-envelope helpers, the event-stream sink and its idle grace |
+| [`../../lib/http/index.ts`](../../lib/http/index.ts) | The served-page kit shared with `plan`: one server entry (`serveHttp`), page/script/JSON/event-stream headers, `ServeResponse`, the request-envelope helpers, the event-stream sink and its idle grace. The mount contract is the leaf [`mount.ts`](../../lib/http/mount.ts), which is the only one a registration graph may reach |
 | [`../../lib/browser.ts`](../../lib/browser.ts) | Cross-platform browser opener (shared with `plan`) |
 
 ## Testing

package/docs/extensions/file-open.md

@@ -7,17 +7,15 @@ effective working directory.
 
 ## 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 |
-|---|---|---|---|
-| 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 |
+| Capability | How | What you get |
+|---|---|---|
+| Native open | `/open`, `open_path` | The file or directory opens in the application the OS associates with its type. |
+| Reveal in the file manager | `/open -r`, `open_path` with `reveal: true` | The target is selected in the file manager instead of opened. |
+| 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. |
+| 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. |
+| Pasted-path cleanup | `/open`, `open_path` | The editor's `@` mention prefix, surrounding quotes, and control characters are stripped before the path is used. |
+| 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. |
+| Session-outliving launch | `/open`, `open_path` | The handler runs detached, so the application outlives the Pi session. |
 
 ## Quickstart
 

package/docs/extensions/file-read.md

@@ -10,20 +10,18 @@ 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 |
+| Capability | How | What you get |
+|---|---|---|
+| Document extraction | `read_doc` | Plain text from a document or workbook whose bytes the built-in `read` cannot decode. |
+| Paged reading | `read_doc` (`startIndex`, `maxChars`) | A long file arrives in slices, and a truncated result names the offset to ask for next. |
+| Workbook text | `read_doc` on `.xlsx` | One `[Sheet]` heading per worksheet followed by tab-separated rows, so the shape of the file survives. |
+| Confined reads | `read_doc` | A path outside the effective working directory is refused, symlinks resolved, before any parser runs. |
+| Progress and cancellation | `startToolProgress`, the abort signal | A slow extraction shows `Reading... <elapsed>` and can be cancelled instead of looking dead. |
+| 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. |
+| 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. |
+| 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. |
+| Lazy parsers | `read_doc` | Only the format you read loads a library, so registration costs nothing at startup. |
+| Code-point slicing | `read_doc` (`startIndex`, `maxChars`) | CJK and emoji stay well-formed across a page boundary. |
 
 ## Quickstart
 

package/docs/extensions/goal.md

@@ -5,21 +5,19 @@ 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 |
+| Capability | How | What you get |
+|---|---|---|
+| 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. |
+| Phase tracking | `goal`, `/goal done` | The goal is `planning`, `active`, or `achieved`, and only the workflow can open a draft. |
+| Plan-first question | `goal`, `/goal <prompt>`, `/goal raw` | One dialog decides whether a new goal enters plan mode before it is pursued. |
+| 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. |
+| Plan-phase settlement | `planning` goal, `plan` action `exit` | Leaving plan mode without approval makes the draft `active`; approving the plan writes its `## Goal` into it. |
+| 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. |
+| Goal rail | the `Goal · active · …` widget, the `achieved` key | The objective stays one line above the editor while it is pursued. |
+| Per-turn restatement | the `[SESSION GOAL]` reminder | The model reads the pursued objective before each turn, without it entering the transcript. |
+| Open-list check | `goal`, `/goal done` | Completing the goal names the todo items the list still has open. |
+| Branch-following state | tool-result `details`, the `goal` session entry | The goal survives `/resume` and `/tree`, and abandoned branches never leak in. |
+| Command help | `/goal help`, `/goal -h`, `/goal --help` | The verb list and the usage of each form, without changing the goal. |
 
 ## Quickstart
 
@@ -137,7 +135,7 @@ 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
+`lib/plan-entry.ts`, the same ones the `enter` action shows, so the user answers
 once.
 
 A draft whose plan never arrived is settled rather than stranded. If plan mode is
@@ -215,7 +213,7 @@ that is what it is. The `goal` tool stays the silent setter.
   the extension that asks also has to act on the answer — which a command context
   cannot do, since `ExtensionCommandContext` has no `executeTool`. So the consent
   sentence and the request channel live in `lib/plan-entry.ts`: `goal` asks, and
-  `plan` enables silently over `pi.events`. `enter_plan_mode` keeps its own
+  `plan` enables silently over `pi.events`. The `enter` action keeps its own
   confirm for the model-initiated path, using the same sentence, so the user is
   never asked twice and the two texts cannot drift.
 - **The draft is settled, not stranded.** A `planning` goal is normalised by the