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

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

@@ -1,354 +1,96 @@
 # bytefly — the TUI header, footer, user-message marker, turn rule, extension screen, and notifications
 
-`bytefly` owns the terminal chrome, configuration, and diagnostics surfaces
-this package adds: one themed startup header whose two-tone nameplate carries
-the agent and chrome identities, one compact, colorful, width-adaptive two-line
-footer, a two-row `You` nameplate that opens each user message, a receipt rule that
-records each completed turn in the transcript, one keyboard-driven screen with
-three sections — Extensions, every resolved Pi extension with its enable
-checkbox and its health; Skills, every resolved Pi skill with the same checkbox
-and its declared description; and Settings, the common app and `bytefly.json`
-preferences — and an opt-in notify capability that raises an OS notification when a run finishes,
-a job finishes, or the agent asks for input, and a package-update check that
-replaces Pi's startup blocks — the package list and Pi's own release — with one
-notice each and marks a new version on the header.
-DeepSeek is priced from the provider's published yuan rates and peak tariff by
-default; set `price.currency.code` to `USD` to price it from the provider's
-published dollar table instead, under the same peak windows, with Pi's recorded
-dollars covering a model the table does not list. Any other model can be priced
-from your own yuan rates when Pi's
-catalog does not match what a provider actually charges.
+`bytefly` owns the terminal chrome, configuration, and diagnostics surfaces this
+package adds: the startup header and footer, the user-message nameplate, the turn
+rule, the shared notice and tool-block frames, the working line, the `/bytefly`
+control center, OS notifications, and the package-update check. Every surface is
+drawn from the package's `lib/tui/` design system, so a theme swap re-skins the
+whole chrome. The footer prices a session from DeepSeek's published rates by
+default, and from `bytefly.json` otherwise.
 
