@gavin-hu/my-pi-agent 0.15.1 → 0.17.0

package/extensions/bytefly/README.md

@@ -4,13 +4,14 @@
 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 two
-sections — Extensions, every resolved Pi extension with its enable checkbox and
-its health, and Settings, the common app and `bytefly.json` preferences — and
-an opt-in notify capability that raises an OS notification when a run finishes,
+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 block with one notice and marks bytefly's own new version
-on the header.
+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
@@ -35,7 +36,7 @@ How the `run_doctor` call and its result look in the transcript — the call lin
 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
-two-section control center, notifications, and the package-update check.
+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
@@ -58,9 +59,9 @@ that cannot render half blocks the mark falls back to a two-tone `Pi` wordmark.
    / commands · ! bash · !! bash (no context) · /bytefly extensions
 ```
 
-As the terminal narrows, the identity sheds the update marker, then the chrome
-version, then the chrome line, then 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
+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
@@ -152,6 +153,15 @@ 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:
 
@@ -217,7 +227,10 @@ job · 2 background jobs finished
 ```
 
 The rail is painted by the notice's worst severity, so a failure reads red at the
-edge like an errored tool result.
+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
@@ -326,22 +339,26 @@ 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_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).
+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).
 
 ## Commands
 
 | 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 the grouped settings listing with each row's value. |
+| `/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 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. |
 
 Tab completes the subcommands, extension names after `doctor`, and `refresh`;
-`/bytefly settings` and `/bytefly update` take no name.
+`/bytefly settings`, `/bytefly skills`, and `/bytefly update` take no name.
 
 ## Behaviour by mode
 
@@ -355,7 +372,7 @@ print the grouped listing with a per-row health suffix and the headline, or that
 extension's full findings when one is named. In `tui` the screen opens on the
 session's cached report and probes on the first Extensions view; the text modes
 probe before they print. `/bytefly settings` prints the
-grouped settings listing with each row's value outside `tui`; it does not
+flat settings listing with each row's value outside `tui`; it does not
 resolve packages or probe the doctor. The
 proactive session-start check posts a transcript notice through the shared
 `my-pi-agent/notice` renderer rather than a transient notification, and is
@@ -493,13 +510,14 @@ it with its own rates for the models they match:
   changes how the total is printed; the symbol follows the code.
 - **Which source.** Both currencies price a matched record from `rates`; only
   the unmatched case differs. `CNY` contributes nothing for a model it cannot
-  price, while `USD` adds Pi's recorded dollar amount for that record, because
-  that number is already dollars.
+  price and counts the record instead, so the session can name what its total
+  leaves out; `USD` adds Pi's recorded dollar amount for that record, because
+  that number is already dollars and already per model.
 
 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/price/price.test.ts`](./footer/price/price.test.ts), which also prices the built-in
+in [`footer/footer.test.ts`](./footer/footer.test.ts), which also prices the built-in
 table with no config file at all.
 
 ## Content and colors
@@ -575,25 +593,27 @@ and outcome as the width allows.
 
 ## The control center
 
-<img src="../../assets/bytefly.png" alt="The /bytefly control center: the Extensions 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/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%">
 
 `/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. `←`/`→` switch to **Settings**, where the same
-frame lists the curated preferences. `/bytefly settings` opens directly on that
-section. 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 · Settings` section bar beside the section's counts, one row
-grammar (`❯ ◼ name … summary`), and the shared `◼` / `◻` checkbox.
+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` takes no name.
+`refresh`; `/bytefly settings` and `/bytefly skills` take no name.
 
 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
@@ -641,93 +661,72 @@ installs or fetches a package.
 - Offers a reload after pending changes, so the new selection takes effect
   without leaving the session.
 
-**Settings.** The second section uses the same frame and the same `Tab` scope
-switch, with its own cursor. It lists twenty-nine preferences in ten groups:
+**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.
+
+**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 · Settings                           Global · 29 settings
-
-  Startup (1)
-❯ ◻ Bytefly startup TUI                                            Off
-  Notifications (7)
-  ◻ Desktop notifications                                          Off
-  ◼ Turn finished                                                   On
-  ◼ Needs input                                                     On
-  ◼ Job finished                                                    On
-  ◼ Watcher matched                                                 On
-    Delivery method                                               Auto
-    Notification title                                              Pi
-  Diagnostics (2)
-  ◼ Proactive health check                                          On
-    Probe timeout                                                 2000
-  Pricing (3)
-    Currency                                                    CNY (¥)
-    Cost decimals                                                    2
-    Session budget                                                   0
-  Transcript (3)
-    Rail glyph                                                       ╎
-    Achieved goal                                                  Hide
-    Output padding                                                   1
-  Terminal (2)
-    Theme                                                       system
-  ◻ Hardware cursor                                                Off
-  Worktree (4)
-    ◼ Fetch remote                                                 On
-    Base ref                                                    Fresh
-    Branch prefix                                          worktree-
-    Prune after (days)                                             7
-  Snapshots (3)
-    ◼ Automatic snapshots                                          On
-    Snapshots kept                                               20
-    ◼ Safety snapshot                                               On
-  Jobs and watchers (3)
-    ◻ Wake when a job finishes                                     Off
-    ◻ Keep jobs after exit                                         Off
-    ◻ Wake on a match                                              Off
-  Memory (1)
-    ◼ Inject notes                                                  On
+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
+  ◼ Offer the session goal  On
+  ◼ 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 · [ ] group
+  Esc close · ←/→ · Space change · Tab scope · u reset · J JSON · ↑/↓ select
+──────────────────────────────────────────────────────────────────────
 ```
 
