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

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

@@ -1,364 +1,109 @@
 # bytefly — the TUI header, footer, user-message marker, turn rule, extension screen, and notifications
 
-`bytefly` owns the terminal chrome, configuration, and diagnostics surfaces
-this package adds: one themed startup header whose two-tone nameplate carries
-the agent and chrome identities, one compact, colorful, width-adaptive two-line
-footer, a two-row `You` nameplate that opens each user message, a receipt rule that
-records each completed turn in the transcript, one keyboard-driven screen with
-three sections — Extensions, every resolved Pi extension with its enable
-checkbox and its health; Skills, every resolved Pi skill with the same checkbox
-and its declared description; and Settings, the common app and `bytefly.json`
-preferences — and an opt-in notify capability that raises an OS notification when a run finishes,
-a job finishes, or the agent asks for input, and a package-update check that
-replaces Pi's startup blocks — the package list and Pi's own release — with one
-notice each and marks a new version on the header.
-DeepSeek is priced from the provider's published yuan rates and peak tariff by
-default; set `price.currency.code` to `USD` to price it from the provider's
-published dollar table instead, under the same peak windows, with Pi's recorded
-dollars covering a model the table does not list. Any other model can be priced
-from your own yuan rates when Pi's
-catalog does not match what a provider actually charges.
+`bytefly` owns the terminal chrome, configuration, and diagnostics surfaces this
+package adds: the startup header and footer, the user-message nameplate, the turn
+rule, the shared notice and tool-block frames, the working line, the `/bytefly`
+control center, OS notifications, and the package-update check. Every surface is
+drawn from the package's `lib/tui/` design system, so a theme swap re-skins the
+whole chrome. The footer prices a session from DeepSeek's published rates by
+default, and from `bytefly.json` otherwise.
 