-```
-pi --extension ./extensions/bytefly   # load just this extension
-pi -e .                               # load the whole @gavin-hu/my-pi-agent package
-pi install ./                         # install the package
-```
-
-## Tool rendering
-
-How the `run_doctor` call and its result look in the transcript — the call line as a headline and the body indented under it:
-
-<img src="../../assets/tools/run_doctor.png" alt="The run_doctor tool's result: the call line and a one-line, indented doctor summary with a collapsed expand hint" width="100%">
-
-## What it does
-
-The extension owns ten surfaces: the startup header, the footer, the
-user-message marker, the rule between completed turns, the notice block for
-shared transcript notices, the tool-block frame, the live working line, the
-three-section control center, notifications, and the update check.
-
-**Header.** A nameplate: a two-tone half-block mark from the active theme's
-`accent` / `warn` roles, the agent identity (`Pi`, bold, and its version), the
-chrome identity (`enhanced by bytefly` and the package version), a signature
-rule whose `accent` lead sits under the mark, and a grouped help block. The help
-keys resolve live from Pi's keybindings, so a rebound key shows the user's
-chord; the identity and help text are `meta` / `faint` so the mark keeps the
-eye. It opens with a blank row, so the nameplate clears the top edge. It is
-installed only in interactive (`tui`) sessions when Pi's
-`quietStartup` is `true` — the Settings row **Bytefly startup TUI** — and
-`false`, `"header"`, and unset leave Pi's built-in header in place; on terminals
-that cannot render half blocks the mark falls back to a two-tone `Pi` wordmark.
-
-```
- █▀█  Pi v1.2.0
- █▀ █ enhanced by bytefly v0.8.1
- ─────────────────────────────────────────────────
-   escape to interrupt · ctrl+c to clear · ctrl+d to exit (empty)
-   ctrl+o to expand tools · ctrl+t to expand thinking · ctrl+l to select model
-   / commands · ! bash · !! bash (no context) · /bytefly extensions
-```
-
-As the terminal narrows, the identity sheds the chrome marker, then the chrome
-version, then the chrome line, then Pi's marker with the agent name, and the help
-rows drop whole keys, so nothing wraps or clips mid-word. Height sheds the same way: at 28 rows
-all three help groups print, below 28 the middle group (the expand and model
-chords) goes first, below 22 only the `/` commands row survives, and below 16 the
-help block and the leading blank row go, leaving the nameplate and its rule. An
-unknown height keeps the full header. The nameplate sits on the transcript
-margin, which follows Pi's `outputPad` (the value the tool frame and the notice
-use too), and the help hangs one body indent inside it. The mark, tokens,
-identity, and grouped help are tuned in
-[`header/config.ts`](./header/config.ts).
-
-**Footer.** Two lines, each with a left and right zone:
-
-- **Line 1 — identity:** `pwd` and the session name on the left; git state
-  (`⎇ branch · ⑂ worktree`) and the `◉` browse chip on the right.
-- **Line 2 — resources:** the context gauge and usage meters on the left, the
-  child-run roll-up (`↳ 3 · ¥0.12`, present only once a subagent has finished),
-  the mode/alert slot (`≡ plan`) trailing after a `│` when present, and the model
-  and thinking level on the right. The gauge is anchored at column 0, so `%` is
-  always in the same place.
-  The roll-up is its own number, never folded into the session's cost: a subagent
-  runs in its own process, and the footer prices those runs with the same rate
-  table and currency as the session so a currency change moves both. It covers
-  the last 500 child runs of the current process, and starts from zero after
-  `/resume` (the events are not session entries).
-
-```
-~/repo/my-pi-agent                                              ⎇ main · ⑂ smoke
-▰▰▰▰▰▰▱▱▱▱ 62%/200k · ¥0.31 · ↳ 2 · ¥0.06 · ↑42k ↓8.0k · R96k CH 87% │ ≡ plan    opus-4.5 · high
-```
-
-(The examples show the default `¥` symbol. A model that neither `rates` nor the
-built-in table covers contributes nothing in `CNY` mode, so the bar shows no
-figure rather than a guessed one; `USD` mode adds Pi's recorded dollars for that
-record instead — see the currency note under [Configuration](#configuration).)
-
-With no plan mode there is no mode slot, so the `│` is omitted:
-
-```
-~/repo/my-pi-agent                                                    ⎇ main · ⑂ smoke
-▰▰▰▰▰▰▱▱▱▱ 62%/200k · ¥0.31 · ↑42k ↓8.0k · R96k CH 87%             opus-4.5 · high
-```
-
-As the terminal narrows, segments shrink and drop by priority rather than
-clipping. The branch keeps its name and is dropped when the name no longer
-fits, rather than collapsing to a bare glyph:
+## Capabilities
 
-```
-~/repo/project                    ⎇ main · ⑂ smoke
-▰▰▰▰▰▰▱▱▱▱ 62% · ¥0.31 │ ≡ plan    opus-4.5 · high
-```
-
-```
-project   ⎇ main
-62% ≡   opus-4.5
-```
-
-With a named session, the name follows the path and truncates before it drops:
+Status records what a reader can rely on: **Shipped** is in a tagged release, **Unreleased** is complete in the current tree but not yet tagged, and **Partial** has one released part and one unreleased part. Rows are ordered by user value, highest first.
 
-```
-~/repo/project · feature-refac…   ⎇ main
-▰▰▰▰▰▰▱▱▱▱ 62% │ ≡ plan         opus-4.5
-```
+### Chrome
 
-Zero-value meters are omitted, so a fresh session shows only `?/window` instead
-of a row of `¥0.00 · ↑0 ↓0 · R0 W0`. Unknown context usage shows a muted `?`
-with no gauge (known `0%` still draws the empty gauge), so unknown and zero stay
-distinct. Cost keeps the configured precision — the segment drops rather than
-rounding to a misleading `¥0.3` — and a positive amount below one minor unit
-shows as `¥<0.01` rather than `¥0.00`.
-
-DeepSeek needs no config file at all: the bar prices it from the published yuan
-rates and peak tariff built into [`footer/price/config.ts`](./footer/price/config.ts).
-Those tables record the day they were last checked against the published tariff,
-and `doctor` reports how old that is, so a re-pricing shows up as a warning instead
-of a quietly wrong total. A `bytefly.json` can switch to the published dollar table,
-add models of your own, or replace a built-in entry:
-
-```
-~/repo/project                                                          ⎇ main
-▰▰▰▰▰▰▱▱▱▱ 62%/200k · ¥2.50 · ↑42k ↓8.0k · R96k CH 87%             opus-4.5 · high
-```
-
-**Session budget.** `price.budget` puts a threshold under that total, in the same
-currency: when the session's cost reaches it, one `bytefly · Session budget
-reached` notice names what was spent against the budget, and one OS notification
-follows when notify is enabled. It is an alert, not a limit — no turn is blocked or
-aborted — and it fires once per session, on the turn where the crossing becomes
-final (the run settling), because a warning per turn after that is noise. `0`, the
-default, turns it off. The check reads the total the footer already priced, and
-the footer exists only in `tui` sessions, so a print or JSON run has no budget
-alert; the footer's own numbers are visible in every interactive session.
-
-**Unpriced records.** `CNY` has no fallback, so a record for a model with no
-`price.rates` entry contributes nothing to the total — with nothing on screen
-saying so. The footer counts those records on the pass it already prices, and
-one `bytefly · Records with no CNY rate` notice names the count and the two
-fixes: switch `price.currency.code` to `USD` (Pi's catalog is per model, tiers
-included) or add yuan `price.rates` entries. It fires once per session, on the
-run that settles, like the budget alert. `USD` never counts one: Pi's recorded
-amount covers every model.
-
-**User message.** Every user message opens with a two-row `You` nameplate —
-the label over a rule that spans the width — above the message:
-
-```
-You
-────────────────────────────────────
-
-the message the user typed
-```
-
-It is always on in interactive sessions and has no config file. Pi renders a
-user message as Markdown and owns its colors, so bytefly's only lever is a
-`registerMarkdownTransformer`: the nameplate is a single level-2 heading whose
-text is padded so the rule wraps onto the second row, and both rows carry the
-accent because the themes point `mdHeading` at it. The block carries no fill —
-the shipped themes set `userMessageBg` to the terminal default, so it reads like
-the tool blocks. The nameplate is separated from the message by a blank line, so
-the message's own Markdown (a fence, a list, a second paragraph) parses exactly
-as it would without it, and a soft wrap of one long line stays at the margin
-because the renderer wraps it, not bytefly. The label and the rule are tuned
-in [`message/config.ts`](./message/config.ts).
-
-**Working line.** Pi's working row shows a static `Working`, so a long run
-reads the same as a short one. While the row is up, bytefly advances its
-message once a second and hands it back to Pi when the row comes down. Before
-the first tool starts it is a count:
-
-```
-Working… 12s
-```
-
-Once a top-level tool starts, the row becomes a live run line: the tool, how
-many top-level tools this run has started, and the elapsed time.
-
-```
-edit · 3 tools · 12s
-```
-
-A nested tool call (one carrying `parentToolCallId`, such as a codemode script's
-inner call) neither counts nor takes over the line, so the number matches the
-tool blocks in the transcript. The line keeps the last tool name while the
-model streams after it, and a tool event repaints the row immediately instead
-of waiting for the next tick. The line covers the whole run, tool calls
-included. It is tied to the row's visibility: it starts on `turn_start`, stops
-on `agent_end`, and is reset on `session_shutdown`; turns inside one run do not
-restart it, and a retry starts a new run. The words and the interval are tuned
-in [`working/config.ts`](./working/config.ts).
-
-**Turn separator.** After each completed turn the extension appends an inert
-entry and draws a centered receipt rule — `╌╌╌ turn N · duration · N tools ╌╌╌`
-— across the transcript; see [Turn separator](#turn-separator). No config file is
-needed and there is no command.
+| Capability | How | What you get | Status |
+|---|---|---|---|
+| Startup header | `quietStartup` | One two-tone nameplate with the agent and chrome versions and the live help keys, in place of Pi's startup header and resource listing. | Shipped |
+| Two-line footer | every `tui` session | 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 |
+| Priced session total | the `price` section of `bytefly.json` | The session's spend in yuan or dollars, with DeepSeek priced out of the box. | Shipped |
+| Delegated-run cost roll-up | the `↳` footer segment | A finished subagent's cost appears beside the session total, without merging the two ledgers. | Shipped |
+| User-message nameplate | every `tui` session | Each user message opens with a two-row `You` label and rule. | Shipped |
+| Turn receipt | the `bytefly-separator` entry | One rule per completed turn, recording its number, duration, tool count, and outcome. | Shipped |
+| Shared notices | the `my-pi-agent/notice` type | Any extension's notice renders at the transcript margin with a severity-coloured rail. | Shipped |
+| Compaction canvas | the shipped `themes/` palettes | Pi's `/compact` block keeps its content and loses its fill, so it sits on the canvas. | Shipped |
+| Tool-block frame | `registerToolRenderer` | Every tool block leads with its own call line and hangs its result from the transcript rail. | Shipped |
+| Working line | `ctx.ui.setWorkingMessage` | The working row counts seconds, then names the running tool and how many tools the run has started. | Shipped |
+
+### Control center
+
+| Capability | How | What you get | Status |
+|---|---|---|---|
+| 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 |
+| 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 |
+| Health report | `run_doctor`, `/bytefly doctor` | Prerequisites, parse errors, and aged rate tables as text and typed data. | Shipped |
 
-**Notices.** Any extension in the package can post a transcript notice under the
-shared `my-pi-agent/notice` type; bytefly draws it at the transcript's margin —
-a `source · title` headline at the margin, then rail-led rows, each with its own
-severity glyph:
+### Upkeep
 
-```
-job · 2 background jobs finished
-╎ ✓ j1 build · exit 0
-╎ ✕ j2 test · exit 1
+| Capability | How | What you get | Status |
+|---|---|---|---|
+| Currency and peak tariff | `price.currency.code`, `price.peak` | `CNY` and `USD` are separate pricing methods with published rates; DeepSeek's peak windows apply per token record. | Shipped |
+| Session budget alert | `price.budget` | One notice, and one OS notification, when the session total reaches the threshold. | Shipped |
+| Unpriced-record notice | `price.currency.code` | A `CNY` session names the records it could not price, and the two ways to fix it. | Shipped |
+| Desktop notifications | `notify.enabled`, `notify.turnFinished`, `notify.needsInput`, `notify.jobFinished`, `notify.matchFound` | An OS notification when a run settles, the agent needs you, a job finishes, or a watcher matches. | Shipped |
+| Proactive health check | `doctor.proactive` | At session start, when the startup header is on, a hard requirement is probed once and reported before the first turn. | Shipped |
+| Update check | `/bytefly update` | One notice per session lists every package behind, and the header marks a new version. | Shipped |
+| Update action | `/bytefly upgrade` | Pi's own package manager installs the configured packages behind a confirmation, clearing the marker and naming the reload the new version needs. | Unreleased |
+| Pi release notice | `automatic: Pi's release notice` | Pi's own newer version gets the same themed notice and header marker, without a second check. | Shipped |
+
+## Quickstart
+
+```bash
+pi --extension ./extensions/bytefly    # load just this extension
+pi -e .                                # load the whole @gavin-hu/my-pi-agent package
+pi install ./                          # install the package for a user
 ```
 
-The rail is painted by the notice's worst severity, so a failure reads red at the
-edge like an errored tool result, and the headline's title takes the notice's own
-severity — a warning reads yellow where its sentence is, while an `info` or `ok`
-notice stays body text. A row's label stays body text too: its severity is the
-glyph it hangs on, so one failing row never tints the rest of the list.
-
-`job` and `watch` post one when a background job finishes or a watched line
-matches, so the report the model reads is visible too. `doctor` posts one when a
-hard requirement is missing at session start, with a row per finding and the
-command that fixes it:
-
-```
-doctor · 1 missing prerequisite
-╎ ✕ worktree (git) · install git and make sure it is on PATH
+```text
+/bytefly                            # the control center, on Extensions
+/bytefly doctor                     # the report run_doctor returns
 ```
 
-The type and the `NoticeDetails` shape are the shared contract in
-[`lib/notice.ts`](../../lib/notice.ts), and the severity glyphs and item cap
-are tuned in [`notice/config.ts`](./notice/config.ts). Every field is sanitized
-and clipped at the boundary, and a message without `details` keeps Pi's default
-custom-message box.
-
-**Compaction.** `/compact` is Pi's own surface: its summary block is a built-in
-message component, so bytefly cannot replace, hide, or shorten it. The shipped
-themes only remove its fill — `customMessageBg` is the terminal default — and
-paint the `[compaction]` label in the accent, so the block sits on the canvas
-like the rest of the transcript. Pi's branch summaries and skill invocations
-share the same tokens.
-
-<img src="../../assets/compaction.png" alt="The /compact summary block: a [compaction] label, the compacted token count, and the summary Markdown on the terminal canvas, with no background band" width="100%">
+## Tool
 
-**Tool blocks.** Every tool block leads with the tool's own call line as the
-headline — the tool name in the theme's tool-title colour — and its result body
-sits two columns in directly beneath it, led by the transcript rail, instead of
-Pi's filled status background:
-
-```
-read src/app.ts
-╎ const answer = 42;
-```
+<img src="../../assets/tools/run_doctor.png" alt="The run_doctor tool's result: the call line and a one-line, indented doctor summary with a collapsed expand hint" width="100%">
 
-The two tools that mutate a file, `edit` and `write`, carry their result on the
-call body — the edit diff, the written file content — so that body is railed
-like any other result. There is no status band: the diff's own red/green line
-colours, with the changed words in reverse video, and the `edit` / `write`
-headline are what mark a file change.
+`run_doctor` — `exposure: "direct"` (the default), `executionMode: "sequential"`,
+read-only, closed-world. It reports whether each extension has what it needs at
+runtime — binaries on `PATH`, optional packages and browsers, login and state
+files, and config files that fail to parse — and it probes and changes nothing.
+Its `readOnlyHint` is what the shared default-deny policy in `lib/policy.ts`
+reads to allow it in plan mode.
 
-A `registerToolRenderer` resolver switches the row to `renderShell: "self"`,
-leaves the call's own first line as the headline, and indents the rest of the
-call and the whole result under it. A shell call's `$` / `>` prompt becomes the
-tool name and the command is repainted in the body colour, and a primary subject
-(a path, URL, query, pattern) is demoted to the body colour too, so the name is
-the call line's only accent (`bash bun run check`, `read src/app.ts`). The
-tool's own
-`renderCall`/`renderResult` are passed through, so syntax highlighting, diffs,
-previews, and truncation notices are unchanged — only the frame is bytefly's.
-The body carries the transcript rail, painted by status (a running result takes
-the accent, a failure red, a finished one neutral) and drawn with the glyph from
-the `chrome.rail` setting. A result frame is always railed; a call frame is railed
-only for `edit` and `write`, whose call body carries the result — every other
-call's headline and continuation lines stay plain-indented. Package renderers
-clip a call to one physical line (middle clip for a path or URL), so it cannot
-leak into the body column; Pi's own renderers still wrap, and the frame keeps a
-wrapped continuation unrailed and loses the accent there too, with the rail
-beginning at the result underneath. A rejected call renders as one sanitized
-`error` line in the error role; a running tool shows a live elapsed label, and a
-finished long call appends its duration. A tool with
-no renderer of its own is framed around a generic call/result fallback, whose
-call line reads like a built-in — the leading string argument bare, the rest as
-trailing options (`open_path src/app.ts`) — rather than dumping raw `key=value`
-pairs. A tool that draws its own shell (`edit`) is framed too:
-`renderShell: "self"` only tells Pi not to draw its box around the renderer, so
-its diff would otherwise sit at the wrong indent; the frame drops the blank
-edges its own `Box` pads itself with, and hands it a theme whose `bg` is inert so
-it never paints a band the rest of the transcript does not have.
-
-The call line is one colour grammar, shared with Pi's built-ins: the tool name is
-`toolTitle` and bold and is the line's only accent; a primary subject (a query, a
-URL, a path, a status) reads in the body role (`label`), counts and summaries are
-`muted`, trailing options are `dim`, and the result body is `toolOutput`. The
-shipped themes point `toolTitle` at the accent and `label` at the body colour, so
-the name is the call line's one accent and the subject follows as body text; a
-theme that maps `toolTitle` elsewhere is respected rather than overridden.
+| Parameter | Type | Meaning |
+|---|---|---|
+| `extension` | string, optional | Report a single extension instead of every extension. |
+| `refresh` | boolean, optional | Ignore the findings cached earlier in this session and probe again. |
 
-**Control center.** `/bytefly [extension] [refresh]` opens a keyboard-driven
-dock list of every Pi extension the session resolves — across personal settings
-and, when trusted, the project — one row per extension with its enable checkbox
-and its worst-severity health, and writes a `+pattern` / `-pattern` toggle into
-the matching `settings.json`. `←`/`→` switch to Settings, which lists the
-preferences this package and Pi expose: bytefly startup TUI, desktop notifications,
-the transcript rail glyph, output padding, and the hardware cursor. The focused
-extension's findings, or the focused setting's source and target file, sit
-underneath, and `run_doctor` returns the same report as text and typed data.
-Only a missing
-*hard* requirement posts a notice at session start; everything else waits in the
-report.
-See [The control center](#the-control-center).
-
-**Notify.** Off by default, one `notify` section in `bytefly.json` turns on OS
-notifications for unattended runs: when a full agent run settles, when a
-background job finishes, when the agent opens a prompt asking for input, and when
-an armed `watch` wake match fires as the agent becomes idle. The
-method follows the terminal (OSC 777, OSC 99, a Windows toast) or falls back to
-the platform notifier (`osascript`, `notify-send`); see
-[Notifications](#notifications).
-
-**Update check.** In the background at an interactive session's start, Pi's
-package manager reports which configured packages are behind. bytefly suppresses
-Pi's own startup block, caches the snapshot in `<agentDir>/bytefly/update.json`
-with the time it was read, and posts one transcript notice listing every package
-plus `pi update --extensions`. This package's new version alone puts `↑0.12.0`
-after the header's chrome version and adds its release URL to the notice. A
-session inside the 24-hour window reuses the cache without a package-manager
-call, and `/bytefly update` re-runs the check on demand. Pi's own newer release
-is drawn the same way: Pi resolves it from `pi.dev` and would draw `Update
-Available`, and bytefly patches the method that draws it, so the release becomes
-a notice naming `pi update` and the changelog and marks `Pi v1.3.0 ↑1.4.0` on
-the agent line. `PI_OFFLINE` uses the cached marker with no notice, only `tui`
-starts the background check, and a failed read is silent and not cached, so the
-next session tries again; see [Update check](#update-check).
+Result (`details` / `structuredContent`): `{ headline, missing, degraded, extensions }`,
+one finding per check with its `check`, `severity`, `detail`, and optional `hint`.
+The same report is what `/bytefly doctor` prints, and what
+[the control center](#the-control-center) draws.
 
 ## Commands
 
+One command runs the screen, prints the report, and re-checks updates:
+
 | Command | What it does |
 |---|---|
 | `/bytefly [extension] [refresh]` | Open the control center on Extensions. In `tui` it mounts a docked list; every other mode prints the grouped listing, or one extension's full findings when named. |
@@ -356,9 +98,11 @@ next session tries again; see [Update check](#update-check).
 | `/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. |
+| `/bytefly upgrade` | Install what the check found, behind a confirmation: Pi's own package manager updates every configured package, the marker is re-read, and one line reports the result and the reload it needs. `PI_OFFLINE` and a pinned npm version skip the work. It resolves no packages and mounts no screen. |
 
 Tab completes the subcommands, extension names after `doctor`, and `refresh`;
-`/bytefly settings`, `/bytefly skills`, and `/bytefly update` take no name.
+`/bytefly settings`, `/bytefly skills`, `/bytefly update`, and `/bytefly upgrade`
+take no name.
 
 ## Behaviour by mode
 
@@ -387,20 +131,20 @@ print/JSON/RPC run gets an OS-level notification or none.
 Two things are JSON: the transcript rail's glyph (`chrome.rail`, default `╎`,
 read at `session_start`/`session_tree`) and this extension's three config
 sections — `price`, `notify`, and `doctor`. Everything else about the look is
-tuned in code: the header in [`header/config.ts`](./header/config.ts) (mark and
+tuned in code: the header in [`header/config.ts`](../../extensions/bytefly/header/config.ts) (mark and
 identity tokens, tagline, grouped help), the footer in
-[`footer/config.ts`](./footer/config.ts) (thresholds, gauge glyphs and widths,
+[`footer/config.ts`](../../extensions/bytefly/footer/config.ts) (thresholds, gauge glyphs and widths,
 separators, icons, status keys), and the turn separator in
-[`separator/config.ts`](./separator/config.ts) (glyph, label prefix, padding,
+[`separator/config.ts`](../../extensions/bytefly/separator/config.ts) (glyph, label prefix, padding,
 minimum duration, outcome wording, colors).
 
 Every key of every section is listed with its type, default, and bounds in
-[`docs/configuration.md`](../../docs/configuration.md); this section
+[`docs/configuration.md`](../configuration.md); this section
 covers what that table cannot — when each section is read, and what the cost
 does when no rate matches.
 
 `bytefly.json` is one shared document with a top-level section per extension (see
-[Configuration](../../docs/configuration.md)). It is read from the global
+[Configuration](../configuration.md)). It is read from the global
 document, then `<cwd>/.pi/bytefly.json`, project winning. The old per-extension
 files (`document.json`, `jobs.json`, …) are no longer read; `bun run config:migrate`
 moves them into the shared document.
@@ -477,13 +221,140 @@ the model reads the same sentence.
 - The extension screen registers no model-facing tool; toggling writes only
   through Pi's `settings.json`, and `run_doctor` is read-only.
 
+## Startup header
+
+A nameplate: a two-tone half-block mark from the active theme's `accent` /
+`warn` roles, the agent identity (`Pi`, bold, and its version), the chrome
+identity (`enhanced by bytefly` and the package version), a signature rule whose
+`accent` lead sits under the mark, and a grouped help block. The help keys
+resolve live from Pi's keybindings, so a rebound key shows the user's chord; the
+identity and help text are `meta` / `faint` so the mark keeps the eye. It opens
+with a blank row, so the nameplate clears the top edge. It is installed only in
+interactive (`tui`) sessions when Pi's `quietStartup` is `true` — the Settings
+row **Bytefly startup TUI** — and `false`, `"header"`, and unset leave Pi's
+built-in header in place; on terminals that cannot render half blocks the mark
+falls back to a two-tone `Pi` wordmark.
+
+```
+ █▀█  Pi v1.2.0
+ █▀ █ enhanced by bytefly v0.8.1
+ ─────────────────────────────────────────────────
+   escape to interrupt · ctrl+c to clear · ctrl+d to exit (empty)
+   ctrl+o to expand tools · ctrl+t to expand thinking · ctrl+l to select model
+   / commands · ! bash · !! bash (no context) · /bytefly extensions
+```
+
+As the terminal narrows, the identity sheds the chrome marker, then the chrome
+version, then the chrome line, then Pi's marker with the agent name, and the help
+rows drop whole keys, so nothing wraps or clips mid-word. Height sheds the same way: at 28 rows
+all three help groups print, below 28 the middle group (the expand and model
+chords) goes first, below 22 only the `/` commands row survives, and below 16 the
+help block and the leading blank row go, leaving the nameplate and its rule. An
+unknown height keeps the full header. The nameplate sits on the transcript
+margin, which follows Pi's `outputPad` (the value the tool frame and the notice
+use too), and the help hangs one body indent inside it. The mark, tokens,
+identity, and grouped help are tuned in
+[`header/config.ts`](../../extensions/bytefly/header/config.ts).
+
+## Content and colors
+
+Two lines, each with a left and right zone:
+
+- **Line 1 — identity:** `pwd` and the session name on the left; git state
+  (`⎇ branch · ⑂ worktree`) and the `◉` browse chip on the right.
+- **Line 2 — resources:** the context gauge and usage meters on the left, the
+  child-run roll-up (`↳ 3 · ¥0.12`, present only once a subagent has finished),
+  the mode/alert slot (`≡ plan`) trailing after a `│` when present, and the model
+  and thinking level on the right. The gauge is anchored at column 0, so `%` is
+  always in the same place.
+  The roll-up is its own number, never folded into the session's cost: a subagent
+  runs in its own process, and the footer prices those runs with the same rate
+  table and currency as the session so a currency change moves both. It covers
+  the last 500 child runs of the current process, and starts from zero after
+  `/resume` (the events are not session entries).
+
+```
+~/repo/my-pi-agent                                              ⎇ main · ⑂ smoke
+▰▰▰▰▰▰▱▱▱▱ 62%/200k · ¥0.31 · ↳ 2 · ¥0.06 · ↑42k ↓8.0k · R96k CH 87% │ ≡ plan    opus-4.5 · high
+```
+
+(The examples show the default `¥` symbol. A model that neither `rates` nor the
+built-in table covers contributes nothing in `CNY` mode, so the bar shows no
+figure rather than a guessed one; `USD` mode adds Pi's recorded dollars for that
+record instead — see [Cost calculation](#cost-calculation).)
+
+With no plan mode there is no mode slot, so the `│` is omitted:
+
+```
+~/repo/my-pi-agent                                                    ⎇ main · ⑂ smoke
+▰▰▰▰▰▰▱▱▱▱ 62%/200k · ¥0.31 · ↑42k ↓8.0k · R96k CH 87%             opus-4.5 · high
+```
+
+As the terminal narrows, segments shrink and drop by priority rather than
+clipping. The branch keeps its name and is dropped when the name no longer
+fits, rather than collapsing to a bare glyph:
+
+```
+~/repo/project                    ⎇ main · ⑂ smoke
+▰▰▰▰▰▰▱▱▱▱ 62% · ¥0.31 │ ≡ plan    opus-4.5 · high
+```
+
+```
+project   ⎇ main
+62% ≡   opus-4.5
+```
+
+With a named session, the name follows the path and truncates before it drops:
+
+```
+~/repo/project · feature-refac…   ⎇ main
+▰▰▰▰▰▰▱▱▱▱ 62% │ ≡ plan         opus-4.5
+```
+
+Zero-value meters are omitted, so a fresh session shows only `?/window` instead
+of a row of `¥0.00 · ↑0 ↓0 · R0 W0`. Unknown context usage shows a muted `?`
+with no gauge (known `0%` still draws the empty gauge), so unknown and zero stay
+distinct. Cost keeps the configured precision — the segment drops rather than
+rounding to a misleading `¥0.3` — and a positive amount below one minor unit
+shows as `¥<0.01` rather than `¥0.00`.
+
+Each segment reads a theme role and carries its own drop order:
+
+| Segment | Line / zone | Color | Drops |
+|---|---|---|---|
+| pwd | 1 left | dim | last |
+| session | 1 left | muted, bracketed | after worktree |
+| browse | 1 right | success glyph + accent port | first |
+| branch | 1 right | muted (warning when detached) | last |
+| worktree | 1 right | success | first |
+| context gauge + `%` | 2 left | muted ≤70 · warning 71–90 · error >90 | never |
+| `/window` | 2 left | dim | before cost |
+| cost | 2 left | muted | after tokens |
+| tokens `↑in ↓out` | 2 left | dim | after cache |
+| cache `R… CH …%` | 2 left | dim | first |
+| statuses | 2 left | as emitted by each extension | before the model clips |
+| model | 2 right | accent | never |
+| thinking level | 2 right | thinking token | before cost |
+
+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.
+
 ## Cost calculation
 
 Pi prices every model call from its bundled catalog in USD, and the provider API
 never returns a price. The footer can total that catalog directly, or replace
 it with its own rates for the models they match:
 
-- **Which built-in rates.** [`footer/price/config.ts`](./footer/price/config.ts) ships DeepSeek's published
+- **Which built-in rates.** [`footer/price/config.ts`](../../extensions/bytefly/footer/price/config.ts) ships DeepSeek's published
   yuan prices for `CNY` and its published dollar prices for `USD`, per model, with
   the peak schedule that doubles the price during peak hours
   ([DeepSeek's pricing page](https://api-docs.deepseek.com/quick_start/pricing)).
@@ -514,41 +385,66 @@ it with its own rates for the models they match:
   leaves out; `USD` adds Pi's recorded dollar amount for that record, because
   that number is already dollars and already per model.
 
+DeepSeek needs no config file at all: the bar prices it from the published yuan
+rates and peak tariff built into [`footer/price/config.ts`](../../extensions/bytefly/footer/price/config.ts).
+Those tables record the day they were last checked against the published tariff,
+and `doctor` reports how old that is, so a re-pricing shows up as a warning instead
+of a quietly wrong total. A `bytefly.json` can switch to the published dollar table,
+add models of your own, or replace a built-in entry:
+
+```
+~/repo/project                                                          ⎇ main
+▰▰▰▰▰▰▱▱▱▱ 62%/200k · ¥2.50 · ↑42k ↓8.0k · R96k CH 87%             opus-4.5 · high
+```
+
+`price.budget` puts a threshold under that total, in the same currency: when the
+session's cost reaches it, one `bytefly · Session budget reached` notice names
+what was spent against the budget, and one OS notification follows when notify
+is enabled. It is an alert, not a limit — no turn is blocked or aborted — and it
+fires once per session, on the turn where the crossing becomes final (the run
+settling), because a warning per turn after that is noise. `0`, the default,
+turns it off. The check reads the total the footer already priced, and the
+footer exists only in `tui` sessions, so a print or JSON run has no budget
+alert; the footer's own numbers are visible in every interactive session.
+
+`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.
+
 For example, DeepSeek flash at `¥2` in and `¥8` out per million, with the
 published peak windows and `offPeakMultiplier: 0.5`, prices a 1M-in + 1M-out
 turn at `¥10.00` at peak and `¥5.00` off-peak. That example is worked end to end
-in [`footer/footer.test.ts`](./footer/footer.test.ts), which also prices the built-in
+in [`footer/footer.test.ts`](../../extensions/bytefly/footer/footer.test.ts), which also prices the built-in
 table with no config file at all.
 
-## Content and colors
+## The user-message nameplate
 
-| Segment | Line / zone | Color | Drops |
-|---|---|---|---|
-| pwd | 1 left | dim | last |
-| session | 1 left | muted, bracketed | after worktree |
-| browse | 1 right | success glyph + accent port | first |
-| branch | 1 right | muted (warning when detached) | last |
-| worktree | 1 right | success | first |
-| context gauge + `%` | 2 left | muted ≤70 · warning 71–90 · error >90 | never |
-| `/window` | 2 left | dim | before cost |
-| cost | 2 left | muted | after tokens |
-| tokens `↑in ↓out` | 2 left | dim | after cache |
-| cache `R… CH …%` | 2 left | dim | first |
-| statuses | 2 left | as emitted by each extension | before the model clips |
-| model | 2 right | accent | never |
-| thinking level | 2 right | thinking token | before cost |
+Every user message opens with a two-row `You` nameplate — the label over a rule
+that spans the width — above the message:
 
-The worktree status is read from the `worktree` status key, so the
-[worktree](../worktree/) extension and the bar agree. The browse chip is read
-from the `browse` status key published by [file-browse](../file-browse/) while
-its server runs, and shows the two-tone `◉ <port>` (green glyph, accent port).
-The trailing slot shows plan-style alerts when present and is omitted otherwise;
-a plan chip's trailing plan file name is dropped, so the slot reads `≡ plan`
-even though the built-in footer keeps the name. An alert (a failed job) sorts to
-the front of the slot. The slot trails the meters after a `│`, so the context
-gauge always starts the line. It keeps each extension's own colour when it
-compacts, and it is droppable: a tight bar drops the slot rather than truncating
-the model, which sits at the end of the line.
+```
+You
+────────────────────────────────────
+
+the message the user typed
+```
+
+It is always on in interactive sessions and has no config file. Pi renders a
+user message as Markdown and owns its colors, so bytefly's only lever is a
+`registerMarkdownTransformer`: the nameplate is a single level-2 heading whose
+text is padded so the rule wraps onto the second row, and both rows carry the
+accent because the themes point `mdHeading` at it. The block carries no fill —
+the shipped themes set `userMessageBg` to the terminal default, so it reads like
+the tool blocks. The nameplate is separated from the message by a blank line, so
+the message's own Markdown (a fence, a list, a second paragraph) parses exactly
+as it would without it, and a soft wrap of one long line stays at the margin
+because the renderer wraps it, not bytefly. The label and the rule are tuned
+in [`message/config.ts`](../../extensions/bytefly/message/config.ts).
 
 ## Turn separator
 
@@ -589,11 +485,143 @@ and outcome as the width allows.
   rule; disable the whole extension with `bytefly` instead.
 - There is no runtime command; the glyph, label prefix, padding, colors, and
   minimum duration are tuned in
-  [`separator/config.ts`](./separator/config.ts).
+  [`separator/config.ts`](../../extensions/bytefly/separator/config.ts).
+
+## Notices
+
+Any extension in the package can post a transcript notice under the shared
+`my-pi-agent/notice` type; bytefly draws it at the transcript's margin — a
+`source · title` headline at the margin, then rail-led rows, each with its own
+severity glyph:
+
+```
+job · 2 background jobs finished
+╎ ✓ j1 build · exit 0
+╎ ✕ j2 test · exit 1
+```
+
+The rail is painted by the notice's worst severity, so a failure reads red at the
+edge like an errored tool result, and the headline's title takes the notice's own
+severity — a warning reads yellow where its sentence is, while an `info` or `ok`
+notice stays body text. A row's label stays body text too: its severity is the
+glyph it hangs on, so one failing row never tints the rest of the list.
+
+`job` and `watch` post one when a background job finishes or a watched line
+matches, so the report the model reads is visible too. `doctor` posts one when a
+hard requirement is missing at session start, with a row per finding and the
+command that fixes it:
+
+```
+doctor · 1 missing prerequisite
+╎ ✕ worktree (git) · install git and make sure it is on PATH
+```
+
+Only a missing *hard* requirement posts a notice at session start; everything
+else waits in the report.
+
+The type and the `NoticeDetails` shape are the shared contract in
+[`lib/notice.ts`](../../lib/notice.ts), and the severity glyphs and item cap
+are tuned in [`notice/config.ts`](../../extensions/bytefly/notice/config.ts). Every field is sanitized
+and clipped at the boundary, and a message without `details` keeps Pi's default
+custom-message box.
+
+## Compaction
+
+`/compact` is Pi's own surface: its summary block is a built-in message
+component, so bytefly cannot replace, hide, or shorten it. The shipped themes
+only remove its fill — `customMessageBg` is the terminal default — and paint the
+`[compaction]` label in the accent, so the block sits on the canvas like the
+rest of the transcript. Pi's branch summaries and skill invocations share the
+same tokens.
+
+<img src="../../assets/screens/compaction.png" alt="The /compact summary block: a [compaction] label, the compacted token count, and the summary Markdown on the terminal canvas, with no background band" width="100%">
+
+## Tool blocks
+
+Every tool block leads with the tool's own call line as the headline — the tool
+name in the theme's tool-title colour — and its result body sits two columns in
+directly beneath it, led by the transcript rail, instead of Pi's filled status
+background:
+
+```
+read src/app.ts
+╎ const answer = 42;
+```
+
+The two tools that mutate a file, `edit` and `write`, carry their result on the
+call body — the edit diff, the written file content — so that body is railed
+like any other result. There is no status band: the diff's own red/green line
+colours, with the changed words in reverse video, and the `edit` / `write`
+headline are what mark a file change.
+
+A `registerToolRenderer` resolver switches the row to `renderShell: "self"`,
+leaves the call's own first line as the headline, and indents the rest of the
+call and the whole result under it. A shell call's `$` / `>` prompt becomes the
+tool name and the command is repainted in the body colour, and a primary subject
+(a path, URL, query, pattern) is demoted to the body colour too, so the name is
+the call line's only accent (`bash bun run check`, `read src/app.ts`). The
+tool's own
+`renderCall`/`renderResult` are passed through, so syntax highlighting, diffs,
+previews, and truncation notices are unchanged — only the frame is bytefly's.
+The body carries the transcript rail, painted by status (a running result takes
+the accent, a failure red, a finished one neutral) and drawn with the glyph from
+the `chrome.rail` setting. A result frame is always railed; a call frame is railed
+only for `edit` and `write`, whose call body carries the result — every other
+call's headline and continuation lines stay plain-indented. Package renderers
+clip a call to one physical line (middle clip for a path or URL), so it cannot
+leak into the body column; Pi's own renderers still wrap, and the frame keeps a
+wrapped continuation unrailed and loses the accent there too, with the rail
+beginning at the result underneath. A rejected call renders as one sanitized
+`error` line in the error role; a running tool shows a live elapsed label, and a
+finished long call appends its duration. A tool with
+no renderer of its own is framed around a generic call/result fallback, whose
+call line reads like a built-in — the leading string argument bare, the rest as
+trailing options (`open_path src/app.ts`) — rather than dumping raw `key=value`
+pairs. A tool that draws its own shell (`edit`) is framed too:
+`renderShell: "self"` only tells Pi not to draw its box around the renderer, so
+its diff would otherwise sit at the wrong indent; the frame drops the blank
+edges its own `Box` pads itself with, and hands it a theme whose `bg` is inert so
+it never paints a band the rest of the transcript does not have.
+
+The call line is one colour grammar, shared with Pi's built-ins: the tool name is
+`toolTitle` and bold and is the line's only accent; a primary subject (a query, a
+URL, a path, a status) reads in the body role (`label`), counts and summaries are
+`muted`, trailing options are `dim`, and the result body is `toolOutput`. The
+shipped themes point `toolTitle` at the accent and `label` at the body colour, so
+the name is the call line's one accent and the subject follows as body text; a
+theme that maps `toolTitle` elsewhere is respected rather than overridden.
+
+## The working line
+
+Pi's working row shows a static `Working`, so a long run reads the same as a
+short one. While the row is up, bytefly advances its message once a second and
+hands it back to Pi when the row comes down. Before the first tool starts it is
+a count:
+
+```
+Working… 12s
+```
+
+Once a top-level tool starts, the row becomes a live run line: the tool, how
+many top-level tools this run has started, and the elapsed time.
+
+```
+edit · 3 tools · 12s
+```
+
+A nested tool call (one carrying `parentToolCallId`, such as a codemode script's
+inner call) neither counts nor takes over the line, so the number matches the
+tool blocks in the transcript. The line keeps the last tool name while the
+model streams after it, and a tool event repaints the row immediately instead
+of waiting for the next tick. The line covers the whole run, tool calls
+included. It is tied to the row's visibility: it starts on `turn_start`, stops
+on `agent_end`, and is reset on `session_shutdown`; turns inside one run do not
+restart it, and a retry starts a new run. The words and the interval are tuned
+in [`working/config.ts`](../../extensions/bytefly/working/config.ts).
 
 ## The control center
 
-<img src="../../assets/bytefly.png" alt="The /bytefly control center: the Extensions, Skills, and Settings section bar with the `Global · 10 extensions · 2 off · 1 missing` counts, one checkbox row per extension with its verdict, the focused extension's report, and the key hints" width="100%">
+<img src="../../assets/screens/bytefly.png" alt="The /bytefly control center: 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
@@ -681,14 +709,14 @@ enable list this screen's checkbox rows can write. Themes stay with `pi config`;
 `ROADMAP.md` carries the reason under *Deliberately left thin*.
 
 **Settings.** The third section uses the same frame and the same `Tab` scope
-switch, with its own cursor. It is the shortlist a session changes: thirteen
+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 · 13 settings
+  Extensions · Skills · Settings                    Global · 12 settings
 
 ❯ ◻ Bytefly startup TUI  Off
   ◼ Theme  system
@@ -711,7 +739,7 @@ Bytefly ────────────────────────
 ──────────────────────────────────────────────────────────────────────
 ```
 
-<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%">
+<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 |
 |---|---|---|
@@ -755,17 +783,17 @@ shows where the value comes from — `Global · ~/.pi/agent/bytefly.json`, `Proj
 — even when the terminal is too short for the detail body — and closing offers
 the same reload confirm as an extension or skill toggle.
 
-The list is capped at thirteen rows so the screen keeps fitting a 24-row
+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
 ceiling). Everything else stays in `bytefly.json` — the tuning numbers, the
 cosmetic labels, and the Pi preferences Pi's own `/settings` owns — and
 `test/settings-coverage.test.ts` keeps the split honest: every loader key is
-either a row or a declared JSON-only edit with the reason it left. Six
-`bytefly.json` sections therefore have no row at all (`chrome`, `goal`, `plan`,
-`watch`, `worktree`, `memory`), as do `notify.title`, `doctor.timeoutMs`,
+either a row or a declared JSON-only edit with the reason it left. Most
+`bytefly.json` sections therefore have no row at all — `chrome`, `goal`, `watch`,
+`worktree`, and `memory` among them — just as `notify.title`, `doctor.timeoutMs`,
 `price.currency.decimals`, `rewind.max`, `rewind.safetySnapshot`,
 `job.detachedByDefault`, and `watch.wakeOnMatch` inside sections that do. Each is
-documented in [`docs/configuration.md`](../../docs/configuration.md).
+documented in [`docs/configuration.md`](../configuration.md).
 
 Two of the five sections belong to other extensions (`rewind` and `job`). The
 screen cannot import their normalizers, so it reports the leaf as
@@ -780,7 +808,7 @@ with `true` or `false`.
 
 App rows are **Global only**: Pi's setters for them write the personal
 `settings.json`, and only resource paths have public project setters. Project
-scope therefore lists the eleven `bytefly.json` rows and a
+scope therefore lists the ten `bytefly.json` rows and a
 `App settings are Global only.` note rather than promising a write that cannot
 happen. A `bytefly.json` row writes one leaf in the selected scope (a depth-1
 key, or a nested one such as `price.currency.code`) through a per-key writer, so
@@ -792,7 +820,7 @@ The non-`tui` form prints the headline and one `Label: Value` row per line, in
 screen order:
 
 ```
-bytefly: Settings · Global · 13 settings
+bytefly: Settings · Global · 12 settings
   Bytefly startup TUI: Off
   Theme: bytefly-dark
   Desktop notifications: On
@@ -884,10 +912,10 @@ the same entry in `lib/requirements.ts`, so the two cannot drift.
 
 ## Notifications
 
-The notify capability exists for unattended runs: start a long turn, leave the
-terminal, and get a desktop notification when Pi needs you — or when it is done.
-It fires on four events, each independently switchable in the `notify` section
-of `bytefly.json` (see [Configuration](#configuration)):
+The notify capability is off by default and exists for unattended runs: start a
+long turn, leave the terminal, and get a desktop notification when Pi needs you
+— or when it is done. It fires on four events, each independently switchable in
+the `notify` section of `bytefly.json` (see [Configuration](#configuration)):
 
 - **A run settled** (`agent_settled`). Pi finished the turn and waits for the
   next message. An aborted run is skipped: interrupting with Escape means the
@@ -896,10 +924,10 @@ of `bytefly.json` (see [Configuration](#configuration)):
   `ask_user_question`, a plan review, a subagent approval. A prompt opened while
   idle is a command the user just typed, so it does not fire; the run boundary
   is what separates "the agent is asking" from "the user is asking".
-- **A background job finished.** The [job](../job/) extension announces each
+- **A background job finished.** The [job](./job.md) extension announces each
   terminal transition on the shared `pi.events` bus
   (`my-pi-agent/job-finished`); bytefly listens and never imports it.
-- **A watcher matched.** A [watch](../watch/) whose `wake` is on matched, and
+- **A watcher matched.** A [watch](./watch.md) whose `wake` is on matched, and
   announced it on `my-pi-agent/watch-match` with the cycle's
   count, the watcher, and its newest line. The body names that line, sanitized and
   clipped to 80 characters, because the line is the alert: a watch usually tails a
@@ -1018,17 +1046,27 @@ release without a restart. Opening the control center never checks: the screen h
 no update surface, and the only request paths are `session_start` and this
 command.
 
+`/bytefly upgrade` is the half that writes. It asks for a confirmation and then
+calls the package manager's own `update()`: the same manager that reads the
+packages configured in `settings.json`, owns the install root, and honours a
+project's `npmCommand`, so no shell and no `pi update` command is involved. Pi
+skips a pinned npm version, and `PI_OFFLINE` skips the whole path. The manager
+returns nothing, so the answer is a re-read of what is left: `every configured
+package is updated — reload to use the new version`, or a warning when a package
+is still behind after a successful run; a failed install prints the manager's own
+message. The running session keeps the old code loaded until it reloads, which is
+why the line says so, and each source the manager reports is shown while it runs.
+
 ## Limitations
 
 - **Bytefly startup TUI is the startup surface only.** It installs or removes
   bytefly's startup header and the proactive doctor notice; the footer, turn
   rule, and transcript renderers stay on. Use `PI_DISABLED_EXTENSIONS=bytefly`
   (or `pi config`) to turn off all of bytefly.
-- **App settings are Global only.** Pi's setters for preferences such as
-  `quietStartup` (the **Bytefly startup TUI** row), `outputPad`,
-  `showHardwareCursor`, and `theme` write the personal `settings.json`; the
-  screen hides those rows in Project scope rather than writing a file Pi cannot
-  manage.
+- **App settings are Global only.** Pi's setters for the two app preferences
+  the screen carries — `quietStartup` (the **Bytefly startup TUI** row) and
+  `theme` — write the personal `settings.json`; the screen hides those rows in
+  Project scope rather than writing a file Pi cannot manage.
 - **The Theme row offers only this package's palettes.** `system`,
   `bytefly-dark`, and `bytefly-light` are the whole cycle; Pi's built-ins and any
   user, project, or other package's theme stay in Pi's `/settings` → **Theme**,
@@ -1041,7 +1079,7 @@ command.
 - **The list is a shortlist, not the whole document.** A row is one boolean,
   enum, string, or number; the tuning numbers, the labels, and the Pi
   preferences `/settings` owns stay in their files, and the catalogue is capped
-  at thirteen rows so the screen fits a 24-row terminal. `doctor.skip` (an
+  at twelve rows so the screen fits a 24-row terminal. `doctor.skip` (an
   array), the `rates` table, and `price.peak` (a nested object) could never be a
   row; the rest are declared JSON-only with their reason in
   `test/settings-coverage.test.ts`.
@@ -1049,16 +1087,18 @@ command.
   because a two-column glyph would push every railed body one cell right; the
   loader drops anything else, and the former four-glyph menu is the
   configuration reference's example list.
-- **`doctor`, `settings`, `skills`, and `update` are reserved first arguments.**
-  `/bytefly doctor` always selects the report, so an extension literally named
-  `doctor` cannot be narrowed to by name; `settings`, `skills`, and `update` are
-  reserved the same way.
+- **`doctor`, `settings`, `skills`, `update`, and `upgrade` are reserved first
+  arguments.** `/bytefly doctor` always selects the report, so an extension
+  literally named `doctor` cannot be narrowed to by name; `settings`, `skills`,
+  `update`, and `upgrade` are reserved the same way.
 - **The picker manages the `extensions` and `skills` resource types.** Prompts
   and themes stay with Pi's own `pi config`.
 - **Built-in extensions are not listed** (`builtin:mcp`, `builtin:codemode`, …):
   their authoritative names are not exposed to extensions. Use `pi config`.
-- **Packages are not installed, removed, or updated here**; use `pi install`,
-  `pi remove`, and `pi update`.
+- **Nothing is installed or removed here.** `/bytefly upgrade` runs Pi's own
+  update for the packages configured in `settings.json`; adding a package is
+  still `pi install`, removing one is `pi remove`, and Pi itself is still
+  `pi update`.
 - **The update list is Pi's.** Only packages configured in `settings.json` are
   checked; `pi -e .`, a temporary checkout, and other unmanaged loads get no
   update prompt. The version arrow and release URL still come from npm's
@@ -1077,7 +1117,9 @@ command.
   restores both on shutdown. A future Pi that changes either method shape makes
   that shim inert, and Pi's own block can come back.
 - **No auto-update, and the release URL is text only.** The notice names a
-  command instead of running one, and the notice renderer cannot open a link, so
+  command instead of running one; the only path that writes is `/bytefly
+  upgrade`, and it waits for a confirmation. The notice renderer cannot open a
+  link, so
   the release row prints the URL and nothing more — no changelog body, no way to
   click through from the transcript. Pi's optional release note arrives as one
   sanitized `release notes` row, so a multi-paragraph note is flattened and
@@ -1147,7 +1189,7 @@ command.
   `bytefly.json`.
 - No per-model cost breakdown and no on-screen marker for which tariff or
   which source produced a number.
-- No todo-count segment; the [todo](../todo/) widget already shows progress.
+- No todo-count segment; the [todo](./todo.md) widget already shows progress.
 - No shelling out for git ahead/behind; the footer data provider exposes only
   the branch.
 - No session or model data in the header: it shows the nameplate and the grouped
@@ -1187,12 +1229,12 @@ rather than showing a wrong value.
 | Notifications | `agent_settled` (skipped when aborted), `ui_prompt_start` only while `agent_start`…`agent_settled` marks a run active, and `my-pi-agent/job-finished` on `pi.events`; the `notify` section of `bytefly.json` gates each. Delivery writes an OSC 777/99 sequence to stdout or spawns `osascript`, `notify-send`, or `powershell.exe`. The bus subscription is created in `session_start` and released in `session_shutdown`, and the `job` extension never imports bytefly. |
 | Picker discovery | `SettingsManager.create(...)` plus `DefaultPackageManager.resolve({ onMissing: "skip" })`, both public exports; both views drop `bytefly`'s own entrypoint. |
 | Picker writes | `SettingsManager` setters (`setExtensionPaths`, `setPackages`, `setProjectExtensionPaths`, `setProjectPackages`) then `flush()`; `ctx.reload()` after the screen closes when changes are pending. |
-| Settings writes | App rows call `SettingsManager` setters (`setQuietStartup`, `setOutputPad`, `setShowHardwareCursor`, `setTheme`) on the global store and `flush()`, then surface `drainErrors()`; `bytefly.json` rows call `writeConfigValuesAt` on the selected scope's document with the row's leaf path, so a nested key (`price.currency.decimals`) and a flat one (`notify.method`) share one writer, and a row that also writes a companion leaf (the currency and its default precision) applies both in one document pass; and `u` calls `unsetConfigValueAt` with the same path. A failed or refused write shows a notice in the screen's hint row and leaves the displayed value unchanged; a successful one marks the screen dirty. |
+| Settings writes | App rows call `SettingsManager` setters (`setQuietStartup`, `setTheme`) on the global store and `flush()`, then surface `drainErrors()`; `bytefly.json` rows call `writeConfigValuesAt` on the selected scope's document with the row's leaf path, so a nested key (`price.currency.decimals`) and a flat one (`notify.method`) share one writer, and a row that also writes a companion leaf (the currency and its default precision) applies both in one document pass; and `u` calls `unsetConfigValueAt` with the same path. A failed or refused write shows a notice in the screen's hint row and leaves the displayed value unchanged; a successful one marks the screen dirty. |
 | Doctor tool | `pi.registerTool("run_doctor")`, read-only (`readOnlyHint: true`, `openWorldHint: false`), direct exposure and active on registration (the defaults, so not declared), with a typed `outputSchema` mirroring `structuredContent`. Its `readOnlyHint` is what the shared default-deny policy in `lib/policy.ts` reads to allow it in plan mode. |
 | Doctor probes | `run_doctor` and the screen share the session cache created by `registerDoctor`; the screen mounts on that cache and probes on the first Extensions view (the command's `refresh` forces it), while the text modes probe before printing, and `/bytefly refresh` and `refresh: true` re-probe. Probes spawn `<binary> --version`, lazily import optional packages, and read config files through `lib/requirements.ts`; nothing is ever written. |
 | Status routing | Reads `footerData.getExtensionStatuses()` (a custom footer replaces the built-in one entirely); `worktree` routes to line 1, plan/alert statuses to line 2's trailing slot. |
 | Release notice | `session_start` in `tui` mode patches `InteractiveMode.prototype.showNewVersionNotification` through the shared `patchPrototypeMethod`, so the release Pi resolved becomes `pi.sendMessage(piReleaseNotice(...))` under the shared notice type and `paintLatest` records its version for the agent line's marker (`onUpdate` re-installs the header). The callback posts once per load and only while the session is live; a throw calls the captured original, so Pi's own box is the fallback. `session_shutdown` restores the method and clears the marker. |
-| Update check | `session_start` in `tui` mode installs a suppression on `DefaultPackageManager.prototype.checkForAvailableUpdates`, then reads `<agentDir>/bytefly/update.json`. A fresh entry whose key matches the cwd and effective package sources is recorded without a package-manager call; otherwise bytefly fires `fetchAvailableUpdates()` without awaiting, resolves this package's version through `fetchLatestVersion()` when Pi reports it, writes the snapshot, and records it. `onUpdate` re-installs the header, and `pi.sendMessage(updateNotice(...))` posts the one notice with its version arrow and release URL. `PI_OFFLINE` paints the cached marker only. `/bytefly update` calls the returned `UpdateHandle.recheck()`, which bypasses the window and returns an `UpdateOutcome`; a generation counter drops a background reply that lands after `session_shutdown`, a per-load flag keeps it to one announcement, and shutdown restores Pi's method. |
+| Update check | `session_start` in `tui` mode installs a suppression on `DefaultPackageManager.prototype.checkForAvailableUpdates`, then reads `<agentDir>/bytefly/update.json`. A fresh entry whose key matches the cwd and effective package sources is recorded without a package-manager call; otherwise bytefly fires `fetchAvailableUpdates()` without awaiting, resolves this package's version through `fetchLatestVersion()` when Pi reports it, writes the snapshot, and records it. `onUpdate` re-installs the header, and `pi.sendMessage(updateNotice(...))` posts the one notice with its version arrow and release URL. `PI_OFFLINE` paints the cached marker only. `/bytefly update` calls the returned `UpdateHandle.recheck()`, which bypasses the window and returns an `UpdateOutcome`; `/bytefly upgrade` calls `UpdateHandle.apply()`, which runs `applyUpdates()` — Pi's `DefaultPackageManager.update()`, with its progress passed to `ctx.ui.notify` — and then re-reads the snapshot so the marker cannot outlive the version it named. A generation counter drops a background reply that lands after `session_shutdown`, a per-load flag keeps it to one announcement, and shutdown restores Pi's method. |
 | Config | `bytefly.json` from the agent directory and `<cwd>/.pi`; the `price` section is read once per footer install (a new session or a session-tree change), the `notify` and `doctor` sections at `session_start`, and the `chrome` section's rail glyph at `session_start`/`session_tree`. Nothing watches the document. The update check has no section: it is on whenever `PI_OFFLINE` is off, and its 24 h window is not configurable. |
 | Data sources | `footerData.getGitBranch()`, `footerData.getAvailableProviderCount()`, `ctx.getContextUsage()`, `ctx.sessionManager.getEntries()`, `ctx.sessionManager.getSessionName()`, `ctx.model`; subscribes to `footerData.onBranchChange` to repaint. |
 | State storage | None besides the inert separator entries. The footer reads session entries and the price config (a memoized scan) and writes no tool-result `details`; it appends `bytefly-separator` entries excluded from LLM context. The screen derives its view from the picker runtime, the current reports, and the skill index, and persists extension and skill toggles through `settings.json`. The Settings section derives from a snapshot of the personal `settings.json` and both `bytefly.json` documents, and persists through the same `SettingsManager` setters or the per-leaf `bytefly.json` writer. Doctor's findings are session-scoped in memory only — cached for the session, never written to the session or a file. Notify holds only the config and the run-active flag in its closure. The update check holds this package's version in the per-load `UpdateSource` and one project-scoped snapshot in `<agentDir>/bytefly/update.json`. |
@@ -1306,7 +1348,7 @@ rather than showing a wrong value.
   `worktree` and `browse` are location, so the `◉ <port>` chip sits beside `⎇`
   branch and `⑂` worktree and the left zone stays the filesystem identity; a
   plan or a failed job is mode or alert, so it takes the slot after the gauge.
-  The [wechat](../wechat/) extension publishes `✆ wechat` while its bridge runs,
+  The [wechat](./wechat.md) extension publishes `✆ wechat` while its bridge runs,
   which is why the bar has to render `getExtensionStatuses()` at all.
 - **Segments degrade; they do not clip.** Each `Segment` carries progressively
   shorter `forms` and a `weight`; the layout advances the lowest-priority form
@@ -1502,10 +1544,10 @@ columns, gauge), so the look follows the active theme.
 | `working/config.ts` | Counter tuning (`WORKING_CONFIG`): the words, the tool singular/plural, and the tick interval. |
 | `working/format.ts` | Pure `formatElapsed` (whole seconds) and the working-message shape: the plain count and the `tool · N tools · elapsed` run line. |
 | `working/register.ts` | Starts the tick on `turn_start`, tracks top-level tools on `tool_execution_start`, and cancels on `agent_end`/`session_shutdown`. |
-| `panel/types.ts` | `PanelSection` (`extensions` | `skills` | `settings`), `PanelRow` with its optional skill info, `SkillInfo`, and `PanelModel`, the merged row model. |
+| `panel/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.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/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/skills.ts` | Skill metadata through Pi's own `loadSkills`, keyed by resolved path, plus the deduplicated paths both discovery views read. |