-| Group | Row | Source | Values |
-|---|---|---|---|
-| Startup | Bytefly startup TUI | Pi `settings.json` (`quietStartup`) | Off, On |
-| Notifications | Desktop notifications | `notify.enabled` | Off, On |
-| Notifications | Turn finished | `notify.turnFinished` | Off, On |
-| Notifications | Needs input | `notify.needsInput` | Off, On |
-| Notifications | Job finished | `notify.jobFinished` | Off, On |
-| Notifications | Watcher matched | `notify.matchFound` | Off, On |
-| Notifications | Delivery method | `notify.method` | Auto, OSC 777, OSC 99, Windows toast, macOS, Linux |
-| Notifications | Notification title | `notify.title` | Text, up to 40 characters |
-| Diagnostics | Proactive health check | `doctor.proactive` | Off, On |
-| Diagnostics | Probe timeout | `doctor.timeoutMs` | Number, 100–30000 ms |
-| Pricing | Currency | `price.currency.code` | CNY, USD |
-| Pricing | Cost decimals | `price.currency.decimals` | 0, 1, 2, 3, 4 |
-| Pricing | Session budget | `price.budget` | Number, `0` = off |
-| Transcript | Rail glyph | `chrome.rail` | Text, exactly one column |
-| Transcript | Achieved goal | `goal.achieved` | Show, Hide |
-| Transcript | Output padding | Pi `settings.json` | 0, 1 |
-| Terminal | Theme | Pi `settings.json` (`theme`) | `system`, `bytefly-dark`, `bytefly-light` |
-| Terminal | Hardware cursor | Pi `settings.json` | Off, On |
-| Worktree | Base ref | `worktree.baseRef` | Fresh, Head |
-| Worktree | Branch prefix | `worktree.branchPrefix` | Text, trimmed, required |
-| Worktree | Fetch remote | `worktree.fetchRemote` | Off, On |
-| Worktree | Prune after (days) | `worktree.pruneAfterDays` | Number, 0–3650 |
-| Snapshots | Automatic snapshots | `rewind.autoSnapshots` | Off, On |
-| Snapshots | Snapshots kept | `rewind.max` | Number, 0–1000 |
-| Snapshots | Safety snapshot | `rewind.safetySnapshot` | Off, On |
-| Jobs and watchers | Wake when a job finishes | `job.wakeOnFinish` | Off, On |
-| Jobs and watchers | Keep jobs after exit | `job.detachedByDefault` | Off, On |
-| Jobs and watchers | Wake on a match | `watch.wakeOnMatch` | Off, On |
-| Memory | Inject notes | `memory.inject` | Off, On |
-
-Choosing **Currency** also writes that currency's default precision. Both rows
-stay editable afterwards, so the footer follows the explicit values.
+<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 |
+| Offer the session goal | `plan.goalPrompt` | 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 |
+
+Choosing **Currency** also writes that currency's default precision
+(`price.currency.decimals`). Both stay editable in `bytefly.json` afterwards, so
+the footer follows the explicit values.
 
 The **Theme** row lists `system` first, then the palettes this package ships,
 `bytefly-dark` and `bytefly-light`; it cycles no further, so a bytefly screen
