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

package/docs/extensions/bytefly.md

@@ -17,8 +17,8 @@ Status records what a reader can rely on: **Shipped** is in a tagged release, **
 | 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 | Location, branch, context, spend, and model on two lines that shed parts rather than clip. | Shipped |
-| Extension status chips | `footerData.getExtensionStatuses()` | Worktree, browse, plan, and alert statuses appear in the footer, using each extension's own colour. | 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 |
@@ -32,12 +32,12 @@ Status records what a reader can rely on: **Shipped** is in a tagged release, **
 
 | Capability | How | What you get | Status |
 |---|---|---|---|
-| Extension list | `/bytefly` | Every resolved extension with an enable checkbox, one health verdict, and its findings. | Shipped |
-| Settings list | `/bytefly settings` | The curated preferences with each value beside its label, editable in place. | Shipped |
+| 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 |
-| Skill list | `/bytefly skills` | Every resolved skill with the same checkbox and the description its `SKILL.md` declares. | Shipped |
-| Scoped writes | `Tab`, `Space`, `x` | A toggle lands in the personal or project `settings.json`, and `x` clears a project override. | Shipped |
-| Reload after changes | `/bytefly` after a pending write | The screen offers the reload that applies extension, skill, or setting changes instead of leaving the session to be restarted by hand. | 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 |
 
 ### Upkeep
@@ -45,7 +45,7 @@ Status records what a reader can rely on: **Shipped** is in a tagged release, **
 | 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` | One notice, and one OS notification, when the session total reaches the threshold. | 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 |
@@ -97,12 +97,13 @@ One command runs the screen, prints the report, and re-checks updates:
 | `/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`, `/bytefly update`, and `/bytefly upgrade`
-take no name.
+`/bytefly settings`, `/bytefly skills`, `/bytefly prices`, `/bytefly update`, and
+`/bytefly upgrade` take no name.
 
 ## Behaviour by mode
 
@@ -193,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 |
 
@@ -231,7 +232,7 @@ 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
+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.
 
@@ -260,13 +261,14 @@ identity, and grouped help are tuned in
 
 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 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
+  session's page port (`◉ 4780`) while anything is served on it. One server serves
+  every page of a session, so it is one number from one status key.
 - **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.
+  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
@@ -274,8 +276,8 @@ Two lines, each with a left and right zone:
   `/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
+~/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
@@ -283,11 +285,18 @@ 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 there is no mode slot, so the `│` is omitted:
+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
+~/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, the session's port joins the run beside the worktree:
+
+```
+~/repo/my-pi-agent                                                                 ⎇ main · ◉ 4780
+▰▰▰▰▰▰▱▱▱▱ 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
@@ -295,20 +304,29 @@ 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
+~/repo/my-pi-agent       ≡ plan · ⎇ main · ⑂
+▰▰▰▰▰▰▱▱▱▱ 62%/200k · ¥0.31  opus-4.5 · high
 ```
 
 ```
-project   ⎇ main
-62% ≡   opus-4.5
+~/my-pi-agent     ⎇ main
+▰▰▰▰▰▰▱▱▱▱ 62%  opus-4.5
+```
+
+The port drops the digits before the page they name: it compacts to `◉` once
+the number no longer fits, 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% │ ≡ plan         opus-4.5
+~/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
@@ -324,29 +342,33 @@ Each segment reads a theme role and carries its own drop order:
 |---|---|---|---|
 | 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 |
+| port `◉ 4780` | 1 right | success glyph + accent port | 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 |
+| 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 browse chip is read
-from the `browse` status key published by [file-browse](./file-browse.md) 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.
+[worktree](./worktree.md) extension and the bar agree. The port is the `http`
+status key, published by [serve](./serve.md) while anything is mounted on the
+session's server — one number, because one socket serves every page a session
+opens. It is a two-tone `<glyph> <port>` with a green glyph and an accent port,
+and it compacts from `◉ 4780` to `◉` before it drops, so a bar too narrow for
+the number still says a page is up.
+
+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
 
@@ -407,14 +429,27 @@ 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.
 
