@iowarp/clio-coder 0.3.0 → 0.3.1

package/src/interactive/overlays/auth-dialog.ts

@@ -0,0 +1,221 @@
+import {
+	type Component,
+	Input,
+	type OverlayHandle,
+	Text,
+	type TUI,
+	truncateToWidth,
+	visibleWidth,
+} from "../../engine/tui.js";
+import { buildHint, FocusBox, showClioOverlayFrame } from "../overlay-frame.js";
+import { clioTheme, GLYPH, screenTitle } from "../theme/index.js";
+
+export const AUTH_DIALOG_WIDTH = 88;
+const ELLIPSIS = "…";
+const KEY_WIDTH = 10;
+
+export interface AuthDialogHandle {
+	handle: OverlayHandle;
+	controller: {
+		setLines(lines: ReadonlyArray<string>): void;
+		appendLine(line: string): void;
+		prompt(label: string): Promise<string>;
+		cancel(): void;
+		dismiss(): void;
+	};
+}
+
+function fitLine(text: string, width: number): string {
+	const safeWidth = Math.max(1, width);
+	if (visibleWidth(text) <= safeWidth) return text;
+	return truncateToWidth(text, safeWidth, ELLIPSIS, true);
+}
+
+function keyCell(label: string): string {
+	const theme = clioTheme();
+	const key = theme.fg("dim", label);
+	const width = visibleWidth(label);
+	return `${key}${" ".repeat(Math.max(0, KEY_WIDTH - width))}`;
+}
+
+function normalizeAuthLine(line: string): string {
+	return line.replace(/\.\.\./g, ELLIPSIS);
+}
+
+function formatAuthChoiceLine(line: string): string | null {
+	const match = /^(?<marker>[* ])\s*(?<index>\d+)\.\s*(?<label>.+)$/.exec(line);
+	if (!match?.groups) return null;
+	const theme = clioTheme();
+	const markerText = match.groups.marker ?? " ";
+	const indexText = match.groups.index ?? "";
+	const labelText = match.groups.label ?? "";
+	const marker = markerText === "*" ? theme.fg("accent", GLYPH.cursor) : " ";
+	const index = theme.fg("dim", `${indexText}.`);
+	const label = markerText === "*" ? theme.style("accent", labelText, { bold: true }) : theme.fg("muted", labelText);
+	return `${marker} ${index} ${label}`;
+}
+
+function formatAuthBodyLine(line: string): string {
+	const theme = clioTheme();
+	const normalized = normalizeAuthLine(line).trimEnd();
+	if (normalized.length === 0) return "";
+
+	const choiceLine = formatAuthChoiceLine(normalized);
+	if (choiceLine) return choiceLine;
+
+	if (/^Target ready\b/.test(normalized)) {
+		return theme.fg("success", `${GLYPH.ok} ${normalized}`);
+	}
+	if (/^(Target check failed|Unknown selection:)/.test(normalized)) {
+		return theme.fg("error", `${GLYPH.error} ${normalized}`);
+	}
+
+	const colonIndex = normalized.indexOf(":");
+	if (colonIndex > 0 && colonIndex <= 18 && normalized.slice(colonIndex, colonIndex + 3) !== "://") {
+		const key = normalized.slice(0, colonIndex);
+		const value = normalized.slice(colonIndex + 1).trimStart();
+		if (/^[A-Za-z][A-Za-z ]*$/.test(key)) {
+			return `${keyCell(key)} ${theme.fg("muted", value)}`;
+		}
+	}
+
+	return theme.fg("muted", normalized);
+}
+
+function renderInputWithDesignCursor(input: Input, width: number): string[] {
+	const theme = clioTheme();
+	return input
+		.render(width)
+		.map((line) =>
+			fitLine(line.startsWith("> ") ? `${theme.fg("accent", `${GLYPH.cursor} `)}${line.slice(2)}` : line, width),
+		);
+}
+
+function createAuthDialogController(
+	title: string,
+	onCancel: () => void,
+): {
+	box: FocusBox;
+	controller: AuthDialogHandle["controller"];
+	getHint: () => string;
+} {
+	const titleView = new Text("");
+	const bodyView = new Text("");
+	const promptView = new Text("");
+	const input = new Input();
+	const inputView: Component = {
+		render: (width) => renderInputWithDesignCursor(input, width),
+		handleInput: (data) => input.handleInput(data),
+		invalidate: () => input.invalidate(),
+	};
+	let lines: string[] = [];
+	let promptLabel: string | null = null;
+	let resolver: ((value: string) => void) | undefined;
+	let rejecter: ((error: Error) => void) | undefined;
+	let currentHint = buildHint([]);
+
+	titleView.setText(screenTitle(clioTheme(), title));
+	const box = new FocusBox([], {
+		onInput: (data) => {
+			if (promptLabel) input.handleInput(data);
+		},
+	});
+
+	input.onSubmit = () => {
+		if (!resolver) return;
+		const resolve = resolver;
+		resolver = undefined;
+		rejecter = undefined;
+		const value = input.getValue();
+		promptLabel = null;
+		input.setValue("");
+		rebuild();
+		resolve(value);
+	};
+	input.onEscape = () => {
+		cancel();
+	};
+	rebuild();
+
+	return {
+		box,
+		controller: {
+			setLines,
+			appendLine,
+			prompt,
+			cancel,
+			dismiss,
+		},
+		getHint: () => currentHint,
+	};
+
+	function rebuild(): void {
+		box.clear();
+		box.addChild(titleView);
+		bodyView.setText(lines.map(formatAuthBodyLine).join("\n"));
+		box.addChild(bodyView);
+		if (promptLabel) {
+			promptView.setText(clioTheme().fg("dim", normalizeAuthLine(promptLabel)));
+			currentHint = buildHint([{ key: "Enter", verb: "submit" }]);
+			box.addChild(promptView);
+			box.addChild(inputView);
+		} else {
+			currentHint = buildHint([]);
+		}
+		box.invalidate();
+	}
+
+	function rejectPending(message: string): void {
+		if (!rejecter) return;
+		const reject = rejecter;
+		resolver = undefined;
+		rejecter = undefined;
+		promptLabel = null;
+		input.setValue("");
+		rebuild();
+		reject(new Error(message));
+	}
+
+	function setLines(nextLines: ReadonlyArray<string>): void {
+		lines = [...nextLines];
+		rebuild();
+	}
+
+	function appendLine(line: string): void {
+		lines = [...lines, line];
+		rebuild();
+	}
+
+	function prompt(label: string): Promise<string> {
+		promptLabel = label;
+		input.setValue("");
+		rebuild();
+		return new Promise((resolve, reject) => {
+			resolver = resolve;
+			rejecter = reject;
+		});
+	}
+
+	function cancel(): void {
+		rejectPending("cancelled");
+		onCancel();
+	}
+
+	function dismiss(): void {
+		rejectPending("dismissed");
+	}
+}
+
+export function openAuthDialog(tui: TUI, title: string, onCancel: () => void): AuthDialogHandle {
+	const { box, controller, getHint } = createAuthDialogController(title, onCancel);
+	const handle = showClioOverlayFrame(tui, box, {
+		anchor: "center",
+		width: AUTH_DIALOG_WIDTH,
+		title: "Authentication",
+		footerHint: getHint,
+	});
+	return {
+		handle,
+		controller,
+	};
+}