@@ -739,24 +738,34 @@ and is replaced by the next choice here, so manage those in Pi's `/settings` →
 **Theme**.
 
 `Space` (or `Enter`) changes the focused row: a boolean toggles, an enum cycles
-forward, and a text row opens an inline editor on its value — the notification
-title, the probe timeout, the branch prefix, and the rail glyph. `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),
-`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 — and
-`[` / `]` jump to the previous or next group. The detail pane names
-the source, describes the preference, and shows
-where the value comes from — `Global · ~/.pi/agent/bytefly.json`, `Project ·
+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 toggle.
-
-Six of the ten `bytefly.json` sections belong to other extensions. The screen
-cannot import their normalizers, so it reports the leaf as the file states it and
-declares the loader's default; `test/settings-coverage.test.ts` holds the
+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
+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. Five
+`bytefly.json` sections therefore have no row at all (`chrome`, `goal`, `watch`,
+`worktree`, `memory`), as do `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).
+
+Three of the six sections belong to other extensions (`rewind`, `job`, and
+`plan`). 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
@@ -767,31 +776,28 @@ 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 twenty-five `bytefly.json` rows and a
+scope therefore lists the eleven `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.decimals`) through a per-key
-writer, so every sibling key, section, `$schema`, and `version` is preserved. A
-malformed document is refused with a notice instead of overwritten, and `u`
-removes that one leaf through the same writer's `unsetConfigValueAt`.
+key, or a nested one such as `price.currency.code`) through a per-key writer, so
+every sibling key, section, `$schema`, and `version` is preserved. A malformed
+document is refused with a notice instead of overwritten, and `u` removes that
+one leaf through the same writer's `unsetConfigValueAt`.
 
-The non-`tui` form prints the headline, the groups, and `Label: Value` rows:
+The non-`tui` form prints the headline and one `Label: Value` row per line, in
+screen order:
 
 ```
-bytefly: Settings · Global · 29 settings
-
-Startup (1)
+bytefly: Settings · Global · 14 settings
   Bytefly startup TUI: Off
-
-Notifications (7)
+  Theme: system
   Desktop notifications: Off
   Turn finished: On
   Needs input: On
   Job finished: On
   Watcher matched: On
   Delivery method: Auto
-  Notification title: Pi
-...
+  ...
 ```
 
 The doctor side probes every declared extension and reports each check as `ok`,
@@ -826,21 +832,21 @@ headline; a named extension prints its full findings instead.
 
 | Key | Effect |
 |---|---|
-| `←` / `→` | Show the Extensions or Settings section. |
-| `Space` | Toggle the focused extension (Extensions); change the focused setting (Settings), or open the editor on a text row. |
-| `x` | Clear the focused extension's project override (Extensions, Project scope). |
-| `Enter` | Expand or collapse the focused extension's findings (Extensions); change the focused setting, or open the editor on a text row (Settings). |
+| `←` / `→` | 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). |
 | `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 (Settings). |
+| `[` / `]` | 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. |
 | `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 either section. |
+| `Tab` | Switch between Global and Project scope, in any section. |
 | `r` | Re-probe the doctor (Extensions). |
-| `↑`/`↓`, `j`/`k` | Move the selection, in either section. |
-| `PgUp`/`PgDn` | Move a page, in either section. |
-| `g` / `G`, `Home` / `End` | Jump to the first or last row, in either section. |
+| `↑`/`↓`, `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
@@ -931,7 +937,7 @@ suppresses Pi's own `Package Updates Available` block, and draws one notice for
 every row Pi returned.
 
 ```
