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

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

@@ -3,26 +3,23 @@
  *
  * Each segment carries progressively shorter `forms` and a `weight`; the layout
  * engine advances forms and drops segments from the highest weight down, so the
- * bar degrades predictably instead of clipping arbitrary text.
+ * bar degrades predictably instead of clipping arbitrary text. Colors come from
+ * the design-system roles, so the bar follows the active theme.
  */
 
 import type { Theme } from "@earendil-works/pi-coding-agent";
 import { stripTerminalSequences } from "@earendil-works/pi-tui";
 import { formatTokens, sanitize, sanitizeLine } from "../../../../lib/format.ts";
+import { gaugeBar } from "../../../../lib/tui/gauge.ts";
+import { chip } from "../../../../lib/tui/rows.ts";
+import { paint } from "../../../../lib/tui/tokens.ts";
 import { CONFIG } from "../config.ts";
-import {
-	computeGauge,
-	contextColor,
-	formatCost,
-	formatCwd,
-	formatPercent,
-	thinkingColor,
-	truncateLabel,
-} from "./format.ts";
+import { contextRole, formatCost, formatCwd, formatPercent, thinkingColor, truncateLabel } from "./format.ts";
 import { compactStatus, dropStatusDetail } from "./status.ts";
 import type { Segment, StatusSnapshot } from "../types.ts";
 
