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

package/docs/extensions/bytefly.md

@@ -10,35 +10,34 @@ default, and from `bytefly.json` otherwise.
 
 ## Capabilities
 
-Status records what a reader can rely on: **Shipped** is in a tagged release, **Unreleased** is complete in the current tree but not yet tagged, and **Partial** has one released part and one unreleased part. Rows are ordered by user value, highest first.
-
 ### Chrome
 
-| Capability | How | What you get | Status |
-|---|---|---|---|
-| Startup header | `quietStartup` | One two-tone nameplate with the agent and chrome versions and the live help keys, in place of Pi's startup header and resource listing. | Shipped |
-| Two-line footer | every `tui` session | State on one line — location, modes, and alerts — and meters on the other — context, spend, tokens, cache, and model — each shedding parts rather than clipping. | Shipped |
-| Extension status chips | `footerData.getExtensionStatuses()` | Worktree, browse, plan, and alert statuses appear in the footer, using each extension's own colour. A failed job is the one chip no width drops. | Shipped |
-| Priced session total | the `price` section of `bytefly.json` | The session's spend in yuan or dollars, with DeepSeek priced out of the box. | Shipped |
-| Delegated-run cost roll-up | the `↳` footer segment | A finished subagent's cost appears beside the session total, without merging the two ledgers. | Shipped |
-| User-message nameplate | every `tui` session | Each user message opens with a two-row `You` label and rule. | Shipped |
-| Turn receipt | the `bytefly-separator` entry | One rule per completed turn, recording its number, duration, tool count, and outcome. | Shipped |
-| Shared notices | the `my-pi-agent/notice` type | Any extension's notice renders at the transcript margin with a severity-coloured rail. | Shipped |
-| Compaction canvas | the shipped `themes/` palettes | Pi's `/compact` block keeps its content and loses its fill, so it sits on the canvas. | Shipped |
-| Tool-block frame | `registerToolRenderer` | Every tool block leads with its own call line and hangs its result from the transcript rail. | Shipped |
-| Working line | `ctx.ui.setWorkingMessage` | The working row counts seconds, then names the running tool and how many tools the run has started. | Shipped |
+| Capability | How | What you get |
+|---|---|---|
+| 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. |
+| Two-line footer | every `tui` session | State on one line — location, modes, and alerts — and meters on the other — context, spend, tokens, cache, and model — each shedding parts rather than clipping. |
+| Extension status chips | `footerData.getExtensionStatuses()` | Worktree, browse, plan, and alert statuses appear in the footer, using each extension's own colour. A failed job is the one chip no width drops. |
+| Priced session total | the `price` section of `bytefly.json` | The session's spend in yuan or dollars, with DeepSeek priced out of the box. |
+| Delegated-run cost roll-up | the `↳` footer segment | A finished subagent's cost appears beside the session total, without merging the two ledgers. |
+| User-message nameplate | every `tui` session | Each user message opens with a two-row `You` label and rule. |
+| Turn receipt | the `bytefly-separator` entry | One rule per completed turn, recording its number, duration, tool count, and outcome. |
+| Shared notices | the `my-pi-agent/notice` type | Any extension's notice renders at the transcript margin with a severity-coloured rail. |
+| Compaction canvas | the shipped `themes/` palettes | Pi's `/compact` block keeps its content and loses its fill, so it sits on the canvas. |
+| Tool-block frame | `registerToolRenderer` | Every tool block leads with its own call line and hangs its result from the transcript rail. |
+| Working line | `ctx.ui.setWorkingMessage` | The composer's top border carries it beside Pi's spinner: the elapsed count, then how many tools the run has started. |
+| Plan-mode chord | `Shift+Tab` at the main editor | Flips `auto` and plan through `plan`'s request channel; the footer mode segment and the composer border follow. Shift+Tab is taken from Pi's thinking cycle only while `plan` is loaded, and restored on shutdown. |
 
 ### Control center
 