- █▀█  Pi v1.3.0
+ █▀█  Pi v1.3.0 ↑1.4.0
  █▀ █ enhanced by bytefly v0.11.4 ↑0.12.0
 ```
 
@@ -947,9 +953,10 @@ The marker is the shared `↑` glyph and this package's newest version — the a
 is one cell wide, so the header's column math is unchanged — painted with the
 header's `accent` role: an action rather than a warning, so the muted version
 beside it stays quiet and the transcript is not turned yellow for a normal state.
-Other packages never change the header. The marker is part of the chrome cell, so
-the two identity cells still line up, and it is the first thing the identity
-sheds when the terminal narrows.
+Pi's own newer version marks the agent line the same way, after `Pi v1.3.0`.
+Other packages never change the header. The marker is part of the identity cell,
+so the two cells still line up, and it is the first thing the identity sheds when
+the terminal narrows.
 
 The notice is the shared transcript block: the `bytefly · title` headline at the
 margin, one rail row per package with this package's version arrow or the other
@@ -957,6 +964,26 @@ package's scope, then the fixing command and this package's release URL, all at
 `info` severity because nothing is broken. It stays in scrollback and the model
 reads the same names, version, command, and URL in plain text.
 
+Pi's own release takes the same route. Pi resolves its newer version from
+`pi.dev` and would draw a bordered `Update Available` block from
+`InteractiveMode.showNewVersionNotification`; bytefly replaces that method, so
+the release Pi already fetched becomes one shared notice and the agent line's
+marker:
+
+```
+ bytefly · pi v1.4.0 is available
+ ╎ ◌ pi · v1.3.0 → v1.4.0
+ ╎ ◌ update · pi update
+ ╎ ◌ changelog · https://pi.dev/changelog
+```
+
+That notice is bytefly's rendering, not a second check: Pi makes the request and
+resolves the release, and bytefly reads the same answer, including the release's
+optional `note` as a `release notes` row sanitized to one line. `PI_OFFLINE` and
+`PI_SKIP_VERSION_CHECK` keep their Pi meaning, and a host whose method is missing
+or renamed keeps its own block. The patch is process-wide like the package one,
+installed at `session_start` and restored at `session_shutdown`.
+
 The list is Pi's decision: npm ranges, git refs, project scope, a missing
 install, and `PI_OFFLINE` all follow its package manager. The only extra read is
 `GET https://registry.npmjs.org/@gavin-hu%2Fmy-pi-agent/latest` when Pi reports
@@ -1004,18 +1031,23 @@ command.
 - **Project overrides of app settings are not shown.** App rows read the
   personal file; a `.pi/settings.json` override still wins at runtime, and
   `pi config` is the place to manage it.
-- **Arrays and tables stay JSON.** A row is one boolean, enum, string, or number.
-  `doctor.skip` (an array), the `rates` table, and `price.peak` (a nested object)
-  are still `bytefly.json` edits; every scalar preference has a row.
-- **A custom rail glyph must be one column.** The editor refuses anything else,
+- **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
+  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`.
+- **The rail glyph is typed in `bytefly.json`.** It must be exactly one column,
   because a two-column glyph would push every railed body one cell right; the
-  former four-glyph menu is now the description's example list.
-- **`doctor`, `settings`, and `update` are reserved first arguments.**
+  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` and `update` are reserved
-  the same way.
-- **The picker manages only the `extensions` resource type.** Skills, prompts,
-  and themes are handled by Pi's own `pi config`.
+  `doctor` cannot be narrowed to by name; `settings`, `skills`, and `update` 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`,
@@ -1030,16 +1062,19 @@ command.
   package sources; there is no setting for it, and `/bytefly` and `doctor` do not
   report the version. A failed or slow background request is retried by the next
   session, or immediately by `/bytefly update`.
-- **The marker needs the bytefly startup TUI.** It lives on the custom header,
+- **The markers need the bytefly startup TUI.** They live on the custom header,
   so with `quietStartup` off the notice is the whole signal.
-- **Pi's block is suppressed by a host shim.** bytefly wraps
-  `DefaultPackageManager.prototype.checkForAvailableUpdates` at `session_start`
-  and restores it on shutdown. A future Pi that changes that method shape makes
-  the shim inert, and Pi's own block can come back.
+- **Pi's blocks are suppressed by host shims.** bytefly wraps
+  `DefaultPackageManager.prototype.checkForAvailableUpdates` and
+  `InteractiveMode.prototype.showNewVersionNotification` at `session_start` and
+  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
   the release row prints the URL and nothing more — no changelog body, no way to
-  click through from the transcript.
+  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
+  clipped at the width.
 - **Project toggles are two-state per press** (`enable`/`disable`). `x` clears
   the override, which is the third state; a resource with no project entry in
   `pi config` is still managed there.
@@ -1055,7 +1090,10 @@ 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.
+  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.
 - **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
@@ -1131,12 +1169,12 @@ 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`, and `registerHeader` returns a `refresh()` handle that re-installs the last context's header when that 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 **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. |
 | 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 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. |
