pi-crew 0.6.3 → 0.7.1

package/src/ui/render-diff.ts

@@ -22,6 +22,32 @@ export function replaceTabs(text: string): string {
 	return text.replace(/\t/g, "   ");
 }
 
+/**
+ * Minimum similarity (fraction of unchanged chars) required before applying
+ * word-level intra-line diff highlighting. Below this, the two lines are
+ * considered unrelated and rendered plainly to avoid noisy full-line
+ * inverse-video (e.g. an empty line replaced by a large block of code).
+ */
+const WORD_DIFF_MIN_SIM = 0.15;
+
+/**
+ * Compute the similarity between two strings as the fraction of unchanged
+ * characters relative to the longer of the two strings, using word-level
+ * diff to identify the common (unchanged) parts. Returns a value in [0, 1].
+ */
+function computeSimilarity(oldContent: string, newContent: string): number {
+	const wordDiff = Diff.diffWords(oldContent, newContent);
+	let commonChars = 0;
+	for (const part of wordDiff) {
+		if (!part.removed && !part.added) {
+			commonChars += part.value.length;
+		}
+	}
+	const maxLen = Math.max(oldContent.length, newContent.length);
+	if (maxLen === 0) return 1; // both empty -> identical
+	return commonChars / maxLen;
+}
+
 function renderIntraLineDiff(theme: CrewTheme, oldContent: string, newContent: string): { removedLine: string; addedLine: string } {
 	const wordDiff = Diff.diffWords(oldContent, newContent);
 	let removedLine = "";
@@ -95,9 +121,17 @@ export function renderDiff(diffText: string, options: RenderDiffOptions = {}): s
 			}
 
 			if (removedLines.length === 1 && addedLines.length === 1) {
-				const { removedLine, addedLine } = renderIntraLineDiff(theme, replaceTabs(removedLines[0]!.content), replaceTabs(addedLines[0]!.content));
-				result.push(theme.fg("toolDiffRemoved", `-${removedLines[0]!.lineNum} ${removedLine}`));
-				result.push(theme.fg("toolDiffAdded", `+${addedLines[0]!.lineNum} ${addedLine}`));
+				const oldContent = replaceTabs(removedLines[0]!.content);
+				const newContent = replaceTabs(addedLines[0]!.content);
+				const similarity = computeSimilarity(oldContent, newContent);
+				if (similarity >= WORD_DIFF_MIN_SIM) {
+					const { removedLine, addedLine } = renderIntraLineDiff(theme, oldContent, newContent);
+					result.push(theme.fg("toolDiffRemoved", `-${removedLines[0]!.lineNum} ${removedLine}`));
+					result.push(theme.fg("toolDiffAdded", `+${addedLines[0]!.lineNum} ${addedLine}`));
+				} else {
+					result.push(theme.fg("toolDiffRemoved", `-${removedLines[0]!.lineNum} ${oldContent}`));
+					result.push(theme.fg("toolDiffAdded", `+${addedLines[0]!.lineNum} ${newContent}`));
+				}
 			} else {
 				for (const removed of removedLines) {
 					result.push(theme.fg("toolDiffRemoved", `-${removed.lineNum} ${replaceTabs(removed.content)}`));

package/src/ui/settings-overlay.ts

@@ -5,12 +5,13 @@
  */
 import type { CrewTheme } from "./theme-adapter.ts";
 import { DynamicCrewBorder } from "./dynamic-border.ts";
+import { discoverPiThemes, getActivePiTheme } from "./theme-discovery.ts";
 
 // ---------------------------------------------------------------------------
 // Types
 // ---------------------------------------------------------------------------
 
-export type SettingType = "boolean" | "enum" | "number" | "string" | "agent";
+export type SettingType = "boolean" | "enum" | "number" | "string" | "agent" | "action";
 
 export interface SettingDef {
 	id: string;
@@ -21,11 +22,16 @@ export interface SettingDef {
 	values?: string[];
 	/** Tab grouping */
 	tab: string;
+	/** For type="action": identifier dispatched to onAction (e.g. "piTheme"). */
+	action?: string;
 }
 
 export interface SettingsOverlayCallbacks {
 	onChange: (id: string, value: unknown) => void;
 	onClose: () => void;
+	/** Dispatched for type="action" settings (e.g. Pi theme switch, which
+	 * writes to settings.json rather than pi-crew config). Optional. */
+	onAction?: (action: string, value: unknown) => void;
 }
 
 interface TabDef {
@@ -43,6 +49,7 @@ const TABS: TabDef[] = [
 	{ id: "limits", label: "Limits", icon: "📐" },
 	{ id: "agents", label: "Agents", icon: "🤖" },
 	{ id: "ui", label: "UI", icon: "🖥" },
+	{ id: "themes", label: "Themes", icon: "🎨" },
 	{ id: "autonomous", label: "Auto", icon: "🚀" },
 	{ id: "advanced", label: "Advanced", icon: "🔧" },
 ];
@@ -74,6 +81,8 @@ const SETTINGS: SettingDef[] = [
 	{ id: "ui.dashboardWidth", label: "Dashboard Width", type: "number", tab: "ui", description: "Dashboard width as percentage or pixels." },
 	{ id: "ui.autoOpenDashboard", label: "Auto Open Dashboard", type: "boolean", tab: "ui", description: "Auto-open dashboard when a run starts." },
 	{ id: "ui.widgetPlacement", label: "Widget Placement", type: "enum", values: ["bottom", "hidden"], tab: "ui", description: "Where to place the crew widget." },
+	// ── Themes tab ──
+	{ id: "__piTheme__", label: "Pi UI Theme", type: "action", action: "piTheme", values: discoverPiThemes().map((t) => t.name), tab: "themes", description: "Overall terminal theme. Switches live (no restart). Currently: " + (getActivePiTheme() ?? "dark (default)") },
 	// Autonomous
 	{ id: "autonomous.enabled", label: "Enabled", type: "boolean", tab: "autonomous", description: "Enable autonomous pi-crew delegation." },
 	{ id: "autonomous.injectPolicy", label: "Inject Policy", type: "boolean", tab: "autonomous", description: "Inject delegation policy into agent context." },
@@ -196,12 +205,21 @@ function isExplicitlySet(config: Record<string, unknown>, id: string): boolean {
 	return getNestedValue(config, id) !== undefined;
 }
 
+/** Resolve the live current value for a setting, including special-case IDs
+ * (e.g. __piTheme__ which lives in Pi's settings.json, not pi-crew config). */
+function currentValueFor(config: Record<string, unknown>, id: string): unknown {
+	if (id === "__piTheme__") return getActivePiTheme() ?? "dark";
+	return getNestedValue(config, id);
+}
+
 // ---------------------------------------------------------------------------
 // Submenu: Select from list (enum picker)
 // ---------------------------------------------------------------------------
 
 class SelectSubmenu {
 	private selectedIndex = 0;
+	private scrollOffset = 0;
+	private readonly maxVisible = 14;
 	private readonly items: string[];
 	private readonly theme: CrewTheme;
 	private readonly onSelect: (value: string) => void;
@@ -217,35 +235,57 @@ class SelectSubmenu {
 		this.onSelect = onSelect;
 		this.onCancel = onCancel;
 		this.selectedIndex = Math.max(0, options.indexOf(current));
+		// Center the cursor in the visible window on open.
+		this.scrollOffset = Math.max(0, this.selectedIndex - Math.floor(this.maxVisible / 2));
 	}
 
 	invalidate(): void {}
 
+	private ensureVisible(): void {
+		if (this.selectedIndex < this.scrollOffset) {
+			this.scrollOffset = this.selectedIndex;
+		} else if (this.selectedIndex >= this.scrollOffset + this.maxVisible) {
+			this.scrollOffset = this.selectedIndex - this.maxVisible + 1;
+		}
+	}
+
 	render(width: number): string[] {
+		void width;
 		const lines: string[] = [];
 		lines.push(this.theme.bold(this.theme.fg("accent", this.title)));
 		if (this.description) {
 			lines.push(this.theme.fg("muted", this.description));
 		}
 		lines.push("");
-		for (const [i, item] of this.items.entries()) {
+		const start = this.scrollOffset;
+		const end = Math.min(start + this.maxVisible, this.items.length);
+		const needsScroll = this.items.length > this.maxVisible;
+		if (needsScroll && start > 0) {
+			lines.push(this.theme.fg("dim", `  ▲ ${start} more above`));
+		}
+		for (let i = start; i < end; i++) {
 			const isSelected = i === this.selectedIndex;
 			const prefix = isSelected ? " → " : "   ";
-			const line = `${prefix}${item}`;
+			const line = `${prefix}${this.items[i]}`;
 			lines.push(isSelected ? (this.theme.inverse?.(line) ?? line) : line);
 		}
+		if (needsScroll && end < this.items.length) {
+			lines.push(this.theme.fg("dim", `  ▼ ${this.items.length - end} more below`));
+		}
 		lines.push("");
-		lines.push(this.theme.fg("dim", "Enter to select · Esc to go back"));
+		lines.push(this.theme.fg("dim", "↑↓ navigate · Enter to select · Esc to go back"));
 		return lines;
 	}
 
 	handleInput(data: string): void {
 		if (data === "\x1b[A" || data === "k") {
 			this.selectedIndex = (this.selectedIndex - 1 + this.items.length) % this.items.length;
+			this.ensureVisible();
 			return;
 		}
 		if (data === "\x1b[B" || data === "j") {
 			this.selectedIndex = (this.selectedIndex + 1) % this.items.length;
+			this.ensureVisible();
 			return;
 		}
 		if (data === "\r" || data === "\n") {
@@ -514,8 +554,8 @@ class SettingsOverlay {
 
 			const effective = this.changedValues.has(def.id)
 				? this.changedValues.get(def.id)
-				: getNestedValue(this.config, def.id);
-			const isDefault = !this.changedValues.has(def.id) && !isExplicitlySet(this.config, def.id);
+				: currentValueFor(this.config, def.id);
+			const isDefault = !this.changedValues.has(def.id) && !isExplicitlySet(this.config, def.id) && def.id !== "__piTheme__";
 			const valueStr = formatValue(effective, def.id);
 			const suffix = isDefault && (effective !== undefined || EFFECTIVE_DEFAULTS[def.id] !== undefined) ? " (default)" : "";
 
@@ -696,6 +736,28 @@ class SettingsOverlay {
 				);
 				break;
 			}
+			case "action": {
+				if (!def.values?.length || !def.action) break;
+				const actionCurrent = typeof this.changedValues.get(def.id) === "string"
+					? (this.changedValues.get(def.id) as string)
+					: (currentValueFor(this.config, def.id) as string | undefined) ?? "";
+				this.submenuSettingId = def.id;
+				this.submenu = new SelectSubmenu(
+					def.label,
+					def.description ?? "",
+					def.values,
+					actionCurrent,
+					this.theme,
+					(value: string) => {
+						this.changedValues.set(def.id, value);
+						this.callbacks.onAction?.(def.action!, value);
+						this.submenu = null;
+						this.submenuSettingId = null;
+					},
+					() => { this.submenu = null; this.submenuSettingId = null; },
+				);
+				break;
+			}
 		}
 	}
 
@@ -717,7 +779,8 @@ export function createSettingsOverlay(
 	theme: CrewTheme,
 	onChange: (id: string, value: unknown) => void,
 	done: () => void,
+	onAction?: (action: string, value: unknown) => void,
 ) {
-	const overlay = new SettingsOverlay(config, theme, { onChange, onClose: done });
+	const overlay = new SettingsOverlay(config, theme, { onChange, onClose: done, onAction });
 	return { overlay, component: overlay };
 }

package/src/ui/status-colors.ts

@@ -1,6 +1,6 @@
 import type { CrewTheme, CrewThemeColor } from "./theme-adapter.ts";
 
-export type RunStatus = "queued" | "running" | "completed" | "failed" | "cancelled" | "stopped" | "blocked" | (string & {});
+export type RunStatus = "queued" | "running" | "waiting" | "completed" | "failed" | "cancelled" | "stopped" | "blocked" | "stale" | "needs_attention" | (string & {});
 
 export function colorForStatus(status: RunStatus): CrewThemeColor {
 	switch (status) {
@@ -17,6 +17,8 @@ export function colorForStatus(status: RunStatus): CrewThemeColor {
 		case "blocked":
 		case "stopped":
 			return "warning";
+		case "needs_attention":
+			return "warning";
 		case "queued":
 		default:
 			return "dim";
@@ -42,6 +44,8 @@ export function iconForStatus(status: RunStatus, options?: { runningGlyph?: stri
 			return "◦";
 		case "blocked":
 			return "⏸";
+		case "needs_attention":
+			return "⚠";
 		default:
 			return "·";
 	}

package/src/ui/syntax-highlight.ts

@@ -1,7 +1,16 @@
+/**
+ * Syntax highlighting for pi-crew UI.
+ *
+ * Uses cli-highlight (sync) with the active Pi theme's syntax colors.
+ * Falls back to plain text (theme.fg on every line) if the language is
+ * unsupported or highlighting fails.
+ */
 import { supportsLanguage, highlight } from "cli-highlight";
 import type { CrewTheme } from "./theme-adapter.ts";
 import { asCrewTheme } from "./theme-adapter.ts";
 
+// ── cli-highlight theme bridge ──────────────────────────────────────────
+
 function buildCliTheme(theme: CrewTheme): Record<string, (text: string) => string> {
 	return {
 		keyword: (text) => theme.fg("syntaxKeyword", text),
@@ -22,13 +31,29 @@ function buildCliTheme(theme: CrewTheme): Record<string, (text: string) => strin
 	};
 }
 
-/** @internal */
-function detectLanguageFromPath(filePath: string): string | undefined {
-	const ext = filePath.split(".").pop()?.toLowerCase();
-	if (!ext) return undefined;
-	return languageMap[ext];
+function hlCliSync(code: string, language: string | undefined, theme: CrewTheme): string {
+	if (!language) {
+		return code
+			.split("\n")
+			.map((line) => theme.fg("mdCodeBlock", line))
+			.join("\n");
+	}
+	try {
+		return highlight(code, {
+			language,
+			ignoreIllegals: true,
+			theme: buildCliTheme(theme),
+		}).trimEnd();
+	} catch {
+		return code
+			.split("\n")
+			.map((line) => theme.fg("mdCodeBlock", line))
+			.join("\n");
+	}
 }
 
+// ── Language detection ──────────────────────────────────────────────────
+
 export const languageMap: Record<string, string> = {
 	ts: "typescript",
 	tsx: "typescript",
@@ -69,27 +94,19 @@ export const languageMap: Record<string, string> = {
 	php: "php",
 };
 
+/** @internal */
+function detectLanguageFromPath(filePath: string): string | undefined {
+	const ext = filePath.split(".").pop()?.toLowerCase();
+	if (!ext) return undefined;
+	return languageMap[ext];
+}
+
+// ── Public API ──────────────────────────────────────────────────────────
+
 export function highlightCode(code: string, language: string | undefined, themeLike: unknown = undefined): string {
 	const theme = asCrewTheme(themeLike);
 	const validLanguage = language && supportsLanguage(language) ? language : undefined;
-	if (!validLanguage) {
-		return code
-			.split("\n")
-			.map((line) => theme.fg("mdCodeBlock", line))
-			.join("\n");
-	}
-	try {
-		return highlight(code, {
-			language: validLanguage,
-			ignoreIllegals: true,
-			theme: buildCliTheme(theme),
-		}).trimEnd();
-	} catch {
-		return code
-			.split("\n")
-			.map((line) => theme.fg("mdCodeBlock", line))
-			.join("\n");
-	}
+	return hlCliSync(code, validLanguage, theme);
 }
 
 export function highlightJson(payload: string, themeLike: unknown = undefined): string {
@@ -115,3 +132,5 @@ export function highlightJson(payload: string, themeLike: unknown = undefined):
 		}
 	}
 }
+
+export { detectLanguageFromPath };

package/src/ui/theme-adapter.ts

@@ -9,9 +9,22 @@ export type CrewThemeColor =
 	| "muted"
 	| "dim"
 	| "text"
+	| "thinkingText"
+	// Tool rendering
+	| "toolTitle"
+	| "toolOutput"
 	| "toolDiffAdded"
 	| "toolDiffRemoved"
 	| "toolDiffContext"
+	// Markdown
+	| "mdHeading"
+	| "mdLink"
+	| "mdCode"
+	| "mdCodeBlock"
+	| "mdQuote"
+	| "mdHr"
+	| "mdListBullet"
+	// Syntax highlighting
 	| "syntaxKeyword"
 	| "syntaxString"
 	| "syntaxNumber"
@@ -21,15 +34,81 @@ export type CrewThemeColor =
 	| "syntaxType"
 	| "syntaxOperator"
 	| "syntaxPunctuation"
-	| "mdCodeBlock";
+	// Message display
+	| "userMessageText"
+	| "customMessageLabel"
+	// Thinking gradient (6 levels, low→high intensity)
+	| "thinkingOff"
+	| "thinkingMinimal"
+	| "thinkingLow"
+	| "thinkingMedium"
+	| "thinkingHigh"
+	| "thinkingXhigh"
+	// Special
+	| "bashMode";
 
 export type CrewThemeBg =
 	| "selectedBg"
 	| "userMessageBg"
+	| "customMessageBg"
 	| "toolPendingBg"
 	| "toolSuccessBg"
 	| "toolErrorBg";
 
+/** ANSI fallback values for theme color slots when the active theme doesn't define them. */
+export const THEME_COLOR_FALLBACKS: Record<CrewThemeColor, string> = {
+	accent: "\x1b[36m",
+	border: "\x1b[38;5;240m",
+	borderAccent: "\x1b[35m",
+	borderMuted: "\x1b[38;5;236m",
+	success: "\x1b[32m",
+	error: "\x1b[31m",
+	warning: "\x1b[33m",
+	muted: "\x1b[38;5;245m",
+	dim: "\x1b[38;5;240m",
+	text: "\x1b[39m",
+	thinkingText: "\x1b[38;5;245m",
+	toolTitle: "\x1b[36m",
+	toolOutput: "\x1b[38;5;245m",
+	toolDiffAdded: "\x1b[32m",
+	toolDiffRemoved: "\x1b[31m",
+	toolDiffContext: "\x1b[38;5;245m",
+	mdHeading: "\x1b[33m",
+	mdLink: "\x1b[35m",
+	mdCode: "\x1b[32m",
+	mdCodeBlock: "\x1b[39m",
+	mdQuote: "\x1b[38;5;245m",
+	mdHr: "\x1b[38;5;240m",
+	mdListBullet: "\x1b[36m",
+	syntaxKeyword: "\x1b[35m",
+	syntaxString: "\x1b[32m",
+	syntaxNumber: "\x1b[33m",
+	syntaxComment: "\x1b[38;5;245m",
+	syntaxFunction: "\x1b[36m",
+	syntaxVariable: "\x1b[39m",
+	syntaxType: "\x1b[35m",
+	syntaxOperator: "\x1b[35m",
+	syntaxPunctuation: "\x1b[35m",
+	userMessageText: "\x1b[39m",
+	customMessageLabel: "\x1b[35m",
+	thinkingOff: "\x1b[38;5;236m",
+	thinkingMinimal: "\x1b[38;5;245m",
+	thinkingLow: "\x1b[35m",
+	thinkingMedium: "\x1b[35m",
+	thinkingHigh: "\x1b[36m",
+	thinkingXhigh: "\x1b[35m",
+	bashMode: "\x1b[32m",
+};
+
+/** Map a thinking intensity level (0–5) to a theme color slot. */
+export function thinkingColorForLevel(level: number): CrewThemeColor {
+	const slots: CrewThemeColor[] = [
+		"thinkingOff", "thinkingMinimal", "thinkingLow",
+		"thinkingMedium", "thinkingHigh", "thinkingXhigh",
+	];
+	return slots[Math.min(Math.max(level, 0), 5)] ?? "thinkingOff";
+}
+
 export interface CrewTheme {
 	fg(color: CrewThemeColor, text: string): string;
 	bg?(color: CrewThemeBg, text: string): string;

package/src/ui/theme-discovery.ts

@@ -0,0 +1,188 @@
+/**
+ * Pi UI theme discovery and selection.
+ *
+ * Exposes:
+ *  - Pi UI theme discovery (builtins + custom ~/.pi/agent/themes/*.json)
+ *  - The active Pi theme
+ *  - setPiTheme() to persist a choice in ~/.pi/agent/settings.json
+ *
+ * Wired into the `team-settings themes` / `theme` subcommands.
+ */
+
+export interface PiThemeInfo {
+	/** Theme name (filename stem or builtin id). */
+	name: string;
+	/** Where it comes from. */
+	source: "builtin" | "custom";
+	/** Absolute path to the .json file, if applicable. */
+	path?: string;
+	/** Human-friendly display name from the JSON `name` field, if present. */
+	displayName?: string;
+	/** "dark" or "light" — derived from background luminance. */
+	mode?: "dark" | "light";
+}
+
+/** Builtin Pi themes shipped with the pi-coding-agent package. */
+const BUILTIN_PI_THEMES = ["dark", "light"];
+
+/**
+ * Detect whether a theme is dark or light based on its background luminance.
+ * Reads vars.bg or export.pageBg or a resolved colors ref. Returns undefined
+ * if it can't be determined.
+ */
+function detectThemeMode(json: Record<string, unknown>): "dark" | "light" | undefined {
+	const vars = json.vars as Record<string, string> | undefined;
+	const bgRaw = vars?.bg;
+	if (!bgRaw || !/^#[0-9a-fA-F]{6}$/.test(bgRaw)) return undefined;
+	const r = parseInt(bgRaw.slice(1, 3), 16);
+	const g = parseInt(bgRaw.slice(3, 5), 16);
+	const b = parseInt(bgRaw.slice(5, 7), 16);
+	// Relative luminance (ITU-R BT.709)
+	const lum = (0.2126 * r + 0.7152 * g + 0.0722 * b) / 255;
+	return lum < 0.5 ? "dark" : "light";
+}
+
+function customThemesDir(): string {
+	const home = process.env.HOME ?? process.env.USERPROFILE ?? "";
+	return home ? `${home}/.pi/agent/themes` : "";
+}
+
+function settingsPath(): string {
+	const home = process.env.HOME ?? process.env.USERPROFILE ?? "";
+	return home ? `${home}/.pi/agent/settings.json` : "";
+}
+
+/** Discover all available Pi UI themes (builtins + custom). */
+export function discoverPiThemes(): PiThemeInfo[] {
+	const out: PiThemeInfo[] = [];
+	const seen = new Set<string>();
+
+	// Builtins
+	for (const name of BUILTIN_PI_THEMES) {
+		if (seen.has(name)) continue;
+		seen.add(name);
+		out.push({ name, source: "builtin", displayName: name, mode: name === "light" ? "light" : "dark" });
+	}
+
+	// Custom themes from ~/.pi/agent/themes/
+	const dir = customThemesDir();
+	try {
+		// eslint-disable-next-line @typescript-eslint/no-require-imports
+		const fs = require("node:fs");
+		if (dir && fs.existsSync(dir)) {
+			for (const file of fs.readdirSync(dir) as string[]) {
+				if (!file.endsWith(".json")) continue;
+				const name = file.slice(0, -5);
+				if (seen.has(name)) continue;
+				const fullPath = `${dir}/${file}`;
+				let displayName: string | undefined;
+				let mode: "dark" | "light" | undefined;
+				try {
+					const json = JSON.parse(fs.readFileSync(fullPath, "utf8"));
+					displayName = typeof json.name === "string" ? json.name : undefined;
+					mode = detectThemeMode(json);
+				} catch {
+					// keep undefined
+				}
+				seen.add(name);
+				out.push({ name, source: "custom", path: fullPath, displayName, mode });
+			}
+		}
+	} catch {
+		// directory unreadable — skip
+	}
+
+	return out.sort((a, b) => a.name.localeCompare(b.name));
+}
+
+/** Read the currently active Pi theme from ~/.pi/agent/settings.json. */
+export function getActivePiTheme(): string | undefined {
+	try {
+		// eslint-disable-next-line @typescript-eslint/no-require-imports
+		const fs = require("node:fs");
+		const p = settingsPath();
+		if (!p || !fs.existsSync(p)) return undefined;
+		const json = JSON.parse(fs.readFileSync(p, "utf8"));
+		return typeof json.theme === "string" ? json.theme : undefined;
+	} catch {
+		return undefined;
+	}
+}
+
+/** Persist a Pi theme choice in ~/.pi/agent/settings.json. Returns the path or throws. */
+export function setPiTheme(name: string): string {
+	// eslint-disable-next-line @typescript-eslint/no-require-imports
+	const fs = require("node:fs");
+	const p = settingsPath();
+	if (!p) throw new Error("Could not determine settings path (no HOME).");
+	let settings: Record<string, unknown> = {};
+	try {
+		if (fs.existsSync(p)) {
+			settings = JSON.parse(fs.readFileSync(p, "utf8"));
+		}
+	} catch {
+		// corrupt settings — start fresh
+		settings = {};
+	}
+	settings.theme = name;
+	fs.writeFileSync(p, JSON.stringify(settings, null, 2) + "\n", "utf8");
+	return p;
+}
+
+// ---------------------------------------------------------------------------
+// Formatted listing for `team-settings themes`
+// ---------------------------------------------------------------------------
+
+/**
+ * Build the full formatted listing of Pi UI themes for display.
+ * Shows available themes, the active selection, and switching instructions.
+ */
+export function formatThemesListing(): string {
+	const piThemes = discoverPiThemes();
+	const activePi = getActivePiTheme();
+	const lines: string[] = [];
+
+	const darkThemes = piThemes.filter((t) => t.mode !== "light");
+	const lightThemes = piThemes.filter((t) => t.mode === "light");
+
+	lines.push("═══ Theme Gallery ═══");
+	lines.push("");
+
+	// ── Dark themes ──
+	if (darkThemes.length) {
+		lines.push("Dark themes:");
+		lines.push("");
+		for (const t of darkThemes) {
+			lines.push(themeLine(t, activePi));
+		}
+		lines.push("");
+	}
+
+	// ── Light themes ──
+	if (lightThemes.length) {
+		lines.push("Light themes:");
+		lines.push("");
+		for (const t of lightThemes) {
+			lines.push(themeLine(t, activePi));
+		}
+		lines.push("");
+	}
+
+	lines.push("  Switch (live, no restart): team-settings theme <name>");
+	lines.push("  Browse interactively:      /team-settings → Themes tab");
+	lines.push("");
+
+	lines.push("Notes:");
+	lines.push("  • Switching applies live via ctx.ui.setTheme() (Pi redraws immediately).");
+	lines.push("  • Bundled crew-* themes deploy to ~/.pi/agent/themes/ on startup.");
+	lines.push(`  • ${piThemes.length} themes available (${darkThemes.length} dark, ${lightThemes.length} light).`);
+
+	return lines.join("\n");
+}
+
+function themeLine(t: PiThemeInfo, active: string | undefined): string {
+	const isActive = t.name === active;
+	const tag = isActive ? " ← active" : "";
+	const src = t.source === "builtin" ? " (builtin)" : "";
+	return `  ${isActive ? "●" : "○"} ${t.name}${src}${tag}`;
+}