-| Capability | How | What you get | Status |
-|---|---|---|---|
-| One frame, three sections | `/bytefly`, `/bytefly skills`, `/bytefly settings` | Extensions, skills, and settings in one dock: the worst problem in the header, each section's count on the tabs, the write scope at the right, and one body height for all three, so changing section never resizes the screen. | Shipped |
-| Resource rows and the block | `Space`, `Enter`, `?` | A name-first row — `worktree`, not `worktree/index.ts` — with one checkbox, one status glyph and one verdict word, and the focused row's findings, path, source, state, and health beside the list at 96 columns and under it below. | Shipped |
-| Grouped settings | `/bytefly settings` | Twelve preferences under `Startup`, `Notifications`, `Session`, and `Price`, each value in one aligned column and editable in place; `J` shows the stored JSON section. | Shipped |
-| Theme selection | the `Theme` row in `/bytefly settings` | `system` and the package's `bytefly-dark` and `bytefly-light` palettes are one selection; a reload applies it. | Shipped |
-| Filters and scope | `/`, `!`, `s`, `x` | Narrow the rows by text or to what needs attention — the chips on the tab row say which — and choose where a toggle lands, the personal or project `settings.json`, with `x` clearing a project override. | Shipped |
-| Reload after changes | `R` | `unsaved changes` joins the header while a write is pending, and `R` reloads to apply it instead of leaving the session to be restarted by hand. | Shipped |
-| Health report | `run_doctor`, `/bytefly doctor` | Prerequisites, parse errors, and aged rate tables as text and typed data. | Shipped |
+| Capability | How | What you get |
+|---|---|---|
+| One frame, three sections | `/bytefly`, `/bytefly skills`, `/bytefly settings` | Extensions, skills, and settings in one dock: the worst problem in the header, each section's count on the tabs, the write scope at the right, and one body height for all three, so changing section never resizes the screen. |
+| Resource rows and the block | `Space`, `Enter`, `?` | A name-first row — `worktree`, not `worktree/index.ts` — with one checkbox, one status glyph and one verdict word, and the focused row's findings, path, source, state, and health beside the list at 96 columns and under it below. |
+| Grouped settings | `/bytefly settings` | Fifteen preferences under `Startup`, `Notifications`, `Session`, `Board`, and `Price`, each value in one aligned column and editable in place; `J` shows the stored JSON section. |
+| 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. |
+| Filters and scope | `/`, `!`, `s`, `x` | Narrow the rows by text or to what needs attention — the chips on the tab row say which — and choose where a toggle lands, the personal or project `settings.json`, with `x` clearing a project override. |
+| Reload after changes | `R` | `unsaved changes` joins the header while a write is pending, and `R` reloads to apply it instead of leaving the session to be restarted by hand. |
+| Health report | `run_doctor`, `/bytefly doctor` | Prerequisites, parse errors, and aged rate tables as text and typed data. |
 
 ### Upkeep
 
@@ -229,7 +228,9 @@ A nameplate: a two-tone half-block mark from the active theme's `accent` /
 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
+one raw hint, `shift+tab to toggle plan`, is bytefly's own editor chord rather
+than a bindable Pi action. The identity and help text are `meta` / `faint` so the
+mark keeps the eye. It opens
 with a blank row, so the nameplate clears the top edge. It is installed only in
 interactive (`tui`) sessions when Pi's `quietStartup` is `true` — the Settings
 row **Startup screen** — and `false`, `"header"`, and unset leave Pi's
@@ -261,14 +262,17 @@ identity, and grouped help are tuned in
 
 Two lines, each with a left and right zone:
 
-- **Line 1 — identity:** `pwd` and the session name on the left; on the right the
-  alert, then the mode chips (`≡ plan`), then `⎇ branch · ⑂ worktree`, then the
-  session's page port (`◉ 4780`) while anything is served on it. One server serves
-  every page of a session, so it is one number from one status key.
-- **Line 2 — resources:** the context gauge and usage meters on the left, the
-  child-run roll-up (`↳ 3 · ¥0.12`, present only once a subagent has finished),
-  and the model and thinking level on the right. The gauge is anchored at column
-  0, so `%` is always in the same place.
+- **Line 1 — identity:** `pwd` and the name this session is on the team as on the left —
+  the bus's roster label when it has one, and Pi's own session name when it has none, so a
+  session off the bus reads exactly as it did; on the right the
+  alert, then the remaining status chips (a job count, a rewind timeline, the
+  `✆` bridge), then `⎇ branch · ⑂ worktree`, then the session's page port
+  (`◉ 4780`) while anything is served on it. One server serves every page of a
+  session, so it is one number from one status key.
+- **Line 2 — resources:** the mode (`▶ auto` or `≡ plan`), the context gauge and
+  usage meters on the left, the child-run roll-up (`↳ 3 · ¥0.12`, present only
+  once a subagent has finished), and the model and thinking level on the right.
+  The gauge follows the mode, so `%` stays put once the mode stops changing.
   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