package/src/interactive/overlays/context-reset.ts

@@ -0,0 +1,108 @@
+import {
+	type OverlayHandle,
+	type SelectItem,
+	SelectList,
+	type SelectListLayoutOptions,
+	type TUI,
+	truncateToWidth,
+	visibleWidth,
+} from "../../engine/tui.js";
+import { buildHint, DEFAULT_SELECT_THEME, FocusBox, showClioOverlayFrame } from "../overlay-frame.js";
+import type { ContextClearCommandOptions } from "../slash-commands.js";
+import { clioTheme } from "../theme/index.js";
+
+export const CONTEXT_RESET_OVERLAY_WIDTH = 72;
+const ELLIPSIS = "…";
+
+export type ContextResetMutationChoice = "preserve-clio-md" | "delete-clio-md";
+
+export interface OpenContextResetOverlayDeps {
+	/** Called only for one of the two mutating choices. */
+	onReset: (choice: ContextResetMutationChoice) => void;
+	/** Called for both the explicit Cancel row and Esc. */
+	onCancel: () => void;
+}
+
+/** Translate one confirmed chooser action into the existing context-domain contract. */
+export function contextResetOptions(choice: ContextResetMutationChoice): ContextClearCommandOptions {
+	return choice === "delete-clio-md" ? { all: true, confirmed: true, confirmedAll: true } : { confirmed: true };
+}
+
+/** Three intentional outcomes, ordered with the least destructive action first. */
+export function buildContextResetItems(): SelectItem[] {
+	return [
+		{
+			value: "preserve-clio-md",
+			label: "Preserve CLIO-CODER.md",
+			description: "remove generated context and keep the project handbook",
+		},
+		{
+			value: "delete-clio-md",
+			label: "Delete CLIO-CODER.md",
+			description: "remove generated context and the project handbook",
+		},
+		{
+			value: "cancel",
+			label: "Cancel",
+			description: "close without changing any files",
+		},
+	];
+}
+
+function singleLine(text: string): string {
+	return text.replace(/[\r\n]+/g, " ").trim();
+}
+
+/** Keep every choice on one terminal row even when the overlay is clamped. */
+function buildSelectPresentation(items: ReadonlyArray<SelectItem>): {
+	items: SelectItem[];
+	layout: SelectListLayoutOptions;
+} {
+	const descriptions = new Map(items.map((item) => [item.value, singleLine(item.description ?? "")]));
+	return {
+		items: items.map((item) => ({ value: item.value, label: item.label })),
+		layout: {
+			minPrimaryColumnWidth: 18,
+			maxPrimaryColumnWidth: 64,
+			truncatePrimary: ({ text, maxWidth, item, isSelected }) => {
+				const label = singleLine(text);
+				const description = descriptions.get(item.value) ?? "";
+				if (description.length === 0 || maxWidth < 44) {
+					return truncateToWidth(label, maxWidth, ELLIPSIS, true);
+				}
+
+				const labelWidth = Math.max(1, Math.min(22, maxWidth - 14));
+				const fittedLabel = truncateToWidth(label, labelWidth, ELLIPSIS, true);
+				const spacing = " ".repeat(Math.max(1, labelWidth + 2 - visibleWidth(fittedLabel)));
+				const descriptionWidth = Math.max(1, maxWidth - visibleWidth(fittedLabel) - visibleWidth(spacing));
+				const fittedDescription = truncateToWidth(description, descriptionWidth, ELLIPSIS, true);
+				const body = `${fittedLabel}${spacing}${fittedDescription}`;
+				return isSelected ? body : `${fittedLabel}${clioTheme().fg("muted", `${spacing}${fittedDescription}`)}`;
+			},
+		},
+	};
+}
+
+/** Open the `/context reset` choice dialog. Cancel paths never reach onReset. */
+export function openContextResetOverlay(tui: TUI, deps: OpenContextResetOverlayDeps): OverlayHandle {
+	const choices = buildContextResetItems();
+	const presentation = buildSelectPresentation(choices);
+	const list = new SelectList(presentation.items, choices.length, DEFAULT_SELECT_THEME, presentation.layout);
+	list.onSelect = (item: SelectItem): void => {
+		if (item.value === "preserve-clio-md" || item.value === "delete-clio-md") {
+			deps.onReset(item.value);
+			return;
+		}
+		deps.onCancel();
+	};
+	list.onCancel = (): void => {
+		deps.onCancel();
+	};
+
+	return showClioOverlayFrame(tui, new FocusBox(list), {
+		anchor: "center",
+		width: CONTEXT_RESET_OVERLAY_WIDTH,
+		title: "Reset Project Context",
+		footerHint: buildHint([{ key: "Enter", verb: "select" }]),
+	});
+}