+| 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. |
 | Tool blocks | `registerToolRenderer` returns, for every tool, `renderShell: "self"`; `renderCall` leaves the tool's own first line as the block's headline (a shell prompt shown as the tool name, its command repainted in the body colour, and a primary subject demoted to the body colour) and indents the rest of the call two columns under it, `renderResult` indents its body the same and leads it with the status-coloured rail, and each wraps the tool's own renderer (or a generic fallback). `edit` and `write` carry their result on the call body, so that body is railed too. |
-| Screen command | `pi.registerCommand("bytefly")` takes `[doctor] [settings] [extension] [refresh]`: `tui` mounts a dock screen via `ctx.ui.custom()` with the rails suppressed; other modes print through `ctx.ui.notify()` — the grouped listing, `run_doctor`'s report for `doctor`, or the grouped settings listing with values for `settings`. A named extension is checked against the discovered set before any probe. Tab completes the subcommands, extension names after `doctor`, and `refresh`; `/bytefly settings` rejects a name. |
+| Screen command | `pi.registerCommand("bytefly")` takes `[doctor] [settings] [extension] [refresh]`: `tui` mounts a dock screen via `ctx.ui.custom()` with the rails suppressed; other modes print through `ctx.ui.notify()` — the grouped listing, `run_doctor`'s report for `doctor`, or the flat settings listing with values for `settings`. A named extension is checked against the discovered set before any probe. Tab completes the subcommands, extension names after `doctor`, and `refresh`; `/bytefly settings` rejects a name. |
 | Turn separator | `registerEntryRenderer("bytefly-separator")` draws each stored receipt; `agent_start` opens it, top-level `tool_execution_start`/`tool_execution_end` count tools and failures, and `agent_settled` appends `pi.appendEntry("bytefly-separator", { turn, durationMs, tools, failures, aborted })` in `tui` mode only. The receipt fields are omitted when no `agent_start` was seen, so an older or partially observed entry stays `{ turn }`. |
 | Working line | `turn_start` starts a 1s tick that drives `ctx.ui.setWorkingMessage` in `tui` mode; before a tool runs the message is `Working… Ns`, and each top-level `tool_execution_start` repaints it as `tool · N tools · Ns` (nested calls carrying `parentToolCallId` are skipped). `agent_end` restores Pi's default and cancels the tick (also on `session_shutdown`). No config file and no persisted state; the count lives in the register's closure. |
 | 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. |
@@ -1146,11 +1184,12 @@ rather than showing a wrong value.
 | 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. |
 | 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 and the current reports, and persists extension 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`. |
-| Lifecycle | `session_start` installs the header when Pi's `quietStartup` is `true` and the footer, loads the chrome rail glyph, points the doctor runtime at the session cwd, probes the extensions with hard requirements when `bytefly.json`'s `doctor.proactive` is on and `quietStartup` is `true`, loads the notify config and subscribes to the job bus, and starts the package-update check; `session_tree` reinstalls the header and footer and reloads the rail; `session_shutdown` restores Pi's built-in header, footer, and package-update method, disposes the branch subscription, drops doctor's cached findings, drops the notify bus subscription, and clears the recorded version. |
+| 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`. |
+| Lifecycle | `session_start` installs the header when Pi's `quietStartup` is `true` and the footer, loads the chrome rail glyph, points the doctor runtime at the session cwd, probes the extensions with hard requirements when `bytefly.json`'s `doctor.proactive` is on and `quietStartup` is `true`, loads the notify config and subscribes to the job bus, and starts the package-update check; `session_tree` reinstalls the header and footer and reloads the rail; `session_shutdown` restores Pi's built-in header, footer, package-update method, and release-notice method, disposes the branch subscription, drops doctor's cached findings, drops the notify bus subscription, and clears the recorded versions. |
 
 ## Design notes
 
@@ -1344,7 +1383,7 @@ rather than showing a wrong value.
   a third layer.** An extension cannot import another extension's modules, so
   the only legal home for a shared prerequisite table is `lib/requirements.ts`;
   the report itself is a pure function of the probe results.
-- **The install hint has one home.** `document` and `web-access` format their
+- **The install hint has one home.** `file-read` and `web-access` format their
   tool errors from the same `REQUIREMENTS` entries `doctor` prints, so a user
   reads the same command whether a tool failed or the report named it.
 - **Settings are a curated table, not a schema walker.** The rows cover every