@@ -276,8 +280,8 @@ Two lines, each with a left and right zone:
   `/resume` (the events are not session entries).
 
 ```
-~/repo/my-pi-agent                                                         ≡ plan · ⎇ main · ⑂ smoke
-▰▰▰▰▰▰▱▱▱▱ 62%/200k · ¥0.31 · ↳ 2 · ¥0.06 · ↑42k ↓8.0k · R96k CH 87%                 opus-4.5 · high
+~/repo/my-pi-agent                                                                  ⎇ main · ⑂ smoke
+≡ plan · ▰▰▰▰▰▰▱▱▱▱ 62%/200k · ¥0.31 · ↳ 2 · ¥0.06 · ↑42k ↓8.0k · R96k CH 87%      opus-4.5 · high
 ```
 
 (The examples show the default `¥` symbol. A model that neither `rates` nor the
@@ -285,11 +289,11 @@ built-in table covers contributes nothing in `CNY` mode, so the bar shows no
 figure rather than a guessed one; `USD` mode adds Pi's recorded dollars for that
 record instead — see [Cost calculation](#cost-calculation).)
 
-With no plan mode the mode slot is simply absent:
+With no plan mode the mode segment reads its other state:
 
 ```
 ~/repo/my-pi-agent                                                                  ⎇ main · ⑂ smoke
-▰▰▰▰▰▰▱▱▱▱ 62%/200k · ¥0.31 · ↑42k ↓8.0k · R96k CH 87%                               opus-4.5 · high
+▶ auto · ▰▰▰▰▰▰▱▱▱▱ 62%/200k · ¥0.31 · ↑42k ↓8.0k · R96k CH 87%                    opus-4.5 · high
 ```
 
 While a page is served, the session's port joins the run beside the worktree:
@@ -304,13 +308,13 @@ clipping. The branch keeps its name and is dropped when the name no longer
 fits, rather than collapsing to a bare glyph:
 
 ```
-~/repo/my-pi-agent       ≡ plan · ⎇ main · ⑂
-▰▰▰▰▰▰▱▱▱▱ 62%/200k · ¥0.31  opus-4.5 · high
+~/repo/my-pi-agent       ⎇ main · ⑂
+≡ plan · ▰▰▰▰▰▰▱▱▱▱ 62%/200k · ¥0.31   opus-4.5 · high
 ```
 
 ```
 ~/my-pi-agent     ⎇ main
-▰▰▰▰▰▰▱▱▱▱ 62%  opus-4.5
+▶ auto · ▰▰▰▰▰▰▱▱▱▱ 62%  opus-4.5
 ```
 
 The port drops the digits before the page they name: it compacts to `◉` once
@@ -319,14 +323,14 @@ says a page is up.
 
 ```
 ~/repo/my-pi-agent            ⎇ main · ◉
-▰▰▰▰▰▰▱▱▱▱ 62% · ¥0.31   opus-4.5 · high
+≡ plan · ▰▰▰▰▰▰▱▱▱▱ 62% · ¥0.31   opus-4.5 · high
 ```
 
 With a named session, the name follows the path and truncates before it drops:
 
 ```
 ~/repo/project · [feature-refac…]         ⎇ main
-▰▰▰▰▰▰▱▱▱▱ 62%/200k · ¥0.31      opus-4.5 · high
+▶ auto · ▰▰▰▰▰▰▱▱▱▱ 62%/200k · ¥0.31      opus-4.5 · high
 ```
 
 Zero-value meters are omitted, so a fresh session shows only `?/window` instead
@@ -345,6 +349,7 @@ Each segment reads a theme role and carries its own drop order:
 | branch | 1 right | muted (warning when detached) | last |
 | worktree | 1 right | success | first |
 | port `◉ 4780` | 1 right | success glyph + accent port | first |
+| mode `≡ plan` / `▶ auto` | 2 left | warning while planning, accent otherwise | never |
 | context gauge + `%` | 2 left | muted ≤70 · warning 71–90 · error >90 | never |
 | `/window` | 2 left | dim | before cost |
 | cost | 2 left | muted | after tokens |
@@ -362,13 +367,26 @@ opens. It is a two-tone `<glyph> <port>` with a green glyph and an accent port,
 and it compacts from `◉ 4780` to `◉` before it drops, so a bar too narrow for
 the number still says a page is up.
 
-The mode slot holds everything else an extension publishes: a plan chip, a
-job count, a rewind timeline, the `✆` bridge, and an alert's front position. A
-plan chip's trailing plan file name is dropped, so the slot reads `≡ plan` even
-though the built-in footer keeps the name, and an alert (a failed job) sorts to
-the front of it. It keeps each extension's own colour when it compacts, and it is
-droppable: a tight bar drops the slot rather than truncating the model, which
-sits at the end of the line.
+The mode segment leads the resource line: `≡ plan` in the warning role while
+planning, `▶ auto` in accent otherwise. The bar draws that word itself and reads
+only the presence of the `plan-mode` status key, so neither the plan file name nor
+a chip truncated elsewhere can reach it. `auto` is not a
+behaviour of its own: it names Pi's default mode, every tool as it ships and writes
+included, so the segment states which mode the session is in and `≡ plan` is the one
+override that withholds — a mode added later is a third value of this one chip, never a
+second indicator saying what the session may do. `Shift+Tab` at
+the main editor asks [plan](./plan.md) to flip it; the chip and the composer
+border are read from the branch, so `/plan` and the model's own `plan` action `exit`
+move them too. Bytefly unsets Pi's `app.thinking.cycle` chord while it holds the
+key, so `/hotkeys` and the header stop claiming Shift+Tab, and restores it on
+shutdown. A session without `plan` still reads `▶ auto` and keeps the thinking
+cycle.
+
+The status slot beside the branch holds everything else an extension publishes: a
+job count, a rewind timeline, the `✆` bridge, and an alert's front position. An
+alert (a failed job) sorts to the front of it. It keeps each extension's own
+colour when it compacts, and it is droppable: a tight bar drops the slot rather
+than truncating the model, which sits at the end of the line.
 
 ## Cost calculation
 
@@ -619,44 +637,50 @@ edges its own `Box` pads itself with, and hands it a theme whose `bg` is inert s
 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.
+in the `toolTitle` role, 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 `meta`, trailing options are `faint`, 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:
+Pi's working indicator shows a static `Working`, so a long run reads the same as
+a short one. It is drawn on the composer's top border while a run is up, and
+bytefly advances its message once a second and hands it back to Pi when the run
+settles. Before the first tool starts it is a count:
 
 ```
-Working… 12s
+── ◐ 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.
+Once a top-level tool starts, the border adds how many top-level tools this run
+has started:
 
 ```
-edit · 3 tools · 12s
+── ◐ working · 3 tools · 12s ─────────
 ```
 
+The spinner and the colour are Pi's: the indicator owns the `◐` frame and takes
+the composer border's role, so it is `accent` in auto and `warning` while
+planning. The line deliberately does not name the tool — the transcript already
+draws each call as its own block, and one word reads faster than a name that
+changes under you.
+
 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
+inner call) does not count, so the number matches the tool blocks in the
+transcript. A tool event repaints the border immediately instead of waiting for
+the next tick. The line covers the whole run, tool calls
+included. It is tied to the indicator'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/screens/bytefly.png" alt="The /bytefly control center at 120 columns: a `Bytefly` rule with `1 missing` at its right edge, the `Extensions 9 · Skills 0 · Settings 12` tabs with `writes Global` at the right, one name-first row per extension with its checkbox and verdict, and the focused extension's block beside the list — its findings and their fix, Path, Source, State, and Health" width="100%">
+<img src="../../assets/screens/bytefly-extensions.png" alt="The /bytefly control center at 120 columns: a `Bytefly` rule with `1 missing` at its right edge, the `Extensions 9 · Skills 3 · Settings 15` tabs with `writes Global` at the right, one name-first row per extension with its checkbox and verdict, and the focused extension's block beside the list — its findings and their fix, Path, Source, State, and Health" width="100%">
 
 `/bytefly [extension] [refresh]` opens the control center on **Extensions**: a
 keyboard-driven dock of every resource Pi resolves for the session, so the list
@@ -780,9 +804,11 @@ finds the rows that need it.
 - Shows whether each one is enabled (`◼`) or disabled (`◻`) in settings.
 - Gives each row one verdict from the doctor's report: the worst severity's
   glyph (`!` degraded, `✕` missing) and its summary. A row that is `◻` reads
-  `off` instead, because it will not load; a row the session's
-  `PI_DISABLED_EXTENSIONS` excludes reads `env disabled`, so the two axes cannot
-  contradict each other. A row with nothing to report leaves the glyph column
+  `off` instead, because it will not load; a row the session's environment
+  excludes — disabled through `PI_DISABLED_EXTENSIONS`, or an opt-in extension
+  that `PI_ENABLED_EXTENSIONS` does not name — reads `env disabled`, so the two
+  axes cannot contradict each other. The finding beside it names the switch that
+  would change the answer. A row with nothing to report leaves the glyph column
   blank and says `ok` in words when a report exists.
 - Toggles the focused extension with `Space`, writing `+pattern` / `-pattern`
   into `extensions` (and package filter objects) in the write scope. A row in
@@ -826,20 +852,24 @@ 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.
 
+<img src="../../assets/screens/bytefly-skills.png" alt="The /bytefly Skills section at 120 columns: the `Extensions 9 · Skills 3 · Settings 15` tabs with `writes Global` at the right, the three skills this package ships under an `npm:pkg (user) (3)` heading with the focused `init` row marked `hidden`, and its block beside the list — Path, Source, State, the `/skill:init` call, `Model hidden from the model`, and the description the file declares under About" width="100%">
+
 Themes and prompts have no section of their own, by decision rather than by
 omission: a theme is one active selection — a scalar, global setting — and a
 prompt template is a file Pi discovers from a directory, so neither is a scoped
 enable list this screen's checkbox rows can write. Themes stay with `pi config`;
-`ROADMAP.md` carries the reason under *Deliberately left thin*.
+[`architecture.md`](../architecture.md#documented-limits-with-no-planned-card) carries
+the reason.
 
 **Settings.** The third section is the same frame over the curated preferences,
 grouped by what they do rather than by which file holds them: `Startup (2)`,
-`Notifications (5)`, `Session (3)`, and `Price (2)`. It is the shortlist a
-session changes: twelve preferences, each with its value in one aligned column
-instead of beside its label, so a column of values can be read down. Sixteen
-entries — twelve rows and their four headings — fit a 24-row terminal when the
-block sits beside the list; on a narrower one the list scrolls and the block
-keeps its three rows. The frame never grows past the tallest section, however
+`Notifications (5)`, `Session (3)`, `Board (3)`, and `Price (2)`. It is the
+shortlist a session changes: fifteen preferences, each with its value in one
+aligned column instead of beside its label, so a column of values can be read
+down. Twenty entries — fifteen rows and their five headings — want a 28-row
+terminal to be seen whole when the block sits beside the list; on a shorter or
+narrower one the list scrolls, says `showing 1–13 of 15`, and the block keeps its
+three rows. The frame never grows past the tallest section, however
 tall the terminal is. In Project scope the two app rows drop out and the note
 `App settings are Global only.` stands above the list.
 
@@ -850,7 +880,7 @@ description, and `Stored in <origin> · <file>` — `Global`, `Project`,
 otherwise). `J` on a `bytefly.json` row appends that section as the active scope
 stores it, under a `── notify ──` rule.
 
-<img src="../../assets/screens/bytefly-settings.png" alt="The /bytefly Settings section at 120 columns: the `Startup (2)`, `Notifications (5)`, `Session (3)`, and `Price (2)` groups with each value in one aligned column, the `Extensions 9 · Skills 0 · Settings 12` tabs with `writes Global` at the right, and the focused row's block beside the list — its value, description, and the file the value is stored in" width="100%">
+<img src="../../assets/screens/bytefly-settings.png" alt="The /bytefly Settings section at 120 columns: the `Startup (2)`, `Notifications (5)`, `Session (3)`, `Board (3)` and `showing 1–11 of 15` rows with each value in one aligned column, the `Extensions 9 · Skills 3 · Settings 15` tabs with `writes Global` at the right, and the focused row's block beside the list — its value, description, and the file the value is stored in" width="100%">
 
 | Group | Row | Source | Values |
 |---|---|---|---|
@@ -890,9 +920,10 @@ only view of the keys this screen leaves to JSON. A successful change marks the
 block `Saved · reload to apply` and puts `unsaved changes` in the header, and
 closing offers the same reload confirm as an extension or skill toggle.
 
-The list is capped at twelve rows so the screen keeps fitting a 24-row
+The list is capped at fifteen rows so the screen keeps fitting a 28-row
 terminal: adding a setting means removing one (`panel/settings.test.ts` holds the
-ceiling). Everything else stays in `bytefly.json` — the tuning numbers, the
+ceiling, and a 24-row terminal scrolls the list rather than the frame). 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. Most
@@ -915,7 +946,7 @@ Off, because it keeps Pi's header; the next toggle replaces it with `true` or
 
 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 ten `bytefly.json` rows and a
+scope therefore lists the thirteen `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
@@ -927,7 +958,7 @@ The non-`tui` form prints the headline and one `Label: Value` row per line, in
 screen order:
 
 ```
-bytefly: Settings · Global · 12 settings
+bytefly: Settings · Global · 15 settings
   Startup screen: Off
   Theme: bytefly-dark
   Desktop notifications: On
@@ -1143,7 +1174,7 @@ install, and `PI_OFFLINE` all follow its package manager. The only extra read is
 this package, used just to name the version arrow and release URL. A failed
 version read drops those two pieces but keeps the package list and command.
 
-The answer is cached in `<agentDir>/bytefly/update.json` as the package list,
+The answer is cached in `<agent-dir>/bytefly/update.json` as the package list,
 this package's optional version, the time it was read, and a key over the cwd and
 the effective package sources. A session that starts inside the 24-hour window
 reuses that snapshot — painting the marker and posting the notice from it —
@@ -1197,7 +1228,7 @@ why the line says so, and each source the manager reports is shown while it runs
 - **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 twelve rows so the screen fits a 24-row terminal. `doctor.skip` (an
+  at fifteen rows so the screen fits a 28-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`.
@@ -1272,12 +1303,15 @@ why the line says so, and each source the manager reports is shown while it runs
 - **The displayed number is the total, rounded once** — not the sum of rounded
   records.
 - **`doctor` can only check what is declared.** A new extension with no
-  `REQUIREMENTS` entry is invisible to it — `test/structure.test.ts` fails on
+  `REQUIREMENTS` entry is invisible to it — `test/prerequisites.test.ts` fails on
   exactly that, which is why the table cannot rot quietly.
-- **The disabled check reads `PI_DISABLED_EXTENSIONS`** through `lib/env.ts`; it
-  does not read Pi's own `settings.json` disable list, so an extension disabled
-  only there may still be probed. The row labels that state `env disabled`,
-  separately from the picker's `off`.
+- **The disabled check reads the environment** through `lib/env.ts`: the disable
+  list, and the opt-in list that a default-off extension needs. It does not read
+  Pi's own `settings.json` disable list, so an extension disabled only there may
+  still be probed. The row labels that state `env disabled`, separately from the
+  picker's `off` — the picker's `Space` writes settings patterns and cannot set
+  an environment variable, so an opt-in extension is switched on in the shell,
+  not on that screen.
 - **A probe proves a binary runs, not that it works:** a `git` that crashes on a
   specific repository is still `ok`.
 - **Config scope is checked for `<agent-dir>/bytefly.json` and
@@ -1296,11 +1330,14 @@ why the line says so, and each source the manager reports is shown while it runs
   host lacks (or an OSC method off a TTY) and the notification is dropped; only
   `auto` inspects the environment. `doctor` now reports the mismatch as a
   `degraded` finding, which says what to change but does not fix it for you.
-- **The working line is one global row.** `setWorkingMessage` drives the
-  single working row, so bytefly and any other extension setting it race — last
-  writer wins — and the message is reset to Pi's default at `agent_end`. If the
-  row is hidden (`ctx.ui.setWorkingVisible(false)`) the line has no surface,
-  and a reload mid-run does not resume the count until the next turn.
+- **The working line is one global message.** `setWorkingMessage` drives the
+  single working indicator, so bytefly and any other extension setting it race — last
+  writer wins — and the message is reset to Pi's default at `agent_end`. It is drawn
+  on the composer's top border because the mode editor opts into Pi's embedded
+  indicator; an editor that does not (or a host without `embedWorkingStatus`) puts the
+  same line in a row above the composer instead. If the indicator is hidden
+  (`ctx.ui.setWorkingVisible(false)`) the line has no surface, and a reload mid-run
+  does not resume the count until the next turn.
 
 ## Non-goals
 
@@ -1325,7 +1362,7 @@ why the line says so, and each source the manager reports is shown while it runs
 - No sound, action buttons, notification history, or de-duplication; a
   notification is a fire-and-forget message, not an inbox.
 - No frozen per-run working duration: the line is live and is handed back to
-  Pi when the working row comes down, because the extension API exposes no hook
+  Pi when the working indicator comes down, because the extension API exposes no hook
   to keep a finished run's total.
 
 The built-in footer's `(auto)` auto-compact indicator and `(sub)`
@@ -1344,7 +1381,7 @@ rather than showing a wrong value.
 | 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 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. |
+| 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 `working · N tools · Ns` (nested calls carrying `parentToolCallId` are skipped). It renders on the composer's top border, which the mode editor enables with `embedWorkingStatus`. `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. |
 | 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. |
@@ -1353,10 +1390,10 @@ rather than showing a wrong value.
 | 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`; `/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. |
+| Update check | `session_start` in `tui` mode installs a suppression on `DefaultPackageManager.prototype.checkForAvailableUpdates`, then reads `<agent-dir>/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`. |
+| 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 `<agent-dir>/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
@@ -1462,17 +1499,19 @@ rather than showing a wrong value.
   the session's; it prices the `my-pi-agent/subagent-finished` events with the
   same pricer and renders them as `↳`, so "this session" keeps meaning the
   dispatching process and the delegated work stays visible beside it.
-- **The gauge is anchored at column 0, and nothing can displace it.** A leading
-  mode slot used to push the context percentage left and right as plan mode came
-  and went, which is why the mode chip trailed the meters after a `│`; moving the
-  mode slot to the state line leaves the gauge as the resource line's first
-  segment, so the percentage cannot move at all.
+- **The mode leads the resource line, and the gauge follows it.** A tight bar used
+  to push the context percentage around as plan mode came and went; putting the
+  mode first gives the gauge a fixed offset after a segment of fixed width, so the
+  percentage no longer moves as statuses are published. The mode is never
+  dropped: a reader knows which mode the next request lands in before reading how
+  much room is left.
 - **Statuses are routed, not repeated.** The built-in footer renders every
   `setStatus` value on its own line, so the bar sorts them by meaning instead:
   `worktree` is location, so the `◉ <port>` chip sits behind `⎇`
   branch and `⑂` worktree, and it is the session's one page port, so it keeps a
-  weight and a floor of its own; a plan is a mode, so it leads the state line
-  beside them; a failed job is an alert, so it is its own segment ahead of both. The
+  weight and a floor of its own; a plan is a mode, so its chip leads the resource
+  line and bytefly fills in `▶ auto` when it is absent; a failed job is an alert,
+  so it is its own segment ahead of the state chips. The
   [wechat](./wechat.md) extension publishes `✆ wechat` while its bridge runs,
   which is why the bar has to render `getExtensionStatuses()` at all.
 - **A state chip leads its zone, so the zone does not move under it.** The right
@@ -1635,7 +1674,7 @@ rather than showing a wrong value.
 The surfaces are folders: `header/`, `footer/` (the status bar and its price
 calculation), `message/` (the user-message marker), `notice/` (the shared notice),
 `block/` (the tool-block frame), `separator/`, `working/` (the live
-run line on Pi's working row), `panel/` (the
+run line on the composer's top border), `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, Pi's own
@@ -1653,12 +1692,13 @@ columns, gauge), so the look follows the active theme.
 | `header/identity.ts` | `IdentityInput` and `identityCells`: the agent and chrome cells, each with its `↑` marker, in the ladder that sheds the chrome marker, the chrome version, the chrome line, and finally the agent's marker with the row. |
 | `header/register.ts` | Installs/restores the header and owns its session lifecycle. |
 | `footer/register.ts` | Installs/restores the footer and owns its session lifecycle. |
-| `footer/config.ts` | Bar tuning (`CONFIG`): thresholds, gauge, separators, icons, alert and plan status keys, labels. |
+| `footer/config.ts` | Bar tuning (`CONFIG`): thresholds, gauge, separators, icons, alert and mode status keys, labels. |
 | `footer/types.ts` | `StatusSnapshot`, `Segment`, `LineSpec`, `UsageRecord`, and footer/TUI shapes. |
 | `footer/budget.ts` | The session spend guardrail: whether the configured ceiling has been crossed and the one notice that says so — an alert, never a limit. |
 | `footer/delegation.ts` | The child-run ledger: the pricing inputs of the last delegated runs, versioned so the footer re-prices when a subagent finishes. |
 | `footer/collect/entries.ts` | Session entries → usage records, each resolved to the model in effect. |
 | `footer/collect/snapshot.ts` | Snapshot assembly; memoized pricing scan, context estimate, and session name per branch leaf. |
+| `footer/collect/label.ts` | The roster label the bar names this session by: one read of the bus's own record, then every label the bus publishes. |
 | `footer/price/types.ts` | `Currency`, `ModelRates`, `PeakWindow`/`PeakSchedule`, `ByteflyConfig`. |
 | `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. |
@@ -1675,6 +1715,7 @@ columns, gauge), so the look follows the active theme.
 | `message/config.ts` | Nameplate tuning (`MESSAGE_CONFIG`): the label and the rule. |
 | `message/format.ts` | Pure `nameplate` and `styleUserMessage`: the two-row nameplate (label over a full-width rule) and its placement above the message. |
 | `message/register.ts` | Registers the Markdown transformer (the nameplate). |
+| `mode/editor.ts` | The main editor with `Shift+Tab` bound to plan mode: `isShiftTab` consumption, the mode-aware border (`success`/`warning`) applied in `render`, the `app.thinking.cycle` unbind/restore, and `attachModeKey(pi, ctx)` with its idempotent cleanup. Loads on the first TUI session through a dynamic import. |
 | `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. |
@@ -1694,7 +1735,7 @@ columns, gauge), so the look follows the active theme.
 | `panel/join.ts` | The item/report union with the unambiguous-name naming rule — a row is `worktree`, and a directory claims a report only when one resource uses that name — plus unique row keys, groups, ordering, and the skills model that labels rows from `SKILL.md`. |
 | `panel/filter.ts` | The two filters as predicates and chips: a text query over a row's name, path, and source, the attention switch, and what the tab row says is on. |
 | `panel/format.ts` | Non-TUI text: the resource headline and grouped listing with a per-row verdict, the header's attention segments, the one `rowBadge` the screen and the listing share, the section segments and their order, the Settings counts/headline, and the flat Settings listing. |
-| `panel/settings.ts` | The curated Settings catalogue: the twelve descriptors in screen order, their four groups, the value labels (`Off`, `¥5.00`) and display origins, value cycling, stored-value mapping, validation, plus the per-section readers that resolve a row's leaf over the global and project documents. |
+| `panel/settings.ts` | The curated Settings catalogue: the fifteen descriptors in screen order, their five groups, the value labels (`Off`, `¥5.00`) and display origins, value cycling, stored-value mapping, validation, plus the per-section readers that resolve a row's leaf over the global and project documents. |
 | `panel/settings-runtime.ts` | The Settings runtime: snapshot cache, scope guards, app setters, per-leaf `bytefly.json` writes, dirty state, and change listeners. |
 | `panel/themes.ts` | Which themes the Theme row offers: the host's resolved list narrowed to the palettes under this package's `themes/`, identified by directory rather than name. |
 | `panel/prices.ts` | The `/bytefly prices` report: the unpriced models by key, the records behind each, and the one line saying where the keys go. It quotes no price — a rate is the user's to state. |
@@ -1734,7 +1775,7 @@ columns, gauge), so the look follows the active theme.
 | `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` (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/cache.ts` | The project-scoped snapshot: `<agent-dir>/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`, `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. |