-`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.
+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
@@ -621,39 +656,122 @@ in [`working/config.ts`](../../extensions/bytefly/working/config.ts).
 
 ## The control center
 
-<img src="../../assets/screens/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
@@ -664,11 +782,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
@@ -677,30 +794,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
@@ -708,53 +832,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: twelve
-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 · 12 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/screens/bytefly-settings.png" alt="The /bytefly Settings section: one flat list of twelve preferences with each value beside its label, the `Global · 12 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
@@ -771,20 +882,16 @@ 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.
+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/panel.test.ts` holds the
+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
@@ -800,11 +907,11 @@ 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
@@ -821,18 +928,18 @@ screen order:
 
 ```
 bytefly: Settings · Global · 12 settings
-  Bytefly startup TUI: Off
+  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`,
@@ -865,27 +972,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
 
@@ -1059,12 +1177,12 @@ 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 the two app preferences
-  the screen carries — `quietStartup` (the **Bytefly startup TUI** row) and
+  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`,
@@ -1139,10 +1257,11 @@ why the line says so, and each source the manager reports is shown while it runs
   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
@@ -1218,7 +1337,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. |
@@ -1318,9 +1437,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
@@ -1332,24 +1451,40 @@ 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.md) extension publishes `✆ wechat` while its bridge runs,
+  `worktree` is location, so the `◉ <port>` chip sits behind `⎇`
+  branch and `⑂` worktree, and it is the session's one page port, so it keeps a
+  weight and a floor of its own; 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
@@ -1359,15 +1494,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
@@ -1510,8 +1653,10 @@ 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/budget.ts` | The session spend guardrail: whether the configured ceiling has been crossed and the one notice that says so — an alert, never a limit. |
+| `footer/delegation.ts` | The child-run ledger: the pricing inputs of the last delegated runs, versioned so the footer re-prices when a subagent finishes. |
 | `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. |
 | `footer/price/types.ts` | `Currency`, `ModelRates`, `PeakWindow`/`PeakSchedule`, `ByteflyConfig`. |
@@ -1519,13 +1664,14 @@ 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. |
 | `footer/render/lines.ts` | Snapshot → two `LineSpec`s; status routing. |
 | `footer/render/layout.ts` | Width reduction and right-zone folding. |
 | `footer/render/footer.ts` | `StatusBar` component and footer factory. |
+| `footer/render/key.ts` | `snapshotKey`: the bar's repaint key, derived from the snapshot's own shape — sorted object keys, a map as sorted entries, a primitive by value — so a field added to `StatusSnapshot` is in the key the day it is added. |
 | `message/config.ts` | Nameplate tuning (`MESSAGE_CONFIG`): the label and the rule. |
 | `message/format.ts` | Pure `nameplate` and `styleUserMessage`: the two-row nameplate (label over a full-width rule) and its placement above the message. |
 | `message/register.ts` | Registers the Markdown transformer (the nameplate). |