@@ -1407,18 +1446,19 @@ calculation), `message/` (the user-message marker), `notice/` (the shared notice
 run line on Pi's working row), `panel/` (the
 unified screen and its merged model),
 `picker/` (discovery and the settings store), `doctor/` (the `run_doctor` tool
-and its probe runtime), `notify/`, and `update/` (Pi's package list, the host
-suppression, the cache, and the header marker). The chrome and the screen are drawn from
+and its probe runtime), `notify/`, and `update/` (Pi's package list, Pi's own
+release notice, the host patches, the cache, and the header markers). The chrome and the screen are drawn from
 the package's [`lib/tui/`](../../lib/tui/) design system (tokens, rules, rows,
 columns, gauge), so the look follows the active theme.
 
 | File | Responsibility |
 |---|---|
-| `index.ts` | Composition root: the disable guard, the eleven `register*` calls, the one shared output-pad store, and the rail source. |
+| `index.ts` | Composition root: the disable guard, the `register*` calls, the two per-load update stores, the one shared output-pad store, and the rail source. |
 | `pad.ts` | `PadSource` and `createPadStore`: one record of Pi's output pad, so the tool frame, the notice, and the turn separator inset by the same margin. |
 | `chrome.ts` | The transcript rail (`RAIL_ROLES`, `railGlyph`), the `chrome` section's normalizer and loader, and the `RailSource` that `registerChrome` keeps current on `session_start`/`session_tree`. |
 | `header/config.ts` | Header tuning (`HEADER_CONFIG`): mark and identity roles, tagline, and the grouped help entries. |
-| `header/component.ts` | `ByteflyHeader`: the mark, identity rows, signature rule, and grouped help, plus its factory. |
+| `header/component.ts` | `ByteflyHeader`: the mark, the two identity rows mounted from `identityCells`, signature rule, and grouped help, plus its factory. |
+| `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. |
@@ -1429,7 +1469,8 @@ columns, gauge), so the look follows the active theme.
 | `footer/price/config.ts` | The `price` section of `bytefly.json`: schema, defaults, built-in DeepSeek rates/tariff, currency defaults, normalizer, loader. |
 | `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, and the peak multiplier. |
+| `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/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. |
@@ -1438,7 +1479,7 @@ columns, gauge), so the look follows the active theme.
 | `footer/render/footer.ts` | `StatusBar` component and footer factory. |
 | `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. |
+| `message/register.ts` | Registers the Markdown transformer (the nameplate). |
 | `notice/config.ts` | Notice tuning (`NOTICE_CONFIG`): source/title/detail roles, the severity glyphs and roles, the shared rail roles, and the item cap. |
 | `notice/component.ts` | Pure `noticeLines` and `NoticeComponent`: the headline at the margin, the rail-led severity rows, sanitized and width-clipped. |
 | `notice/register.ts` | Registers the message renderer for the shared notice type and hands it the rail source. |