-const dim = (theme: Theme, text: string): string => theme.fg("dim", text);
+/** Tertiary text: paths and de-emphasized meters. */
+const faint = (theme: Theme, text: string): string => paint(theme, "faint", text);
 
 /**
  * The label part of a themed status chip: strip its escape sequences, sanitize
@@ -41,9 +38,9 @@ export function pwdSegment(snapshot: StatusSnapshot, theme: Theme, home: string
 		droppable: false,
 		separator: "",
 		forms: [
-			dim(theme, formatCwd(snapshot.cwd, home, 0)),
-			dim(theme, formatCwd(snapshot.cwd, home, 1)),
-			dim(theme, formatCwd(snapshot.cwd, home, 2)),
+			faint(theme, formatCwd(snapshot.cwd, home, 0)),
+			faint(theme, formatCwd(snapshot.cwd, home, 1)),
+			faint(theme, formatCwd(snapshot.cwd, home, 2)),
 		],
 	};
 }
@@ -54,13 +51,13 @@ export function sessionSegment(snapshot: StatusSnapshot, theme: Theme): Segment
 	const short = truncateLabel(name, CONFIG.sessionLabelMax);
 	// Brackets and a brighter token keep the session name from reading as a
 	// trailing path segment.
-	const forms = [theme.fg("muted", `[${name}]`)];
-	if (short !== name) forms.push(theme.fg("muted", `[${short}]`));
+	const forms = [paint(theme, "meta", `[${name}]`)];
+	if (short !== name) forms.push(paint(theme, "meta", `[${short}]`));
 	return {
 		id: "session",
 		weight: 3,
 		droppable: true,
-		separator: dim(theme, CONFIG.separators.item),
+		separator: faint(theme, CONFIG.separators.item),
 		forms,
 	};
 }
@@ -68,14 +65,13 @@ export function sessionSegment(snapshot: StatusSnapshot, theme: Theme): Segment
 export function branchSegment(snapshot: StatusSnapshot, theme: Theme): Segment | null {
 	if (!snapshot.branch) return null;
 	const detached = snapshot.branch === CONFIG.labels.detached;
-	const color = detached ? "warning" : "muted";
 	const icon = detached ? CONFIG.icons.detached : CONFIG.icons.branch;
 	return {
 		id: "branch",
 		weight: 1,
 		droppable: true,
-		separator: dim(theme, CONFIG.separators.item),
-		forms: [theme.fg(color, `${icon} ${snapshot.branch}`)],
+		separator: faint(theme, CONFIG.separators.item),
+		forms: [chip(theme, icon, snapshot.branch, detached ? "warn" : "meta")],
 	};
 }
 
@@ -83,27 +79,16 @@ export function worktreeSegment(snapshot: StatusSnapshot, theme: Theme): Segment
 	const raw = snapshot.statuses.get(CONFIG.worktreeStatusKey);
 	if (!raw) return null;
 	const icon = CONFIG.icons.worktree;
+	const separator = faint(theme, CONFIG.separators.item);
 	const label = chipLabel(raw);
 	if (!label) {
-		return {
-			id: "worktree",
-			weight: 3,
-			droppable: true,
-			separator: dim(theme, CONFIG.separators.item),
-			forms: [theme.fg("success", icon)],
-		};
+		return { id: "worktree", weight: 3, droppable: true, separator, forms: [paint(theme, "ok", icon)] };
 	}
 	const short = truncateLabel(label, CONFIG.worktreeLabelMax);
-	const forms = [theme.fg("success", `${icon} ${label}`)];
-	if (short !== label) forms.push(theme.fg("success", `${icon} ${short}`));
-	forms.push(theme.fg("success", icon));
-	return {
-		id: "worktree",
-		weight: 3,
-		droppable: true,
-		separator: dim(theme, CONFIG.separators.item),
-		forms,
-	};
+	const forms = [chip(theme, icon, label, "ok")];
+	if (short !== label) forms.push(chip(theme, icon, short, "ok"));
+	forms.push(paint(theme, "ok", icon));
+	return { id: "worktree", weight: 3, droppable: true, separator, forms };
 }
 
 export function browseSegment(snapshot: StatusSnapshot, theme: Theme): Segment | null {
@@ -111,25 +96,20 @@ export function browseSegment(snapshot: StatusSnapshot, theme: Theme): Segment |
 	if (!raw) return null;
 	const icon = CONFIG.icons.browse;
 	const label = chipLabel(raw);
-	const separator = dim(theme, CONFIG.separators.item);
+	const separator = faint(theme, CONFIG.separators.item);
 	if (!label) {
-		return {
-			id: "browse",
-			weight: 3,
-			droppable: true,
-			separator,
-			forms: [theme.fg("success", icon)],
-		};
+		return { id: "browse", weight: 3, droppable: true, separator, forms: [paint(theme, "ok", icon)] };
 	}
+	// A two-tone chip: the `◉` glyph stays green while the port reads as accent.
 	return {
 		id: "browse",
 		weight: 3,
 		droppable: true,
 		separator,
 		forms: [
-			`${theme.fg("success", icon)} ${theme.fg("accent", label)}`,
-			`${theme.fg("success", icon)}${theme.fg("accent", label)}`,
-			theme.fg("success", icon),
+			`${paint(theme, "ok", icon)} ${paint(theme, "accent", label)}`,
+			`${paint(theme, "ok", icon)}${paint(theme, "accent", label)}`,
+			paint(theme, "ok", icon),
 		],
 	};
 }
@@ -150,7 +130,7 @@ export function modesSegment(snapshot: StatusSnapshot, theme: Theme): Segment |
 		})
 		.filter(Boolean);
 	if (others.length === 0) return null;
-	const full = others.join(dim(theme, CONFIG.separators.item));
+	const full = others.join(faint(theme, CONFIG.separators.item));
 	// The compact form keeps each status's own colour (see `compactStatus`); a
 	// two-token badge keeps its count (`↺ 2` -> `↺2`) instead of collapsing to a
 	// bare icon.
@@ -161,31 +141,22 @@ export function modesSegment(snapshot: StatusSnapshot, theme: Theme): Segment |
 		// than truncating the model, which sits at the end of the line.
 		weight: 1,
 		droppable: true,
-		separator: dim(theme, CONFIG.separators.group),
+		separator: faint(theme, CONFIG.separators.group),
 		forms: [full, icons],
 	};
 }
 
 export function contextSegment(snapshot: StatusSnapshot, theme: Theme): Segment {
 	const percent = snapshot.context.percent;
-	const color = contextColor(percent);
-	const percentText = theme.fg(color, formatPercent(percent));
-	const gaugeWidths: readonly number[] = percent === null ? [0] : CONFIG.gauge.widths;
-	const forms = gaugeWidths.map((blocks) => {
-		const { filled, empty } = computeGauge(percent, blocks);
-		const gauge =
-			blocks > 0
-				? theme.fg(color, CONFIG.gauge.full.repeat(filled)) + theme.fg("dim", CONFIG.gauge.empty.repeat(empty)) + " "
-				: "";
-		return `${gauge}${percentText}`;
-	});
-	return {
-		id: "context",
-		weight: 1,
-		droppable: false,
-		separator: "",
-		forms,
-	};
+	const role = contextRole(percent);
+	const percentText = paint(theme, role, formatPercent(percent));
+	// Unknown usage draws no track, so `?` sits where the gauge would be rather
+	// than a full row of empty blocks claiming a known zero.
+	const widths: readonly number[] = percent === null ? [0] : CONFIG.gauge.widths;
+	const forms = widths.map((blocks) =>
+		blocks > 0 ? `${gaugeBar(theme, { percent, blocks, role, emptyRole: "faint" })} ${percentText}` : percentText,
+	);
+	return { id: "context", weight: 1, droppable: false, separator: "", forms };
 }
 
 export function windowSegment(snapshot: StatusSnapshot, theme: Theme): Segment | null {
@@ -195,7 +166,7 @@ export function windowSegment(snapshot: StatusSnapshot, theme: Theme): Segment |
 		weight: 3,
 		droppable: true,
 		separator: "",
-		forms: [dim(theme, `/${formatTokens(snapshot.context.contextWindow)}`)],
+		forms: [faint(theme, `/${formatTokens(snapshot.context.contextWindow)}`)],
 	};
 }
 
@@ -205,8 +176,8 @@ export function costSegment(snapshot: StatusSnapshot, theme: Theme): Segment | n
 		id: "cost",
 		weight: 2,
 		droppable: true,
-		separator: dim(theme, CONFIG.separators.item),
-		forms: [theme.fg("muted", formatCost(snapshot.usage.cost, snapshot.currency))],
+		separator: faint(theme, CONFIG.separators.item),
+		forms: [paint(theme, "meta", formatCost(snapshot.usage.cost, snapshot.currency))],
 	};
 }
 
@@ -220,8 +191,8 @@ export function tokensSegment(snapshot: StatusSnapshot, theme: Theme): Segment |
 		id: "tokens",
 		weight: 4,
 		droppable: true,
-		separator: dim(theme, CONFIG.separators.item),
-		forms: [dim(theme, parts.join(" "))],
+		separator: faint(theme, CONFIG.separators.item),
+		forms: [faint(theme, parts.join(" "))],
 	};
 }
 
@@ -240,8 +211,8 @@ export function cacheSegment(snapshot: StatusSnapshot, theme: Theme): Segment |
 		id: "cache",
 		weight: 5,
 		droppable: true,
-		separator: dim(theme, CONFIG.separators.item),
-		forms: [dim(theme, parts.join(" "))],
+		separator: faint(theme, CONFIG.separators.item),
+		forms: [faint(theme, parts.join(" "))],
 	};
 }
 
@@ -254,7 +225,7 @@ export function modelSegment(snapshot: StatusSnapshot, theme: Theme): Segment {
 			weight: 1,
 			droppable: false,
 			separator: "",
-			forms: [theme.fg("muted", CONFIG.labels.noModel)],
+			forms: [paint(theme, "meta", CONFIG.labels.noModel)],
 		};
 	}
 	const provider = snapshot.providerCount > 1 ? `(${model.provider}) ` : "";
@@ -263,19 +234,21 @@ export function modelSegment(snapshot: StatusSnapshot, theme: Theme): Segment {
 		weight: 1,
 		droppable: false,
 		separator: "",
-		forms: [theme.fg("accent", `${provider}${model.id}`), theme.fg("accent", model.id)],
+		forms: [paint(theme, "accent", `${provider}${model.id}`), paint(theme, "accent", model.id)],
 	};
 }
 
 export function thinkingSegment(snapshot: StatusSnapshot, theme: Theme): Segment | null {
 	if (!snapshot.model?.reasoning) return null;
 	const level = snapshot.thinkingLevel ?? "off";
+	// The reasoning scale is Pi's own seven-token ramp, not a design role: a
+	// level colors itself from `thinkingColor`.
 	const color = thinkingColor(level);
 	return {
 		id: "thinking",
 		weight: 2,
 		droppable: true,
-		separator: dim(theme, CONFIG.separators.item),
+		separator: faint(theme, CONFIG.separators.item),
 		forms: [theme.fg(color, level)],
 	};
 }

package/extensions/bytefly/header/component.ts

@@ -3,16 +3,18 @@
  *
  * It draws bytefly's nameplate: a two-tone mark beside the agent identity (Pi
  * and its version) and the chrome identity (the tagline, bytefly, and its
- * version), a `─` rule, and a grouped help block. The mark is theme-colored and
- * falls back to a wordmark where half blocks do not render, the help keys are
- * resolved live from Pi's keybindings, and every line is truncated to the width
- * it is given.
+ * version), a signature rule whose accent lead sits under the mark, and a
+ * grouped help block. The mark and text are theme-colored through the shared
+ * design-system roles, the mark falls back to a wordmark where half blocks do
+ * not render, the help keys are resolved live from Pi's keybindings, and every
+ * line is truncated to the width it is given.
  */
 
 import { keyText, type Theme, VERSION } from "@earendil-works/pi-coding-agent";
 import { type Component, type TUI, truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
-import { screenHint } from "../../../lib/tui.ts";
-import { keyHintText } from "../../../lib/ui.ts";
+import { screenHint } from "../../../lib/tui/chrome.ts";
+import { keyHintText } from "../../../lib/tui/glyphs.ts";
+import { paint } from "../../../lib/tui/tokens.ts";
 import { HEADER_CONFIG, type HelpEntry } from "./config.ts";
 
 /** The header's shape, resolved once per apply so `render` stays cheap. */
@@ -33,9 +35,9 @@ function markBlock(line: string): string {
 
 /** The two mark lines: the half-block logo, or the wordmark where it will not render. */
 function markLines(theme: Theme, halfBlocks: boolean): [string, string] {
-	const { markColor, markAccent } = HEADER_CONFIG;
-	if (halfBlocks) return [theme.fg(markColor, "█▀█"), theme.fg(markAccent, "█▀ █")];
-	return [theme.fg(markColor, "P") + theme.fg(markAccent, "i"), ""];
+	const { markRole, markAccentRole } = HEADER_CONFIG;
+	if (halfBlocks) return [paint(theme, markRole, "█▀█"), paint(theme, markAccentRole, "█▀ █")];
+	return [paint(theme, markRole, "P") + paint(theme, markAccentRole, "i"), ""];
 }
 
 /** One help entry split into the text to print and its description. */
@@ -61,20 +63,20 @@ export class ByteflyHeader implements Component {
 		const w = Math.max(1, width);
 		const theme = this.getTheme();
 		const view = this.view();
-		const { padX, nameColor, versionColor, chromeTagline, chromeName, chromeVersion, help } = HEADER_CONFIG;
+		const { padX, nameRole, chromeRole, detailRole, chromeTagline, chromeName, chromeVersion, help } = HEADER_CONFIG;
 		const pad = " ".repeat(Math.min(padX, Math.max(0, w - 1)));
 		const [markTop, markBottom] = markLines(theme, view.halfBlocks);
 
-		const version = view.showVersion && this.version ? theme.fg(versionColor, `v${this.version}`) : "";
+		const version = view.showVersion && this.version ? paint(theme, detailRole, `v${this.version}`) : "";
 		// The wordmark mark spells the app name, so the agent cell carries only the
 		// version there; the half-block mark does not, so the name stays beside it.
 		const agent = view.halfBlocks
 			? version
-				? `${theme.fg(nameColor, HEADER_CONFIG.appName)} ${version}`
-				: theme.fg(nameColor, HEADER_CONFIG.appName)
+				? `${theme.bold(paint(theme, nameRole, HEADER_CONFIG.appName))} ${version}`
+				: theme.bold(paint(theme, nameRole, HEADER_CONFIG.appName))
 			: version;
-		const chrome = `${theme.fg(versionColor, chromeTagline)} ${theme.fg(nameColor, chromeName)}`;
-		const chromeVersioned = chromeVersion ? `${chrome} ${theme.fg(versionColor, `v${chromeVersion}`)}` : chrome;
+		const chrome = `${paint(theme, detailRole, chromeTagline)} ${paint(theme, chromeRole, chromeName)}`;
+		const chromeVersioned = chromeVersion ? `${chrome} ${paint(theme, detailRole, `v${chromeVersion}`)}` : chrome;
 
 		// The identity rows shed as one block: chrome version, chrome line, agent.
 		const states: Array<readonly [string, string]> = [
@@ -89,11 +91,26 @@ export class ByteflyHeader implements Component {
 		return [
 			this.identityLine(pad, markTop, agentCell, w),
 			this.identityLine(pad, markBottom, chromeCell, w),
-			`${pad}${theme.fg("borderMuted", "─".repeat(Math.max(0, w - pad.length)))}`,
+			this.rule(theme, w, pad),
 			...help.map((row) => this.helpLine(theme, w, row)),
 		];
 	}
 
+	/**
+	 * The nameplate's signature rule: an accent lead as wide as the mark, so the
+	 * rule is anchored to the mark, then a muted fill to the edge.
+	 */
+	private rule(theme: Theme, width: number, pad: string): string {
+		const remaining = Math.max(0, width - pad.length);
+		const lead = Math.min(MARK_WIDTH, remaining);
+		const fill = remaining - lead;
+		return (
+			pad +
+			paint(theme, HEADER_CONFIG.ruleAccentRole, "─".repeat(lead)) +
+			paint(theme, HEADER_CONFIG.ruleRole, "─".repeat(fill))
+		);
+	}
+
 	/** A nameplate row: the padded mark, a gutter, then the identity cell if it survived. */
 	private identityLine(pad: string, mark: string, cell: string, width: number): string {
 		const line = cell ? `${pad}${markBlock(mark)} ${cell}` : `${pad}${markBlock(mark)}`;

package/extensions/bytefly/header/config.ts

@@ -3,14 +3,16 @@
  *
  * The header is a nameplate: a two-tone mark beside the agent identity (Pi and
  * its version) and the chrome identity (the tagline, bytefly, and its version),
- * a `─` rule, and a grouped help block. The mark and the text are drawn from the
- * active theme's tokens, and the help keys are resolved live from Pi's
- * keybindings, so a rebound key is respected.
+ * a signature rule whose accent lead sits under the mark, and a grouped help
+ * block. Every color is a design-system role resolved by the active theme, and
+ * the help keys are resolved live from Pi's keybindings, so a rebound key is
+ * respected.
  */
 
-import type { AppKeybinding, ThemeColor } from "@earendil-works/pi-coding-agent";
+import type { AppKeybinding } from "@earendil-works/pi-coding-agent";
+import { EXPAND_KEYBINDING } from "../../../lib/tui/glyphs.ts";
+import type { TuiRole } from "../../../lib/tui/tokens.ts";
 import pkg from "../../../package.json";
-import { EXPAND_KEYBINDING } from "../../../lib/ui.ts";
 
 /** One help entry: a Pi keybinding resolved live, or a raw key or command prefix. */
 export type HelpEntry =
@@ -23,14 +25,20 @@ export interface HeaderConfig {
 	readonly appName: string;
 	/** Print Pi's version on the agent line. */
 	readonly showVersion: boolean;
-	/** Theme token for the mark's top line. */
-	readonly markColor: ThemeColor;
-	/** Theme token for the mark's bottom line. */
-	readonly markAccent: ThemeColor;
-	/** Theme token for the agent and chrome names. */
-	readonly nameColor: ThemeColor;
-	/** Theme token for the versions, the tagline, and the help descriptions. */
-	readonly versionColor: ThemeColor;
+	/** Role for the mark's top line. */
+	readonly markRole: TuiRole;
+	/** Role for the mark's bottom line. */
+	readonly markAccentRole: TuiRole;
+	/** Role for the agent name. */
+	readonly nameRole: TuiRole;
+	/** Role for the chrome name. */
+	readonly chromeRole: TuiRole;
+	/** Role for the versions, the tagline, and the help descriptions. */
+	readonly detailRole: TuiRole;
+	/** Role for the rule's accent lead under the mark. */
+	readonly ruleAccentRole: TuiRole;
+	/** Role for the rest of the rule. */
+	readonly ruleRole: TuiRole;
 	/** Columns of left padding, matching Pi's built-in header indent. */
 	readonly padX: number;
 	/** The tagline before the chrome name, so the relationship reads in words. */
@@ -46,10 +54,13 @@ export interface HeaderConfig {
 export const HEADER_CONFIG: HeaderConfig = {
 	appName: "Pi",
 	showVersion: true,
-	markColor: "accent",
-	markAccent: "warning",
-	nameColor: "muted",
-	versionColor: "dim",
+	markRole: "accent",
+	markAccentRole: "warn",
+	nameRole: "label",
+	chromeRole: "meta",
+	detailRole: "faint",
+	ruleAccentRole: "accent",
+	ruleRole: "rule",
 	padX: 1,
 	chromeTagline: "enhanced by",
 	chromeName: "bytefly",
@@ -74,7 +85,6 @@ export const HEADER_CONFIG: HeaderConfig = {
 			{ raw: "!", description: "bash" },
 			{ raw: "!!", description: "bash (no context)" },
 			{ raw: "/bytefly", description: "extensions" },
-			{ raw: "/doctor", description: "checks" },
 			{ binding: "app.message.followUp", description: "to queue follow-up" },
 			{ binding: "app.clipboard.pasteImage", description: "paste files" },
 		],

package/extensions/bytefly/index.ts

@@ -3,7 +3,7 @@
  * feature folders: `header/` (the themed startup mark and version), `footer/`
  * (the two-line, width-adaptive status bar with its price calculation),
  * `separator/` (the transcript turn rule), `panel/` (the unified `/bytefly`
- * screen, also reachable as `/extensions` and `/doctor`), `doctor/` (the
+ * screen and its `doctor` report), `doctor/` (the
  * `run_doctor` tool and its session-scoped probe runtime), and `notify/` (OS
  * notifications for unattended runs).
  *

package/extensions/bytefly/panel/commands.ts

@@ -1,12 +1,12 @@
 /**
- * The `/bytefly` surface: one runner that opens the unified panel, with
- * `/extensions` and `/doctor` registered against the same handler.
+ * The `/bytefly` surface: one command, `/bytefly [doctor] [extension] [refresh]`.
  *
- * In `tui` mode it mounts the dock screen; every other mode prints the same
- * information as text. Discovery, the doctor probe, and the dirty-to-reload
- * confirm all live here, so the three command names cannot drift. The doctor
- * runtime is injected by the composition root, so `run_doctor` and the screen
- * keep reading one session cache.
+ * Without `doctor` it opens the extension screen: the dock in `tui`, the
+ * grouped listing elsewhere. With `doctor` it produces the doctor report — the
+ * same text `run_doctor` returns — for the whole set or one named extension; in
+ * `tui` the report is the dock screen. Discovery, the doctor probe, and the
+ * dirty-to-reload confirm all live here. The doctor runtime is injected by the
+ * composition root, so `run_doctor` and the screen keep reading one cache.
  */
 
 import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
@@ -14,10 +14,10 @@ import { getAgentDir } from "@earendil-works/pi-coding-agent";
 import { sanitizeLine } from "../../../lib/format.ts";
 import { withRailsSuppressed } from "../../../lib/rails.ts";
 import { REQUIREMENTS, type ExtensionReport } from "../../../lib/requirements.ts";
-import { formatExtension, hasProblems } from "../doctor/format.ts";
+import { formatExtension, formatReport, hasProblems } from "../doctor/format.ts";
 import type { DoctorRuntime } from "../doctor/runtime.ts";
 import { discoverExtensions, type DiscoveryDeps } from "../picker/discovery.ts";
-import { createExtensionsPickerRuntime } from "../picker/runtime.ts";
+import { createExtensionsPickerRuntime, type ExtensionsPickerRuntime } from "../picker/runtime.ts";
 import type { Discovery } from "../picker/types.ts";
 import { formatListing } from "./format.ts";
 import { buildPanelModel, extensionName } from "./join.ts";
@@ -42,20 +42,63 @@ function selectableNames(discovery: Discovery): Set<string> {
 	return names;
 }
 
-/** The shared completion list: every declared extension, then `refresh`. */
+/** Argument completions: the `doctor` subcommand, every declared extension, then `refresh`. */
 function completions(prefix: string): Array<{ value: string; label: string }> | null {
-	const options = [...Object.keys(REQUIREMENTS), "refresh"].filter((option) => option.startsWith(prefix));
+	const options = ["doctor", ...Object.keys(REQUIREMENTS), "refresh"].filter((option) => option.startsWith(prefix));
 	return options.length > 0 ? options.map((value) => ({ value, label: value })) : null;
 }
 
-/** Register `/bytefly`, `/extensions`, and `/doctor` against one runner. */
+/** Which bytefly surface the arguments select. */
+type PanelMode = "screen" | "doctor";
+
+/** `/bytefly [doctor] [extension] [refresh]`, parsed. */
+interface PanelArgs {
+	mode: PanelMode;
+	/** The extension to narrow to, when one is named. */
+	name?: string;
+	/** Re-probe the doctor instead of reusing the session cache. */
+	refresh: boolean;
+}
+
+/** Parse `/bytefly [doctor] [extension] [refresh]`; extra tokens are ignored. */
+function parseArgs(args: string): PanelArgs {
+	const parts = args.trim().split(/\s+/).filter(Boolean);
+	const refresh = parts.includes("refresh");
+	const rest = parts.filter((part) => part !== "refresh");
+	const mode: PanelMode = rest[0] === "doctor" ? "doctor" : "screen";
+	return { mode, name: rest[mode === "doctor" ? 1 : 0], refresh };
+}
+
+/**
+ * Print one extension's full findings, or say why it has none. The screen's
+ * named form and the `doctor` subcommand share this text path.
+ */
+function notifyExtension(
+	ctx: ExtensionCommandContext,
+	name: string,
+	reports: readonly ExtensionReport[],
+	runtime: ExtensionsPickerRuntime,
+): void {
+	const report = reports.find((entry) => entry.extension === name);
+	if (report) {
+		ctx.ui.notify(formatExtension(report), hasProblems([report]) ? "warning" : "info");
+		return;
+	}
+	const item = runtime.items().find((entry) => extensionName(entry.path) === name);
+	ctx.ui.notify(
+		item
+			? `bytefly: ${sanitizeLine(item.path)} — no doctor report`
+			: `bytefly: no extension named "${sanitizeLine(name)}"`,
+		"info",
+	);
+}
+
+/** Register the single `/bytefly` command. */
 export function registerPanel(pi: ExtensionAPI, deps: PanelCommandDeps): void {
 	const discover = deps.discover ?? discoverExtensions;
 
 	const handler = async (args: string, ctx: ExtensionCommandContext): Promise<void> => {
-		const parts = args.trim().split(/\s+/).filter(Boolean);
-		const refresh = parts.includes("refresh");
-		const name = parts.find((part) => part !== "refresh");
+		const { mode, name, refresh } = parseArgs(args);
 
 		const cwd = ctx.cwd ?? process.cwd();
 		const agentDir = getAgentDir();
@@ -88,18 +131,11 @@ export function registerPanel(pi: ExtensionAPI, deps: PanelCommandDeps): void {
 
 		if (ctx.mode !== "tui") {
 			if (name !== undefined) {
-				const report = reports.find((entry) => entry.extension === name);
-				if (report) {
-					ctx.ui.notify(formatExtension(report), hasProblems([report]) ? "warning" : "info");
-					return;
-				}
-				const item = runtime.items().find((entry) => extensionName(entry.path) === name);
-				ctx.ui.notify(
-					item
-						? `bytefly: ${sanitizeLine(item.path)} — no doctor report`
-						: `bytefly: no extension named "${sanitizeLine(name)}"`,
-					"info",
-				);
+				notifyExtension(ctx, name, reports, runtime);
+				return;
+			}
+			if (mode === "doctor") {
+				ctx.ui.notify(formatReport(reports), hasProblems(reports) ? "warning" : "info");
 				return;
 			}
 			const model = buildPanelModel({ items: runtime.items(), reports, agentDir });
@@ -136,12 +172,10 @@ export function registerPanel(pi: ExtensionAPI, deps: PanelCommandDeps): void {
 		if (reload) await ctx.reload();
 	};
 
-	const descriptions: Array<[string, string]> = [
-		["bytefly", "Open the bytefly extension screen: /bytefly [extension] [refresh]"],
-		["extensions", "List and enable/disable extensions"],
-		["doctor", "Check extensions and enable or disable one: /doctor [extension] [refresh]"],
-	];
-	for (const [command, description] of descriptions) {
-		pi.registerCommand(command, { description, getArgumentCompletions: completions, handler });
-	}
+	pi.registerCommand("bytefly", {
+		description:
+			"Open the bytefly extension screen: /bytefly [extension] [refresh]; /bytefly doctor [extension] [refresh] prints the doctor report",
+		getArgumentCompletions: completions,
+		handler,
+	});
 }

package/extensions/bytefly/panel/format.ts

@@ -8,18 +8,18 @@
  * came from a probe is sanitized by `doctor/format.ts`.
  */
 
-import type { ThemeColor } from "@earendil-works/pi-coding-agent";
-import { GLYPHS } from "../../../lib/ui.ts";
+import type { TuiRole } from "../../../lib/tui/tokens.ts";
+import { GLYPHS } from "../../../lib/tui/glyphs.ts";
 import { reportSeverity, reportSummary } from "../doctor/format.ts";
 import type { PanelModel, PanelRow } from "./types.ts";
 
 /** The settings scope the screen shows. */
 export type PanelScope = "global" | "project";
 
-/** One segment of the headline, with its semantic color for the TUI. */
+/** One segment of the headline, with its design role for the TUI. */
 export interface SummarySegment {
 	text: string;
-	color: ThemeColor;
+	color: TuiRole;
 }
 
 /** Row and problem counts over a model. */
@@ -67,19 +67,19 @@ export function summarySegments(model: PanelModel, scope: PanelScope, options: S
 	const counts = panelCounts(model);
 	const segments: SummarySegment[] = [{ text: scope === "global" ? "Global" : "Project", color: "accent" }];
 	if (options.filter !== undefined) {
-		segments.push({ text: `${options.filter} only`, color: "muted" });
+		segments.push({ text: `${options.filter} only`, color: "meta" });
 	} else {
 		const noun = options.compact ? "ext" : counts.extensions === 1 ? "extension" : "extensions";
-		segments.push({ text: `${counts.extensions} ${noun}`, color: "muted" });
+		segments.push({ text: `${counts.extensions} ${noun}`, color: "meta" });
 		if (counts.disabled > 0) {
-			segments.push({ text: `${counts.disabled} ${options.compact ? "off" : "disabled"}`, color: "muted" });
+			segments.push({ text: `${counts.disabled} ${options.compact ? "off" : "disabled"}`, color: "meta" });
 		}
 	}
 	const problems: string[] = [];
 	if (counts.missing > 0) problems.push(`${counts.missing} missing`);
 	if (counts.degraded > 0) problems.push(`${counts.degraded} degraded`);
 	if (problems.length > 0) {
-		segments.push({ text: problems.join(", "), color: counts.missing > 0 ? "error" : "warning" });
+		segments.push({ text: problems.join(", "), color: counts.missing > 0 ? "bad" : "warn" });
 	}
 	return segments;
 }