@gavin-hu/my-pi-agent 0.8.0 → 0.9.0

package/README.md

@@ -11,7 +11,7 @@ context across sessions. `my-pi-agent` is a single [Pi](https://pi.dev) package
 that adds sixteen extensions and two themes — install the pack, turn off what
 you do not want, and keep using Pi unchanged.
 
-<img src="./assets/bytefly-chrome.png" alt="A terminal window running the Pi TUI with the bytefly header, hint row, context and loaded extensions, a turn separator, and the status bar" width="100%">
+![A terminal window running the Pi TUI with the bytefly header, hint row, context and loaded extensions, a turn separator, and the status bar](assets/bytefly-chrome.png)
 
 ## Contents
 
@@ -59,10 +59,11 @@ pi -e .                                                    # try it for one run
 
 Then, from inside Pi:
 
-- `/extensions` (an alias of `/bytefly`) lists every loaded extension with its
-  runtime health and enables or disables one.
-- `/doctor` opens the same screen, narrowed to one extension when named, and
-  checks that each enabled extension has what it needs at runtime.
+- `/bytefly [extension] [refresh]` opens the extension screen, lists every loaded
+  extension with its runtime health, and enables or disables one.
+- `/bytefly doctor [extension] [refresh]` prints the doctor report —
+  `run_doctor`'s text — and checks that each enabled extension has what it needs
+  at runtime.
 - `/settings` → **Theme** selects a theme.
 - `/plan <task>` starts a task in read-only planning mode.
 
@@ -105,7 +106,7 @@ extension's own `README.md` has the full tool and command surface.
 
 | Extension | Tools and commands | What it does |
 |---|---|---|
-| [`bytefly`](./extensions/bytefly/) | `/bytefly`, `/extensions`, `/doctor`, `run_doctor` | A themed header and width-adaptive footer, a rule between completed turns, the `/bytefly` extension screen (aliases `/extensions` and `/doctor`) that lists every extension with its health and enables or disables one, and an opt-in `notify` capability that raises OS notifications when a run or a background job finishes or the agent asks for input. DeepSeek is priced out of the box, and `bytefly.json` is the shared config document every extension reads. |
+| [`bytefly`](./extensions/bytefly/) | `/bytefly` (with the `doctor` subcommand), `run_doctor` | A themed header and width-adaptive footer, a rule between completed turns, the `/bytefly` extension screen that lists every extension with its health and enables or disables one (`/bytefly doctor` prints the doctor report), and an opt-in `notify` capability that raises OS notifications when a run or a background job finishes or the agent asks for input. DeepSeek is priced out of the box, and `bytefly.json` is the shared config document every extension reads. |
 | [`bytefly-dark`](./themes/bytefly-dark.json) / [`bytefly-light`](./themes/bytefly-light.json) | `/settings` → **Theme** | A GitHub-inspired dark palette and its light companion, with optional automatic light/dark switching. |
 
 ## Configuration
@@ -146,9 +147,9 @@ stops the factories from registering; to drop the whole package, use Pi's
 - **OS** — Windows, macOS, and Linux; the full check suite runs on all three in
   CI.
 - **git** on `PATH` for the `worktree` and `rewind` extensions; everything else
-  degrades or disables cleanly, and `/doctor` tells you what is missing.
+  degrades or disables cleanly, and `/bytefly doctor` tells you what is missing.
 - Optional runtime pieces (for example a browser for HTML exports) are reported
-  per extension by `/doctor`.
+  per extension by `/bytefly doctor`.
 
 ## Contributing
 

package/README.zh-CN.md

@@ -10,7 +10,7 @@
 `my-pi-agent` 是一个 [Pi](https://pi.dev) 包，新增十六个扩展和两个主题 —— 安装
 整个包，关掉你不需要的部分，其余照常使用 Pi。
 
-<img src="./assets/bytefly-chrome.png" alt="一个运行 Pi TUI 的终端窗口，包含 bytefly 头部、提示行、上下文与已加载扩展、回合分隔线以及状态栏" width="100%">
+![一个运行 Pi TUI 的终端窗口，包含 bytefly 头部、提示行、上下文与已加载扩展、回合分隔线以及状态栏](assets/bytefly-chrome.png)
 
 ## 目录
 
@@ -55,10 +55,10 @@ pi -e .                                                    # 试运行一次
 
 然后在 Pi 中：
 
-- `/extensions`（`/bytefly` 的别名）列出每个已加载扩展及其运行时健康状况，并启用
-  或禁用一个扩展。
-- `/doctor` 打开同一屏幕，指定扩展名时只显示该扩展，并检查每个已启用扩展在运行时
-  是否具备所需条件。
+- `/bytefly [extension] [refresh]` 打开扩展屏幕，列出每个已加载扩展及其运行时健康
+  状况，并启用或禁用一个扩展。
+- `/bytefly doctor [extension] [refresh]` 打印 doctor 报告（`run_doctor` 的文本），
+  检查每个已启用扩展在运行时是否具备所需条件。
 - `/settings` → **Theme** 选择主题。
 - `/plan <任务>` 以只读规划模式开始一个任务。
 
@@ -101,7 +101,7 @@ pi -e .                                                    # 试运行一次
 
 | 扩展 | 工具与命令 | 说明 |
 |---|---|---|
-| [`bytefly`](./extensions/bytefly/) | `/bytefly`, `/extensions`, `/doctor`, `run_doctor` | 主题化头部与宽度自适应页脚、已完成回合之间的分隔线、`/bytefly` 扩展屏幕（别名 `/extensions` 和 `/doctor`）——列出每个扩展及其健康状况并启用或禁用一个扩展；以及可选的 `notify` 能力：当一次运行或后台任务结束、或智能体请求输入时发出系统通知。DeepSeek 开箱即定价，`bytefly.json` 是每个扩展都会读取的共享配置文档。 |
+| [`bytefly`](./extensions/bytefly/) | `/bytefly`（`doctor` 子命令）、`run_doctor` | 主题化头部与宽度自适应页脚、已完成回合之间的分隔线、`/bytefly` 扩展屏幕——列出每个扩展及其健康状况并启用或禁用一个扩展（`/bytefly doctor` 打印 doctor 报告）；以及可选的 `notify` 能力：当一次运行或后台任务结束、或智能体请求输入时发出系统通知。DeepSeek 开箱即定价，`bytefly.json` 是每个扩展都会读取的共享配置文档。 |
 | [`bytefly-dark`](./themes/bytefly-dark.json) / [`bytefly-light`](./themes/bytefly-light.json) | `/settings` → **Theme** | GitHub 风格的深色调色板及其浅色搭档，并支持可选的自动浅色/深色切换。 |
 
 ## 配置
@@ -139,8 +139,8 @@ Pi 的 `--no-extensions`，或从你的设置中删除该包。
 - **Pi** —— 需要一个可用的安装；`my-pi-agent` 是一个包，不是分叉。
 - **操作系统** —— Windows、macOS 和 Linux；完整检查套件在三者的 CI 上都会运行。
 - **git** 需在 `PATH` 上，供 `worktree` 和 `rewind` 扩展使用；其余部分会优雅降级或
-  禁用，`/doctor` 会告诉你缺什么。
-- 可选的运行时组件（例如用于 HTML 导出的浏览器）由 `/doctor` 按扩展报告。
+  禁用，`/bytefly doctor` 会告诉你缺什么。
+- 可选的运行时组件（例如用于 HTML 导出的浏览器）由 `/bytefly doctor` 按扩展报告。
 
 ## 参与贡献
 

package/extensions/bytefly/README.md

@@ -23,17 +23,17 @@ The extension owns five surfaces: the startup header, the footer, the rule
 between completed turns, the extension screen, and notifications.
 
 **Header.** A nameplate: a two-tone half-block mark from the active theme's
-`accent` / `warning` tokens, the agent identity (`Pi` and its version), the
-chrome identity (`enhanced by bytefly` and the package version), a `─` rule, 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 `muted`/`dim`
-so the mark keeps the eye. It is installed only in interactive (`tui`) sessions,
-and on terminals that cannot render half blocks the mark falls back to a
-two-tone `Pi` wordmark.
+`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 is installed only in interactive (`tui`) sessions, and 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.7.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
@@ -133,19 +133,18 @@ the platform notifier (`osascript`, `notify-send`); see
 | Command | What it does |
 |---|---|
 | `/bytefly [extension] [refresh]` | Open the extension screen. In `tui` it mounts a docked list; every other mode prints the grouped listing, or one extension's full findings when named. |
-| `/extensions` | Alias for `/bytefly`: the same screen and the same handler. |
-| `/doctor [extension] [refresh]` | Alias for `/bytefly`: the same screen and the same handler. |
+| `/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. |
 
-Tab completes extension names and `refresh` for all three commands.
+Tab completes `doctor`, extension names, and `refresh`.
 
 ## Behaviour by mode
 
 The header, footer, and turn rule are installed only in interactive (`tui`)
 sessions and are always on; every mode loads the extension, and non-TUI modes
 change nothing. The screen is available in every mode: in `tui`, `/bytefly` and
-its `/extensions` and `/doctor` aliases mount the docked screen, while RPC,
-JSON, and print modes print the grouped listing with a per-row health suffix and
-the headline, or that extension's full findings when one is named. The
+`/bytefly doctor` mount the docked screen, while RPC, JSON, and print modes
+print the grouped listing with a per-row health suffix and the headline, or that
+extension's full findings when one is named. The
 proactive session-start warning is skipped when there is no UI. Notify runs in
 every mode and picks its method from the environment; the OSC methods need a
 TTY, so a print/JSON/RPC run gets an OS-level notification or none.
@@ -394,10 +393,13 @@ it:
 extension Pi resolves for the session, so the list matches what actually loads.
 It merges the former extensions picker and doctor report into one row per
 extension: the picker's enable checkbox and label, the doctor's worst-severity
-glyph and summary. `/extensions` and `/doctor [extension] [refresh]` are
-registered against the same handler, so all three names open the same screen;
-`[extension]` narrows it to one extension and `refresh` re-probes the doctor
-before it opens. Tab completes extension names and `refresh`.
+glyph and summary. The screen is drawn from the design system: a label-first
+`bytefly ────` title rule, one row grammar (`❯ ◼ ✓ name … summary`), and the
+shared `◼` / `◻` checkbox. `/bytefly doctor [extension] [refresh]` selects the doctor
+report, the same text the `run_doctor` tool returns; in `tui` it opens the same
+screen. `[extension]` narrows either surface to one extension and `refresh`
+re-probes the doctor before it opens. Tab completes `doctor`, extension names,
+and `refresh`.
 
 The screen reuses Pi's own settings and package resolution (`SettingsManager`
 plus `DefaultPackageManager` with `onMissing: "skip"`), so opening it never
@@ -408,7 +410,7 @@ installs or fetches a package.
 - Omits `bytefly`'s own entrypoint from the picker groups, so the tool that
   manages the list is never a selectable row; its doctor report still appears in
   the trailing `Not resolved` group.
-- Shows whether each one is enabled (`[x]`) or disabled (`[ ]`).
+- Shows whether each one is enabled (`◼`) or disabled (`◻`).
 - Shows the worst severity for a reported extension (`✓` ok, `!` degraded, `✕`
   missing, `∅` disabled) and its summary; an extension with no doctor report
   leaves the glyph column and the summary blank rather than claiming `ok`.
@@ -524,6 +526,9 @@ control-free line before it reaches an escape sequence or a shell argument.
 
 ## Limitations
 
+- **`doctor` is a reserved first argument.** `/bytefly doctor` always selects the
+  report, so an extension literally named `doctor` cannot be narrowed to by
+  name.
 - **The picker manages only the `extensions` resource type.** Skills, prompts,
   and themes are handled by Pi's own `pi config`.
 - **Built-in extensions are not listed** (`builtin:mcp`, `builtin:codemode`, …):
@@ -602,7 +607,7 @@ rather than showing a wrong value.
 |---|---|
 | Header | `ctx.ui.setHeader` with a custom component, replacing Pi's built-in header; installed only when `ctx.mode === "tui"`. The mark and text are drawn from the active theme's tokens, the help keys resolve live through `keyText`, and the mark falls back to a wordmark on Apple Terminal (`isAppleTerminalSession`), mirroring Pi's built-in. |
 | Footer | `ctx.ui.setFooter` with a custom component, replacing Pi's built-in footer; installed only when `ctx.mode === "tui"`. |
-| Screen command | `pi.registerCommand("bytefly"`, `"extensions"`, and `"doctor"`) share one handler: `tui` mounts a dock screen via `ctx.ui.custom()` with the rails suppressed, other modes print through `ctx.ui.notify()`. Tab completes extension names and `refresh`. |
+| Screen command | `pi.registerCommand("bytefly")` takes `[doctor] [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, or `run_doctor`'s report for `doctor`. Tab completes `doctor`, extension names, and `refresh`. |
 | Turn separator | `registerEntryRenderer("bytefly-separator")` draws each rule; `agent_settled` appends `pi.appendEntry("bytefly-separator", { turn })` in `tui` mode only. |
 | 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. |
@@ -617,12 +622,18 @@ rather than showing a wrong value.
 
 ## Design notes
 
+- **One kit, one look.** Every bytefly surface is drawn from the package's
+  `lib/tui/` design system: a role is resolved by the active theme, a rule comes
+  from `rules.ts`, a list row from `rows.ts`, a meter from `gauge.ts`, and a
+  width from `columns.ts`. Nothing in bytefly names a literal color, and a
+  theme swap re-skins the whole chrome.
 - **The header is a nameplate, not a dashboard.** Pi's built-in brand colors are
   fixed, so the mark ignores the active theme; bytefly's header draws a two-tone
-  mark from `accent`/`warning` and pairs it with the agent identity, the chrome
-  identity, and a grouped help block. It adds no session or model data — that is
-  the footer's job — and it stays a fixed four-plus rows so the startup
-  transcript never reflows.
+  mark from the `accent`/`warn` roles, a signature rule whose accent lead sits
+  under the mark, and pairs them with the agent identity, the chrome identity,
+  and a grouped help block. It adds no session or model data — that is the
+  footer's job — and it stays a fixed four-plus rows so the startup transcript
+  never reflows.
 - **Two lines, four zones.** Line 1 is identity (`pwd` left, branch + worktree
   right); line 2 is resources (meters left, model + level right). This keeps
   "where am I / what state" separate from "how much am I burning".
@@ -722,7 +733,7 @@ rather than showing a wrong value.
   reads the same command whether a tool failed or the report named it.
 - **The doctor is quiet by default at startup.** Only `missing` findings warn,
   only for enabled extensions, only with a UI, and only once per session;
-  `degraded` findings — including a malformed config — wait in `/doctor`, because
+  `degraded` findings — including a malformed config — wait in `/bytefly doctor`, because
   a session that nags about an optional package is worse than one that never
   mentions it.
 - **Probe the real thing.** `subagent`'s requirement resolves through the same
@@ -737,13 +748,15 @@ rather than showing a wrong value.
 The surfaces are folders: `header/`, `footer/` (the status bar and its price
 calculation), `separator/`, `panel/` (the unified screen and its merged model),
 `picker/` (discovery and the settings store), `doctor/` (the `run_doctor` tool
-and its probe runtime), and `notify/`.
+and its probe runtime), and `notify/`. The chrome and the screen are drawn from
+the package's [`lib/tui/`](../../lib/tui/) design system (tokens, rules, rows,
+columns, gauge), so the look follows the active theme.
 
 | File | Responsibility |
 |---|---|
 | `index.ts` | Composition root: the disable guard and the six `register*` calls. |
-| `header/config.ts` | Header tuning (`HEADER_CONFIG`): mark and identity tokens, padding, tagline, and the grouped help entries. |
-| `header/component.ts` | `ByteflyHeader`: the mark, identity rows, rule, and grouped help, plus its factory. |
+| `header/config.ts` | Header tuning (`HEADER_CONFIG`): mark and identity roles, padding, tagline, and the grouped help entries. |
+| `header/component.ts` | `ByteflyHeader`: the mark, identity rows, signature rule, and grouped help, plus its factory. |
 | `header/register.ts` | Installs/restores the header and owns its session lifecycle. |
 | `footer/register.ts` | Installs/restores the footer and owns its session lifecycle. |
 | `footer/config.ts` | Bar tuning (`CONFIG`): thresholds, gauge, separators, icons, status keys, labels. |
@@ -755,22 +768,22 @@ and its probe runtime), and `notify/`.
 | `footer/price/rates.ts` | Model-key matching: exact and wildcard, most specific first. |
 | `footer/price/schedule.ts` | Peak-window parsing and evaluation in a configured zone. |
 | `footer/price/price.ts` | Records → totals: rates, peak multiplier, recorded-cost fallback. |
-| `footer/render/format.ts` | Generic formatters (tokens, cost in the configured currency, cwd, gauge, colors). |
+| `footer/render/format.ts` | Generic formatters (tokens, cost in the configured currency, cwd, the context role, truncation). |
 | `footer/render/status.ts` | Status-chip transforms: `compactStatus` and `dropStatusDetail`. |
-| `footer/render/segments.ts` | The segment builders: forms, weights, separators, colors. |
+| `footer/render/segments.ts` | The segment builders: forms, weights, separators, roles. |
 | `footer/render/lines.ts` | Snapshot → two `LineSpec`s; status routing. |
 | `footer/render/layout.ts` | Width reduction and right-zone folding. |
 | `footer/render/footer.ts` | `StatusBar` component and footer factory. |
-| `separator/config.ts` | Turn-rule tuning: `customType`, glyph, label prefix, padding, and colors. |
+| `separator/config.ts` | Turn-rule tuning: `customType`, glyph, label prefix, padding, and roles. |
 | `separator/register.ts` | Registers the entry renderer and appends a separator on `agent_settled`. |
 | `separator/component.ts` | `SeparatorComponent`: the stateless entry renderer. |
-| `separator/format.ts` | Pure `separatorLabel` / `separatorParts` / `separatorLine`. |
-| `separator/types.ts` | `TurnSeparatorData`, `SeparatorParts`. |
+| `separator/format.ts` | Pure `separatorLine`: the centered turn rule, drawn by the kit's `centeredRule`. |
+| `separator/types.ts` | `TurnSeparatorData`. |
 | `panel/types.ts` | `PanelRow` and `PanelModel`, the merged row model. |
 | `panel/join.ts` | The item/report union with the unambiguous-name health rule and unique row keys, groups, and ordering. |
 | `panel/format.ts` | Non-TUI text: the headline and the grouped listing with a per-row health suffix. |
-| `panel/tui.ts` | `PanelComponent`, the unified dock screen. |
-| `panel/commands.ts` | `/bytefly`, `/extensions`, and `/doctor`: one runner for the screen and its text modes. |
+| `panel/tui.ts` | `PanelComponent`, the unified dock screen, drawn from the `lib/tui/` kit. |
+| `panel/commands.ts` | `/bytefly`: one command for the screen, the `doctor` report, and their text modes. |
 | `picker/types.ts` | Picker host seams (`SettingsStore`, `ExtensionResolver`, `Discovery`) and row types. |
 | `picker/resources.ts` | Pure grouping, labels, display names, and pattern helpers. |
 | `picker/toggle.ts` | Pure next-settings transforms for global and project toggles. |
@@ -781,7 +794,7 @@ and its probe runtime), and `notify/`.
 | `doctor/tools.ts` | The `run_doctor` tool and its renderers. |
 | `doctor/schema.ts` | Tool parameters and the structured output schema. |
 | `doctor/config.ts` | `DEFAULT_CONFIG`, `normalizeConfig`, `loadConfig` for the `doctor` section of `bytefly.json`. |
-| `doctor/format.ts` | Pure report text, summary, glyphs, detail lines, and the proactive warning sentence. |
+| `doctor/format.ts` | Pure report text, summary, severity roles and glyphs, detail lines, and the proactive warning sentence. |
 | `notify/types.ts` | `NotifyConfig`, `NotifyMethod`, and the method list. |
 | `notify/config.ts` | The `notify` section of `bytefly.json`: defaults, validation, loader. |
 | `notify/dispatch.ts` | Method selection and delivery: OSC 777/99, Windows toast, `osascript`, `notify-send`, over injected seams. |

package/extensions/bytefly/doctor/format.ts

@@ -12,7 +12,8 @@ import type { Theme } from "@earendil-works/pi-coding-agent";
 import { wrapTextWithAnsi } from "@earendil-works/pi-tui";
 import { sanitizeLine } from "../../../lib/format.ts";
 import type { ExtensionReport, Finding, FindingSeverity } from "../../../lib/requirements.ts";
-import { GLYPHS } from "../../../lib/ui.ts";
+import { GLYPHS } from "../../../lib/tui/glyphs.ts";
+import { paint, type TuiRole } from "../../../lib/tui/tokens.ts";
 
 /** Counts the report headline uses. */
 export interface ReportCounts {
@@ -102,15 +103,40 @@ export function formatWarning(findings: readonly Finding[]): string {
 		byExtension.set(finding.extension, list);
 	}
 	const parts = [...byExtension].map(([extension, checks]) => `${sanitizeLine(extension)} (${checks.join(", ")})`);
-	return `doctor: missing ${parts.join("; ")} — run /doctor`;
+	return `doctor: missing ${parts.join("; ")} — run /bytefly doctor`;
 }
 
-/** The severity glyph, from the shared vocabulary. */
+/** The design role a severity is drawn in. */
+export function severityRole(severity: FindingSeverity): TuiRole {
+	switch (severity) {
+		case "missing":
+			return "bad";
+		case "degraded":
+			return "warn";
+		case "info":
+			return "faint";
+		default:
+			return "ok";
+	}
+}
+
+/** The bare severity glyph, from the shared vocabulary. */
+export function severityGlyphChar(severity: FindingSeverity): string {
+	switch (severity) {
+		case "missing":
+			return GLYPHS.cross;
+		case "degraded":
+			return GLYPHS.warn;
+		case "info":
+			return GLYPHS.disabled;
+		default:
+			return GLYPHS.check;
+	}
+}
+
+/** The severity glyph, themed by role. */
 export function severityGlyph(severity: FindingSeverity, theme: Theme): string {
-	if (severity === "missing") return theme.fg("error", GLYPHS.cross);
-	if (severity === "degraded") return theme.fg("warning", GLYPHS.warn);
-	if (severity === "info") return theme.fg("dim", GLYPHS.disabled);
-	return theme.fg("success", GLYPHS.check);
+	return paint(theme, severityRole(severity), severityGlyphChar(severity));
 }
 
 /** The severity that represents an extension: worst finding wins. */
@@ -147,7 +173,7 @@ export function detailLines(
 	const budget = Math.max(1, rows);
 	const shown = includeInfo ? report.findings : report.findings.filter((finding) => finding.severity !== "info");
 	if (shown.length === 0) {
-		return [`  ${theme.fg("dim", report.enabled ? "no problems" : "disabled")}`];
+		return [`  ${paint(theme, "faint", report.enabled ? "no problems" : "disabled")}`];
 	}
 
 	const lines: string[] = [];
@@ -160,10 +186,10 @@ export function detailLines(
 		}
 		if (finding.hint) {
 			for (const line of wrapTextWithAnsi(`→ ${sanitizeLine(finding.hint)}`, Math.max(1, width - 4))) {
-				lines.push(`    ${theme.fg("dim", line)}`);
+				lines.push(`    ${paint(theme, "faint", line)}`);
 			}
 		}
 	}
 	if (lines.length <= budget) return lines;
-	return [...lines.slice(0, budget - 1), `  ${theme.fg("dim", "…")}`];
+	return [...lines.slice(0, budget - 1), `  ${paint(theme, "faint", "…")}`];
 }

package/extensions/bytefly/doctor/tools.ts

@@ -9,7 +9,8 @@
 
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { missingFindings } from "../../../lib/requirements.ts";
-import { reuseText, toolDetails } from "../../../lib/tui.ts";
+import { reuseText, toolDetails } from "../../../lib/tui/chrome.ts";
+import { paint, type TuiRole } from "../../../lib/tui/tokens.ts";
 import { formatExtension, formatReport, isProblemSeverity } from "./format.ts";
 import type { DoctorRuntime } from "./runtime.ts";
 import { DoctorOutput, DoctorParams, TOOL_NAME, type DoctorArgs, type DoctorStructured } from "./schema.ts";
@@ -93,20 +94,20 @@ export function registerTools(pi: ExtensionAPI, runtime: DoctorRuntime): void {
 			const input = args as DoctorArgs;
 			const scope = `${input.extension ? ` ${input.extension}` : ""}${input.refresh ? " (refresh)" : ""}`;
 			const text = reuseText(context?.lastComponent);
-			text.setText(`${theme.fg("toolTitle", "doctor")}${theme.fg("dim", scope)}`);
+			text.setText(`${theme.fg("toolTitle", "doctor")}${paint(theme, "faint", scope)}`);
 			return text;
 		},
 
 		renderResult(result, _options, theme, context) {
 			const structured = toolDetails<DoctorStructured>(result.details);
-			const tone = (structured?.missing ?? 0) > 0 ? "error" : (structured?.degraded ?? 0) > 0 ? "warning" : "success";
+			const tone: TuiRole = (structured?.missing ?? 0) > 0 ? "bad" : (structured?.degraded ?? 0) > 0 ? "warn" : "ok";
 			const text = reuseText(context?.lastComponent);
 			if (!structured) {
 				const first = result.content[0];
-				text.setText(first?.type === "text" ? first.text : theme.fg("muted", "doctor: no result"));
+				text.setText(first?.type === "text" ? first.text : paint(theme, "meta", "doctor: no result"));
 				return text;
 			}
-			text.setText(theme.fg(tone, summaryLines(structured).join("\n")));
+			text.setText(paint(theme, tone, summaryLines(structured).join("\n")));
 			return text;
 		},
 	});

package/extensions/bytefly/footer/config.ts

@@ -7,7 +7,7 @@
  * configuration is `bytefly.json`, read by `../price/config.ts`.
  */
 
-import { GLYPHS, SEPARATORS, STATUS_KEYS } from "../../../lib/ui.ts";
+import { GLYPHS, SEPARATORS, STATUS_KEYS } from "../../../lib/tui/glyphs.ts";
 
 export const CONFIG = {
 	/** Context percentage thresholds. */

package/extensions/bytefly/footer/render/format.ts

@@ -6,9 +6,10 @@
  */
 
 import type { ThinkingLevel } from "@earendil-works/pi-agent-core";
-import type { ThemeColor } from "@earendil-works/pi-coding-agent";
 import { stripTerminalSequences, truncateToWidth } from "@earendil-works/pi-tui";
 import { shortenPath } from "../../../../lib/format.ts";
+import { gaugeRole } from "../../../../lib/tui/gauge.ts";
+import type { TuiRole } from "../../../../lib/tui/tokens.ts";
 import { CONFIG } from "../config.ts";
 import { DEFAULT_CURRENCY } from "../price/config.ts";
 import type { Currency } from "../price/types.ts";
@@ -65,23 +66,9 @@ export function formatCwd(cwd: string, home: string | undefined, level: 0 | 1 |
 	return parts.length <= 2 ? shortened : `…/${parts.slice(-2).join("/")}`;
 }
 
-/** Filled/empty block counts for a percentage across `blocks` cells. */
-export function computeGauge(percent: number | null, blocks: number): { filled: number; empty: number } {
-	if (blocks <= 0) return { filled: 0, empty: 0 };
-	if (percent === null) return { filled: 0, empty: blocks };
-	const clamped = Math.max(0, Math.min(100, percent));
-	// Floor so the bar is only full at 100%; force one block for any non-zero
-	// usage so a small percentage is still visible.
-	const filled = Math.max(clamped > 0 ? 1 : 0, Math.floor((clamped / 100) * blocks));
-	return { filled, empty: blocks - filled };
-}
-
-/** Gauge color for a context percentage. Neutral until it crosses a threshold. */
-export function contextColor(percent: number | null): ThemeColor {
-	if (percent === null) return "muted";
-	if (percent > CONFIG.thresholds.danger) return "error";
-	if (percent > CONFIG.thresholds.warn) return "warning";
-	return "muted";
+/** The design role a context percentage is drawn in. Neutral until it crosses a threshold. */
+export function contextRole(percent: number | null): TuiRole {
+	return gaugeRole(percent, CONFIG.thresholds);
 }
 
 const THINKING_TOKENS: Record<ThinkingLevel, ThinkingColor> = {

package/extensions/bytefly/footer/render/layout.ts

@@ -10,6 +10,7 @@
 
 import type { Theme } from "@earendil-works/pi-coding-agent";
 import { truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
+import { paint } from "../../../../lib/tui/tokens.ts";
 import { CONFIG } from "../config.ts";
 import type { LineSpec, Segment } from "../types.ts";
 
@@ -135,5 +136,5 @@ export function renderLine(spec: LineSpec, width: number, theme: Theme): string
 		if (!collapseSeparator(states)) break;
 	}
 
-	return truncateToWidth(assemble(states, target), target, theme.fg("dim", "…"));
+	return truncateToWidth(assemble(states, target), target, paint(theme, "faint", "…"));
 }