@@ -1454,19 +1495,29 @@ 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` | `settings`), `PanelRow`, 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. |
-| `panel/format.ts` | Non-TUI text: the extension headline and grouped listing with a per-row health suffix, plus the section segments, the Settings counts/headline, and the grouped Settings listing. |
-| `panel/settings.ts` | The curated Settings catalogue: descriptors, snapshot views and origins, value cycling, stored-value mapping, validation, and grouping, 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 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/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/tui.ts` | `PanelComponent`, the two-section dock screen (Extensions list and Settings list) and its section composition; the editing key map is `tui/editing.ts` and the shared frame is `tui/frame.ts`. |
-| `panel/commands.ts` | `/bytefly`: one command for the screen sections, the `doctor` report, the settings listing, and their text modes. |
-| `picker/types.ts` | Picker host seams (`SettingsStore`, `ExtensionResolver`, `Discovery`), the app-settings setters, and row types. |
-| `picker/resources.ts` | Pure grouping, labels, display names, and pattern helpers. |
+| `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/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/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. |
+| `picker/resources.ts` | Pure grouping, labels, display names per resource kind, and pattern helpers. |
 | `picker/toggle.ts` | Pure next-settings transforms for global and project toggles. |
-| `picker/discovery.ts` | Host wiring: builds the global and effective views from Pi's managers, and the two settings stores for the settings-only command path. |
-| `picker/runtime.ts` | Picker scope, live view copies, dirty tracking, and persistence. |
+| `picker/discovery.ts` | Host wiring: builds both kinds' global and effective views from Pi's managers, and the two settings stores for the settings-only command path. |
+| `picker/runtime.ts` | Picker scope, live view copies, dirty tracking, and persistence, for both resource kinds through one ops table. |
 | `doctor/register.ts` | Registers `run_doctor` and the proactive session-start check; returns the runtime. |
 | `doctor/runtime.ts` | Host seams, the session cache, and the two probe modes. |
 | `doctor/tools.ts` | The `run_doctor` tool and its renderers. |
@@ -1478,14 +1529,16 @@ columns, gauge), so the look follows the active theme.
 | `notify/dispatch.ts` | Method selection and delivery: OSC 777/99, Windows toast, `osascript`, `notify-send`, over injected seams. |
 | `notify/format.ts` | Pure notification text: session label and the turn / input / job / watch bodies. |
 | `notify/register.ts` | Registers the four triggers, loads the config at `session_start`, and owns the job- and watch-bus subscriptions. |
-| `update/types.ts` | `PackageUpdate`, derived from Pi's public manager method, and `PackageUpdateCheck`. |
-| `update/suppress.ts` | The host shim: capture Pi's `checkForAvailableUpdates`, replace it with an empty result, and restore it on shutdown. |
+| `update/types.ts` | `PackageUpdate` and `PackageUpdateCheck`, derived from Pi's public manager method; `PiRelease` and `ReleaseNoticePrototype`, derived from Pi's notification method. |
+| `update/patch.ts` | `patchPrototypeMethod`: the one host-method replacement both update surfaces use — a per-method `Symbol.for` marker, idempotent reuse, a restore that only puts back its own replacement, and an inert result when the host has no such method. |
+| `update/suppress.ts` | The two host shims over `patchPrototypeMethod`: capture Pi's `checkForAvailableUpdates` and replace it with an empty result, and hand `showNewVersionNotification`'s release to bytefly (falling back to the captured original if that throws). |
 | `update/check.ts` | Pi's package list through `DefaultPackageManager`, plus the registry `GET` that names this package's version for the marker, arrow, and release URL. |
 | `update/version.ts` | Pure semver parsing and `isNewerVersion`, including prerelease precedence. |
-| `update/state.ts` | `UpdateSource` and `createUpdateState` (this package's known version, one record per load), plus `UpdateOutcome`, the four answers an explicit re-check can give. |
+| `update/state.ts` | `UpdateSource` and `createUpdateState` (one known version per subject per load), `paintLatest` (record and repaint the header only on a change), plus `UpdateOutcome`, the four answers an explicit re-check can give. |
 | `update/cache.ts` | The project-scoped snapshot: `<agentDir>/bytefly/update.json`, the cwd/package key, the 24 h window in `isFresh`, a validated read that degrades to a miss, and the atomic write. |
-| `update/format.ts` | `updateMarker`, `updateNotice`, `releaseUrl`, and `updateOutcomeText`: the header's `↑0.12.0`, the multi-package notice, and the one line `/bytefly update` prints. |
-| `update/register.ts` | The lifecycle: suppression, the cache-first session-start read, the async package-manager call, this package's version lookup, the `PI_OFFLINE` and `tui` gates, the once-per-load announcement, the shutdown generation guard, and the `recheck()` handle `/bytefly update` calls. |
+| `update/format.ts` | `updateMarker`, `updateNotice`, `releaseUrl`, `updateOutcomeText`, and `piReleaseNotice`, plus the shared command/link rows: the header's `↑0.12.0`, the multi-package notice, the line `/bytefly update` prints, and the notice that replaces Pi's `Update Available` box. |
+| `update/register.ts` | The package-update lifecycle: suppression, the cache-first session-start read, the async package-manager call, this package's version lookup, the `PI_OFFLINE` and `tui` gates, the once-per-load announcement, the shutdown generation guard, and the `recheck()` handle `/bytefly update` calls. |
+| `update/release.ts` | Pi's own release lifecycle: install the notification patch in `tui` mode, record the release's version for the agent-line marker, post the notice once per load while the session is live, and restore the method on shutdown. |
 
 ## Testing
 
@@ -1517,10 +1570,12 @@ transforms (`picker/toggle`), discovery with an injected factory
 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 screen's rendering (`panel/tui`), its editing key map (`tui/editing`),
-the shared frame (`tui/frame`), and the command through
-the bytefly factory (`panel/commands`).
+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`