package/src/interactive/overlays/cwd-fallback.ts

@@ -0,0 +1,141 @@
+/**
+ * cwd-fallback overlay (Phase 12 slice 12d).
+ *
+ * Two-choice overlay shown after `session.resume(...)` when the recorded
+ * cwd no longer exists on disk (see src/domains/session/cwd-fallback.ts).
+ * Continue uses the terminal's current cwd; Cancel returns the user to
+ * whatever session was current before the resume and closes the overlay.
+ *
+ * The overlay stays intentionally small: a SelectList owns behavior while the
+ * rendered rows follow the shared dialog grammar.
+ */
+
+import {
+	type OverlayHandle,
+	type SelectItem,
+	SelectList,
+	type SelectListLayoutOptions,
+	type TUI,
+	truncateToWidth,
+	visibleWidth,
+} from "../../engine/tui.js";
+import { buildHint, DEFAULT_SELECT_THEME, FocusBox, showClioOverlayFrame } from "../overlay-frame.js";
+import { clioTheme } from "../theme/index.js";
+
+export const CWD_FALLBACK_OVERLAY_WIDTH = 88;
+const ELLIPSIS = "…";
+
+/** Reasons surfaced by resolveSessionCwd. Overlay maps each to a description line. */
+export type CwdFallbackReason = "no-cwd" | "missing" | "not-a-directory";
+
+export interface OpenCwdFallbackOverlayDeps {
+	/** Absolute path the resumed session recorded in meta.cwd. May be empty when reason="no-cwd". */
+	sessionCwd: string;
+	/** Absolute path of the terminal's current working directory. */
+	currentCwd: string;
+	/** Why the session cwd failed to resolve. */
+	reason: CwdFallbackReason;
+	/** Invoked when the user picks Continue. */
+	onContinue: () => void;
+	/**
+	 * Invoked when the user picks Cancel or presses Esc. The caller should
+	 * restore the prior session (if any) or re-open the /resume overlay.
+	 */
+	onCancel: () => void;
+	/** Close the overlay. Always fires before onContinue/onCancel returns. */
+	onClose: () => void;
+}
+
+function reasonPhrase(reason: CwdFallbackReason, sessionCwd: string): string {
+	if (reason === "no-cwd") return "session has no recorded cwd";
+	if (reason === "missing") return `session cwd ${sessionCwd} is missing`;
+	return `session cwd ${sessionCwd} is not a directory`;
+}
+
+function singleLine(text: string): string {
+	return text.replace(/[\r\n]+/g, " ").trim();
+}
+
+function buildSelectPresentation(items: ReadonlyArray<SelectItem>): {
+	items: SelectItem[];
+	layout: SelectListLayoutOptions;
+} {
+	const descriptions = new Map(items.map((item) => [item.value, singleLine(item.description ?? "")]));
+	return {
+		items: items.map((item) => ({ value: item.value, label: item.label })),
+		layout: {
+			minPrimaryColumnWidth: 24,
+			maxPrimaryColumnWidth: 38,
+			truncatePrimary: ({ text, maxWidth, item, isSelected }) => {
+				const label = singleLine(text);
+				const description = descriptions.get(item.value) ?? "";
+				if (description.length === 0 || maxWidth < 32) {
+					return truncateToWidth(label, maxWidth, ELLIPSIS, true);
+				}
+
+				const theme = clioTheme();
+				const preferredLabelWidth = Math.max(24, Math.min(38, visibleWidth(label) + 2));
+				const labelWidth = Math.max(1, Math.min(preferredLabelWidth, maxWidth - 12));
+				const fittedLabel = truncateToWidth(label, labelWidth, ELLIPSIS, true);
+				const spacing = " ".repeat(Math.max(1, labelWidth + 2 - visibleWidth(fittedLabel)));
+				const descWidth = Math.max(1, maxWidth - visibleWidth(fittedLabel) - visibleWidth(spacing));
+				const fittedDescription = truncateToWidth(description, descWidth, ELLIPSIS, true);
+				const body = `${fittedLabel}${spacing}${fittedDescription}`;
+				return isSelected ? body : `${fittedLabel}${theme.fg("muted", `${spacing}${fittedDescription}`)}`;
+			},
+		},
+	};
+}
+
+/**
+ * Pure builder. Exposed so tests can assert row shape without booting the TUI.
+ * Two rows: Continue (uses process cwd) and Cancel (returns to picker).
+ */
+export function buildCwdFallbackItems(args: {
+	currentCwd: string;
+	sessionCwd: string;
+	reason: CwdFallbackReason;
+}): SelectItem[] {
+	const why = reasonPhrase(args.reason, args.sessionCwd);
+	return [
+		{
+			value: "continue",
+			label: `Continue in ${args.currentCwd}`,
+			description: `${why}; use this terminal's cwd instead`,
+		},
+		{
+			value: "cancel",
+			label: "Cancel",
+			description: "close this overlay and return to the session picker",
+		},
+	];
+}
+
+export function openCwdFallbackOverlay(tui: TUI, deps: OpenCwdFallbackOverlayDeps): OverlayHandle {
+	const items = buildCwdFallbackItems({
+		currentCwd: deps.currentCwd,
+		sessionCwd: deps.sessionCwd,
+		reason: deps.reason,
+	});
+	const presentation = buildSelectPresentation(items);
+	const list = new SelectList(presentation.items, items.length, DEFAULT_SELECT_THEME, presentation.layout);
+	list.onSelect = (item: SelectItem): void => {
+		if (item.value === "continue") {
+			deps.onContinue();
+		} else {
+			deps.onCancel();
+		}
+		deps.onClose();
+	};
+	list.onCancel = (): void => {
+		deps.onCancel();
+		deps.onClose();
+	};
+	const box = new FocusBox(list);
+	return showClioOverlayFrame(tui, box, {
+		anchor: "center",
+		width: CWD_FALLBACK_OVERLAY_WIDTH,
+		title: "Session Working Directory",
+		footerHint: buildHint([{ key: "Enter", verb: "select" }]),
+	});
+}