-```
-pi --extension ./extensions/bytefly   # load just this extension
-pi -e .                               # load the whole @gavin-hu/my-pi-agent package
-pi install ./                         # install the package
-```
-
-## Tool rendering
-
-How the `run_doctor` call and its result look in the transcript — the call line as a headline and the body indented under it:
-
-<img src="../../assets/tools/run_doctor.png" alt="The run_doctor tool's result: the call line and a one-line, indented doctor summary with a collapsed expand hint" width="100%">
-
-## What it does
-
-The extension owns ten surfaces: the startup header, the footer, the
-user-message marker, the rule between completed turns, the notice block for
-shared transcript notices, the tool-block frame, the live working line, the
-three-section control center, notifications, and the update check.
-
-**Header.** A nameplate: a two-tone half-block mark from the active theme's
-`accent` / `warn` roles, the agent identity (`Pi`, bold, and its version), the
-chrome identity (`enhanced by bytefly` and the package version), a signature
-rule whose `accent` lead sits under the mark, and a grouped help block. The help
-keys resolve live from Pi's keybindings, so a rebound key shows the user's
-chord; the identity and help text are `meta` / `faint` so the mark keeps the
-eye. It opens with a blank row, so the nameplate clears the top edge. It is
-installed only in interactive (`tui`) sessions when Pi's
-`quietStartup` is `true` — the Settings row **Bytefly startup TUI** — and
-`false`, `"header"`, and unset leave Pi's built-in header in place; on terminals
-that cannot render half blocks the mark falls back to a two-tone `Pi` wordmark.
-
-```
- █▀█  Pi v1.2.0
- █▀ █ enhanced by bytefly v0.8.1
- ─────────────────────────────────────────────────
-   escape to interrupt · ctrl+c to clear · ctrl+d to exit (empty)
-   ctrl+o to expand tools · ctrl+t to expand thinking · ctrl+l to select model
-   / commands · ! bash · !! bash (no context) · /bytefly extensions
-```
-
-As the terminal narrows, the identity sheds the chrome marker, then the chrome
-version, then the chrome line, then Pi's marker with the agent name, and the help
-rows drop whole keys, so nothing wraps or clips mid-word. Height sheds the same way: at 28 rows
-all three help groups print, below 28 the middle group (the expand and model
-chords) goes first, below 22 only the `/` commands row survives, and below 16 the
-help block and the leading blank row go, leaving the nameplate and its rule. An
-unknown height keeps the full header. The nameplate sits on the transcript
-margin, which follows Pi's `outputPad` (the value the tool frame and the notice
-use too), and the help hangs one body indent inside it. The mark, tokens,
-identity, and grouped help are tuned in
-[`header/config.ts`](./header/config.ts).
-
-**Footer.** Two lines, each with a left and right zone:
-
-- **Line 1 — identity:** `pwd` and the session name on the left; git state
-  (`⎇ branch · ⑂ worktree`) and the `◉` browse chip on the right.
-- **Line 2 — resources:** the context gauge and usage meters on the left, the
-  child-run roll-up (`↳ 3 · ¥0.12`, present only once a subagent has finished),
-  the mode/alert slot (`≡ plan`) trailing after a `│` when present, and the model
-  and thinking level on the right. The gauge is anchored at column 0, so `%` is
-  always in the same place.
-  The roll-up is its own number, never folded into the session's cost: a subagent
-  runs in its own process, and the footer prices those runs with the same rate
-  table and currency as the session so a currency change moves both. It covers
-  the last 500 child runs of the current process, and starts from zero after
-  `/resume` (the events are not session entries).
-
-```
-~/repo/my-pi-agent                                              ⎇ main · ⑂ smoke
-▰▰▰▰▰▰▱▱▱▱ 62%/200k · ¥0.31 · ↳ 2 · ¥0.06 · ↑42k ↓8.0k · R96k CH 87% │ ≡ plan    opus-4.5 · high
-```
-
-(The examples show the default `¥` symbol. A model that neither `rates` nor the
-built-in table covers contributes nothing in `CNY` mode, so the bar shows no
-figure rather than a guessed one; `USD` mode adds Pi's recorded dollars for that
-record instead — see the currency note under [Configuration](#configuration).)
-
-With no plan mode there is no mode slot, so the `│` is omitted:
+## Capabilities
 
-```
-~/repo/my-pi-agent                                                    ⎇ main · ⑂ smoke
-▰▰▰▰▰▰▱▱▱▱ 62%/200k · ¥0.31 · ↑42k ↓8.0k · R96k CH 87%             opus-4.5 · high
-```
-
-As the terminal narrows, segments shrink and drop by priority rather than
-clipping. The branch keeps its name and is dropped when the name no longer
-fits, rather than collapsing to a bare glyph:
-
-```
-~/repo/project                    ⎇ main · ⑂ smoke
-▰▰▰▰▰▰▱▱▱▱ 62% · ¥0.31 │ ≡ plan    opus-4.5 · high
-```
-
-```
-project   ⎇ main
-62% ≡   opus-4.5
-```
-
-With a named session, the name follows the path and truncates before it drops:
+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.
 
-```
-~/repo/project · feature-refac…   ⎇ main
-▰▰▰▰▰▰▱▱▱▱ 62% │ ≡ plan         opus-4.5
-```
-
-Zero-value meters are omitted, so a fresh session shows only `?/window` instead
-of a row of `¥0.00 · ↑0 ↓0 · R0 W0`. Unknown context usage shows a muted `?`
-with no gauge (known `0%` still draws the empty gauge), so unknown and zero stay
-distinct. Cost keeps the configured precision — the segment drops rather than
-rounding to a misleading `¥0.3` — and a positive amount below one minor unit
-shows as `¥<0.01` rather than `¥0.00`.
-
-DeepSeek needs no config file at all: the bar prices it from the published yuan
-rates and peak tariff built into [`footer/price/config.ts`](./footer/price/config.ts).
-Those tables record the day they were last checked against the published tariff,
-and `doctor` reports how old that is, so a re-pricing shows up as a warning instead
-of a quietly wrong total. A `bytefly.json` can switch to the published dollar table,
-add models of your own, or replace a built-in entry:
-
-```
-~/repo/project                                                          ⎇ main
-▰▰▰▰▰▰▱▱▱▱ 62%/200k · ¥2.50 · ↑42k ↓8.0k · R96k CH 87%             opus-4.5 · high
-```
-
-**Session budget.** `price.budget` puts a threshold under that total, in the same
-currency: when the session's cost reaches it, one `bytefly · Session budget
-reached` notice names what was spent against the budget, and one OS notification
-follows when notify is enabled. It is an alert, not a limit — no turn is blocked or
-aborted — and it fires once per session, on the turn where the crossing becomes
-final (the run settling), because a warning per turn after that is noise. `0`, the
-default, turns it off. The check reads the total the footer already priced, and
-the footer exists only in `tui` sessions, so a print or JSON run has no budget
-alert; the footer's own numbers are visible in every interactive session.
-
-**Unpriced records.** `CNY` has no fallback, so a record for a model with no
-`price.rates` entry contributes nothing to the total — with nothing on screen
-saying so. The footer counts those records on the pass it already prices, and
-one `bytefly · Records with no CNY rate` notice names the count and the two
-fixes: switch `price.currency.code` to `USD` (Pi's catalog is per model, tiers
-included) or add yuan `price.rates` entries. It fires once per session, on the
-run that settles, like the budget alert. `USD` never counts one: Pi's recorded
-amount covers every model.
-
-**User message.** Every user message opens with a two-row `You` nameplate —
-the label over a rule that spans the width — above the message:
-
-```
-You
-────────────────────────────────────
-
-the message the user typed
-```
-
-It is always on in interactive sessions and has no config file. Pi renders a
-user message as Markdown and owns its colors, so bytefly's only lever is a
-`registerMarkdownTransformer`: the nameplate is a single level-2 heading whose
-text is padded so the rule wraps onto the second row, and both rows carry the
-accent because the themes point `mdHeading` at it. The block carries no fill —
-the shipped themes set `userMessageBg` to the terminal default, so it reads like
-the tool blocks. The nameplate is separated from the message by a blank line, so
-the message's own Markdown (a fence, a list, a second paragraph) parses exactly
-as it would without it, and a soft wrap of one long line stays at the margin
-because the renderer wraps it, not bytefly. The label and the rule are tuned
-in [`message/config.ts`](./message/config.ts).
-
-**Working line.** Pi's working row shows a static `Working`, so a long run
-reads the same as a short one. While the row is up, bytefly advances its
-message once a second and hands it back to Pi when the row comes down. Before
-the first tool starts it is a count:
-
-```
-Working… 12s
-```
-
-Once a top-level tool starts, the row becomes a live run line: the tool, how
-many top-level tools this run has started, and the elapsed time.
-
-```
-edit · 3 tools · 12s
-```
-
-A nested tool call (one carrying `parentToolCallId`, such as a codemode script's
-inner call) neither counts nor takes over the line, so the number matches the
-tool blocks in the transcript. The line keeps the last tool name while the
-model streams after it, and a tool event repaints the row immediately instead
-of waiting for the next tick. The line covers the whole run, tool calls
-included. It is tied to the row's visibility: it starts on `turn_start`, stops
-on `agent_end`, and is reset on `session_shutdown`; turns inside one run do not
-restart it, and a retry starts a new run. The words and the interval are tuned
-in [`working/config.ts`](./working/config.ts).
+### Chrome
 
-**Turn separator.** After each completed turn the extension appends an inert
-entry and draws a centered receipt rule — `╌╌╌ turn N · duration · N tools ╌╌╌`
-— across the transcript; see [Turn separator](#turn-separator). No config file is
-needed and there is no command.
+| Capability | How | What you get | Status |
+|---|---|---|---|
+| Startup header | `quietStartup` | One two-tone nameplate with the agent and chrome versions and the live help keys, in place of Pi's startup header and resource listing. | Shipped |
+| Two-line footer | every `tui` session | State on one line — location, modes, and alerts — and meters on the other — context, spend, tokens, cache, and model — each shedding parts rather than clipping. | Shipped |
+| Extension status chips | `footerData.getExtensionStatuses()` | Worktree, browse, plan, and alert statuses appear in the footer, using each extension's own colour. A failed job is the one chip no width drops. | Shipped |
+| Priced session total | the `price` section of `bytefly.json` | The session's spend in yuan or dollars, with DeepSeek priced out of the box. | Shipped |
+| Delegated-run cost roll-up | the `↳` footer segment | A finished subagent's cost appears beside the session total, without merging the two ledgers. | Shipped |
+| User-message nameplate | every `tui` session | Each user message opens with a two-row `You` label and rule. | Shipped |
+| Turn receipt | the `bytefly-separator` entry | One rule per completed turn, recording its number, duration, tool count, and outcome. | Shipped |
+| Shared notices | the `my-pi-agent/notice` type | Any extension's notice renders at the transcript margin with a severity-coloured rail. | Shipped |
+| Compaction canvas | the shipped `themes/` palettes | Pi's `/compact` block keeps its content and loses its fill, so it sits on the canvas. | Shipped |
+| Tool-block frame | `registerToolRenderer` | Every tool block leads with its own call line and hangs its result from the transcript rail. | Shipped |
+| Working line | `ctx.ui.setWorkingMessage` | The working row counts seconds, then names the running tool and how many tools the run has started. | Shipped |
+
+### Control center
+
+| Capability | How | What you get | Status |
+|---|---|---|---|
+| One frame, three sections | `/bytefly`, `/bytefly skills`, `/bytefly settings` | Extensions, skills, and settings in one dock: the worst problem in the header, each section's count on the tabs, the write scope at the right, and one body height for all three, so changing section never resizes the screen. | Shipped |
+| Resource rows and the block | `Space`, `Enter`, `?` | A name-first row — `worktree`, not `worktree/index.ts` — with one checkbox, one status glyph and one verdict word, and the focused row's findings, path, source, state, and health beside the list at 96 columns and under it below. | Shipped |
+| Grouped settings | `/bytefly settings` | Twelve preferences under `Startup`, `Notifications`, `Session`, and `Price`, each value in one aligned column and editable in place; `J` shows the stored JSON section. | Shipped |
+| Theme selection | the `Theme` row in `/bytefly settings` | `system` and the package's `bytefly-dark` and `bytefly-light` palettes are one selection; a reload applies it. | Shipped |
+| Filters and scope | `/`, `!`, `s`, `x` | Narrow the rows by text or to what needs attention — the chips on the tab row say which — and choose where a toggle lands, the personal or project `settings.json`, with `x` clearing a project override. | Shipped |
+| Reload after changes | `R` | `unsaved changes` joins the header while a write is pending, and `R` reloads to apply it instead of leaving the session to be restarted by hand. | Shipped |
+| Health report | `run_doctor`, `/bytefly doctor` | Prerequisites, parse errors, and aged rate tables as text and typed data. | Shipped |
 
-**Notices.** Any extension in the package can post a transcript notice under the
-shared `my-pi-agent/notice` type; bytefly draws it at the transcript's margin —
-a `source · title` headline at the margin, then rail-led rows, each with its own
-severity glyph:
+### Upkeep
 
-```
-job · 2 background jobs finished
-╎ ✓ j1 build · exit 0
-╎ ✕ j2 test · exit 1
+| Capability | How | What you get | Status |
+|---|---|---|---|
+| Currency and peak tariff | `price.currency.code`, `price.peak` | `CNY` and `USD` are separate pricing methods with published rates; DeepSeek's peak windows apply per token record. | Shipped |
+| Session budget alert | `price.budget` | The session total shows as `spent/limit` in the footer, and one notice plus one OS notification fires when it reaches the threshold. | Partial |
+| Unpriced-record notice | `price.currency.code` | A `CNY` session names the records it could not price, and the two ways to fix it. | Shipped |
+| Desktop notifications | `notify.enabled`, `notify.turnFinished`, `notify.needsInput`, `notify.jobFinished`, `notify.matchFound` | An OS notification when a run settles, the agent needs you, a job finishes, or a watcher matches. | Shipped |
+| Proactive health check | `doctor.proactive` | At session start, when the startup header is on, a hard requirement is probed once and reported before the first turn. | Shipped |
+| Update check | `/bytefly update` | One notice per session lists every package behind, and the header marks a new version. | Shipped |
+| Update action | `/bytefly upgrade` | Pi's own package manager installs the configured packages behind a confirmation, clearing the marker and naming the reload the new version needs. | Unreleased |
+| Pi release notice | `automatic: Pi's release notice` | Pi's own newer version gets the same themed notice and header marker, without a second check. | Shipped |
+
+## Quickstart
+
+```bash
+pi --extension ./extensions/bytefly    # load just this extension
+pi -e .                                # load the whole @gavin-hu/my-pi-agent package
+pi install ./                          # install the package for a user
 ```
 
-The rail is painted by the notice's worst severity, so a failure reads red at the
-edge like an errored tool result, and the headline's title takes the notice's own
-severity — a warning reads yellow where its sentence is, while an `info` or `ok`
-notice stays body text. A row's label stays body text too: its severity is the
-glyph it hangs on, so one failing row never tints the rest of the list.
-
-`job` and `watch` post one when a background job finishes or a watched line
-matches, so the report the model reads is visible too. `doctor` posts one when a
-hard requirement is missing at session start, with a row per finding and the
-command that fixes it:
-
+```text
+/bytefly                            # the control center, on Extensions
+/bytefly doctor                     # the report run_doctor returns
 ```
-doctor · 1 missing prerequisite
-╎ ✕ worktree (git) · install git and make sure it is on PATH
-```
-
-The type and the `NoticeDetails` shape are the shared contract in
-[`lib/notice.ts`](../../lib/notice.ts), and the severity glyphs and item cap
-are tuned in [`notice/config.ts`](./notice/config.ts). Every field is sanitized
-and clipped at the boundary, and a message without `details` keeps Pi's default
-custom-message box.
 
-**Compaction.** `/compact` is Pi's own surface: its summary block is a built-in
-message component, so bytefly cannot replace, hide, or shorten it. The shipped
-themes only remove its fill — `customMessageBg` is the terminal default — and
-paint the `[compaction]` label in the accent, so the block sits on the canvas
-like the rest of the transcript. Pi's branch summaries and skill invocations
-share the same tokens.
+## Tool
 
-<img src="../../assets/compaction.png" alt="The /compact summary block: a [compaction] label, the compacted token count, and the summary Markdown on the terminal canvas, with no background band" width="100%">
+<img src="../../assets/tools/run_doctor.png" alt="The run_doctor tool's result: the call line and a one-line, indented doctor summary with a collapsed expand hint" width="100%">
 
-**Tool blocks.** Every tool block leads with the tool's own call line as the
-headline — the tool name in the theme's tool-title colour — and its result body
-sits two columns in directly beneath it, led by the transcript rail, instead of
-Pi's filled status background:
+`run_doctor` — `exposure: "direct"` (the default), `executionMode: "sequential"`,
+read-only, closed-world. It reports whether each extension has what it needs at
+runtime — binaries on `PATH`, optional packages and browsers, login and state
+files, and config files that fail to parse — and it probes and changes nothing.
+Its `readOnlyHint` is what the shared default-deny policy in `lib/policy.ts`
+reads to allow it in plan mode.
 
-```
-read src/app.ts
-╎ const answer = 42;
-```
-
-The two tools that mutate a file, `edit` and `write`, carry their result on the
-call body — the edit diff, the written file content — so that body is railed
-like any other result. There is no status band: the diff's own red/green line
-colours, with the changed words in reverse video, and the `edit` / `write`
-headline are what mark a file change.
-
-A `registerToolRenderer` resolver switches the row to `renderShell: "self"`,
-leaves the call's own first line as the headline, and indents the rest of the
-call and the whole result under it. A shell call's `$` / `>` prompt becomes the
-tool name and the command is repainted in the body colour, and a primary subject
-(a path, URL, query, pattern) is demoted to the body colour too, so the name is
-the call line's only accent (`bash bun run check`, `read src/app.ts`). The
-tool's own
-`renderCall`/`renderResult` are passed through, so syntax highlighting, diffs,
-previews, and truncation notices are unchanged — only the frame is bytefly's.
-The body carries the transcript rail, painted by status (a running result takes
-the accent, a failure red, a finished one neutral) and drawn with the glyph from
-the `chrome.rail` setting. A result frame is always railed; a call frame is railed
-only for `edit` and `write`, whose call body carries the result — every other
-call's headline and continuation lines stay plain-indented. Package renderers
-clip a call to one physical line (middle clip for a path or URL), so it cannot
-leak into the body column; Pi's own renderers still wrap, and the frame keeps a
-wrapped continuation unrailed and loses the accent there too, with the rail
-beginning at the result underneath. A rejected call renders as one sanitized
-`error` line in the error role; a running tool shows a live elapsed label, and a
-finished long call appends its duration. A tool with
-no renderer of its own is framed around a generic call/result fallback, whose
-call line reads like a built-in — the leading string argument bare, the rest as
-trailing options (`open_path src/app.ts`) — rather than dumping raw `key=value`
-pairs. A tool that draws its own shell (`edit`) is framed too:
-`renderShell: "self"` only tells Pi not to draw its box around the renderer, so
-its diff would otherwise sit at the wrong indent; the frame drops the blank
-edges its own `Box` pads itself with, and hands it a theme whose `bg` is inert so
-it never paints a band the rest of the transcript does not have.
-
-The call line is one colour grammar, shared with Pi's built-ins: the tool name is
-`toolTitle` and bold and is the line's only accent; a primary subject (a query, a
-URL, a path, a status) reads in the body role (`label`), counts and summaries are
-`muted`, trailing options are `dim`, and the result body is `toolOutput`. The
-shipped themes point `toolTitle` at the accent and `label` at the body colour, so
-the name is the call line's one accent and the subject follows as body text; a
-theme that maps `toolTitle` elsewhere is respected rather than overridden.
+| Parameter | Type | Meaning |
+|---|---|---|
+| `extension` | string, optional | Report a single extension instead of every extension. |
+| `refresh` | boolean, optional | Ignore the findings cached earlier in this session and probe again. |
 
-**Control center.** `/bytefly [extension] [refresh]` opens a keyboard-driven
-dock list of every Pi extension the session resolves — across personal settings
-and, when trusted, the project — one row per extension with its enable checkbox
-and its worst-severity health, and writes a `+pattern` / `-pattern` toggle into
-the matching `settings.json`. `←`/`→` switch to Settings, which lists the
-preferences this package and Pi expose: bytefly startup TUI, desktop notifications,
-the transcript rail glyph, output padding, and the hardware cursor. The focused
-extension's findings, or the focused setting's source and target file, sit
-underneath, and `run_doctor` returns the same report as text and typed data.
-Only a missing
-*hard* requirement posts a notice at session start; everything else waits in the
-report.
-See [The control center](#the-control-center).
-
-**Notify.** Off by default, one `notify` section in `bytefly.json` turns on OS
-notifications for unattended runs: when a full agent run settles, when a
-background job finishes, when the agent opens a prompt asking for input, and when
-an armed `watch` wake match fires as the agent becomes idle. The
-method follows the terminal (OSC 777, OSC 99, a Windows toast) or falls back to
-the platform notifier (`osascript`, `notify-send`); see
-[Notifications](#notifications).
-
-**Update check.** In the background at an interactive session's start, Pi's
-package manager reports which configured packages are behind. bytefly suppresses
-Pi's own startup block, caches the snapshot in `<agentDir>/bytefly/update.json`
-with the time it was read, and posts one transcript notice listing every package
-plus `pi update --extensions`. This package's new version alone puts `↑0.12.0`
-after the header's chrome version and adds its release URL to the notice. A
-session inside the 24-hour window reuses the cache without a package-manager
-call, and `/bytefly update` re-runs the check on demand. Pi's own newer release
-is drawn the same way: Pi resolves it from `pi.dev` and would draw `Update
-Available`, and bytefly patches the method that draws it, so the release becomes
-a notice naming `pi update` and the changelog and marks `Pi v1.3.0 ↑1.4.0` on
-the agent line. `PI_OFFLINE` uses the cached marker with no notice, only `tui`
-starts the background check, and a failed read is silent and not cached, so the
-next session tries again; see [Update check](#update-check).
+Result (`details` / `structuredContent`): `{ headline, missing, degraded, extensions }`,
+one finding per check with its `check`, `severity`, `detail`, and optional `hint`.
+The same report is what `/bytefly doctor` prints, and what
+[the control center](#the-control-center) draws.
 
 ## Commands
 
+One command runs the screen, prints the report, and re-checks updates:
+
 | Command | What it does |
 |---|---|
 | `/bytefly [extension] [refresh]` | Open the control center on Extensions. In `tui` it mounts a docked list; every other mode prints the grouped listing, or one extension's full findings when named. |
 | `/bytefly settings` | Open the control center on Settings. Outside `tui` it prints one `Label: Value` line per setting. |
 | `/bytefly skills` | Open the control center on Skills. Outside `tui` it prints the grouped skills listing with one row per skill. |
 | `/bytefly doctor [extension] [refresh]` | Print the doctor report. Outside `tui` it prints `run_doctor`'s text for every extension, or one named extension's findings; in `tui` it mounts the same docked screen. |
+| `/bytefly prices` | Name the models this session could not price: the `price.rates` key for each, the records behind it, and where to add it. It prices the session when asked, so it answers in every mode — the footer that carries the same fact exists only in `tui`. No rate is suggested. |
 | `/bytefly update` | Re-run the package update check now, ignoring the cache window, and report what it found — the updateable packages, this package's version and release URL when known, `PI_OFFLINE`, or an unreadable list. It resolves no packages and probes no extension. |
+| `/bytefly upgrade` | Install what the check found, behind a confirmation: Pi's own package manager updates every configured package, the marker is re-read, and one line reports the result and the reload it needs. `PI_OFFLINE` and a pinned npm version skip the work. It resolves no packages and mounts no screen. |
 
 Tab completes the subcommands, extension names after `doctor`, and `refresh`;
-`/bytefly settings`, `/bytefly skills`, and `/bytefly update` take no name.
+`/bytefly settings`, `/bytefly skills`, `/bytefly prices`, `/bytefly update`, and
+`/bytefly upgrade` take no name.
 
 ## Behaviour by mode
 
@@ -387,20 +132,20 @@ print/JSON/RPC run gets an OS-level notification or none.
 Two things are JSON: the transcript rail's glyph (`chrome.rail`, default `╎`,
 read at `session_start`/`session_tree`) and this extension's three config
 sections — `price`, `notify`, and `doctor`. Everything else about the look is
-tuned in code: the header in [`header/config.ts`](./header/config.ts) (mark and
+tuned in code: the header in [`header/config.ts`](../../extensions/bytefly/header/config.ts) (mark and
 identity tokens, tagline, grouped help), the footer in
-[`footer/config.ts`](./footer/config.ts) (thresholds, gauge glyphs and widths,
+[`footer/config.ts`](../../extensions/bytefly/footer/config.ts) (thresholds, gauge glyphs and widths,
 separators, icons, status keys), and the turn separator in
-[`separator/config.ts`](./separator/config.ts) (glyph, label prefix, padding,
+[`separator/config.ts`](../../extensions/bytefly/separator/config.ts) (glyph, label prefix, padding,
 minimum duration, outcome wording, colors).
 
 Every key of every section is listed with its type, default, and bounds in
-[`docs/configuration.md`](../../docs/configuration.md); this section
+[`docs/configuration.md`](../configuration.md); this section
 covers what that table cannot — when each section is read, and what the cost
 does when no rate matches.
 
 `bytefly.json` is one shared document with a top-level section per extension (see
-[Configuration](../../docs/configuration.md)). It is read from the global
+[Configuration](../configuration.md)). It is read from the global
 document, then `<cwd>/.pi/bytefly.json`, project winning. The old per-extension
 files (`document.json`, `jobs.json`, …) are no longer read; `bun run config:migrate`
 moves them into the shared document.
@@ -449,7 +194,7 @@ catch-all prices everything).
 | Section | Read at | Applies to |
 |---|---|---|
 | `chrome` | `session_start`, `session_tree` | the rail glyph |
-| `price` | the footer install (`session_start`, `session_tree`) | the cost total |
+| `price` | the footer install (`session_start`, `session_tree`) | the cost total and the budget ceiling beside it |
 | `notify` | `session_start` | which events are announced, and how |
 | `doctor` | `session_start` | the proactive check |
 
@@ -477,13 +222,166 @@ the model reads the same sentence.
 - The extension screen registers no model-facing tool; toggling writes only
   through Pi's `settings.json`, and `run_doctor` is read-only.
 
+## Startup header
+
+A nameplate: a two-tone half-block mark from the active theme's `accent` /
+`warn` roles, the agent identity (`Pi`, bold, and its version), the chrome
+identity (`enhanced by bytefly` and the package version), a signature rule whose
+`accent` lead sits under the mark, and a grouped help block. The help keys
+resolve live from Pi's keybindings, so a rebound key shows the user's chord; the
+identity and help text are `meta` / `faint` so the mark keeps the eye. It opens
+with a blank row, so the nameplate clears the top edge. It is installed only in
+interactive (`tui`) sessions when Pi's `quietStartup` is `true` — the Settings
+row **Startup screen** — and `false`, `"header"`, and unset leave Pi's
+built-in header in place; on terminals that cannot render half blocks the mark
+falls back to a two-tone `Pi` wordmark.
+
+```
+ █▀█  Pi v1.2.0
+ █▀ █ enhanced by bytefly v0.8.1
+ ─────────────────────────────────────────────────
+   escape to interrupt · ctrl+c to clear · ctrl+d to exit (empty)
+   ctrl+o to expand tools · ctrl+t to expand thinking · ctrl+l to select model
+   / commands · ! bash · !! bash (no context) · /bytefly extensions
+```
+
+As the terminal narrows, the identity sheds the chrome marker, then the chrome
+version, then the chrome line, then Pi's marker with the agent name, and the help
+rows drop whole keys, so nothing wraps or clips mid-word. Height sheds the same way: at 28 rows
+all three help groups print, below 28 the middle group (the expand and model
+chords) goes first, below 22 only the `/` commands row survives, and below 16 the
+help block and the leading blank row go, leaving the nameplate and its rule. An
+unknown height keeps the full header. The nameplate sits on the transcript
+margin, which follows Pi's `outputPad` (the value the tool frame and the notice
+use too), and the help hangs one body indent inside it. The mark, tokens,
+identity, and grouped help are tuned in
+[`header/config.ts`](../../extensions/bytefly/header/config.ts).
+
+## Content and colors
+
+Two lines, each with a left and right zone:
+
+- **Line 1 — identity:** `pwd` and the session name on the left; on the right the
+  alert, then the mode chips (`≡ plan`), then `⎇ branch · ⑂ worktree`, then the
+  ports (`⊞ 5043 · ◉ 4909`) while a page is being served. The board page and the
+  file browser each publish one status key, and the bar reads both as a single
+  segment, so they share a weight, a position, and a floor.
+- **Line 2 — resources:** the context gauge and usage meters on the left, the
+  child-run roll-up (`↳ 3 · ¥0.12`, present only once a subagent has finished),
+  and the model and thinking level on the right. The gauge is anchored at column
+  0, so `%` is always in the same place.
+  The roll-up is its own number, never folded into the session's cost: a subagent
+  runs in its own process, and the footer prices those runs with the same rate
+  table and currency as the session so a currency change moves both. It covers
+  the last 500 child runs of the current process, and starts from zero after
+  `/resume` (the events are not session entries).
+
+```
+~/repo/my-pi-agent                                                         ≡ plan · ⎇ main · ⑂ smoke
+▰▰▰▰▰▰▱▱▱▱ 62%/200k · ¥0.31 · ↳ 2 · ¥0.06 · ↑42k ↓8.0k · R96k CH 87%                 opus-4.5 · high
+```
+
+(The examples show the default `¥` symbol. A model that neither `rates` nor the
+built-in table covers contributes nothing in `CNY` mode, so the bar shows no
+figure rather than a guessed one; `USD` mode adds Pi's recorded dollars for that
+record instead — see [Cost calculation](#cost-calculation).)
+
+With no plan mode the mode slot is simply absent:
+
+```
+~/repo/my-pi-agent                                                                  ⎇ main · ⑂ smoke
+▰▰▰▰▰▰▱▱▱▱ 62%/200k · ¥0.31 · ↑42k ↓8.0k · R96k CH 87%                               opus-4.5 · high
+```
+
+While a page is served, its port joins the run beside the worktree — both pages as
+one cluster, in a fixed order, so the pair reads as a pair:
+
+```
+~/repo/my-pi-agent                                                          ⎇ main · ⊞ 5043 · ◉ 4909
+▰▰▰▰▰▰▱▱▱▱ 62%/200k · ¥0.31 · ↑42k ↓8.0k · R96k CH 87%                               opus-4.5 · high
+```
+
+As the terminal narrows, segments shrink and drop by priority rather than
+clipping. The branch keeps its name and is dropped when the name no longer
+fits, rather than collapsing to a bare glyph:
+
+```
+~/repo/my-pi-agent       ≡ plan · ⎇ main · ⑂
+▰▰▰▰▰▰▱▱▱▱ 62%/200k · ¥0.31  opus-4.5 · high
+```
+
+```
+~/my-pi-agent     ⎇ main
+▰▰▰▰▰▰▱▱▱▱ 62%  opus-4.5
+```
+
+A port is dropped before the pages it names are: the cluster compacts to
+`⊞ ◉` once the digits no longer fit, so the narrowest bar that fits the location
+chips still says a page is up.
+
+```
+~/repo/my-pi-agent          ⎇ main · ⊞ ◉
+▰▰▰▰▰▰▱▱▱▱ 62% · ¥0.31   opus-4.5 · high
+```
+
+With a named session, the name follows the path and truncates before it drops:
+
+```
+~/repo/project · [feature-refac…]         ⎇ main
+▰▰▰▰▰▰▱▱▱▱ 62%/200k · ¥0.31      opus-4.5 · high
+```
+
+Zero-value meters are omitted, so a fresh session shows only `?/window` instead
+of a row of `¥0.00 · ↑0 ↓0 · R0 W0`. Unknown context usage shows a muted `?`
+with no gauge (known `0%` still draws the empty gauge), so unknown and zero stay
+distinct. Cost keeps the configured precision — the segment drops rather than
+rounding to a misleading `¥0.3` — and a positive amount below one minor unit
+shows as `¥<0.01` rather than `¥0.00`.
+
+Each segment reads a theme role and carries its own drop order:
+
+| Segment | Line / zone | Color | Drops |
+|---|---|---|---|
+| pwd | 1 left | dim | last |
+| session | 1 left | muted, bracketed | after worktree |
+| branch | 1 right | muted (warning when detached) | last |
+| worktree | 1 right | success | first |
+| ports `⊞ 5043 · ◉ 4909` | 1 right | success glyphs + accent ports | first, in one step |
+| context gauge + `%` | 2 left | muted ≤70 · warning 71–90 · error >90 | never |
+| `/window` | 2 left | dim | before cost |
+| cost | 2 left | muted | after tokens |
+| tokens `↑in ↓out` | 2 left | dim | after cache |
+| cache `R… CH …%` | 2 left | dim | first |
+| statuses | 1 right | as emitted by each extension | before branch |
+| model | 2 right | accent | never |
+| thinking level | 2 right | thinking token | before cost |
+
+The worktree status is read from the `worktree` status key, so the
+[worktree](./worktree.md) extension and the bar agree. The ports are the `board`
+and `browse` status keys, published by [board](./board.md) and
+[file-browse](./file-browse.md) while their pages are served. One segment reads
+both, in a fixed order (board, then browse), each a two-tone `<glyph> <port>`
+with a green glyph and an accent port. That is one fact — "a page is up on this
+port" — so it gets one weight and one floor: the pair compacts from
+`⊞ 5043 · ◉ 4909` to `⊞ 5043 ◉ 4909` to `⊞ ◉`, and it drops as a unit, where
+separate chips once let the board port outlive the browse one by four columns
+for no reason a reader could see.
+
+The mode slot holds everything else an extension publishes: a plan chip, a
+job count, a rewind timeline, the `✆` bridge, and an alert's front position. A
+plan chip's trailing plan file name is dropped, so the slot reads `≡ plan` even
+though the built-in footer keeps the name, and an alert (a failed job) sorts to
+the front of it. It keeps each extension's own colour when it compacts, and it is
+droppable: a tight bar drops the slot rather than truncating the model, which
+sits at the end of the line.
+
 ## Cost calculation
 
 Pi prices every model call from its bundled catalog in USD, and the provider API
 never returns a price. The footer can total that catalog directly, or replace
 it with its own rates for the models they match:
 
-- **Which built-in rates.** [`footer/price/config.ts`](./footer/price/config.ts) ships DeepSeek's published
+- **Which built-in rates.** [`footer/price/config.ts`](../../extensions/bytefly/footer/price/config.ts) ships DeepSeek's published
   yuan prices for `CNY` and its published dollar prices for `USD`, per model, with
   the peak schedule that doubles the price during peak hours
   ([DeepSeek's pricing page](https://api-docs.deepseek.com/quick_start/pricing)).
@@ -514,41 +412,79 @@ it with its own rates for the models they match:
   leaves out; `USD` adds Pi's recorded dollar amount for that record, because
   that number is already dollars and already per model.
 
+DeepSeek needs no config file at all: the bar prices it from the published yuan
+rates and peak tariff built into [`footer/price/config.ts`](../../extensions/bytefly/footer/price/config.ts).
+Those tables record the day they were last checked against the published tariff,
+and `doctor` reports how old that is, so a re-pricing shows up as a warning instead
+of a quietly wrong total. A `bytefly.json` can switch to the published dollar table,
+add models of your own, or replace a built-in entry:
+
+```
+~/repo/project                                                          ⎇ main
+▰▰▰▰▰▰▱▱▱▱ 62%/200k · ¥2.50 · ↑42k ↓8.0k · R96k CH 87%             opus-4.5 · high
+```
+
+`price.budget` puts a threshold under that total, in the same currency: when the
+session's cost reaches it, one `bytefly · Session budget reached` notice names
+what was spent against the budget, and one OS notification follows when notify
+is enabled. It is an alert, not a limit — no turn is blocked or aborted — and it
+fires once per session, on the turn where the crossing becomes final (the run
+settling), because a warning per turn after that is noise. `0`, the default,
+turns it off. The check reads the total the footer already priced, and the
+footer exists only in `tui` sessions, so a print or JSON run has no budget
+alert; the footer's own numbers are visible in every interactive session.
+
+A record nothing prices contributes nothing to the total. `CNY` has no fallback at
+all; `USD` falls back to Pi's recorded amount, which is `0` for a model its catalog
+does not know either. So "unpriced" means the same thing in both modes — no
+`price.rates` key matched **and** nothing else priced it — and it is counted by
+*model*, because a count says the total is short while a key says what to do:
+
+- The footer's cost segment marks it: `¥1.23 · 2 unpriced`, dropping to the count
+  alone on a narrow bar. A session where nothing could be priced shows `2 unpriced`
+  beside no price at all, where it used to show nothing.
+- `/bytefly prices` lists them — the key, the records behind it, and the line saying
+  where the keys go. It prices the session when asked, so it works in every mode,
+  including the ones with no footer.
+- One `bytefly · Records with no rate` notice fires per session, on the run that
+  settles, naming up to three keys. The two fixes it offers are both honest: switch
+  `price.currency.code` to `USD` (Pi's catalog is per model, tiers included) or add
+  `price.rates` entries for those keys.
+
+The key is the `price.rates` vocabulary, so it is copy-pasteable: `provider/model`,
+`*` for a side the history does not name, and a model id containing a slash kept
+whole (`openrouter/anthropic/claude-fable-5`). A genuinely free model — a local one
+whose recorded cost is `0` — is listed too; adding its key costs nothing.
+
 For example, DeepSeek flash at `¥2` in and `¥8` out per million, with the
 published peak windows and `offPeakMultiplier: 0.5`, prices a 1M-in + 1M-out
 turn at `¥10.00` at peak and `¥5.00` off-peak. That example is worked end to end
-in [`footer/footer.test.ts`](./footer/footer.test.ts), which also prices the built-in
+in [`footer/footer.test.ts`](../../extensions/bytefly/footer/footer.test.ts), which also prices the built-in
 table with no config file at all.
 
-## Content and colors
+## The user-message nameplate
 
-| Segment | Line / zone | Color | Drops |
-|---|---|---|---|
-| pwd | 1 left | dim | last |
-| session | 1 left | muted, bracketed | after worktree |
-| browse | 1 right | success glyph + accent port | first |
-| branch | 1 right | muted (warning when detached) | last |
-| worktree | 1 right | success | first |
-| context gauge + `%` | 2 left | muted ≤70 · warning 71–90 · error >90 | never |
-| `/window` | 2 left | dim | before cost |
-| cost | 2 left | muted | after tokens |
-| tokens `↑in ↓out` | 2 left | dim | after cache |
-| cache `R… CH …%` | 2 left | dim | first |
-| statuses | 2 left | as emitted by each extension | before the model clips |
-| model | 2 right | accent | never |
-| thinking level | 2 right | thinking token | before cost |
+Every user message opens with a two-row `You` nameplate — the label over a rule
+that spans the width — above the message:
 
-The worktree status is read from the `worktree` status key, so the
-[worktree](../worktree/) extension and the bar agree. The browse chip is read
-from the `browse` status key published by [file-browse](../file-browse/) while
-its server runs, and shows the two-tone `◉ <port>` (green glyph, accent port).
-The trailing slot shows plan-style alerts when present and is omitted otherwise;
-a plan chip's trailing plan file name is dropped, so the slot reads `≡ plan`
-even though the built-in footer keeps the name. An alert (a failed job) sorts to
-the front of the slot. The slot trails the meters after a `│`, so the context
-gauge always starts the line. It keeps each extension's own colour when it
-compacts, and it is droppable: a tight bar drops the slot rather than truncating
-the model, which sits at the end of the line.
+```
+You
+────────────────────────────────────
+
+the message the user typed
+```
+
+It is always on in interactive sessions and has no config file. Pi renders a
+user message as Markdown and owns its colors, so bytefly's only lever is a
+`registerMarkdownTransformer`: the nameplate is a single level-2 heading whose
+text is padded so the rule wraps onto the second row, and both rows carry the
+accent because the themes point `mdHeading` at it. The block carries no fill —
+the shipped themes set `userMessageBg` to the terminal default, so it reads like
+the tool blocks. The nameplate is separated from the message by a blank line, so
+the message's own Markdown (a fence, a list, a second paragraph) parses exactly
+as it would without it, and a soft wrap of one long line stays at the margin
+because the renderer wraps it, not bytefly. The label and the rule are tuned
+in [`message/config.ts`](../../extensions/bytefly/message/config.ts).
 
 ## Turn separator
 
@@ -589,43 +525,258 @@ and outcome as the width allows.
   rule; disable the whole extension with `bytefly` instead.
 - There is no runtime command; the glyph, label prefix, padding, colors, and
   minimum duration are tuned in
-  [`separator/config.ts`](./separator/config.ts).
+  [`separator/config.ts`](../../extensions/bytefly/separator/config.ts).
+
+## Notices
+
+Any extension in the package can post a transcript notice under the shared
+`my-pi-agent/notice` type; bytefly draws it at the transcript's margin — a
+`source · title` headline at the margin, then rail-led rows, each with its own
+severity glyph:
+
+```
+job · 2 background jobs finished
+╎ ✓ j1 build · exit 0
+╎ ✕ j2 test · exit 1
+```
+
+The rail is painted by the notice's worst severity, so a failure reads red at the
+edge like an errored tool result, and the headline's title takes the notice's own
+severity — a warning reads yellow where its sentence is, while an `info` or `ok`
+notice stays body text. A row's label stays body text too: its severity is the
+glyph it hangs on, so one failing row never tints the rest of the list.
+
+`job` and `watch` post one when a background job finishes or a watched line
+matches, so the report the model reads is visible too. `doctor` posts one when a
+hard requirement is missing at session start, with a row per finding and the
+command that fixes it:
+
+```
+doctor · 1 missing prerequisite
+╎ ✕ worktree (git) · install git and make sure it is on PATH
+```
+
+Only a missing *hard* requirement posts a notice at session start; everything
+else waits in the report.
+
+The type and the `NoticeDetails` shape are the shared contract in
+[`lib/notice.ts`](../../lib/notice.ts), and the severity glyphs and item cap
+are tuned in [`notice/config.ts`](../../extensions/bytefly/notice/config.ts). Every field is sanitized
+and clipped at the boundary, and a message without `details` keeps Pi's default
+custom-message box.
+
+## Compaction
+
+`/compact` is Pi's own surface: its summary block is a built-in message
+component, so bytefly cannot replace, hide, or shorten it. The shipped themes
+only remove its fill — `customMessageBg` is the terminal default — and paint the
+`[compaction]` label in the accent, so the block sits on the canvas like the
+rest of the transcript. Pi's branch summaries and skill invocations share the
+same tokens.
+
+<img src="../../assets/screens/compaction.png" alt="The /compact summary block: a [compaction] label, the compacted token count, and the summary Markdown on the terminal canvas, with no background band" width="100%">
+
+## Tool blocks
+
+Every tool block leads with the tool's own call line as the headline — the tool
+name in the theme's tool-title colour — and its result body sits two columns in
+directly beneath it, led by the transcript rail, instead of Pi's filled status
+background:
+
+```
+read src/app.ts
+╎ const answer = 42;
+```
+
+The two tools that mutate a file, `edit` and `write`, carry their result on the
+call body — the edit diff, the written file content — so that body is railed
+like any other result. There is no status band: the diff's own red/green line
+colours, with the changed words in reverse video, and the `edit` / `write`
+headline are what mark a file change.
+
+A `registerToolRenderer` resolver switches the row to `renderShell: "self"`,
+leaves the call's own first line as the headline, and indents the rest of the
+call and the whole result under it. A shell call's `$` / `>` prompt becomes the
+tool name and the command is repainted in the body colour, and a primary subject
+(a path, URL, query, pattern) is demoted to the body colour too, so the name is
+the call line's only accent (`bash bun run check`, `read src/app.ts`). The
+tool's own
+`renderCall`/`renderResult` are passed through, so syntax highlighting, diffs,
+previews, and truncation notices are unchanged — only the frame is bytefly's.
+The body carries the transcript rail, painted by status (a running result takes
+the accent, a failure red, a finished one neutral) and drawn with the glyph from
+the `chrome.rail` setting. A result frame is always railed; a call frame is railed
+only for `edit` and `write`, whose call body carries the result — every other
+call's headline and continuation lines stay plain-indented. Package renderers
+clip a call to one physical line (middle clip for a path or URL), so it cannot
+leak into the body column; Pi's own renderers still wrap, and the frame keeps a
+wrapped continuation unrailed and loses the accent there too, with the rail
+beginning at the result underneath. A rejected call renders as one sanitized
+`error` line in the error role; a running tool shows a live elapsed label, and a
+finished long call appends its duration. A tool with
+no renderer of its own is framed around a generic call/result fallback, whose
+call line reads like a built-in — the leading string argument bare, the rest as
+trailing options (`open_path src/app.ts`) — rather than dumping raw `key=value`
+pairs. A tool that draws its own shell (`edit`) is framed too:
+`renderShell: "self"` only tells Pi not to draw its box around the renderer, so
+its diff would otherwise sit at the wrong indent; the frame drops the blank
+edges its own `Box` pads itself with, and hands it a theme whose `bg` is inert so
+it never paints a band the rest of the transcript does not have.
+
+The call line is one colour grammar, shared with Pi's built-ins: the tool name is
+`toolTitle` and bold and is the line's only accent; a primary subject (a query, a
+URL, a path, a status) reads in the body role (`label`), counts and summaries are
+`muted`, trailing options are `dim`, and the result body is `toolOutput`. The
+shipped themes point `toolTitle` at the accent and `label` at the body colour, so
+the name is the call line's one accent and the subject follows as body text; a
+theme that maps `toolTitle` elsewhere is respected rather than overridden.
+
+## The working line
+
+Pi's working row shows a static `Working`, so a long run reads the same as a
+short one. While the row is up, bytefly advances its message once a second and
+hands it back to Pi when the row comes down. Before the first tool starts it is
+a count:
+
+```
+Working… 12s
+```
+
+Once a top-level tool starts, the row becomes a live run line: the tool, how
+many top-level tools this run has started, and the elapsed time.
+
+```
+edit · 3 tools · 12s
+```
+
+A nested tool call (one carrying `parentToolCallId`, such as a codemode script's
+inner call) neither counts nor takes over the line, so the number matches the
+tool blocks in the transcript. The line keeps the last tool name while the
+model streams after it, and a tool event repaints the row immediately instead
+of waiting for the next tick. The line covers the whole run, tool calls
+included. It is tied to the row's visibility: it starts on `turn_start`, stops
+on `agent_end`, and is reset on `session_shutdown`; turns inside one run do not
+restart it, and a retry starts a new run. The words and the interval are tuned
+in [`working/config.ts`](../../extensions/bytefly/working/config.ts).
 
 ## The control center
 
-<img src="../../assets/bytefly.png" alt="The /bytefly control center: the Extensions, Skills, and Settings section bar with the `Global · 10 extensions · 2 off · 1 missing` counts, one checkbox row per extension with its verdict, the focused extension's report, and the key hints" width="100%">
+<img src="../../assets/screens/bytefly.png" alt="The /bytefly control center at 120 columns: a `Bytefly` rule with `1 missing` at its right edge, the `Extensions 9 · Skills 0 · Settings 12` tabs with `writes Global` at the right, one name-first row per extension with its checkbox and verdict, and the focused extension's block beside the list — its findings and their fix, Path, Source, State, and Health" width="100%">
 
 `/bytefly [extension] [refresh]` opens the control center on **Extensions**: a
-keyboard-driven dock list of every extension Pi resolves for the session, so the
-list matches what actually loads. `←`/`→` move to **Skills** and then
-**Settings**, one section per press and stopping at the ends, where the same
-frame lists every resolved skill and the curated preferences. `/bytefly skills`
-and `/bytefly settings` open their section directly. It merges the former
-extensions picker and doctor report into one row per extension: the picker's
-enable checkbox and label, then one verdict — `off` when the row is switched off
-in settings, `env disabled` when `PI_DISABLED_EXTENSIONS` excludes it, otherwise
-the doctor's worst-severity glyph and summary. The screen is drawn from the
-design system: a label-first `Bytefly ────` title rule,
-the `Extensions · Skills · Settings` section bar beside the section's counts, one
-row grammar (`❯ ◼ name … summary`), the shared `◼` / `◻` checkbox, and the closing
-rule under the key hints that Pi's own list screens draw.
-`/bytefly doctor [extension] [refresh]` selects the doctor report, the same text
-the `run_doctor` tool returns; in `tui` it opens the same screen. `[extension]`
-narrows the Extensions section to one extension and `refresh` forces the first
-probe. Tab completes the subcommands, extension names after `doctor`, and
-`refresh`; `/bytefly settings` and `/bytefly skills` take no name.
+keyboard-driven dock of every resource Pi resolves for the session, so the list
+matches what actually loads. `/bytefly skills` and `/bytefly settings` open the
+other two sections directly, and `←`/`→` (or `h`/`l`, or `Tab`) change section,
+wrapping at the ends because the tabs read as a ring. `/bytefly <extension>`
+narrows the list to one extension, and `refresh` forces the first probe. One
+frame draws all three sections.
 
 The screen opens on the findings the session already has, and the Extensions
 section probes once on its first view (the hint shows `refreshing…` while it
 runs). `/bytefly settings` therefore never waits for a probe, and a failed probe
 is a notice with the screen still open rather than a refused command. A refusal
-or a failed write appears in the screen's own hint row (the key hints step
-aside) and clears on the next key, so nothing is written behind the screen.
+or a failed write appears in the screen's own hint row — the key hints step
+aside — and clears on the next key, so nothing is written behind the screen.
 
 The screen reuses Pi's own settings and package resolution (`SettingsManager`
 plus `DefaultPackageManager` with `onMissing: "skip"`), so opening it never
 installs or fetches a package.
 
+**One frame.** The `Bytefly ────` header rule carries the screen's attention at
+its right edge — `1 missing` or `2 degraded` in the severity's own colour, else
+`2 off`, else `all clear`, with `unsaved changes` after it while a write is
+pending. The tab row below names every section with the rows it holds,
+`Extensions 9 · Skills 0 · Settings 12`, the active tab in the accent and the
+counts faint, then any filter chips (`/git`, `needs attention`, `changed only`),
+with `writes Global` (or `writes Project`) at the right edge. The scope is a word
+there because no count line has to carry it any more: the counts are on the tabs,
+the problems are in the header, and the scope is at the right.
+
+The body is padded to the tallest section's row count, group headings counted, so
+all three sections draw the same height and the dock does not resize when the
+tabs change. A shorter section pads its last rows with blanks; a longer one
+scrolls inside the same height and puts `showing 3–14 of 19` on its last body
+row. The height is measured from both resource lists and the visible scope's
+settings rows, so changing tab does not resize the dock: only a resize of the
+terminal moves the hint row, or the Project scope's one-line note on a terminal
+too short to hold both.
+
+**Two panes.** At 96 columns and wider the focused row's block sits in a side
+column after a `╎` divider: the row's name and verdict; the doctor's findings,
+under a `── findings ──` rule and each with its fix; `Path`, `Source`, and
+`State` for a resolved resource; `Health` when the row has a report; and
+`Saved · reload to apply` once something is pending. Below 96 columns the same
+block is drawn under the list in three rows, clipped, ending with
+`… N more lines` when it has more to say; it leaves out what the row above
+already says — the name and verdict on a resource row, the label and value on a
+settings row, and the path when there are findings to show instead.
+
+The picture above is 120 columns wide; the two frames below are the same screen
+at 100 and 80.
+
+```
+Bytefly ────────────────────────────────────────────────────────────────────────────────── 1 missing
+  Extensions 9 · Skills 0 · Settings 12                                                writes Global
+
+  npm:pkg (user) (9)                                    ╎   worktree 1 missing
+  ◼   file-read                                         ╎   ── findings ────────────────────────────
+  ◼   job                                               ╎   git: not found on PATH — worktree
+  ◼   memory                                            ╎   isolation
+  ◼   plan                                              ╎     → install git and make sure it is on
+  ◼   subagent                                          ╎     PATH (https://git-scm.com/downloads).
+  ◼   todo                                              ╎   symlink: the host cannot create symlinks
+  ◻ ∅ web-access  off                                   ╎     → copy the included files by hand.
+  ◻ ∅ wechat     off                                    ╎   Path       /pkg/extensions/worktree/ind…
+❯ ◼ ✕ worktree   1 missing                              ╎   Source     npm:pkg (user)
+  Not resolved (1)                                      ╎   State      enabled
+      bytefly    ok                                     ╎   Health     1 missing
+                                                        ╎
+                                                        ╎
+                                                        ╎
+                                                        ╎
+
+  Esc close · ←/→ section · Space toggle · Enter detail · / filter · ? keys · r refresh · s scope
+────────────────────────────────────────────────────────────────────────────────────────────────────
+```
+
+```
+Bytefly ────────────────────────────────────────────────────────────── 1 missing
+  Extensions 9 · Skills 0 · Settings 12                            writes Global
+
+  npm:pkg (user) (9)
+  ◼   file-read
+  ◼   job
+  ◼   memory
+  ◼   plan
+  ◼   subagent
+  ◼   todo
+  ◻ ∅ web-access  off
+  ◻ ∅ wechat     off
+❯ ◼ ✕ worktree   1 missing
+  Not resolved (1)
+      bytefly    ok
+
+  git: not found on PATH — worktree isolation
+    → install git and make sure it is on PATH (https://git-scm.com/downloads).
+… 2 more lines
+
+  Esc close · ←/→ section · Space toggle · Enter detail · / filter · ? keys
+────────────────────────────────────────────────────────────────────────────────
+```
+
+At 80 columns the block's three rows clip to the first finding and its fix and
+say how many lines are left out, and the hint row has already shed `r refresh`
+and `s scope` from its right edge.
+
+**Rows.** A row is named for the resource, not for its file: `worktree`, not
+`worktree/index.ts`. The picker's `folder/file.ts` label survives only where two
+resources share a directory name, because the two rows would otherwise read
+alike. What is left is one checkbox, one status glyph and one verdict word —
+`off`, `1 missing`, `2 degraded`, `env disabled`, `not loaded` for a skill Pi
+refused, `hidden` for one its frontmatter keeps from the model — and a clean row
+carries no glyph and no word at all, so the column reads as one shape and the eye
+finds the rows that need it.
+
 - Lists every resolved extension, grouped by source (each package, user
   settings, project settings), sorted packages-first and then by display name.
 - Omits `bytefly`'s own entrypoint from the picker groups, so the tool that
@@ -636,11 +787,10 @@ installs or fetches a package.
   glyph (`!` degraded, `✕` missing) and its summary. A row that is `◻` reads
   `off` instead, because it will not load; a row the session's
   `PI_DISABLED_EXTENSIONS` excludes reads `env disabled`, so the two axes cannot
-  contradict each other. The glyph marks what needs attention, so a row with
-  nothing to report — a clean report or none at all — leaves the glyph column
+  contradict each other. A row with nothing to report leaves the glyph column
   blank and says `ok` in words when a report exists.
 - Toggles the focused extension with `Space`, writing `+pattern` / `-pattern`
-  into `extensions` (and package filter objects) in the active scope. A row in
+  into `extensions` (and package filter objects) in the write scope. A row in
   the trailing `Not resolved` group has no pattern to write, so `Space` says so
   instead of doing nothing.
 - Clears the focused extension's project override with `x` in Project scope: the
@@ -649,30 +799,37 @@ installs or fetches a package.
   created), and the row returns to its inherited state. A row with no override
   says so instead of writing, and Global scope does not offer the key — the
   personal file is the base layer.
-- Switches the write scope with `Tab`: **Global** (personal `settings.json`) or
-  **Project** (`.pi/settings.json`, only when the project is trusted; an
-  untrusted project refuses with a notice).
 - Expands or collapses the focused extension's findings with `Enter` — per row,
-  so another row stays as it was — and grows the pane to the free terminal
-  height while expanded. Re-probes with `r`; while a probe is in flight the hint
-  shows `refreshing…` and a second `r` is ignored, so probes cannot stack.
+  so another row stays as it was — and gives the block the screen's whole body
+  height while it is open, so its findings are not clipped to three rows.
+- Re-probes with `r`; while a probe is in flight the hint shows `refreshing…` and
+  a second `r` is ignored, so probes cannot stack.
 - Checks an `<extension>` name against the discovered set before probing, so a
   typo fails immediately instead of waiting for every prerequisite check.
-- Offers a reload after pending changes, so the new selection takes effect
-  without leaving the session.
+- Reloads with `R`, so a new selection takes effect without leaving the session.
+
+**Filters.** `/` opens an editor seeded with the current query. The query applies
+as it is typed — a filter that only took effect on `Enter` would make the reader
+wait to see it work — and matches a row's name, path, and source (Settings: its
+label, description, and value). `Esc` clears it rather than leaving a hidden
+narrowing behind. `!` keeps only the rows worth acting on: a resource row that
+needs attention, or on Settings a value that differs from its default. The chips
+on the tab row say which is on, and an emptied section says
+`Nothing matches the filter.`
 
 **Skills.** The second section is the same list over Pi's skills: one row per
 skill, grouped by source and sorted by name, labelled with the name its
 `SKILL.md` declares (or the folder name when it declares none). `Space` writes
 `+pattern` / `-pattern` into `skills` — or a package's `skills` filter — in the
-active scope, and `Tab` and `x` behave as they do for extensions. A row's verdict
-comes from the skill's own file: `off` when it is disabled, `hidden` when
-frontmatter sets `disable-model-invocation` so only `/skill:<name>` loads it, and
-`not loaded` with Pi's reason when the file was refused. The detail pane carries
-the resolved path and the declared description, one line until `Enter` expands
-it. There is nothing to probe, so `r` is not offered here; the metadata is read
-once when the section first appears, so an edited `SKILL.md` shows on the next
-open.
+write scope, and `x` behaves as it does for extensions. A row's verdict comes
+from the skill's own file: `off` when it is disabled, `hidden` when frontmatter
+sets `disable-model-invocation` so only `/skill:<name>` loads it, and
+`not loaded` with Pi's reason when the file was refused. The block carries
+`Path`, `Call` (`/skill:<name>`), `Model` when the skill is hidden from the
+model, `Problem` when Pi refused the file, and the declared description — one
+line until `Enter` expands it. There is nothing to probe, so `r` is not offered
+here; the metadata is read once when the section first appears, so an edited
+`SKILL.md` shows on the next open.
 
 Themes and prompts have no section of their own, by decision rather than by
 omission: a theme is one active selection — a scalar, global setting — and a
@@ -680,53 +837,40 @@ prompt template is a file Pi discovers from a directory, so neither is a scoped
 enable list this screen's checkbox rows can write. Themes stay with `pi config`;
 `ROADMAP.md` carries the reason under *Deliberately left thin*.
 
-**Settings.** The third section uses the same frame and the same `Tab` scope
-switch, with its own cursor. It is the shortlist a session changes: thirteen
-preferences on one flat line each, the value beside its label, and no group
-headings. The whole list fits a 24-row terminal, and the frame stops growing
-there however tall the terminal is.
-
-```
-Bytefly ──────────────────────────────────────────────────────────────
-  Extensions · Skills · Settings                    Global · 13 settings
-
-❯ ◻ Bytefly startup TUI  Off
-  ◼ Theme  system
-  ◻ Desktop notifications  Off
-  ◼ Turn finished  On
-  ◼ Needs input  On
-  ◼ Job finished  On
-  ◼ Watcher matched  On
-  ◻ Wake when a job finishes  Off
-  ◼ Automatic snapshots  On
-  ◼ Proactive health check  On
-    Currency  CNY (¥)
-    Session budget  0
-
-  Bytefly startup TUI — Pi setting
-  Use bytefly's startup header in place of Pi's startup TUI.
-  Default · ~/.pi/agent/settings.json
-
-  Esc close · ←/→ · Space change · Tab scope · u reset · J JSON · ↑/↓ select
-──────────────────────────────────────────────────────────────────────
-```
-
-<img src="../../assets/bytefly-settings.png" alt="The /bytefly Settings section: one flat list of thirteen preferences with each value beside its label, the `Global · 13 settings` counts, and a three-row detail pane naming the focused row's source, description, and file" width="100%">
-
-| Row | Source | Values |
-|---|---|---|
-| Bytefly startup TUI | Pi `settings.json` (`quietStartup`) | Off, On |
-| Theme | Pi `settings.json` (`theme`) | `system`, `bytefly-dark`, `bytefly-light` |
-| Desktop notifications | `notify.enabled` | Off, On |
-| Turn finished | `notify.turnFinished` | Off, On |
-| Needs input | `notify.needsInput` | Off, On |
-| Job finished | `notify.jobFinished` | Off, On |
-| Watcher matched | `notify.matchFound` | Off, On |
-| Wake when a job finishes | `job.wakeOnFinish` | Off, On |
-| Automatic snapshots | `rewind.autoSnapshots` | Off, On |
-| Proactive health check | `doctor.proactive` | Off, On |
-| Currency | `price.currency.code` | CNY, USD |
-| Session budget | `price.budget` | Number, `0` = off |
+**Settings.** The third section is the same frame over the curated preferences,
+grouped by what they do rather than by which file holds them: `Startup (2)`,
+`Notifications (5)`, `Session (3)`, and `Price (2)`. It is the shortlist a
+session changes: twelve preferences, each with its value in one aligned column
+instead of beside its label, so a column of values can be read down. Sixteen
+entries — twelve rows and their four headings — fit a 24-row terminal when the
+block sits beside the list; on a narrower one the list scrolls and the block
+keeps its three rows. The frame never grows past the tallest section, however
+tall the terminal is. In Project scope the two app rows drop out and the note
+`App settings are Global only.` stands above the list.
+
+The block carries `Now` with the value, `About` with the preference's own
+description, and `Stored in <origin> · <file>` — `Global`, `Project`,
+`Inherited from Global`, or `Default`, with the file that supplied the value
+(`~/.pi/agent/settings.json` for an app row, the active scope's `bytefly.json`
+otherwise). `J` on a `bytefly.json` row appends that section as the active scope
+stores it, under a `── notify ──` rule.
+
+<img src="../../assets/screens/bytefly-settings.png" alt="The /bytefly Settings section at 120 columns: the `Startup (2)`, `Notifications (5)`, `Session (3)`, and `Price (2)` groups with each value in one aligned column, the `Extensions 9 · Skills 0 · Settings 12` tabs with `writes Global` at the right, and the focused row's block beside the list — its value, description, and the file the value is stored in" width="100%">
+
+| Group | Row | Source | Values |
+|---|---|---|---|
+| Startup | Startup screen | Pi `settings.json` (`quietStartup`) | Off, On |
+| Startup | Theme | Pi `settings.json` (`theme`) | `system`, `bytefly-dark`, `bytefly-light` |
+| Notifications | Desktop notifications | `notify.enabled` | Off, On |
+| Notifications | When a turn ends | `notify.turnFinished` | Off, On |
+| Notifications | When the agent needs you | `notify.needsInput` | Off, On |
+| Notifications | When a job ends | `notify.jobFinished` | Off, On |
+| Notifications | When a watcher matches | `notify.matchFound` | Off, On |
+| Session | Resume after a job | `job.wakeOnFinish` | Off, On |
+| Session | Snapshot before a turn | `rewind.autoSnapshots` | Off, On |
+| Session | Health check at startup | `doctor.proactive` | Off, On |
+| Price | Currency | `price.currency.code` | `CNY (¥)`, `USD ($)` |
+| Price | Session budget | `price.budget` | `Off`, or the amount as `¥5.00` |
 
 Choosing **Currency** also writes that currency's default precision
 (`price.currency.decimals`). Both stay editable in `bytefly.json` afterwards, so
@@ -743,44 +887,40 @@ and is replaced by the next choice here, so manage those in Pi's `/settings` →
 
 `Space` (or `Enter`) changes the focused row: a boolean toggles, an enum cycles
 forward, and the one text row — **Session budget** — opens an inline editor on its
-amount. `u` deletes the focused row's key so its default applies again (`Already
-at its default.` when nothing is stored in that scope; an inherited Project value
-says so instead), and `J` swaps the detail pane for the focused row's whole
-section as the active scope stores it — the only view of the keys this screen
-leaves to JSON. The detail pane names the source, describes the preference, and
-shows where the value comes from — `Global · ~/.pi/agent/bytefly.json`, `Project ·
-.pi/bytefly.json`, `Inherited from Global · ~/.pi/agent/bytefly.json`, or
-`Default · <the active scope's file>`; an app row names the personal
-`settings.json`. A successful change marks the screen `Saved · reload to apply`
-— even when the terminal is too short for the detail body — and closing offers
-the same reload confirm as an extension or skill toggle.
-
-The list is capped at thirteen rows so the screen keeps fitting a 24-row
-terminal: adding a setting means removing one (`panel/panel.test.ts` holds the
+amount. `u` deletes the focused row's key so its default applies again (`<row>
+is already at its default.` when nothing is stored in that scope; an inherited
+Project value says so instead, and an app row answers that Pi has no unset), and
+`J` appends the focused row's whole section as the active scope stores it — the
+only view of the keys this screen leaves to JSON. A successful change marks the
+block `Saved · reload to apply` and puts `unsaved changes` in the header, and
+closing offers the same reload confirm as an extension or skill toggle.
+
+The list is capped at twelve rows so the screen keeps fitting a 24-row
+terminal: adding a setting means removing one (`panel/settings.test.ts` holds the
 ceiling). Everything else stays in `bytefly.json` — the tuning numbers, the
 cosmetic labels, and the Pi preferences Pi's own `/settings` owns — and
 `test/settings-coverage.test.ts` keeps the split honest: every loader key is
-either a row or a declared JSON-only edit with the reason it left. Six
-`bytefly.json` sections therefore have no row at all (`chrome`, `goal`, `plan`,
-`watch`, `worktree`, `memory`), as do `notify.title`, `doctor.timeoutMs`,
+either a row or a declared JSON-only edit with the reason it left. Most
+`bytefly.json` sections therefore have no row at all — `chrome`, `goal`, `watch`,
+`worktree`, and `memory` among them — just as `notify.title`, `doctor.timeoutMs`,
 `price.currency.decimals`, `rewind.max`, `rewind.safetySnapshot`,
 `job.detachedByDefault`, and `watch.wakeOnMatch` inside sections that do. Each is
-documented in [`docs/configuration.md`](../../docs/configuration.md).
+documented in [`docs/configuration.md`](../configuration.md).
 
 Two of the five sections belong to other extensions (`rewind` and `job`). The
 screen cannot import their normalizers, so it reports the leaf as
 the file states it and declares the loader's default; the same test holds the
 catalogue to every loader's defaults and bounds in both directions.
 
-**Bytefly startup TUI** is the one row whose label differs from the Pi key it
-writes: On writes `"quietStartup": true` (bytefly's header replaces Pi's startup
-detail), and Off writes `false` (Pi's built-in header stays). A hand-set
-`"header"` reads Off, because it keeps Pi's header; the next toggle replaces it
-with `true` or `false`.
+**Startup screen** is the one row whose label differs from the Pi key it writes:
+On writes `"quietStartup": true` (bytefly's header replaces Pi's startup detail),
+and Off writes `false` (Pi's built-in header stays). A hand-set `"header"` reads
+Off, because it keeps Pi's header; the next toggle replaces it with `true` or
+`false`.
 
 App rows are **Global only**: Pi's setters for them write the personal
 `settings.json`, and only resource paths have public project setters. Project
-scope therefore lists the eleven `bytefly.json` rows and a
+scope therefore lists the ten `bytefly.json` rows and a
 `App settings are Global only.` note rather than promising a write that cannot
 happen. A `bytefly.json` row writes one leaf in the selected scope (a depth-1
 key, or a nested one such as `price.currency.code`) through a per-key writer, so
@@ -792,19 +932,19 @@ The non-`tui` form prints the headline and one `Label: Value` row per line, in
 screen order:
 
 ```
-bytefly: Settings · Global · 13 settings
-  Bytefly startup TUI: Off
+bytefly: Settings · Global · 12 settings
+  Startup screen: Off
   Theme: bytefly-dark
   Desktop notifications: On
-  Turn finished: On
-  Needs input: On
-  Job finished: On
-  Watcher matched: On
-  Wake when a job finishes: On
-  Automatic snapshots: On
-  Proactive health check: On
+  When a turn ends: On
+  When the agent needs you: On
+  When a job ends: On
+  When a watcher matches: On
+  Resume after a job: On
+  Snapshot before a turn: On
+  Health check at startup: On
   Currency: CNY (¥)
-  Session budget: 5
+  Session budget: ¥5.00
 ```
 
 The doctor side probes every declared extension and reports each check as `ok`,
@@ -837,27 +977,38 @@ headline; a named extension prints its full findings instead.
 
 ### Keys
 
+One table in [`panel/tui/keys.ts`](../../extensions/bytefly/panel/tui/keys.ts)
+drives the bindings, the hint row, and the `?` key list, so a key cannot drift
+from its hint or its help line. The hint row is per section and drops whole hints
+from the right as the width runs out, so `Esc` and the section keys survive on a
+narrow terminal; the Settings section's row is the shorter one.
+
 | Key | Effect |
 |---|---|
-| `←` / `→` | Show the previous or next section — Extensions, Skills, Settings; the ends stop. |
-| `Space` | Toggle the focused extension or skill; change the focused setting, or open the editor on a text row. |
-| `x` | Clear the focused resource's project override (Extensions and Skills, Project scope). |
-| `Enter` | Expand or collapse the focused extension's findings, or the focused skill's description; change the focused setting, or open the editor on a text row (Settings). |
+| `Esc` (`Ctrl+C`) | Close the screen. |
+| `←` / `→`, `h` / `l`, `Tab` / `Shift+Tab` | Previous or next section — Extensions, Skills, Settings — wrapping at the ends. |
+| `↑` / `↓`, `j` / `k` | Move to the previous or next row. |
+| `PgUp` / `PgDn` | Move a page. |
+| `Home` / `End`, `g` / `G` | Jump to the first or last row. |
+| `[` / `]` | Jump to the previous or next group; a group heading is never the focus. |
+| `Space` | Toggle the focused extension or skill; change the focused value (Settings). |
+| `Enter` | Expand or collapse the focused row's findings, or a skill's description; change the focused value, or open the editor on a text row (Settings). |
+| `/` | Filter the rows by text; the query applies as it is typed and `Esc` clears it. |
+| `!` | Show only the rows that need attention; on Settings, only values changed from their default. |
+| `s` | Switch where a change is written: Global or Project. |
+| `x` | Drop the focused resource's Project override, so Global applies again (Extensions and Skills, Project scope only). |
+| `r` | Re-probe every extension's requirements (Extensions only); a second `r` while one is in flight is ignored. |
+| `R` | Reload now, to apply what you changed; with nothing pending it says so instead. |
 | `u` | Delete the focused setting's key so its default applies again (Settings, `bytefly.json` rows). |
-| `J` | Show or hide the focused row's whole section as stored (Settings, `bytefly.json` rows). |
-| `[` / `]` | Jump to the previous or next group (Extensions and Skills). |
-| `←` / `→`, `Home` / `End` (`Ctrl+A` / `Ctrl+E`) | Move the editor's caret while a text row is being edited. |
+| `J` | Show or hide the focused row's whole `bytefly.json` section as stored (Settings). |
+| `?` | Show the key list in the focused row's block; `?` again hides it. |
+| `←` / `→`, `Home` / `End` (`Ctrl+A` / `Ctrl+E`) | Move the editor's caret while a text row or the filter is being edited. |
 | `Backspace` / `Delete`, `Ctrl+U` | Edit the buffer: delete a character, or clear it. |
 | `Enter` / `Esc` (editing) | Save the buffer, or cancel and restore the stored value. |
-| `Tab` | Switch between Global and Project scope, in any section. |
-| `r` | Re-probe the doctor (Extensions). |
-| `↑`/`↓`, `j`/`k` | Move the selection, in any section. |
-| `PgUp`/`PgDn` | Move a page, in any section. |
-| `g` / `G`, `Home` / `End` | Jump to the first or last row, in any section. |
-| `Esc` / `Ctrl+C` | Close the screen. |
 
-Mouse wheel scrolling and clicking a row to focus it work; every action also
-has a keyboard path.
+`Esc` clears an open filter or editor before it closes the screen, so nothing
+typed is left narrowing the list or half-written. Mouse wheel scrolling and
+clicking a row to focus it work; every action also has a keyboard path.
 
 ### What is checked
 
@@ -884,10 +1035,10 @@ the same entry in `lib/requirements.ts`, so the two cannot drift.
 
 ## Notifications
 
-The notify capability exists for unattended runs: start a long turn, leave the
-terminal, and get a desktop notification when Pi needs you — or when it is done.
-It fires on four events, each independently switchable in the `notify` section
-of `bytefly.json` (see [Configuration](#configuration)):
+The notify capability is off by default and exists for unattended runs: start a
+long turn, leave the terminal, and get a desktop notification when Pi needs you
+— or when it is done. It fires on four events, each independently switchable in
+the `notify` section of `bytefly.json` (see [Configuration](#configuration)):
 
 - **A run settled** (`agent_settled`). Pi finished the turn and waits for the
   next message. An aborted run is skipped: interrupting with Escape means the
@@ -896,10 +1047,10 @@ of `bytefly.json` (see [Configuration](#configuration)):
   `ask_user_question`, a plan review, a subagent approval. A prompt opened while
   idle is a command the user just typed, so it does not fire; the run boundary
   is what separates "the agent is asking" from "the user is asking".
-- **A background job finished.** The [job](../job/) extension announces each
+- **A background job finished.** The [job](./job.md) extension announces each
   terminal transition on the shared `pi.events` bus
   (`my-pi-agent/job-finished`); bytefly listens and never imports it.
-- **A watcher matched.** A [watch](../watch/) whose `wake` is on matched, and
+- **A watcher matched.** A [watch](./watch.md) whose `wake` is on matched, and
   announced it on `my-pi-agent/watch-match` with the cycle's
   count, the watcher, and its newest line. The body names that line, sanitized and
   clipped to 80 characters, because the line is the alert: a watch usually tails a
@@ -1018,17 +1169,27 @@ release without a restart. Opening the control center never checks: the screen h
 no update surface, and the only request paths are `session_start` and this
 command.
 
+`/bytefly upgrade` is the half that writes. It asks for a confirmation and then
+calls the package manager's own `update()`: the same manager that reads the
+packages configured in `settings.json`, owns the install root, and honours a
+project's `npmCommand`, so no shell and no `pi update` command is involved. Pi
+skips a pinned npm version, and `PI_OFFLINE` skips the whole path. The manager
+returns nothing, so the answer is a re-read of what is left: `every configured
+package is updated — reload to use the new version`, or a warning when a package
+is still behind after a successful run; a failed install prints the manager's own
+message. The running session keeps the old code loaded until it reloads, which is
+why the line says so, and each source the manager reports is shown while it runs.
+
 ## Limitations
 
-- **Bytefly startup TUI is the startup surface only.** It installs or removes
+- **The Startup screen row is the startup surface only.** It installs or removes
   bytefly's startup header and the proactive doctor notice; the footer, turn
   rule, and transcript renderers stay on. Use `PI_DISABLED_EXTENSIONS=bytefly`
   (or `pi config`) to turn off all of bytefly.
-- **App settings are Global only.** Pi's setters for preferences such as
-  `quietStartup` (the **Bytefly startup TUI** row), `outputPad`,
-  `showHardwareCursor`, and `theme` write the personal `settings.json`; the
-  screen hides those rows in Project scope rather than writing a file Pi cannot
-  manage.
+- **App settings are Global only.** Pi's setters for the two app preferences
+  the screen carries — `quietStartup` (the **Startup screen** row) and
+  `theme` — write the personal `settings.json`; the screen hides those rows in
+  Project scope rather than writing a file Pi cannot manage.
 - **The Theme row offers only this package's palettes.** `system`,
   `bytefly-dark`, and `bytefly-light` are the whole cycle; Pi's built-ins and any
   user, project, or other package's theme stay in Pi's `/settings` → **Theme**,
@@ -1041,7 +1202,7 @@ command.
 - **The list is a shortlist, not the whole document.** A row is one boolean,
   enum, string, or number; the tuning numbers, the labels, and the Pi
   preferences `/settings` owns stay in their files, and the catalogue is capped
-  at thirteen rows so the screen fits a 24-row terminal. `doctor.skip` (an
+  at twelve rows so the screen fits a 24-row terminal. `doctor.skip` (an
   array), the `rates` table, and `price.peak` (a nested object) could never be a
   row; the rest are declared JSON-only with their reason in
   `test/settings-coverage.test.ts`.
@@ -1049,16 +1210,18 @@ command.
   because a two-column glyph would push every railed body one cell right; the
   loader drops anything else, and the former four-glyph menu is the
   configuration reference's example list.
-- **`doctor`, `settings`, `skills`, and `update` are reserved first arguments.**
-  `/bytefly doctor` always selects the report, so an extension literally named
-  `doctor` cannot be narrowed to by name; `settings`, `skills`, and `update` are
-  reserved the same way.
+- **`doctor`, `settings`, `skills`, `update`, and `upgrade` are reserved first
+  arguments.** `/bytefly doctor` always selects the report, so an extension
+  literally named `doctor` cannot be narrowed to by name; `settings`, `skills`,
+  `update`, and `upgrade` are reserved the same way.
 - **The picker manages the `extensions` and `skills` resource types.** Prompts
   and themes stay with Pi's own `pi config`.
 - **Built-in extensions are not listed** (`builtin:mcp`, `builtin:codemode`, …):
   their authoritative names are not exposed to extensions. Use `pi config`.
-- **Packages are not installed, removed, or updated here**; use `pi install`,
-  `pi remove`, and `pi update`.
+- **Nothing is installed or removed here.** `/bytefly upgrade` runs Pi's own
+  update for the packages configured in `settings.json`; adding a package is
+  still `pi install`, removing one is `pi remove`, and Pi itself is still
+  `pi update`.
 - **The update list is Pi's.** Only packages configured in `settings.json` are
   checked; `pi -e .`, a temporary checkout, and other unmanaged loads get no
   update prompt. The version arrow and release URL still come from npm's
@@ -1077,7 +1240,9 @@ command.
   restores both on shutdown. A future Pi that changes either method shape makes
   that shim inert, and Pi's own block can come back.
 - **No auto-update, and the release URL is text only.** The notice names a
-  command instead of running one, and the notice renderer cannot open a link, so
+  command instead of running one; the only path that writes is `/bytefly
+  upgrade`, and it waits for a confirmation. The notice renderer cannot open a
+  link, so
   the release row prints the URL and nothing more — no changelog body, no way to
   click through from the transcript. Pi's optional release note arrives as one
   sanitized `release notes` row, so a multi-paragraph note is flattened and
@@ -1097,10 +1262,11 @@ command.
   Anthropic's 2× one-hour cache write are not modelled; switch to `USD` mode
   to use Pi's recorded cost for those models.
 - **No FX conversion.** The two modes are separate methods; neither converts
-  one currency into the other. A model is priced only by the selected method. A
-  `CNY` session names the records it could not price instead of silently leaving
-  them out — switch to `USD` for Pi's per-model cost, or add yuan `price.rates`
-  entries for the models you use.
+  one currency into the other. A model is priced only by the selected method, and
+  a model neither method can price is named — by key, in the footer, in
+  `/bytefly prices`, and in one notice — instead of being quietly left out. What
+  is *not* built is a table for another provider: rates are sourced data, and
+  `price.rates` is where they go.
 - **Two built-in footer indicators cannot be reproduced.** Pi's `(auto)` marks
   that auto-compaction is on, and its `(sub)` marks a subscription-backed
   provider. Auto-compaction is session state on Pi's own session object, and
@@ -1147,7 +1313,7 @@ command.
   `bytefly.json`.
 - No per-model cost breakdown and no on-screen marker for which tariff or
   which source produced a number.
-- No todo-count segment; the [todo](../todo/) widget already shows progress.
+- No todo-count segment; the [todo](./todo.md) widget already shows progress.
 - No shelling out for git ahead/behind; the footer data provider exposes only
   the branch.
 - No session or model data in the header: it shows the nameplate and the grouped
@@ -1176,7 +1342,7 @@ rather than showing a wrong value.
 
 | Integration point | Details |
 |---|---|
-| Header | `ctx.ui.setHeader` with a custom component, replacing Pi's built-in header; installed only when `ctx.mode === "tui"` and `pi.getSettings().quietStartup === true` (the **Bytefly startup TUI** row). `false`, `"header"`, and unset call `setHeader(undefined)`, leaving Pi's built-in header in place. The nameplate insets by Pi's `outputPad` (read through `pi.getSettings()`), so it sits on the transcript margin, and the help hangs one body indent inside it. The mark and text are drawn from the active theme's tokens, the help keys resolve live through `keyText`, and the mark falls back to a wordmark on Apple Terminal (`isAppleTerminalSession`), mirroring Pi's built-in. The factory reads `tui.terminal.rows` on every render, so the height ladder in `header/config.ts` sheds help groups and then the leading blank row as the terminal shortens (unknown height keeps the full header). The chrome version gains `↑<latest>` from the `UpdateSource`, the agent line gains Pi's own `↑<latest>` from the second store, and `registerHeader` returns a `refresh()` handle that re-installs the last context's header when either value arrives. |
+| Header | `ctx.ui.setHeader` with a custom component, replacing Pi's built-in header; installed only when `ctx.mode === "tui"` and `pi.getSettings().quietStartup === true` (the **Startup screen** row). `false`, `"header"`, and unset call `setHeader(undefined)`, leaving Pi's built-in header in place. The nameplate insets by Pi's `outputPad` (read through `pi.getSettings()`), so it sits on the transcript margin, and the help hangs one body indent inside it. The mark and text are drawn from the active theme's tokens, the help keys resolve live through `keyText`, and the mark falls back to a wordmark on Apple Terminal (`isAppleTerminalSession`), mirroring Pi's built-in. The factory reads `tui.terminal.rows` on every render, so the height ladder in `header/config.ts` sheds help groups and then the leading blank row as the terminal shortens (unknown height keeps the full header). The chrome version gains `↑<latest>` from the `UpdateSource`, the agent line gains Pi's own `↑<latest>` from the second store, and `registerHeader` returns a `refresh()` handle that re-installs the last context's header when either value arrives. |
 | Footer | `ctx.ui.setFooter` with a custom component, replacing Pi's built-in footer; installed only when `ctx.mode === "tui"`. |
 | User message | `pi.registerMarkdownTransformer` puts a two-row `You` nameplate (the label over a full-width rule) above each user message; one padded level-2 heading carries the accent through `mdHeading` for both rows, and the shipped themes set `userMessageBg` to the terminal default, so the block has no fill. Pi renders the result as Markdown, so the surface adds no component or color of its own. |
 | Notice | `registerMessageRenderer(NOTICE_TYPE)` draws every shared transcript notice at the margin from its `details`; the headline stays at the margin with its title painted by the notice's own severity, and its rows hang from the transcript rail, painted by the notice's worst severity, whose glyph comes from the shared `RailSource`. `job` and `watch` post one when their work settles, and `doctor` posts one at `session_start` for a missing hard requirement. The type and shape come from `lib/notice.ts`. A message without `details` falls back to Pi's default custom-message box. |
@@ -1187,12 +1353,12 @@ rather than showing a wrong value.
 | Notifications | `agent_settled` (skipped when aborted), `ui_prompt_start` only while `agent_start`…`agent_settled` marks a run active, and `my-pi-agent/job-finished` on `pi.events`; the `notify` section of `bytefly.json` gates each. Delivery writes an OSC 777/99 sequence to stdout or spawns `osascript`, `notify-send`, or `powershell.exe`. The bus subscription is created in `session_start` and released in `session_shutdown`, and the `job` extension never imports bytefly. |
 | Picker discovery | `SettingsManager.create(...)` plus `DefaultPackageManager.resolve({ onMissing: "skip" })`, both public exports; both views drop `bytefly`'s own entrypoint. |
 | Picker writes | `SettingsManager` setters (`setExtensionPaths`, `setPackages`, `setProjectExtensionPaths`, `setProjectPackages`) then `flush()`; `ctx.reload()` after the screen closes when changes are pending. |
-| Settings writes | App rows call `SettingsManager` setters (`setQuietStartup`, `setOutputPad`, `setShowHardwareCursor`, `setTheme`) on the global store and `flush()`, then surface `drainErrors()`; `bytefly.json` rows call `writeConfigValuesAt` on the selected scope's document with the row's leaf path, so a nested key (`price.currency.decimals`) and a flat one (`notify.method`) share one writer, and a row that also writes a companion leaf (the currency and its default precision) applies both in one document pass; and `u` calls `unsetConfigValueAt` with the same path. A failed or refused write shows a notice in the screen's hint row and leaves the displayed value unchanged; a successful one marks the screen dirty. |
+| Settings writes | App rows call `SettingsManager` setters (`setQuietStartup`, `setTheme`) on the global store and `flush()`, then surface `drainErrors()`; `bytefly.json` rows call `writeConfigValuesAt` on the selected scope's document with the row's leaf path, so a nested key (`price.currency.decimals`) and a flat one (`notify.method`) share one writer, and a row that also writes a companion leaf (the currency and its default precision) applies both in one document pass; and `u` calls `unsetConfigValueAt` with the same path. A failed or refused write shows a notice in the screen's hint row and leaves the displayed value unchanged; a successful one marks the screen dirty. |
 | Doctor tool | `pi.registerTool("run_doctor")`, read-only (`readOnlyHint: true`, `openWorldHint: false`), direct exposure and active on registration (the defaults, so not declared), with a typed `outputSchema` mirroring `structuredContent`. Its `readOnlyHint` is what the shared default-deny policy in `lib/policy.ts` reads to allow it in plan mode. |
 | Doctor probes | `run_doctor` and the screen share the session cache created by `registerDoctor`; the screen mounts on that cache and probes on the first Extensions view (the command's `refresh` forces it), while the text modes probe before printing, and `/bytefly refresh` and `refresh: true` re-probe. Probes spawn `<binary> --version`, lazily import optional packages, and read config files through `lib/requirements.ts`; nothing is ever written. |
 | Status routing | Reads `footerData.getExtensionStatuses()` (a custom footer replaces the built-in one entirely); `worktree` routes to line 1, plan/alert statuses to line 2's trailing slot. |
 | Release notice | `session_start` in `tui` mode patches `InteractiveMode.prototype.showNewVersionNotification` through the shared `patchPrototypeMethod`, so the release Pi resolved becomes `pi.sendMessage(piReleaseNotice(...))` under the shared notice type and `paintLatest` records its version for the agent line's marker (`onUpdate` re-installs the header). The callback posts once per load and only while the session is live; a throw calls the captured original, so Pi's own box is the fallback. `session_shutdown` restores the method and clears the marker. |
-| Update check | `session_start` in `tui` mode installs a suppression on `DefaultPackageManager.prototype.checkForAvailableUpdates`, then reads `<agentDir>/bytefly/update.json`. A fresh entry whose key matches the cwd and effective package sources is recorded without a package-manager call; otherwise bytefly fires `fetchAvailableUpdates()` without awaiting, resolves this package's version through `fetchLatestVersion()` when Pi reports it, writes the snapshot, and records it. `onUpdate` re-installs the header, and `pi.sendMessage(updateNotice(...))` posts the one notice with its version arrow and release URL. `PI_OFFLINE` paints the cached marker only. `/bytefly update` calls the returned `UpdateHandle.recheck()`, which bypasses the window and returns an `UpdateOutcome`; a generation counter drops a background reply that lands after `session_shutdown`, a per-load flag keeps it to one announcement, and shutdown restores Pi's method. |
+| Update check | `session_start` in `tui` mode installs a suppression on `DefaultPackageManager.prototype.checkForAvailableUpdates`, then reads `<agentDir>/bytefly/update.json`. A fresh entry whose key matches the cwd and effective package sources is recorded without a package-manager call; otherwise bytefly fires `fetchAvailableUpdates()` without awaiting, resolves this package's version through `fetchLatestVersion()` when Pi reports it, writes the snapshot, and records it. `onUpdate` re-installs the header, and `pi.sendMessage(updateNotice(...))` posts the one notice with its version arrow and release URL. `PI_OFFLINE` paints the cached marker only. `/bytefly update` calls the returned `UpdateHandle.recheck()`, which bypasses the window and returns an `UpdateOutcome`; `/bytefly upgrade` calls `UpdateHandle.apply()`, which runs `applyUpdates()` — Pi's `DefaultPackageManager.update()`, with its progress passed to `ctx.ui.notify` — and then re-reads the snapshot so the marker cannot outlive the version it named. A generation counter drops a background reply that lands after `session_shutdown`, a per-load flag keeps it to one announcement, and shutdown restores Pi's method. |
 | Config | `bytefly.json` from the agent directory and `<cwd>/.pi`; the `price` section is read once per footer install (a new session or a session-tree change), the `notify` and `doctor` sections at `session_start`, and the `chrome` section's rail glyph at `session_start`/`session_tree`. Nothing watches the document. The update check has no section: it is on whenever `PI_OFFLINE` is off, and its 24 h window is not configurable. |
 | Data sources | `footerData.getGitBranch()`, `footerData.getAvailableProviderCount()`, `ctx.getContextUsage()`, `ctx.sessionManager.getEntries()`, `ctx.sessionManager.getSessionName()`, `ctx.model`; subscribes to `footerData.onBranchChange` to repaint. |
 | State storage | None besides the inert separator entries. The footer reads session entries and the price config (a memoized scan) and writes no tool-result `details`; it appends `bytefly-separator` entries excluded from LLM context. The screen derives its view from the picker runtime, the current reports, and the skill index, and persists extension and skill toggles through `settings.json`. The Settings section derives from a snapshot of the personal `settings.json` and both `bytefly.json` documents, and persists through the same `SettingsManager` setters or the per-leaf `bytefly.json` writer. Doctor's findings are session-scoped in memory only — cached for the session, never written to the session or a file. Notify holds only the config and the run-active flag in its closure. The update check holds this package's version in the per-load `UpdateSource` and one project-scoped snapshot in `<agentDir>/bytefly/update.json`. |
@@ -1276,9 +1442,9 @@ rather than showing a wrong value.
   entry renderer none and adds its component raw, so bytefly's blocks inset
   themselves by that pad: the tool frame and the notice take it from Pi, and the
   turn separator reads the last value a sibling observed (`pad.ts`). Pi's setting
-  is the only knob — bytefly adds no padding of its own. The footer's group
-  separator draws `│` between chips — a divider, not the rail (`╎`), which stays
-  a transcript-only glyph.
+  is the only knob — bytefly adds no padding of its own. The footer draws no
+  rule of its own: it joins its chips with the shared ` · `, and the rail (`╎`)
+  stays a transcript-only glyph.
 - **The header is a nameplate, not a dashboard.** Pi's built-in brand colors are
   fixed, so the mark ignores the active theme; bytefly's header draws a two-tone
   mark from the `accent`/`warn` roles, a signature rule whose accent lead sits
@@ -1290,24 +1456,41 @@ rather than showing a wrong value.
   terminal: the height ladder drops whole help groups, then the leading blank
   row, before the nameplate gives up anything, so a short pane spends its rows
   on the transcript instead of chrome.
-- **Two lines, four zones.** Line 1 is identity (`pwd` left, branch + worktree
-  right); line 2 is resources (meters left, model + level right). This keeps
-  "where am I / what state" separate from "how much am I burning".
+- **Two lines, one job each: state and meters.** Line 1 is state (`pwd` and the
+  session name left; the alert, the modes, then `⎇` branch, `⑂` worktree and the
+  ports right); line 2 is meters (the gauge and usage left; model and level
+  right). The state chips change while a session runs, so they ride the line that
+  has slack: the meters are the dense row, and a fact that moves to the top row is
+  one the bottom row stops dropping to fit. It keeps "where am I / what state"
+  separate from "how much am I burning".
 - **Child spend is a second figure.** The footer never adds a subagent's tokens to
   the session's; it prices the `my-pi-agent/subagent-finished` events with the
   same pricer and renders them as `↳`, so "this session" keeps meaning the
   dispatching process and the delegated work stays visible beside it.
-- **The gauge is anchored at column 0.** A leading mode slot would shift the
-  context percentage left and right as plan mode came and went; trailing it
-  after a `│` keeps the percentage in a fixed place while the mode stays
-  visible as the meters drop.
+- **The gauge is anchored at column 0, and nothing can displace it.** A leading
+  mode slot used to push the context percentage left and right as plan mode came
+  and went, which is why the mode chip trailed the meters after a `│`; moving the
+  mode slot to the state line leaves the gauge as the resource line's first
+  segment, so the percentage cannot move at all.
 - **Statuses are routed, not repeated.** The built-in footer renders every
   `setStatus` value on its own line, so the bar sorts them by meaning instead:
-  `worktree` and `browse` are location, so the `◉ <port>` chip sits beside `⎇`
-  branch and `⑂` worktree and the left zone stays the filesystem identity; a
-  plan or a failed job is mode or alert, so it takes the slot after the gauge.
-  The [wechat](../wechat/) extension publishes `✆ wechat` while its bridge runs,
+  `worktree` and `browse` are location, so the `◉ <port>` chip sits behind `⎇`
+  branch and `⑂` worktree; the `board` key is location too, and the two ports
+  are one segment because they are one fact, so they share a weight and a floor;
+  a plan is a mode, so it leads the state line beside them; a failed job is an
+  alert, so it is its own segment ahead of both. The
+  [wechat](./wechat.md) extension publishes `✆ wechat` while its bridge runs,
   which is why the bar has to render `getExtensionStatuses()` at all.
+- **A state chip leads its zone, so the zone does not move under it.** The right
+  zone is right-aligned: a chip appended to it would push the branch and the
+  worktree label left every time a mode came and went, while a chip prepended to
+  it grows into the empty columns. That is the same stability argument the gauge
+  gets from sitting at column 0, applied to the row that changes.
+- **A failure is never the thing that drops.** The alert segment is the one
+  non-droppable chip: every other fact can be read again — the branch from git,
+  the mode from the session, the spend from `/bytefly prices` — while a failed
+  job that scrolled off the bar is a failure nobody is looking at. It keeps its
+  count (`✗1`) when it compacts.
 - **Segments degrade; they do not clip.** Each `Segment` carries progressively
   shorter `forms` and a `weight`; the layout advances the lowest-priority form
   or drops the lowest-priority segment, and only truncates once everything is
@@ -1317,15 +1500,23 @@ rather than showing a wrong value.
   non-zero usage, so it reads full only at 100% and a small percentage never
   disappears; unknown usage draws no gauge at all. Only at extreme widths does
   `truncateToWidth` clip the remaining text.
-- **Separators shrink to a single space.** Padded separators (` · `, ` │ `)
-  collapse to one space before `truncateToWidth` applies, so adjacent segments
-  never collide and the ellipsis never replaces a `│` with nothing after it.
+- **Separators shrink to a single space.** Every segment is joined by the same
+  padded ` · `, which collapses to one space before `truncateToWidth` applies, so
+  adjacent segments never collide and the ellipsis never replaces a separator
+  with nothing after it.
 - **Statuses compact with their colour.** A themed status's compact icon form
   reattaches its opening and closing SGR sequences around the visible text, so a
   red `✗1` stays red instead of losing its colour exactly when the bar tightens.
   A two-token `icon count` badge (for `rewind`: `↺ 2`) compacts to `↺2`, keeping
-  the count. The slot sorts an alert (a failed job) ahead of the modes and is
-  droppable, so it goes before the model is clipped.
+  the count. A mode is droppable, so it goes before the branch and long before
+  the model is clipped; only an alert is not.
+- **A budget is a position, not a second figure.** With `price.budget` set, the
+  cost segment reads `$0.31/$5` and turns `warn` once the spend reaches the
+  ceiling, which is the same `budgetState` condition the notice fires on, so the
+  bar cannot call a session over budget that the notice has not. The ceiling is
+  formatted by its own `formatLimit` — the number the user typed, with trailing
+  zeros dropped — while the spend keeps the currency's precision; both the bar
+  and the notice use it, so the two cannot disagree about one figure.
 - **Neutral by default; color means something.** A tool block carries no status
   colour except the accent tool name and the status-coloured result rail; an
   informational notice leads with `muted`; a failure is red only where the
@@ -1468,7 +1659,7 @@ columns, gauge), so the look follows the active theme.
 | `header/identity.ts` | `IdentityInput` and `identityCells`: the agent and chrome cells, each with its `↑` marker, in the ladder that sheds the chrome marker, the chrome version, the chrome line, and finally the agent's marker with the row. |
 | `header/register.ts` | Installs/restores the header and owns its session lifecycle. |
 | `footer/register.ts` | Installs/restores the footer and owns its session lifecycle. |
-| `footer/config.ts` | Bar tuning (`CONFIG`): thresholds, gauge, separators, icons, status keys, labels. |
+| `footer/config.ts` | Bar tuning (`CONFIG`): thresholds, gauge, separators, icons, alert and plan status keys, labels. |
 | `footer/types.ts` | `StatusSnapshot`, `Segment`, `LineSpec`, `UsageRecord`, and footer/TUI shapes. |
 | `footer/collect/entries.ts` | Session entries → usage records, each resolved to the model in effect. |
 | `footer/collect/snapshot.ts` | Snapshot assembly; memoized pricing scan, context estimate, and session name per branch leaf. |
@@ -1477,7 +1668,7 @@ columns, gauge), so the look follows the active theme.
 | `footer/price/rates.ts` | Model-key matching: `createRateLookup` splits every key once, splits a key at its first slash (so an OpenRouter model id may contain one), matches exact and wildcard most-specific-first, and remembers the last record's model. |
 | `footer/price/schedule.ts` | Peak-window parsing and evaluation in a configured zone. |
 | `footer/price/price.ts` | Records → totals: rated cost in both modes, Pi's recorded cost as USD's fallback, the peak multiplier, and the count of records CNY could not rate. |
-| `footer/unpriced.ts` | The one notice a CNY session posts for records it could not price, and its OS-notification body. |
+| `footer/unpriced.ts` | The one notice a session posts for records nothing could price: the models by key, the count that the two agree on (`recordsText`), and its OS-notification body. |
 | `footer/render/format.ts` | Generic formatters (tokens, cost in the configured currency, cwd, the context role, truncation). |
 | `footer/render/status.ts` | Status-chip transforms: `compactStatus` and `dropStatusDetail`. |
 | `footer/render/segments.ts` | The segment builders: forms, weights, separators, roles. |
@@ -1502,22 +1693,26 @@ columns, gauge), so the look follows the active theme.
 | `working/config.ts` | Counter tuning (`WORKING_CONFIG`): the words, the tool singular/plural, and the tick interval. |
 | `working/format.ts` | Pure `formatElapsed` (whole seconds) and the working-message shape: the plain count and the `tool · N tools · elapsed` run line. |
 | `working/register.ts` | Starts the tick on `turn_start`, tracks top-level tools on `tool_execution_start`, and cancels on `agent_end`/`session_shutdown`. |
-| `panel/types.ts` | `PanelSection` (`extensions` | `skills` | `settings`), `PanelRow` with its optional skill info, `SkillInfo`, and `PanelModel`, the merged row model. |
-| `panel/join.ts` | The item/report union with the unambiguous-name health rule and unique row keys, groups, and ordering; the skills model that labels rows from `SKILL.md`. |
-| `panel/format.ts` | Non-TUI text: the resource headline and grouped listing with a per-row verdict, the section segments and their order, the Settings counts/headline, and the flat Settings listing. |
-| `panel/settings.ts` | The curated Settings catalogue: the thirteen descriptors in screen order, snapshot views and origins, value cycling, stored-value mapping, validation, plus the per-section readers that resolve a row's leaf over the global and project documents. |
+| `panel/types.ts` | `PanelSection` (`extensions` \| `skills` \| `settings`), `PanelRow` with its optional skill info, `SkillInfo`, and `PanelModel`, the merged row model. |
+| `panel/join.ts` | The item/report union with the unambiguous-name naming rule — a row is `worktree`, and a directory claims a report only when one resource uses that name — plus unique row keys, groups, ordering, and the skills model that labels rows from `SKILL.md`. |
+| `panel/filter.ts` | The two filters as predicates and chips: a text query over a row's name, path, and source, the attention switch, and what the tab row says is on. |
+| `panel/format.ts` | Non-TUI text: the resource headline and grouped listing with a per-row verdict, the header's attention segments, the one `rowBadge` the screen and the listing share, the section segments and their order, the Settings counts/headline, and the flat Settings listing. |
+| `panel/settings.ts` | The curated Settings catalogue: the twelve descriptors in screen order, their four groups, the value labels (`Off`, `¥5.00`) and display origins, value cycling, stored-value mapping, validation, plus the per-section readers that resolve a row's leaf over the global and project documents. |
 | `panel/settings-runtime.ts` | The Settings runtime: snapshot cache, scope guards, app setters, per-leaf `bytefly.json` writes, dirty state, and change listeners. |
 | `panel/themes.ts` | Which themes the Theme row offers: the host's resolved list narrowed to the palettes under this package's `themes/`, identified by directory rather than name. |
+| `panel/prices.ts` | The `/bytefly prices` report: the unpriced models by key, the records behind each, and the one line saying where the keys go. It quotes no price — a rate is the user's to state. |
 | `panel/skills.ts` | Skill metadata through Pi's own `loadSkills`, keyed by resolved path, plus the deduplicated paths both discovery views read. |
-| `panel/tui.ts` | `PanelComponent`, the three-section dock screen: the section switch, the cursors, the toggle chain, and the two list sections through one `LIST_VIEWS` table. |
-| `panel/tui/list-view.ts` | The shared list grammar: the section headline, one resource row, and the key-hint row both sections offer. |
-| `panel/tui/extensions-view.ts` | The Extensions detail pane: the doctor's findings, including the resource path when a row has no verdict. |
-| `panel/tui/skills-view.ts` | The Skills detail pane: the path, the description, and Pi's refusal. |
-| `panel/tui/settings-view.ts` | The Settings rows, the value's source and description pane, the JSON pane, and the editing cell. |
+| `panel/tui.ts` | `PanelComponent`: the section switch, the three cursors and focus keys, the filter and help state, the toggle chain, and the one render that hands the frame its header, tabs, rows, and block. |
+| `panel/tui/keys.ts` | The one key table: each binding with the sections that offer it, the hint row they produce, and the `?` help block, so a key cannot drift from its hint or its help line. |
+| `panel/tui/panes.ts` | The two-pane arithmetic: the 96-column breakpoint, the side-pane width, one composed row with its `╎` divider, and the clip that ends a block with `… N more lines`. |
+| `panel/tui/side-pane.ts` | The focused row's block in both layouts: name and verdict, findings, `Path`, `Source`, `State`, `Health`, a setting's `Now`/`About`/`Stored in`, the JSON pane, and the saved marker. |
+| `panel/tui/section-view.ts` | What the screen derives from the session: the tab counts, the one body height, the header's attention, the filter chips, the empty label, and the merged model for a list section. |
+| `panel/tui/list-view.ts` | The resource row grammar only: the checkbox, the status glyph, the name, and the verdict column. |
+| `panel/tui/settings-view.ts` | The settings row — checkbox, label, value in its measured column, the editing cell — and the editor's hint row. |
 | `panel/tui/entries.ts` | The flat display entries per section and the stable focus keys. |
 | `panel/tui/editing.ts` | The text-row editor's key map: caret moves, delete, clear, commit, cancel. |
-| `panel/tui/frame.ts` | The shared dock frame, the section bar, the detail-row budget, and the optional rows that give way on a short terminal. |
-| `panel/tui/settings-section.ts` | The Settings section's editor and JSON-pane state, its key handling, and the screen it draws. |
+| `panel/tui/frame.ts` | The chrome — the header rule, the tab row with its counts, chips and scope, the group heading, the hint or notice row, and the saved marker — and the height law: one body target for all three sections, the range row, and the rows a short terminal sheds. |
+| `panel/tui/settings-section.ts` | The Settings section's state only: the text editor, the JSON pane, the write chain, and the reset. |
 | `panel/tui/nav.ts` | The panel's cursor arithmetic and one read of a navigation key. |
 | `panel/commands.ts` | `/bytefly`: one command for the screen sections, the `doctor` report, the settings and skills listings, and their text modes. |
 | `picker/types.ts` | Picker host seams (`SettingsStore`, `ResourceResolver`, `Discovery`, `ResourceKind`), the app-settings setters, and row types. |
@@ -1574,15 +1769,20 @@ receipt's width ladder), its register/append/render/disable lifecycle
 covered by the pure helpers (`picker/resources`), the toggle
 transforms (`picker/toggle`), discovery with an injected factory
 (`picker/discovery`), and the runtime state machine (`picker/runtime`). The
-unified screen is covered by its pure model merge (`panel/join`), its text
-formatter (`panel/format`), the settings catalogue and its cycling
-(`panel/settings`), the scope-aware settings runtime (`panel/settings-runtime`,
-including a nested leaf write that keeps its siblings), the skill metadata join
-and loader (`panel/skills`, on real `SKILL.md` files),
-the screen's rendering (`panel/tui`), its list grammar (`tui/list-view`), the
-Skills pane (`tui/skills-view`), the Settings section state (`tui/settings-section`),
-its editing key map (`tui/editing`), the shared frame (`tui/frame`), and the
-command through the bytefly factory (`panel/commands`).
+unified screen is covered by its pure model merge (`panel/join`), its two
+filters and their chips (`panel/filter`), its text formatter (`panel/format`),
+the settings catalogue and its cycling (`panel/settings`), the scope-aware
+settings runtime (`panel/settings-runtime`, including a nested leaf write that
+keeps its siblings), the skill metadata join and loader (`panel/skills`, on real
+`SKILL.md` files), the key table whose hints and help it holds to one source
+(`panel/keys`), the frame and the one height all three sections agree on
+(`panel/layout`), the row grammar and the focused-row block beside and under the
+list (`panel/views`), the two-pane split and its `… N more lines` clip
+(`panel/panes`), the editing key map (`tui/editing`), the component's frames,
+keys, sections, settings, and probe lifecycle (`panel/component`,
+`panel/component-input`, `panel/component-sections`,
+`panel/component-settings`, `panel/component-probing`), and the command through
+the bytefly factory (`panel/commands`) — eighteen suites in all.
 The doctor surface is covered by its pure report
 formatting (`doctor/format`), its config loader (`doctor/config`), and
 registration, the proactive notice, the session cache, and `run_doctor`