@oh-my-pi/pi-coding-agent 15.6.0 → 15.7.1

package/src/main.ts

@@ -49,6 +49,7 @@ import {
 } from "./extensibility/plugins/marketplace";
 import type { MCPManager } from "./mcp";
 import { InteractiveMode, runAcpMode, runPrintMode, runRpcMode } from "./modes";
+import { ALL_SCENES, runSetupWizard, selectSetupScenes } from "./modes/setup-wizard";
 import { initTheme, stopThemeWatcher } from "./modes/theme/theme";
 import type { SubmittedUserInput } from "./modes/types";
 import {
@@ -257,6 +258,8 @@ async function runInteractiveMode(
 	setExtensionUIContext: (uiContext: ExtensionUIContext, hasUI: boolean) => void,
 	lspServers: LspStartupServerInfo[] | undefined,
 	mcpManager: MCPManager | undefined,
+	resuming: boolean,
+	forceSetupWizard: boolean,
 	eventBus?: EventBus,
 	initialMessage?: string,
 	initialImages?: ImageContent[],
@@ -271,7 +274,18 @@ async function runInteractiveMode(
 		eventBus,
 	);
 
-	await mode.init();
+	const setupScenes = await selectSetupScenes(settings.get("setupVersion"), ALL_SCENES, mode, {
+		resuming,
+		isTTY: process.stdin.isTTY && process.stdout.isTTY,
+		setupWizardEnabled: settings.get("startup.setupWizard"),
+		force: forceSetupWizard,
+	});
+
+	await mode.init({ suppressWelcomeIntro: setupScenes.length > 0 });
+
+	if (setupScenes.length > 0) {
+		await runSetupWizard(mode, setupScenes);
+	}
 
 	versionCheckPromise
 		.then(newVersion => {
@@ -693,6 +707,7 @@ interface RunRootCommandDependencies {
 	discoverAuthStorage?: typeof discoverAuthStorage;
 	runAcpMode?: typeof runAcpMode;
 	settings?: Settings;
+	forceSetupWizard?: boolean;
 }
 
 export async function runRootCommand(
@@ -1028,6 +1043,8 @@ export async function runRootCommand(
 				setToolUIContext,
 				lspServers,
 				mcpManager,
+				Boolean(parsedArgs.continue || parsedArgs.resume || parsedArgs.fork),
+				deps.forceSetupWizard === true,
 				eventBus,
 				initialMessage,
 				initialImages,

package/src/modes/components/hook-selector.ts

@@ -24,6 +24,7 @@ import {
 } from "../../modes/utils/keybinding-matchers";
 import { CountdownTimer } from "./countdown-timer";
 import { DynamicBorder } from "./dynamic-border";
+import { renderSegmentTrack } from "./segment-track";
 
 /** One segment of a {@link HookSelectorSlider} — a label, its accent color, and
  *  an optional detail line (e.g. the resolved model name) shown beneath the
@@ -206,28 +207,25 @@ export class HookSelectorComponent extends Container {
 		}
 	}
 
-	/** Render the slider block: the track (dim caption, edge arrows that brighten
-	 *  while there is room to move, one styled segment per option — active = bold
-	 *  in its color, the rest dim, joined by `›`) plus, when the active segment
-	 *  carries a `detail`, a muted second line beneath it (e.g. the resolved model
-	 *  name). Returns one or two `\n`-joined lines. */
+	/** Render the slider block in the style of the status line: each option is a
+	 *  distinctly colored segment, the active one filled as a powerline chip
+	 *  (its accent as the background, a luminance-matched label, flanked by
+	 *  triangle caps) and the rest shown as plain colored labels joined by a thin
+	 *  separator. Edge arrows brighten while there is room to move. When the
+	 *  active segment carries a `detail` (e.g. the resolved model name) a muted
+	 *  second line is appended. Returns one or two `\n`-joined lines. */
 	#renderSliderLine(): string {
 		const slider = this.#slider;
 		if (!slider) return "";
 		const segments = slider.segments;
-		const sep = theme.fg("dim", " › ");
-		const track = segments
-			.map((segment, i) =>
-				i === this.#sliderIndex
-					? theme.bold(theme.fg(segment.color ?? "accent", segment.label))
-					: theme.fg("dim", segment.label),
-			)
-			.join(sep);
-		const leftArrow = theme.fg(this.#sliderIndex > 0 ? "accent" : "dim", "◂");
-		const rightArrow = theme.fg(this.#sliderIndex < segments.length - 1 ? "accent" : "dim", "▸");
+		const active = this.#sliderIndex;
+		const track = renderSegmentTrack(segments, active);
+
+		const leftArrow = theme.fg(active > 0 ? "accent" : "dim", "◂");
+		const rightArrow = theme.fg(active < segments.length - 1 ? "accent" : "dim", "▸");
 		const caption = slider.caption ? `${theme.fg("dim", slider.caption)}  ` : "";
-		const trackLine = `${caption}${leftArrow} ${theme.fg("dim", "[")} ${track} ${theme.fg("dim", "]")} ${rightArrow}`;
-		const detail = segments[this.#sliderIndex]?.detail;
+		const trackLine = `${caption}${leftArrow}  ${track}  ${rightArrow}`;
+		const detail = segments[active]?.detail;
 		if (!detail) return trackLine;
 		return `${trackLine}\n  ${theme.fg("dim", "↳")} ${theme.fg("muted", detail)}`;
 	}

package/src/modes/components/index.ts

@@ -20,6 +20,7 @@ export * from "./model-selector";
 export * from "./oauth-selector";
 export * from "./queue-mode-selector";
 export * from "./read-tool-group";
+export * from "./segment-track";
 export * from "./session-selector";
 export * from "./settings-selector";
 export * from "./show-images-selector";

package/src/modes/components/segment-track.ts

@@ -0,0 +1,52 @@
+/**
+ * Shared renderer for a horizontal row of colored "segments" styled after the
+ * status line: each segment shows in its own accent, the active one is filled
+ * as a powerline chip (its accent as the background, a luminance-matched label,
+ * flanked by triangle caps) and the rest are plain colored labels joined by a
+ * thin separator.
+ *
+ * Used by the plan-mode model-tier slider ({@link HookSelectorComponent}) and
+ * the ctrl+p role-cycle status so both surfaces read identically.
+ */
+import { type ThemeColor, theme } from "../theme/theme";
+
+export interface TrackSegment {
+	label: string;
+	/** Theme color for the segment; defaults to `accent`. */
+	color?: ThemeColor;
+}
+
+const FG_RESET = "\x1b[39m";
+const BG_RESET = "\x1b[49m";
+
+/**
+ * Render `segments` as a colored chip track with `activeIndex` filled. Returns
+ * a single line of styled text with no surrounding caption or arrows — callers
+ * frame it as they need.
+ */
+export function renderSegmentTrack(segments: TrackSegment[], activeIndex: number): string {
+	// Powerline triangles point *into* the chip so the colored caps merge with
+	// the filled body: left cap points left, right cap points right.
+	const capLeft = theme.sep.powerlineRight;
+	const capRight = theme.sep.powerlineLeft;
+	const thinSep = theme.fg("statusLineSep", theme.sep.powerlineThin);
+
+	let track = "";
+	segments.forEach((segment, i) => {
+		if (i > 0) {
+			// A thin separator reads cleanly only between two plain labels; the chip
+			// caps already delimit the active segment, so pad around it instead.
+			track += i === activeIndex || i - 1 === activeIndex ? "  " : ` ${thinSep} `;
+		}
+		const color = segment.color ?? "accent";
+		const fg = theme.getFgAnsi(color);
+		if (i !== activeIndex) {
+			track += `${fg}${segment.label}${FG_RESET}`;
+			return;
+		}
+		const bg = fg.replace("\x1b[38;", "\x1b[48;");
+		const label = `${bg}${theme.getContrastFgAnsi(color)}\x1b[1m ${segment.label} \x1b[22m${BG_RESET}`;
+		track += `${fg}${capLeft}${label}${fg}${capRight}${FG_RESET}`;
+	});
+	return track;
+}

package/src/modes/components/tips.txt

@@ -9,4 +9,5 @@ Did you know? Each kitty/tmux split keeps its own session — `omp -c` resumes t
 Drop the word `ultrathink` in your message for harder multi-step reasoning — watch it glow rainbow as you type
 Say `orchestrate` in your message to drive a multi-phase task with parallel subagents — watch it glow as you type
 Log in to several accounts of the same provider — `/login` again — and omp load-balances across them automatically
-Run `omp auth-broker serve` once and every machine pulls live tokens over the wire — refresh keys never leave the host; `omp auth-gateway` fronts it as a drop-in proxy any OpenAI-compatible client can hit
+Run `omp auth-broker serve` once and every machine pulls live tokens over the wire — refresh keys never leave the host; `omp auth-gateway` fronts it as a drop-in proxy any OpenAI-compatible client can hit
+Press alt+p (or /switch) to switch provider, and ctrl+p to cycle role models smol -> slow -> etc

package/src/modes/components/tool-execution.ts

@@ -15,6 +15,7 @@ import {
 } from "@oh-my-pi/pi-tui";
 import { getProjectDir, logger, sanitizeText } from "@oh-my-pi/pi-utils";
 import { EDIT_MODE_STRATEGIES, type EditMode, type PerFileDiffPreview } from "../../edit";
+import { shimmerEnabled } from "../../modes/theme/shimmer";
 import type { Theme } from "../../modes/theme/theme";
 import { theme } from "../../modes/theme/theme";
 import { BASH_DEFAULT_PREVIEW_LINES } from "../../tools/bash";
@@ -380,7 +381,10 @@ export class ToolExecutionComponent extends Container {
 			this.#toolName === "task" &&
 			(this.#result?.details as { async?: { state?: string } } | undefined)?.async?.state === "running";
 		const isPartialTask = this.#isPartial && this.#toolName === "task" && !isBackgroundAsyncTask;
-		const needsSpinner = isStreamingArgs || isPartialTask;
+		// Sweep the border of bash/eval execution blocks while they're pending.
+		const isPendingExecBlock =
+			this.#isPartial && shimmerEnabled() && (this.#toolName === "bash" || this.#toolName === "eval");
+		const needsSpinner = isStreamingArgs || isPartialTask || isPendingExecBlock;
 		if (needsSpinner && !this.#spinnerInterval) {
 			this.#spinnerInterval = setInterval(() => {
 				const frameCount = theme.spinnerFrames.length;

package/src/modes/components/welcome.ts

@@ -325,8 +325,7 @@ export class WelcomeComponent implements Component {
 	}
 }
 
-// biome-ignore format: preserve ASCII art layout
-const PI_LOGO = ["▀██████████▀", " ╘██    ██  ", "  ██    ██  ", "  ██    ██  ", " ▄██▄  ▄██▄ "];
+export const PI_LOGO = ["▀██████████▀", " ╘██    ██  ", "  ██    ██  ", "  ██    ██  ", " ▄██▄  ▄██▄ "];
 
 /** Multi-stop palette for the diagonal gradient. */
 const GRADIENT_STOPS: ReadonlyArray<readonly [number, number, number]> = [
@@ -343,63 +342,69 @@ const GRADIENT_RAMP_256 = [199, 171, 135, 99, 75, 51, 87];
 /** Half-width of the shine highlight band, expressed in gradient-t units. */
 const SHINE_HALF_WIDTH = 0.18;
 
-interface ShineConfig {
+export interface ShineConfig {
 	/** Overall opacity of the shine overlay, in [0, 1]. */
 	strength: number;
 	/** Center of the shine band along the diagonal, in [0, 1]. */
 	pos: number;
 }
 
+/**
+ * Resolve the gradient SGR foreground escape for a normalized position `t`
+ * (0..1) along the diagonal, compositing the optional sliding shine highlight.
+ * Shared by {@link gradientLogo} and the setup splash so both stay
+ * color-identical (truecolor when available, 256-color ramp otherwise).
+ */
+export function gradientEscape(t: number, shine?: ShineConfig): string {
+	const shineStrength = shine && shine.strength > 0 ? shine.strength : 0;
+	const shinePos = shine ? shine.pos : 0;
+	if (TERMINAL.trueColor) {
+		// 5-stop palette widens the visible color range and avoids the
+		// deep-blue valley a naive HSL lerp falls into.
+		const stops = GRADIENT_STOPS;
+		const seg = t * (stops.length - 1);
+		const i = Math.min(stops.length - 2, Math.floor(seg));
+		const f = seg - i;
+		const a = stops[i];
+		const b = stops[i + 1];
+		let r = a[0] + (b[0] - a[0]) * f;
+		let g = a[1] + (b[1] - a[1]) * f;
+		let bl = a[2] + (b[2] - a[2]) * f;
+		if (shineStrength > 0) {
+			const dist = Math.abs(t - shinePos);
+			const intensity = Math.max(0, 1 - dist / SHINE_HALF_WIDTH) * shineStrength;
+			if (intensity > 0) {
+				r += (255 - r) * intensity;
+				g += (255 - g) * intensity;
+				bl += (255 - bl) * intensity;
+			}
+		}
+		return `\x1b[38;2;${Math.round(r)};${Math.round(g)};${Math.round(bl)}m`;
+	}
+	const ramp = GRADIENT_RAMP_256;
+	let idx = Math.min(ramp.length - 1, Math.max(0, Math.floor(t * (ramp.length - 1) + 0.5)));
+	if (shineStrength > 0) {
+		const dist = Math.abs(t - shinePos);
+		const intensity = Math.max(0, 1 - dist / SHINE_HALF_WIDTH) * shineStrength;
+		// Promote to the brightest ramp slot when the shine band peaks here.
+		if (intensity > 0.5) idx = ramp.length - 1;
+	}
+	return `\x1b[38;5;${ramp[idx]}m`;
+}
+
 /**
  * Apply a multi-stop diagonal gradient (bottom-left → top-right) plus an
  * optional sliding shine band across multi-line art. `phase` (0..1) shifts the
  * gradient along the diagonal, wrapping at 1. When `shine` is provided, a soft
  * white highlight is composited on top, centered at `shine.pos`.
  */
-function gradientLogo(lines: readonly string[], phase = 0, shine?: ShineConfig): string[] {
+export function gradientLogo(lines: readonly string[], phase = 0, shine?: ShineConfig): string[] {
 	const reset = "\x1b[0m";
 	const rows = lines.length;
 	const cols = Math.max(...lines.map(l => l.length));
 	// span+1 so `base` stays strictly < 1: avoids the wrap-around at the
 	// far corner mapping back to t=0 (hot pink) on the resting frame.
 	const span = Math.max(1, cols + rows - 1);
-	const shineStrength = shine && shine.strength > 0 ? shine.strength : 0;
-	const shinePos = shine ? shine.pos : 0;
-	const colorAt = TERMINAL.trueColor
-		? (t: number): string => {
-				// 5-stop palette widens the visible color range and avoids the
-				// deep-blue valley a naive HSL lerp falls into.
-				const stops = GRADIENT_STOPS;
-				const seg = t * (stops.length - 1);
-				const i = Math.min(stops.length - 2, Math.floor(seg));
-				const f = seg - i;
-				const a = stops[i];
-				const b = stops[i + 1];
-				let r = a[0] + (b[0] - a[0]) * f;
-				let g = a[1] + (b[1] - a[1]) * f;
-				let bl = a[2] + (b[2] - a[2]) * f;
-				if (shineStrength > 0) {
-					const dist = Math.abs(t - shinePos);
-					const intensity = Math.max(0, 1 - dist / SHINE_HALF_WIDTH) * shineStrength;
-					if (intensity > 0) {
-						r += (255 - r) * intensity;
-						g += (255 - g) * intensity;
-						bl += (255 - bl) * intensity;
-					}
-				}
-				return `\x1b[38;2;${Math.round(r)};${Math.round(g)};${Math.round(bl)}m`;
-			}
-		: (t: number): string => {
-				const ramp = GRADIENT_RAMP_256;
-				let idx = Math.min(ramp.length - 1, Math.max(0, Math.floor(t * (ramp.length - 1) + 0.5)));
-				if (shineStrength > 0) {
-					const dist = Math.abs(t - shinePos);
-					const intensity = Math.max(0, 1 - dist / SHINE_HALF_WIDTH) * shineStrength;
-					// Promote to the brightest ramp slot when the shine band peaks here.
-					if (intensity > 0.5) idx = ramp.length - 1;
-				}
-				return `\x1b[38;5;${ramp[idx]}m`;
-			};
 	return lines.map((line, y) => {
 		let result = "";
 		for (let x = 0; x < line.length; x++) {
@@ -411,7 +416,7 @@ function gradientLogo(lines: readonly string[], phase = 0, shine?: ShineConfig):
 			// Diagonal: bottom-left (x=0, y=rows-1) → top-right (x=cols-1, y=0)
 			const base = (x + (rows - 1 - y)) / span;
 			const t = (((base + phase) % 1) + 1) % 1;
-			result += colorAt(t) + char + reset;
+			result += gradientEscape(t, shine) + char + reset;
 		}
 		return result;
 	});

package/src/modes/controllers/input-controller.ts

@@ -1,8 +1,10 @@
 import * as fs from "node:fs/promises";
-import { type AgentMessage, ThinkingLevel } from "@oh-my-pi/pi-agent-core";
+import type { AgentMessage } from "@oh-my-pi/pi-agent-core";
 import type { AutocompleteProvider, SlashCommand } from "@oh-my-pi/pi-tui";
 import { $env, sanitizeText } from "@oh-my-pi/pi-utils";
+import { getRoleInfo } from "../../config/model-registry";
 import { isSettingsInitialized, settings } from "../../config/settings";
+import { renderSegmentTrack } from "../../modes/components/segment-track";
 import { TinyTitleDownloadProgressComponent } from "../../modes/components/tiny-title-download-progress";
 import { expandEmoticons } from "../../modes/emoji-autocomplete";
 import { createPromptActionAutocompleteProvider } from "../../modes/prompt-action-autocomplete";
@@ -769,27 +771,16 @@ export class InputController {
 
 			this.ctx.statusLine.invalidate();
 			this.ctx.updateEditorBorderColor();
-			const roleLabel = result.role === "default" ? "default" : result.role;
-			const roleLabelStyled = theme.bold(theme.fg("accent", roleLabel));
-			const thinkingStr =
-				result.model.thinking && result.thinkingLevel !== ThinkingLevel.Off
-					? ` (thinking: ${result.thinkingLevel})`
-					: "";
-			const tempLabel = options?.temporary ? " (temporary)" : "";
-			const cycleSeparator = theme.fg("dim", " > ");
-			const cycleLabel = cycleOrder
-				.map(role => {
-					if (role === result.role) {
-						return theme.bold(theme.fg("accent", role));
-					}
-					return theme.fg("muted", role);
-				})
-				.join(cycleSeparator);
-			const orderLabel = ` (cycle: ${cycleLabel})`;
-			this.ctx.showStatus(
-				`Switched to ${roleLabelStyled}: ${result.model.name || result.model.id}${thinkingStr}${tempLabel}${orderLabel}`,
-				{ dim: false },
+			// The status line already reports the resolved model + thinking level, so
+			// the cycle status is just a status-line-style chip track (active role
+			// filled), matching the plan-approval model slider. A dim suffix flags a
+			// temporary switch since that isn't shown elsewhere.
+			const track = renderSegmentTrack(
+				cycleOrder.map(role => ({ label: role, color: getRoleInfo(role, settings).color })),
+				cycleOrder.indexOf(result.role),
 			);
+			const tempLabel = options?.temporary ? theme.fg("dim", "  (temporary)") : "";
+			this.ctx.showStatus(`${track}${tempLabel}`, { dim: false });
 		} catch (error) {
 			this.ctx.showError(error instanceof Error ? error.message : String(error));
 		}

package/src/modes/interactive-mode.ts

@@ -116,7 +116,14 @@ import {
 	onThemeChange,
 	theme,
 } from "./theme/theme";
-import type { CompactionQueuedMessage, InteractiveModeContext, SubmittedUserInput, TodoItem, TodoPhase } from "./types";
+import type {
+	CompactionQueuedMessage,
+	InteractiveModeContext,
+	InteractiveModeInitOptions,
+	SubmittedUserInput,
+	TodoItem,
+	TodoPhase,
+} from "./types";
 import { UiHelpers } from "./utils/ui-helpers";
 
 const HINT_SHIMMER_PALETTE: ShimmerPalette = {
@@ -368,7 +375,7 @@ export class InteractiveMode implements InteractiveModeContext {
 			this.ui.requestRender(true);
 		};
 		this.editor.onAutocompleteUpdate = () => {
-			this.ui.requestRender();
+			this.ui.requestRender(false, { allowUnknownViewportMutation: true });
 		};
 		this.#syncEditorMaxHeight();
 		this.#resizeHandler = () => {
@@ -431,7 +438,10 @@ export class InteractiveMode implements InteractiveModeContext {
 		this.#observerRegistry = new SessionObserverRegistry();
 	}
 
-	async init(): Promise<void> {
+	playWelcomeIntro(): void {
+		this.#welcomeComponent?.playIntro(() => this.ui.requestRender());
+	}
+	async init(options: InteractiveModeInitOptions = {}): Promise<void> {
 		if (this.isInitialized) return;
 
 		this.keybindings = logger.time("InteractiveMode.init:keybindings", () => KeybindingsManager.create());
@@ -489,7 +499,9 @@ export class InteractiveMode implements InteractiveModeContext {
 			this.ui.addChild(new Spacer(1));
 			this.ui.addChild(this.#welcomeComponent);
 			this.ui.addChild(new Spacer(1));
-			this.#welcomeComponent.playIntro(() => this.ui.requestRender());
+			if (!options.suppressWelcomeIntro) {
+				this.playWelcomeIntro();
+			}
 
 			// Add changelog if provided
 			if (this.#changelogMarkdown) {
@@ -2259,7 +2271,7 @@ export class InteractiveMode implements InteractiveModeContext {
 			this.ui.requestRender(true);
 		};
 		nextEditor.onAutocompleteUpdate = () => {
-			this.ui.requestRender();
+			this.ui.requestRender(false, { allowUnknownViewportMutation: true });
 		};
 		nextEditor.setMaxHeight(this.#computeEditorMaxHeight());
 		if (this.historyStorage) {

package/src/modes/setup-wizard/index.ts

@@ -0,0 +1,88 @@
+import type { Settings } from "../../config/settings";
+import type { InteractiveModeContext } from "../types";
+import { glyphSetupScene } from "./scenes/glyph";
+import { providersSetupScene } from "./scenes/providers";
+import { themeSetupScene } from "./scenes/theme";
+import type { SetupScene } from "./scenes/types";
+import { SetupWizardComponent } from "./wizard-overlay";
+
+export type { SetupScene, SetupSceneController, SetupSceneHost, SetupSceneResult } from "./scenes/types";
+
+export const ALL_SCENES = [
+	providersSetupScene,
+	glyphSetupScene,
+	themeSetupScene,
+] as const satisfies readonly SetupScene[];
+
+export const CURRENT_SETUP_VERSION = ALL_SCENES.reduce((max, scene) => Math.max(max, scene.minVersion), 0);
+
+export interface SetupSceneSelectionOptions {
+	resuming?: boolean;
+	isTTY?: boolean;
+	skipEnv?: string;
+	setupWizardEnabled?: boolean;
+	force?: boolean;
+}
+
+function setupSkipEnvEnabled(value: string | undefined): boolean {
+	if (value === undefined) return false;
+	const normalized = value.trim().toLowerCase();
+	return normalized !== "" && normalized !== "0" && normalized !== "false" && normalized !== "no";
+}
+
+export async function selectSetupScenes(
+	storedVersion: number,
+	scenes: readonly SetupScene[],
+	ctx?: InteractiveModeContext,
+	options: SetupSceneSelectionOptions = {},
+): Promise<SetupScene[]> {
+	const isTTY = options.isTTY ?? (process.stdin.isTTY && process.stdout.isTTY);
+	if (!isTTY) return [];
+	if (!options.force) {
+		if (options.resuming) return [];
+		if (setupSkipEnvEnabled(options.skipEnv ?? Bun.env.OMP_SKIP_SETUP)) return [];
+		if (options.setupWizardEnabled === false) return [];
+	}
+
+	const selected: SetupScene[] = [];
+	for (const scene of scenes) {
+		if (!options.force && scene.minVersion <= storedVersion) continue;
+		if (scene.shouldRun) {
+			if (!ctx) continue;
+			if (!(await scene.shouldRun(ctx))) continue;
+		}
+		selected.push(scene);
+	}
+	return selected;
+}
+
+export async function markSetupWizardComplete(
+	settings: Settings,
+	version: number = CURRENT_SETUP_VERSION,
+): Promise<void> {
+	settings.set("setupVersion", version);
+	await settings.flush();
+}
+
+export async function runSetupWizard(
+	ctx: InteractiveModeContext,
+	scenes: readonly SetupScene[] = ALL_SCENES,
+): Promise<void> {
+	if (scenes.length === 0) return;
+	const component = new SetupWizardComponent(ctx, scenes);
+	const overlay = ctx.ui.showOverlay(component, {
+		width: "100%",
+		maxHeight: "100%",
+		anchor: "top-left",
+		margin: 0,
+	});
+	try {
+		await component.run();
+		await markSetupWizardComplete(ctx.settings);
+	} finally {
+		component.dispose();
+		ctx.ui.setFocus(component);
+		overlay.hide();
+	}
+	ctx.playWelcomeIntro();
+}

package/src/modes/setup-wizard/scenes/glyph.ts

@@ -0,0 +1,96 @@
+import { type SelectItem, SelectList } from "@oh-my-pi/pi-tui";
+import { getSelectListTheme, type SymbolPreset, setSymbolPreset, theme } from "../../theme/theme";
+import type { SetupScene, SetupSceneController, SetupSceneHost } from "./types";
+
+const GLYPH_PRESETS = ["nerd", "unicode", "ascii"] as const satisfies readonly SymbolPreset[];
+
+const GLYPH_LABELS: Readonly<Record<SymbolPreset, string>> = {
+	nerd: "Nerd Font",
+	unicode: "Unicode",
+	ascii: "ASCII",
+};
+
+const GLYPH_SAMPLES: Readonly<Record<SymbolPreset, string>> = {
+	nerd: "      󰉋  ",
+	unicode: "✔  ✖  📁  ⬢  ╭─╮  ├─  •  ⠋  →",
+	ascii: "[ok]  [x]  >  +  [D]  +-+  |--  *  ->",
+};
+
+/** One picker row per preset; the description column shows live sample glyphs instead of prose. */
+const GLYPH_ITEMS: readonly SelectItem[] = GLYPH_PRESETS.map((preset, index) => ({
+	value: preset,
+	label: `${index + 1}  ${GLYPH_LABELS[preset]}`,
+	description: preset === "nerd" ? `${GLYPH_SAMPLES.nerd}  ╭─╮  ├─  ◆  ✔  ✖` : GLYPH_SAMPLES[preset],
+}));
+
+class GlyphSceneController implements SetupSceneController {
+	title = "Choose glyph mode";
+	subtitle = "Pick the row that renders cleanly in your terminal.";
+	#selectList: SelectList;
+	#previewRequest = 0;
+	#committing = false;
+
+	constructor(private readonly host: SetupSceneHost) {
+		this.#selectList = new SelectList(GLYPH_ITEMS, GLYPH_ITEMS.length, getSelectListTheme());
+		const current = theme.getSymbolPreset();
+		const currentIndex = GLYPH_PRESETS.indexOf(current);
+		this.#selectList.setSelectedIndex(currentIndex >= 0 ? currentIndex : 0);
+		this.#selectList.onSelectionChange = item => {
+			this.#preview(item.value as SymbolPreset);
+		};
+		this.#selectList.onSelect = item => {
+			void this.#commit(item.value as SymbolPreset);
+		};
+		this.#selectList.onCancel = () => host.finish("skipped");
+	}
+
+	invalidate(): void {
+		this.#selectList.invalidate();
+	}
+
+	handleInput(data: string): void {
+		if (this.#committing) return;
+		const quickIndex = data >= "1" && data <= "3" ? Number(data) - 1 : -1;
+		if (quickIndex >= 0) {
+			const preset = GLYPH_PRESETS[quickIndex];
+			this.#selectList.setSelectedIndex(quickIndex);
+			this.#preview(preset);
+			return;
+		}
+		this.#selectList.handleInput(data);
+	}
+
+	render(width: number): string[] {
+		return [
+			theme.fg("muted", "If a row shows boxes, tofu, or misaligned icons, pick another."),
+			"",
+			...this.#selectList.render(width),
+		];
+	}
+
+	async #commit(preset: SymbolPreset): Promise<void> {
+		if (this.#committing) return;
+		this.#committing = true;
+		this.#previewRequest += 1;
+		this.host.ctx.settings.set("symbolPreset", preset);
+		await setSymbolPreset(preset);
+		this.host.ctx.ui.invalidate();
+		this.host.finish("done");
+	}
+
+	#preview(preset: SymbolPreset): void {
+		const request = ++this.#previewRequest;
+		void setSymbolPreset(preset).then(() => {
+			if (request !== this.#previewRequest || this.#committing) return;
+			this.host.ctx.ui.invalidate();
+			this.host.requestRender();
+		});
+	}
+}
+
+export const glyphSetupScene: SetupScene = {
+	id: "glyph-mode",
+	title: "Choose glyph mode",
+	minVersion: 1,
+	mount: host => new GlyphSceneController(host),
+};

package/src/modes/setup-wizard/scenes/outro.ts

@@ -0,0 +1,35 @@
+import { padding, truncateToWidth, visibleWidth } from "@oh-my-pi/pi-tui";
+import { gradientLogo, PI_LOGO } from "../../components/welcome";
+import { theme } from "../../theme/theme";
+import { renderStarfield, SETUP_TICK_MS } from "./splash";
+
+export const SETUP_OUTRO_MS = 1200;
+
+function centerLine(line: string, width: number): string {
+	const lineWidth = visibleWidth(line);
+	if (lineWidth >= width) return truncateToWidth(line, width);
+	const left = Math.floor((width - lineWidth) / 2);
+	return padding(left) + line + padding(width - left - lineWidth);
+}
+
+function clampLine(line: string, width: number): string {
+	const truncated = truncateToWidth(line, width);
+	return truncated + padding(Math.max(0, width - visibleWidth(truncated)));
+}
+
+export function renderSetupOutro(width: number, height: number, elapsedMs: number): string[] {
+	const frame = Math.floor(elapsedMs / SETUP_TICK_MS);
+	const lines = renderStarfield(width, height, frame + 1000);
+	const progress = Math.max(0, Math.min(1, elapsedMs / SETUP_OUTRO_MS));
+	const logo = gradientLogo(PI_LOGO, progress * 1.2, { pos: (progress * 2) % 1, strength: 1 - progress });
+	const title = theme.bold(theme.fg("success", `${theme.status.success} Setup saved`));
+	const subtitle = theme.fg("muted", "Handing off to the normal CLI…");
+	const sweepWidth = Math.max(1, Math.min(width - 8, Math.floor((width - 8) * progress)));
+	const sweep = `${theme.fg("accent", "━".repeat(sweepWidth))}${theme.fg("dim", "─".repeat(Math.max(0, width - 8 - sweepWidth)))}`;
+	const content = [...logo, "", title, subtitle, "", sweep];
+	const start = Math.max(0, Math.floor((height - content.length) / 2));
+	for (let i = 0; i < content.length && start + i < lines.length; i++) {
+		lines[start + i] = centerLine(content[i] ?? "", width);
+	}
+	return lines.map(line => clampLine(line, width));
+}