package/src/interactive/overlays/extensions.ts

@@ -0,0 +1,54 @@
+import type { OverlayHandle, TUI } from "../../engine/tui.js";
+import type { SlashCommandContext } from "../slash-commands.js";
+import { clioTheme } from "../theme/index.js";
+import { type ListOverlayItem, openListOverlay } from "./list-overlay.js";
+
+/** @internal exported for contract tests */
+export const EXTENSIONS_EMPTY =
+	"no extensions installed. install one with `clio-coder extensions install <path>`, then `clio-coder extensions list` shows what it contributed.";
+
+export function openExtensionsOverlay(tui: TUI, ctx: SlashCommandContext, onClose: () => void): OverlayHandle {
+	const list = ctx.listExtensions?.() ?? [];
+	const items: ListOverlayItem[] = list.map((ext) => {
+		const state = !ext.enabled ? "disabled" : ext.effective ? "active" : `shadowed:${ext.overriddenBy ?? "higher"}`;
+
+		let meta = state;
+		if (state === "active") {
+			meta = clioTheme().fg("success", "active");
+		} else if (state === "disabled") {
+			meta = clioTheme().fg("dim", "disabled");
+		} else {
+			meta = clioTheme().fg("warning", state);
+		}
+
+		const label = `${ext.id.padEnd(22)} ${ext.scope.padEnd(7)} ${ext.description}`;
+
+		return {
+			id: ext.id,
+			label,
+			meta,
+			group: "Extensions",
+			detail: () => {
+				const lines = [
+					`# Extension: ${ext.id}`,
+					`**Version:** ${ext.version}`,
+					`**Scope:** ${ext.scope}`,
+					`**Description:** ${ext.description}`,
+					`**State:** ${state}`,
+				];
+				if (ext.overriddenBy) {
+					lines.push(`**Overridden By:** ${ext.overriddenBy}`);
+				}
+				return lines;
+			},
+		};
+	});
+
+	return openListOverlay(tui, {
+		title: "Extensions Reference",
+		items,
+		filterable: true,
+		emptyMessage: EXTENSIONS_EMPTY,
+		onClose,
+	});
+}