@@ -1545,21 +1691,25 @@ columns, gauge), so the look follows the active theme.
 | `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 twelve 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/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. |
@@ -1591,62 +1741,66 @@ columns, gauge), so the look follows the active theme.
 
 ## Testing
 
-`extensions/bytefly/` covers the install/restore/toggle lifecycle
-(`extension`), the header's rendering, width shedding, and live theme
-(`header/component`), its quiet-startup lifecycle (`header/register`),
-the formatters (`footer/render/format`), the status-chip transforms
-(`footer/render/status`), entry
-reduction and model inheritance (`footer/collect/entries`), snapshot assembly
-and its memoization (`footer/collect/snapshot`), rate matching
-(`footer/price/rates`), window parsing
-and peak evaluation in two zones (`footer/price/schedule`), the pricing formula,
-the off-peak multiplier, the built-in DeepSeek table with no config file, and the
-fallback (`footer/price/price`), the config schema, its clamping, the built-in
-defaults and their replacement, and the two file layers
-(`footer/price/config`), zone/priority
-assignment
-(`footer/render/lines`), the reduction, separator collapse, and right-zone
-folding across a width sweep from 6 to 120 plus wide characters
-(`footer/render/layout`), exact
-golden output at fixed widths (`footer/render/render`), and the install/skip/
-restore/toggle lifecycle plus a config-driven price (`extension`). The turn
-separator is covered by its pure formatting (`separator/format`, including the
-receipt's width ladder), its register/append/render/disable lifecycle
-(`separator/register`), and the run stats it records. The picker helpers are
-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`).
-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`
-through the factory (`doctor/register`). The notify capability is covered by its section loader
-(`notify/config`), the pure text builders (`notify/format`), method selection and
-delivery over recording seams (`notify/dispatch`), and its four triggers,
-reload, and shutdown through `registerNotify` (`notify/register`). The update
-surface is covered by the version-ordering table (`update/version`), Pi's package
-list and the injected registry read (`update/check`), the host shim and its
-idempotent restore (`update/suppress`), the per-load store (`update/state`), the
-marker, multi-package notice, release URL, and recheck wording (`update/format`),
-the project-scoped snapshot and its window (`update/cache`), and its lifecycle —
-a fresh matching entry reused without a package-manager call, a stale one re-read
-and rewritten, silent on failure or an empty list, cache-only offline, skipped
-outside `tui`, an explicit `recheck()` that ignores the window, and immunity to a
-reply that lands after shutdown (`update/register`).
-The user-message nameplate is covered by its pure transform
-(`message/format`, including a render through pi-tui's real `Markdown`) and its
-registration (`message/register`), plus the factory check in `extension`.
-The notice surface is covered by its pure rows (`notice/component`), its
-renderer registration (`notice/register`), and the shared contract
-(`lib/notice`), plus the factory check in `extension`.
-The tool-block frame is covered by its pure `toolBlockLines` (`block/component`)
-and its generic fallback (`block/fallback`), plus the resolver's shell override,
-self-shell carve-out, and fallback framing (`block/register`).
+Every suite sits beside the code it covers, so a slash-prefixed stem below
+resolves to `extensions/bytefly/<stem>.test.ts`.
+
+`extension` covers the registration, the interactive surfaces, and the command
+wiring through the factory.
+
+`chrome` covers the chrome that frames a session: the config and its pad store;
+the header's frames, width shedding, identity ladder, update marker, live theme,
+quiet-startup lifecycle, and terminal-height shapes; the transcript notice's rows
+and registration; the turn separator's formatting (including the receipt's width
+ladder), component, and register/append/render/disable lifecycle with the run
+stats it records; and the user-message nameplate's transform — through pi-tui's
+real `Markdown` — and its registration.
+
+`footer/footer` covers the bar end to end: the price config, its schema, clamping,
+and defaults; rate matching, window parsing and peak evaluation in two zones, the
+pricing formula with its off-peak multiplier, the built-in DeepSeek table and the
+fallback, the usage records, and the delegation ledger; the snapshot reader and its
+memo, the unpriced notice, and the budget; the formatters, the status-chip
+transforms, the segment builders, line composition, and the repaint key that
+spares an unchanged frame a rebuild; the reduction, separator collapse, and
+right-zone folding across a width sweep from 6 to 120 plus wide characters; and the
+component with its install/skip/restore/toggle lifecycle and a config-driven price.
+
+`block/block` covers the tool-block frame: `toolBlockLines`, the call-headline
+rewrites, `ToolBlock`'s memo, the generic and call fallbacks, and the resolver's
+shell override and self-shell carve-out.
+
+`picker/picker` covers discovery with an injected factory, the resolver and its
+entries, the pattern helpers, and the runtime's toggling, scope, and project
+override across the four list operations.
+
+`panel/…` covers the control centre, one suite per capability: `panel/model` (the
+two panes' merged model and the text formatter), `panel/filter` and its chips, the settings
+catalogue and its cycling (`panel/settings`), the scope-aware 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 (`panel/editing`),
+the update section's view (`panel/update`), the discovery probe (`panel/probe`), 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.
+
+`doctor/doctor` covers the report counts and text, the config loader, the notify
+seam, the published search provider, the proactive probe, the session state,
+`run_doctor`, and the tool wiring.
+
+`notify/notify` covers its config loader, method selection, delivery over recording
+seams, the text builders, and its four triggers plus the handle.
+
+`update/update` covers the cache path and key, the cache read and write with its
+window, the check and the injected registry read, the version ordering, the
+formatters and the release notice, the prototype suppression with its idempotent
+restore, the per-load state, the lifecycle — a fresh matching entry reused without
+a package-manager call, a stale one re-read and rewritten, silent on failure or an
+empty list, cache-only offline, skipped outside `tui`, a `recheck()` that ignores
+the window, and a reply that lands after shutdown — and the `update` action.
+
+`working/working` covers the elapsed format, the counter, and the timer registration.