@iowarp/clio-coder 0.4.5 → 0.4.7

package/src/interactive/overlays/settings.ts

@@ -54,6 +54,7 @@ import {
 	wrapTextWithAnsi,
 } from "../../engine/tui.js";
 import { clockLocal } from "../format-time.js";
+import { localKey } from "../keyboard-owner.js";
 import { buildHint, DEFAULT_SELECT_THEME, showClioOverlayFrame } from "../overlay-frame.js";
 import { barSep, clioTheme, GLYPH, padAnsi, rule, screenTitle } from "../theme/index.js";
 import { modelsForTarget } from "./model-selector.js";
@@ -119,6 +120,7 @@ const SELECT_DOWN = "\u001b[B";
 /** Settings pickers accept the same j/k navigation as the rows that open them. */
 class SettingsSelectList extends SelectList {
 	override handleInput(data: string): void {
+		data = localKey(data);
 		super.handleInput(data === "j" ? SELECT_DOWN : data === "k" ? SELECT_UP : data);
 	}
 }
@@ -149,7 +151,7 @@ const SETTINGS_SECTION_DESCRIPTIONS = {
 	orchestrator: "Interactive chat routing, prompt pre-warm, and the optional proactive-memory model plane.",
 	fleet: "Defaults, profiles, agent bindings, and route activation for dispatched workers, and where they run.",
 	targets: "Configured inference targets: which one chat and the fleet use, and whether each answers.",
-	models: "The /model picker, favorites, and Alt+J / Alt+K cycling.",
+	models: "The /model picker, favorites, and configured model cycling.",
 	budget: "Cost ceiling, per-turn output budget, worker concurrency, and the guardrail backstops.",
 	compaction: "When and how the context window is evicted and summarized under pressure.",
 	retry: "Automatic recovery from transient provider, network, and stalled-stream errors.",
@@ -229,7 +231,7 @@ export const SETTINGS_LABELS_BY_ID = {
 	"retry.maxDelayMs": "Max delay (ms)",
 	"retry.streamStallMs": "Stream stall timeout (ms)",
 	"terminal.showTerminalProgress": "Terminal progress badges",
-	"terminal.outputVerbosity": "Output detail",
+	"terminal.outputVerbosity": "Output style",
 	"terminal.tuiMode": "TUI mode",
 	"terminal.fullscreenScrollbar": "Fullscreen scrollbar",
 	"terminal.smoothStreaming": "Smooth streaming",
@@ -422,7 +424,7 @@ const SETTINGS_DESCRIPTIONS_BY_ID = {
 	"panes.yazi.profile": "Use Clio's managed, themed engine profile or the operator's own file-manager configuration.",
 	"panes.yazi.followCwd": "Push the conversation directory into an already-open companion pane.",
 	"panes.yazi.ratio": "Share of the height the files dock takes, at most half.",
-	scope: "Alt+J and Alt+K model cycle set.",
+	scope: "Configured model-cycle action set.",
 	"modelSelector.recentLimit": "How many recently used models /model remembers.",
 	"modelSelector.favorites": "Exact target/model refs pinned in /model.",
 	"budget.sessionCeilingUsd": "Per-session cost cap.",
@@ -514,7 +516,8 @@ const SETTINGS_HELP_BY_ID: Partial<Record<EditableSettingId, string>> = {
 		"Written by the confirm flow, not by hand, because confirming a remote here would be the record confirming itself. Sync refuses with library_remote_unconfirmed until this equals library.remote. Default: blank.",
 	"library.sync":
 		"Off means `clio-coder library sync` and `push` refuse before touching the network, whatever the remote says. Legal values: true, false · default: false.",
-	"budget.concurrency": "auto sizes to your machine. A fixed number caps how many workers run at once.",
+	"budget.concurrency":
+		"auto allows four local workers. A fixed number caps how many workers run at once; the default is one.",
 	"skills.trustProjectCompatRoots":
 		"Project roots like .claude/skills and .codex/skills are untrusted by default; enabling exposes them to the model.",
 	"attribution.gitCommits":
@@ -539,7 +542,8 @@ const SETTINGS_HELP_BY_ID: Partial<Record<EditableSettingId, string>> = {
 		"Bind base, custom, and shadow native agents such as scout, researcher, and provenance to profiles. ACP delegation agents cannot be bound.",
 	"delegation.defaults.toolGovernance":
 		"clio-coder-policy gates the agent through Clio's safety net; agent-managed trusts the agent; deny-all blocks every tool.",
-	scope: "Choose target-level or exact target/model refs. Alt+J / Alt+K step the chat target through this list.",
+	scope:
+		"Choose target-level or exact target/model refs. Explicit model-cycle bindings step the chat target through this list.",
 	runtimePlugins: "Comma-separated package names, loaded at startup. Restart Clio after changing.",
 	"terminal.notify":
 		"OSC 777, or OSC 9 on iTerm2, Windows Terminal, and ConEmu. Interactive TTY runs only; the body never carries prompt text, file paths, or model output.",
@@ -550,7 +554,7 @@ const SETTINGS_HELP_BY_ID: Partial<Record<EditableSettingId, string>> = {
 	"watchdog.cadenceToolCalls":
 		"Mid-turn firing is how scope drift becomes visible before the turn ends. Leave blank and the watchdog fires at turn end only.",
 	keybindings:
-		"Renderer controls: Alt+O newest tool or worker details, Ctrl+Alt+O or Alt+Shift+O all of them, Alt+P live tool output, Alt+R latest reasoning, Ctrl+Alt+R or Alt+Shift+R all reasoning. Override these in settings.yaml or use /help.",
+		"Alt+O cycles Output style: Compact, Standard, Detailed. Use /view for full reasoning and action details. Shift+Tab changes model thinking effort.",
 };
 
 /** Per-value meaning, surfaced for the current value of an enum knob. */
@@ -623,9 +627,9 @@ const SETTINGS_VALUE_HELP_BY_ID: Partial<Record<EditableSettingId, Record<string
 		false: "no terminal progress badges",
 	},
 	"terminal.outputVerbosity": {
-		minimal: "quiet transcript; tools stay to one-line outcomes and reasoning stays folded",
-		default: "balanced transcript; unfold the latest tool, worker, or reasoning block on demand",
-		verbose: "transparent transcript; reasoning, arguments, and live tool output stay visible",
+		compact: "quiet action summaries, answers, and visible failures",
+		standard: "short reasoning and change previews, clear action outcomes",
+		detailed: "larger bounded previews; full content is available in /view",
 	},
 	"terminal.tuiMode": {
 		regular: "preserve terminal scrollback and render the composer below the transcript",
@@ -834,6 +838,7 @@ export class SubmenuWrapper implements Component {
 	}
 
 	handleInput(data: string): void {
+		data = localKey(data);
 		this.child.handleInput?.(data);
 	}
 
@@ -1252,6 +1257,7 @@ class ScopedModelChecklist implements Component {
 	}
 
 	handleInput(data: string): void {
+		data = localKey(data);
 		const kb = getKeybindings();
 		if (kb.matches(data, "tui.select.up") || data === "k") {
 			this.selectedRow = this.nextEntryIndex(this.selectedRow - 1, -1);
@@ -1923,7 +1929,7 @@ function buildSettingItems(settings: Readonly<ClioSettings>, options?: BuildSett
 			values: ["false", "true"],
 		}),
 		settingItem("terminal.outputVerbosity", terminal.outputDetail, {
-			values: ["minimal", "default", "verbose"],
+			values: ["compact", "standard", "detailed"],
 		}),
 		settingItem("terminal.tuiMode", terminal.mode, {
 			values: ["regular", "fullscreen"],
@@ -2555,7 +2561,7 @@ function applySettingChange(settings: ClioSettings, id: string, value: string):
 			if (value === "true" || value === "false") settings.interface.terminalProgress = value === "true";
 			return;
 		case "terminal.outputVerbosity":
-			if (value === "minimal" || value === "default" || value === "verbose") settings.interface.outputDetail = value;
+			if (value === "compact" || value === "standard" || value === "detailed") settings.interface.outputDetail = value;
 			return;
 		case "terminal.tuiMode":
 			if (value === "regular" || value === "fullscreen") settings.interface.mode = value;
@@ -3036,10 +3042,6 @@ function fixedLines(lines: readonly string[], width: number, height: number): st
 }
 
 /** Typed text, as opposed to an escape sequence or a control byte. */
-function isPrintableInput(data: string): boolean {
-	if (data.length === 0 || data.startsWith("\u001b")) return false;
-	return Array.from(data).every((character) => character >= " " && character !== "\u007f");
-}
 
 function scrollWindow(total: number, selected: number, height: number): [number, number] {
 	if (height <= 0 || total <= height) return [0, total];
@@ -3302,6 +3304,17 @@ export class SettingsCenter implements Component {
 	 * Enter commits it and Esc restores the committed query.
 	 */
 	private filterDraft: string | null = null;
+	private readonly filterInput = new Input();
+	get keyboardScope(): "edit" | "review" {
+		return this.filterDraft !== null ? "edit" : "review";
+	}
+	undoInput(): boolean {
+		if (this.filterDraft === null) return false;
+		this.filterInput.applyEdit("undo");
+		this.filterDraft = this.filterInput.getValue();
+		this.normalizeSelection();
+		return true;
+	}
 	/** Local cycle preview for the selected row; committed on Enter. */
 	private pendingValue: string | null = null;
 
@@ -3359,6 +3372,7 @@ export class SettingsCenter implements Component {
 	 * presses and do nothing.
 	 */
 	handleInput(data: string): void {
+		data = localKey(data);
 		if (isKeyRelease(data)) return;
 		if (matchesKey(data, "escape")) {
 			this.back();
@@ -3375,6 +3389,7 @@ export class SettingsCenter implements Component {
 		const kb = getKeybindings();
 		if (data === "/") {
 			this.filterDraft = this.filterQuery;
+			this.filterInput.setValue(this.filterDraft);
 			return;
 		}
 		if (matchesKey(data, "tab")) {
@@ -3458,17 +3473,10 @@ export class SettingsCenter implements Component {
 			this.options.requestRender?.();
 			return;
 		}
-		if (data === "\x7f" || data === "\b") {
-			this.filterDraft = draft.slice(0, -1);
-			this.normalizeSelection();
-			this.options.requestRender?.();
-			return;
-		}
-		if (isPrintableInput(data)) {
-			this.filterDraft = draft + data;
-			this.normalizeSelection();
-			this.options.requestRender?.();
-		}
+		this.filterInput.handleInput(data);
+		this.filterDraft = this.filterInput.getValue();
+		this.normalizeSelection();
+		this.options.requestRender?.();
 	}
 
 	/** The query the catalog is narrowed by right now: the live draft while the

package/src/interactive/overlays/tree-selector.ts

@@ -2,6 +2,7 @@ import type { SessionContract } from "../../domains/session/contract.js";
 import type { TreeSnapshot, TreeSnapshotNode } from "../../domains/session/tree/navigator.js";
 import {
 	type Component,
+	Input,
 	matchesKey,
 	type OverlayHandle,
 	type TUI,
@@ -9,6 +10,7 @@ import {
 	visibleWidth,
 } from "../../engine/tui.js";
 import { clockLocal, dateLocal } from "../format-time.js";
+import { localKey } from "../keyboard-owner.js";
 import { buildHint, clioError, FocusBox, showClioOverlayFrame } from "../overlay-frame.js";
 import { type ClioTheme, clioTheme, GLYPH } from "../theme/index.js";
 
@@ -204,6 +206,13 @@ export class TreeOverlayView implements Component {
 	private showTimestamps = false;
 	private submode: Submode = "browse";
 	private labelBuffer = "";
+	private readonly labelInput = new Input();
+	undoInput(): boolean {
+		if (this.submode !== "edit-label") return false;
+		this.labelInput.applyEdit("undo");
+		this.labelBuffer = this.labelInput.getValue();
+		return true;
+	}
 	private status = "";
 	private statusKind: "info" | "error" = "info";
 
@@ -300,7 +309,11 @@ export class TreeOverlayView implements Component {
 
 	invalidate(): void {}
 
+	get keyboardScope(): "edit" | "browse" {
+		return this.submode === "edit-label" ? "edit" : "browse";
+	}
 	handleInput(data: string): void {
+		data = localKey(data);
 		if (this.submode === "edit-label") {
 			this.handleLabelInput(data);
 			return;
@@ -344,6 +357,7 @@ export class TreeOverlayView implements Component {
 		if (data === "e") {
 			this.submode = "edit-label";
 			this.labelBuffer = this.currentRow()?.node.label ?? "";
+			this.labelInput.setValue(this.labelBuffer);
 			this.setStatus("");
 			return;
 		}
@@ -375,17 +389,8 @@ export class TreeOverlayView implements Component {
 			this.refresh();
 			return;
 		}
-		// Backspace: DEL (0x7f) or BS (0x08).
-		if (data === "\x7f" || data === "\b") {
-			this.labelBuffer = this.labelBuffer.slice(0, -1);
-			return;
-		}
-		// Swallow other control sequences (arrows, etc.) so they do not end up
-		// in the label buffer.
-		if (data.length === 0) return;
-		// Accept printable chars (including multi-byte UTF-8 runs).
-		if (data.charCodeAt(0) < 0x20) return;
-		this.labelBuffer += data;
+		this.labelInput.handleInput(data);
+		this.labelBuffer = this.labelInput.getValue();
 	}
 
 	private setStatus(status: string, kind: "info" | "error" = "info"): void {

package/src/interactive/permission-hint.ts

@@ -14,6 +14,12 @@ export const MUTATION_PREVIEW_KEY = "v";
  */
 export type PermissionInspectionHint = "none" | "closed" | "open";
 
+/** The key that folds and unfolds the standing approval terms on the card. */
+export const PERMISSION_TERMS_KEY = "?";
+
+/** Whether the terms are open. The composer rail never shows this key, so it defaults closed there. */
+export type PermissionTermsHint = "closed" | "open";
+
 /**
  * The keys that answer a parked call, as data, so the dialog footer and the
  * composer rail render the same policy at any width.
@@ -46,11 +52,18 @@ export type PermissionInspectionHint = "none" | "closed" | "open";
 export function permissionHintEntries(
 	composerHasDraft = false,
 	inspection: PermissionInspectionHint = "none",
+	terms?: PermissionTermsHint,
 ): HintEntry[] {
 	return [
 		composerHasDraft
 			? { key: "Backspace", verb: "clear the draft to allow", short: "clear draft", critical: true }
 			: { key: "Enter", verb: "allow once", short: "allow", critical: true },
+		// The terms key is the card's own and the most droppable entry: the folded
+		// card already states what the keys do in one row. It sits before the
+		// inspect key so the narrowing drops it first.
+		...(terms === undefined
+			? []
+			: [{ key: PERMISSION_TERMS_KEY, verb: terms === "open" ? "hide terms" : "terms", short: "terms", critical: false }]),
 		...(inspection === "none"
 			? []
 			: inspection === "open"

package/src/interactive/permission-overlay.ts

@@ -15,12 +15,24 @@ import {
 	mutationPreviewWindow,
 } from "./mutation-preview.js";
 import { fitHintEntries } from "./overlay-frame.js";
-import { MUTATION_PREVIEW_KEY, type PermissionInspectionHint, permissionHintEntries } from "./permission-hint.js";
+import {
+	MUTATION_PREVIEW_KEY,
+	PERMISSION_TERMS_KEY,
+	type PermissionInspectionHint,
+	type PermissionTermsHint,
+	permissionHintEntries,
+} from "./permission-hint.js";
 import type { ClioToken } from "./theme/index.js";
 
 export { type AskAxis, askAxis } from "../domains/safety/approval-axis.js";
 export { describeCallTarget, sanitizeCallTargetText } from "../domains/safety/call-target.js";
-export { MUTATION_PREVIEW_KEY, type PermissionInspectionHint, permissionHintEntries } from "./permission-hint.js";
+export {
+	MUTATION_PREVIEW_KEY,
+	PERMISSION_TERMS_KEY,
+	type PermissionInspectionHint,
+	type PermissionTermsHint,
+	permissionHintEntries,
+} from "./permission-hint.js";
 
 export interface ApprovalRequestView {
 	requestId: string;
@@ -106,12 +118,16 @@ export interface PermissionOverlayBodyHandle extends Component {
 	isInspecting(): boolean;
 	toggleInspect(): void;
 	scrollInspect(delta: number): void;
+	/** The standing approval terms, folded behind `?` (see `permissionOverlayLines`). */
+	isShowingTerms(): boolean;
+	toggleTerms(): void;
 }
 
 class PermissionOverlayBody implements PermissionOverlayBodyHandle {
 	private preview: MutationPreview | null = null;
 	private scroll = 0;
 	private lastLineCount = 0;
+	private terms = false;
 
 	constructor(
 		private readonly view: ApprovalRequestView,
@@ -143,8 +159,16 @@ class PermissionOverlayBody implements PermissionOverlayBodyHandle {
 		this.scroll = Math.max(0, Math.min(this.scroll + delta, maxScroll));
 	}
 
+	isShowingTerms(): boolean {
+		return this.terms;
+	}
+
+	toggleTerms(): void {
+		this.terms = !this.terms;
+	}
+
 	render(width: number): string[] {
-		if (this.preview === null) return permissionOverlayLines(this.view, width);
+		if (this.preview === null) return permissionOverlayLines(this.view, width, this.terms);
 		const rendered = permissionInspectionLines(this.view, this.preview, width, this.scroll);
 		this.lastLineCount = rendered.wrappedLineCount;
 		return rendered.lines;
@@ -153,13 +177,18 @@ class PermissionOverlayBody implements PermissionOverlayBodyHandle {
 	invalidate(): void {}
 }
 
-function truncate(value: string, max: number): string {
-	return value.length <= max ? value : `${value.slice(0, Math.max(0, max - 1))}…`;
-}
-
-/** `label: value`, with the value ellipsized to what the box actually has. */
-function field(label: string, value: string, width: number): string {
-	return `${label}${truncate(value, Math.max(1, width - label.length))}`;
+/**
+ * `label: value`, folded under the label rather than ellipsized.
+ *
+ * The target used to end in an ellipsis at the box edge, so a deep path lost
+ * its file name, which is the one token that says what the write touches. The
+ * value now wraps at spaces and hard-folds a token longer than the row, and a
+ * continuation row hangs under the value's first column.
+ */
+function field(label: string, value: string, width: number): string[] {
+	const indent = " ".repeat(label.length);
+	const rows = wrapSentence(value, Math.max(1, width - label.length));
+	return rows.map((row, index) => `${index === 0 ? label : indent}${row}`);
 }
 
 /**
@@ -235,8 +264,9 @@ export function permissionOverlayHint(
 	innerWidth: number,
 	composerHasDraft = false,
 	inspection: PermissionInspectionHint = "none",
+	terms: PermissionTermsHint = "closed",
 ): string {
-	return fitHintEntries(permissionHintEntries(composerHasDraft, inspection), innerWidth - 3);
+	return fitHintEntries(permissionHintEntries(composerHasDraft, inspection, terms), innerWidth - 3);
 }
 
 /** The tools whose parked call mutates a file, so a card without a preview owes the operator a reason. */
@@ -287,8 +317,8 @@ function permissionInspectionLines(
 	if (preview.neutralized) notes.push("control characters shown as ·");
 	if (preview.tabsExpanded) notes.push("tabs shown as spaces");
 	const lines = [
-		field("Tool: ", `${view.tool} · Action: ${view.actionClass}`, content),
-		...(view.target !== undefined && view.target.length > 0 ? [field("Target: ", view.target, content)] : []),
+		...field("Tool: ", `${view.tool} · Action: ${view.actionClass}`, content),
+		...(view.target !== undefined && view.target.length > 0 ? field("Target: ", view.target, content) : []),
 		...wrapSentence(`Mutation: ${mutationFactsLine(preview.facts)}`, content),
 		"",
 		...wrapSentence(preview.heading, content),
@@ -299,6 +329,16 @@ function permissionInspectionLines(
 	return { lines, wrappedLineCount: wrapped.length };
 }
 
+/**
+ * The one-row statement of what the three keys do, in the presentation's own
+ * words, so the folded card still says what allow, deny, and stop mean.
+ */
+function termsSummary(presentation: DecisionPresentation, actionClass: string): string {
+	const stop = presentation.requiredActions.find((action) => action.id === "stop");
+	const stopWords = stop?.consequence.includes("main-agent turn") ? "ends the main-agent turn" : "ends the turn";
+	return `Allow runs this one ${actionClass} call and leaves the autonomy level alone. Deny skips it. Stop ${stopWords}. Press ${PERMISSION_TERMS_KEY} for the full terms.`;
+}
+
 /**
  * The overlay's body, laid out for the width the frame gives it.
  *
@@ -306,8 +346,14 @@ function permissionInspectionLines(
  * rest, so a 40-column terminal saw the safety sentences end mid-word and an
  * 80-column one saw the command being authorized end mid-argument, both with
  * nothing marking the cut.
+ *
+ * Seven of the card's thirteen rows were then the same on every call: the
+ * approval, consequence, reversibility, deny, stop, and hard-block sentences.
+ * They are the terms of the decision, not the decision, so they fold behind
+ * `?` and the card leads with what changes per call: the tool, the target in
+ * full, the mutation facts, and who asked.
  */
-function permissionOverlayLines(view: ApprovalRequestView, width: number): string[] {
+function permissionOverlayLines(view: ApprovalRequestView, width: number, terms = false): string[] {
 	const content = Math.max(8, Math.floor(width));
 	const presentation = permissionDecisionPresentation(view);
 	// The parked call is awaiting a decision, not blocked: the raw rejection
@@ -315,19 +361,18 @@ function permissionOverlayLines(view: ApprovalRequestView, width: number): strin
 	// wording contradicts the ask. Tool, Target, Action, and the asking axis
 	// carry everything the operator needs to decide.
 	const lines = [
-		field("Tool: ", `${view.tool} · Action: ${view.actionClass}`, content),
-		...(view.target !== undefined && view.target.length > 0 ? [field("Target: ", view.target, content)] : []),
+		...field("Tool: ", `${view.tool} · Action: ${view.actionClass}`, content),
+		...(view.target !== undefined && view.target.length > 0 ? field("Target: ", view.target, content) : []),
 		// Size and digest stay on the collapsed card whether or not the operator
 		// opens the mutation, so the decision always carries the identity of the
-		// bytes it applies to.
-		// Wrapped, never ellipsized: at 40 columns the digest is the tail of the
-		// line, and ellipsizing it would drop the one fact that ties the decision
-		// to the bytes it applies to.
+		// bytes it applies to. Wrapped, never ellipsized: at 40 columns the digest
+		// is the tail of the line, and ellipsizing it would drop the one fact that
+		// ties the decision to the bytes it applies to.
 		...(view.mutation !== undefined
-			? [
-					...wrapSentence(`Mutation: ${mutationFactsLine(view.mutation)}`, content),
-					...wrapSentence(`Press ${MUTATION_PREVIEW_KEY} to read it before deciding.`, content),
-				]
+			? wrapSentence(
+					`Mutation: ${mutationFactsLine(view.mutation)} · press ${MUTATION_PREVIEW_KEY} to read it before deciding`,
+					content,
+				)
 			: []),
 		...(view.mutation === undefined && view.origin.kind === "worker" && isFileMutationTool(view.tool)
 			? wrapSentence(
@@ -336,6 +381,7 @@ function permissionOverlayLines(view: ApprovalRequestView, width: number): strin
 				)
 			: []),
 		...wrapSentence(`Requested by: ${presentation.requestedByCopy}`, content),
+		...(view.queueDepth !== undefined && view.queueDepth > 1 ? [`1 of ${view.queueDepth} parked`] : []),
 		...(view.artifact !== undefined
 			? [
 					"",
@@ -344,16 +390,19 @@ function permissionOverlayLines(view: ApprovalRequestView, width: number): strin
 				]
 			: []),
 		"",
+	];
+	if (!terms) {
+		lines.push(...wrapSentence(termsSummary(presentation, view.actionClass), content));
+		return lines;
+	}
+	lines.push(
 		...wrapSentence(`Approval: ${presentation.authorizationCopy}`, content),
 		...wrapSentence(`Consequence: ${presentation.consequenceCopy}`, content),
 		...wrapSentence(presentation.reversibilityCopy, content),
 		...wrapSentence(`Deny: ${actionConsequence(presentation, "deny")}`, content),
 		...wrapSentence(`Stop: ${actionConsequence(presentation, "stop")}`, content),
 		...wrapSentence("Hard-blocked actions remain blocked.", content),
-	];
-	if (view.queueDepth !== undefined && view.queueDepth > 1) {
-		lines.splice(lines.indexOf(""), 0, `1 of ${view.queueDepth} parked`);
-	}
+	);
 	return lines;
 }
 

package/src/interactive/prompt-source-label.ts

@@ -0,0 +1,21 @@
+import type { ResourceSourceInfo } from "../domains/resources/collision.js";
+
+/**
+ * The package a prompt came from, in the words the operator installed it by.
+ * A plugin root's source is `plugin:<scope>:<id>`; the rest are Clio's own
+ * roots and the foreign roots it reads, which carry the agent kind and scope.
+ * A leaf on purpose: the slash registry names the source in a card and must
+ * stay off the render graph.
+ */
+export function promptSourceLabel(sourceInfo: Pick<ResourceSourceInfo, "source" | "scope">): string {
+	const source = sourceInfo.source;
+	if (source === undefined) return `${sourceInfo.scope} prompts`;
+	const plugin = /^plugin:(?:[^:]+):(.+)$/u.exec(source);
+	if (plugin?.[1]) return `plugin ${plugin[1]}`;
+	if (source === "config") return "user prompts";
+	if (source === "project") return "project prompts";
+	if (source === "library") return "library";
+	const foreign = /^([a-z0-9-]+)-(user|project)$/u.exec(source);
+	if (foreign?.[1] && foreign[2]) return `${foreign[1]} ${foreign[2]} prompts`;
+	return source;
+}

package/src/interactive/renderers/preview.ts

@@ -0,0 +1,16 @@
+import { truncateToWidth } from "../../engine/tui.js";
+import { clioTheme } from "../theme/index.js";
+
+/** Count terminal rows after wrapping, including the inspection hint. */
+export function previewRows(rows: readonly string[], limit: number, width: number, tail = false): string[] {
+	if (rows.length <= limit) return [...rows];
+	if (limit <= 0) return [];
+	const count = Math.max(0, limit - 1);
+	const hint = clioTheme().fg("dim", truncateToWidth(`… ${rows.length - count} rows · /view`, Math.max(1, width)));
+	return tail ? [hint, ...rows.slice(rows.length - count)] : [...rows.slice(0, count), hint];
+}
+
+/** Leave room for the composer and action identity in a short terminal. */
+export function previewBudget(limit: number, terminalRows = 40): number {
+	return Math.min(limit, Math.max(2, Math.floor((terminalRows - 8) / 2)));
+}

package/src/interactive/renderers/reference-card.ts

@@ -0,0 +1,35 @@
+import { wrapTextWithAnsi } from "../../engine/tui.js";
+import type { PromptReferenceCard } from "../slash-commands.js";
+import { clioTheme, GLYPH } from "../theme/index.js";
+
+/** Matches the transcript's prose gutter so the card's body aligns with turns. */
+const CARD_GUTTER = "  ";
+const TAB_WIDTH = 4;
+
+/**
+ * An operator card: a header naming the command and where it came from, then
+ * the body wrapped to the width with nothing cut. Box-drawing rows that outrun
+ * the width fold onto a second row rather than losing their tail, which is the
+ * one rendering rule the card exists for: the words that carry the information
+ * are at the ends of the sentences.
+ */
+export function renderReferenceCard(card: PromptReferenceCard, width: number): string[] {
+	const theme = clioTheme();
+	const safeWidth = Math.max(8, width);
+	const header = `${theme.fg("dim", GLYPH.user)} ${theme.style("title", `/${card.command}`, { bold: true })}  ${theme.fg(
+		"dim",
+		`reference · ${card.source}`,
+	)}`;
+	const lines = wrapTextWithAnsi(header, safeWidth);
+	const bodyWidth = Math.max(4, safeWidth - CARD_GUTTER.length);
+	for (const raw of card.text.split("\n")) {
+		const expanded = raw.replace(/\t/g, " ".repeat(TAB_WIDTH)).trimEnd();
+		if (expanded.length === 0) {
+			lines.push("");
+			continue;
+		}
+		for (const wrapped of wrapTextWithAnsi(expanded, bodyWidth)) lines.push(`${CARD_GUTTER}${wrapped}`);
+	}
+	lines.push("");
+	return lines;
+}