package/src/interactive/overlays/help-reference.ts

@@ -0,0 +1,140 @@
+import type { OverlayHandle, TUI } from "../../engine/tui.js";
+import type { ClioKeybindingManager } from "../keybinding-manager.js";
+import { commandReference, SLASH_COMMAND_GROUPS } from "../slash-commands.js";
+import { formatKeybindingDetailBodyLines } from "./keybinding-detail.js";
+import { type ListOverlayItem, openListOverlay } from "./list-overlay.js";
+
+function formatKey(raw: string): string {
+	if (raw === "(unbound)") return raw;
+	return raw
+		.split(" / ")
+		.map((single) =>
+			single
+				.split("+")
+				.map((segment) => {
+					const head = segment.charAt(0);
+					return head.length === 0 ? segment : head.toUpperCase() + segment.slice(1);
+				})
+				.join("+"),
+		)
+		.join(" / ");
+}
+
+export function openHelpOverlay(
+	tui: TUI,
+	manager: ClioKeybindingManager,
+	onClose: () => void,
+	initialFilter?: string,
+): OverlayHandle {
+	// Commands are grouped by the verb they perform, in SLASH_COMMAND_GROUPS
+	// order, and keep registry order inside each group.
+	const groupRank = new Map(SLASH_COMMAND_GROUPS.map((group, index) => [group, index] as const));
+	const commands: ListOverlayItem[] = [...commandReference()]
+		.sort((a, b) => (groupRank.get(a.group) ?? 0) - (groupRank.get(b.group) ?? 0))
+		.map((ref) => {
+			const usagePart = ref.usage.length >= 30 ? `${ref.usage} ` : ref.usage.padEnd(30);
+			const label = `${usagePart}${ref.description}`;
+			const item: ListOverlayItem = {
+				id: ref.name,
+				label,
+				group: ref.group,
+				// Overlay key actions are deliberately not duplicated here: each
+				// overlay's footer hint is the live source of its keys, and a static
+				// copy would rot exactly like the old SLASH_HOTKEYS table did.
+				detail: () => {
+					const lines = [`# Command: /${ref.name}`, `**Usage:** \`${ref.usage}\``, `**Description:** ${ref.description}`];
+					if (ref.aliases.length > 0) {
+						lines.push(`**Aliases:** ${ref.aliases.map((a) => `/${a}`).join(", ")}`);
+					}
+					return lines;
+				},
+			};
+			if (ref.aliases.length > 0) {
+				item.meta = ref.aliases.join(", ");
+			}
+			return item;
+		});
+
+	const conflicts = manager.getConflicts();
+	const keys: ListOverlayItem[] = manager.hotkeyEntries().map((row) => {
+		const formattedKeys = formatKey(row.keys);
+		const keysPart = formattedKeys.length >= 24 ? `${formattedKeys} ` : formattedKeys.padEnd(24);
+		const label = `${keysPart}${row.description}`;
+
+		const item: ListOverlayItem = {
+			id: row.id,
+			label,
+			group: "Keys",
+			detail: (width) => {
+				const warnings = manager
+					.platformWarnings()
+					.filter((w) => w.id === row.id)
+					.map((w) => `${w.keys.map(formatKey).join(" / ")} may not fire: ${w.reason}`);
+				const detailEntry = {
+					id: row.id,
+					keys: formattedKeys,
+					action: row.description,
+					source: row.source,
+					warnings,
+				};
+				return formatKeybindingDetailBodyLines(detailEntry, width);
+			},
+		};
+
+		const metaParts: string[] = [];
+		if (row.source === "user") metaParts.push("user");
+		const hasConflict = conflicts.some((c) => c.keybindings.includes(row.id));
+		if (hasConflict) metaParts.push("conflict");
+		if (metaParts.length > 0) {
+			item.meta = metaParts.join(", ");
+		}
+
+		return item;
+	});
+
+	// Static concept topics. Unlike commands and keys these are not generated
+	// from a registry; keep each detail consistent with the enforced behavior
+	// and with the live footer hints on the surface it documents.
+	const topics: ListOverlayItem[] = [
+		{
+			id: "topic-fleet-runs",
+			label: `${"fleet runs & steering".padEnd(30)}Inspect, guide, and cancel delegated workers`,
+			group: "Topics",
+			detail: () => [
+				"# Fleet runs & steering",
+				"**Fleet Runs board**: open it with the configured Dispatch Board key (Alt+W by default). Use Up/Down or `j`/`k` to select a live or recent run.",
+				"**Steer**: press `s` on a live native run to close the board and prefill `@<runId> `. Add guidance and submit it normally. The first notice means queued; a received notice confirms worker delivery.",
+				"**Cancel**: press `x` on a running, stale, queued, or retry-waiting run. The row changes to cancelling while the worker or retry is being stopped.",
+				"**Capabilities**: ACP delegation runs cannot accept live steering. The board footer only advertises actions supported by the selected row.",
+				"**Tasks versus runs**: `/tasks` shows the agent's plan steps. Fleet runs are concrete delegated worker executions and remain in this board as recent terminal history.",
+			],
+		},
+		{
+			id: "topic-autonomy",
+			label: `${"autonomy & safety net".padEnd(30)}How the autonomy level and the always-on guardrails interact`,
+			group: "Topics",
+			detail: () => [
+				"# Autonomy & safety net",
+				"**Tool surface**: which tools exist at all through registration, tool profiles, skill narrowing, and dispatch admission. " +
+					"Violations are terminal denials, never approvable.",
+				"**Safety net** (always on, level-independent): damage-control rules, path policy for secrets and system paths, " +
+					"command-substitution confirmation, and `git_destructive` blocks. Blocks are final at every level; confirm rails ask at every level.",
+				"**Autonomy level** (`/settings`, persisted as `autonomy`): the operator's standing grant per action class for actions the net passed, " +
+					"enforced by the harness at tool admission. read-only denies non-read, suggest parks every non-read call, " +
+					"auto-edit parks unrecognized commands, and full-auto runs them.",
+				"**Approvals**: a parked call waits for a one-shot operator decision; approving resumes only that call. " +
+					"Workers resolve asks per `workers.onPermission` (Approvals Routing); headless runs auto-deny.",
+			],
+		},
+	];
+
+	const items = [...commands, ...keys, ...topics];
+
+	return openListOverlay(tui, {
+		title: "Help Center",
+		items,
+		filterable: true,
+		...(initialFilter ? { initialFilter } : {}),
+		onClose,
+	});
+}