@oh-my-pi/pi-tui 18.3.1 → 18.3.3

package/src/overlays/rewind-selector.ts

@@ -19,12 +19,15 @@
  *
  * Keys: Up/Down step through rendered items in transcript order (within the
  * active column when a strip is open), Left/Right slide between branch
- * variants at a fork and jump between user turns elsewhere, Enter rewinds to
- * the outlined item, Esc cancels.
+ * variants at a fork and jump between user turns elsewhere, `f` opens a
+ * filter (typing narrows the current path to matching items; Esc leaves the
+ * filter with the selection kept), Enter rewinds to the outlined item, Esc
+ * cancels.
  */
 import type { AgentTool } from "@oh-my-pi/pi-agent-core";
 import {
 	type Component,
+	extractPrintableText,
 	matchesKey,
 	padding,
 	routeSgrMouseInput,
@@ -39,6 +42,9 @@ import { matchesAppToolsExpand, matchesSelectCancel, matchesSelectDown, matchesS
 import { ChatTranscriptBuilder } from "../chat/chat-transcript-builder";
 import { TranscriptBrowser, type TranscriptBrowserFrame } from "../chat/transcript-browser";
 import { padToWidth } from "../render/utils";
+import { expandKeyHint } from "../render/render-utils";
+import { formatKeyHint, formatKeyHints } from "../app-keybindings";
+import { editorKey, editorKeys } from "../chrome/keybinding-hints";
 import {
 	appendOutlineEntries,
 	type ComposedColumn,
@@ -110,6 +116,13 @@ export class RewindSelectorComponent implements Component {
 	#slide: { from: number; to: number; startedAt: number } | undefined;
 	#slideTimer: NodeJS.Timeout | undefined;
 
+	/** Filter query while the filter prompt is open; undefined shows the full transcript. */
+	#filter: string | undefined;
+	/** Main transcript rows from the last frame; the filter matches what is on screen. */
+	#mainRows: readonly (readonly string[])[] = [];
+	/** Lowercased plain text per rendered child row array (row arrays are cached, so identity is stable). */
+	#rowText = new WeakMap<readonly string[], string>();
+
 	constructor(
 		entries: TranscriptEntry[],
 		private readonly deps: RewindSelectorDeps,
@@ -235,19 +248,26 @@ export class RewindSelectorComponent implements Component {
 			});
 			return;
 		}
+		if (this.#filter !== undefined) {
+			this.#handleFilterInput(data);
+			return;
+		}
 		if (matchesSelectCancel(data) || matchesKey(data, "escape")) {
 			this.deps.onCancel();
 			return;
 		}
-		if (matchesAppToolsExpand(data)) {
-			this.#expanded = !this.#expanded;
-			this.#builder.setExpanded(this.#expanded);
-			for (const columns of this.#variantCache.values()) {
-				for (const column of columns) column.builder.setExpanded(this.#expanded);
-			}
+		if (matchesKey(data, "f")) {
+			this.#filter = "";
+			this.#activeVariant = 0;
+			this.#siblingSelected = 0;
+			this.#stopSlide();
 			this.deps.requestRender();
 			return;
 		}
+		if (matchesAppToolsExpand(data)) {
+			this.#toggleExpanded();
+			return;
+		}
 		if (matchesSelectUp(data)) {
 			this.#moveVertical(-1);
 			return;
@@ -282,6 +302,115 @@ export class RewindSelectorComponent implements Component {
 		}
 	}
 
+	#toggleExpanded(): void {
+		this.#expanded = !this.#expanded;
+		this.#builder.setExpanded(this.#expanded);
+		for (const columns of this.#variantCache.values()) {
+			for (const column of columns) column.builder.setExpanded(this.#expanded);
+		}
+		this.deps.requestRender();
+	}
+
+	// ========================================================================
+	// Filter
+	// ========================================================================
+
+	#handleFilterInput(data: string): void {
+		if (matchesSelectCancel(data) || matchesKey(data, "escape")) {
+			this.#closeFilter();
+			return;
+		}
+		if (matchesKey(data, "enter") || matchesKey(data, "return") || data === "\n") {
+			const target = this.#filterMatches().includes(this.#selected) ? this.#targets[this.#selected] : undefined;
+			if (target) this.deps.onSelect(target.entryId);
+			return;
+		}
+		if (matchesAppToolsExpand(data)) {
+			this.#toggleExpanded();
+			return;
+		}
+		if (matchesSelectUp(data) || matchesKey(data, "left")) {
+			const userTurnsOnly = !matchesSelectUp(data);
+			this.#stepFiltered(-1, userTurnsOnly);
+			return;
+		}
+		if (matchesSelectDown(data) || matchesKey(data, "right")) {
+			const userTurnsOnly = !matchesSelectDown(data);
+			this.#stepFiltered(1, userTurnsOnly);
+			return;
+		}
+		if (matchesKey(data, "backspace")) {
+			if (this.#filter!.length === 0) {
+				this.#closeFilter();
+				return;
+			}
+			this.#setFilter(this.#filter!.slice(0, -1));
+			return;
+		}
+		const printable = extractPrintableText(data);
+		if (printable) {
+			this.#setFilter(this.#filter! + printable);
+			return;
+		}
+		if (this.#browser.handleScrollKey(data)) {
+			this.deps.requestRender();
+		}
+	}
+
+	/** Leave the filter, keeping the selected item outlined in the full transcript. */
+	#closeFilter(): void {
+		this.#filter = undefined;
+		this.deps.requestRender();
+	}
+
+	/** Update the query; keep the selection when it still matches, else rest on the newest match above it. */
+	#setFilter(query: string): void {
+		this.#filter = query;
+		const matches = this.#filterMatches();
+		if (!matches.includes(this.#selected)) {
+			this.#selected = matches.findLast(index => index < this.#selected) ?? matches.at(-1) ?? this.#selected;
+		}
+		this.deps.requestRender();
+	}
+
+	#stepFiltered(delta: -1 | 1, userTurnsOnly: boolean): void {
+		const matches = this.#filterMatches().filter(index => !userTurnsOnly || this.#targets[index]!.isUserTurn);
+		const next =
+			delta < 0 ? matches.findLast(index => index < this.#selected) : matches.find(index => index > this.#selected);
+		if (next === undefined) return;
+		this.#selected = next;
+		this.deps.requestRender();
+	}
+
+	/**
+	 * Visible main-path target indices whose rendered text contains every
+	 * whitespace-separated query word as a whole word (case-insensitive: `ls`
+	 * matches `ls -la` but not `tools`); all visible targets for an empty query.
+	 * Matching the rendered rows keeps results honest: collapsed tool output
+	 * only matches once Ctrl+O expands it.
+	 */
+	#filterMatches(): number[] {
+		const words = (this.#filter ?? "").toLowerCase().split(/\s+/).filter(Boolean);
+		const patterns = words.map(
+			word => new RegExp(`(?<![\\p{L}\\p{N}_])${RegExp.escape(word)}(?![\\p{L}\\p{N}_])`, "u"),
+		);
+		const matches: number[] = [];
+		for (let index = 0; index < this.#targets.length; index++) {
+			if (!this.#isMainSelectable(index)) continue;
+			const target = this.#targets[index]!;
+			const texts = this.#mainRows.slice(target.start, target.end).map(rows => {
+				let text = this.#rowText.get(rows);
+				if (text === undefined) {
+					text = Bun.stripANSI(rows.join("\n")).toLowerCase();
+					this.#rowText.set(rows, text);
+				}
+				return text;
+			});
+			if (patterns.every(pattern => texts.some(text => pattern.test(text)))) matches.push(index);
+		}
+		return matches;
+	}
+
 	/** Up/Down: step within the active column; leaving a sibling column's top exits the strip. */
 	#moveVertical(delta: -1 | 1): void {
 		if (this.#activeVariant > 0) {
@@ -337,6 +466,7 @@ export class RewindSelectorComponent implements Component {
 		const children = this.#builder.container.children;
 		const prepared = this.#browser.prepareOutline(children, this.#targets, this.#selected, contentWidth);
 		this.#mainVisible = prepared.visible;
+		this.#mainRows = prepared.childRows;
 		if (prepared.selected !== this.#selected) {
 			// The current target collapsed (e.g. expansion toggle): rest on the
 			// nearest visible one and leave the strip.
@@ -345,6 +475,8 @@ export class RewindSelectorComponent implements Component {
 			this.#siblingSelected = 0;
 		}
 
+		if (this.#filter !== undefined) return this.#filterFrame(this.#filter, prepared.childRows, contentWidth);
+
 		const columns = this.#stripColumns();
 		const composed =
 			columns.length > 0
@@ -357,16 +489,64 @@ export class RewindSelectorComponent implements Component {
 						prepared,
 					}).column;
 		const position = this.#targets.length > 0 ? `${this.#selected + 1}/${this.#targets.length}  ` : "";
-		const lateral = columns.length > 0 ? "←/→ branches" : "←/→ user turns";
+		const upDown = editorKeys("tui.select.up", "tui.select.down");
+		const leftRight = formatKeyHints(["left", "right"]);
+		const lateral = columns.length > 0 ? `${leftRight} branches` : `${leftRight} user turns`;
+		const keys = `${upDown} step  ${lateral}  ${formatKeyHint("f")} filter  ${formatKeyHint("enter")} rewind  ${expandKeyHint()} expand  ${editorKey("tui.select.cancel")} cancel`;
 		return {
-			header: [
-				`${theme.icon.rewind} ${theme.bold("Rewind")}${theme.sep.dot}${theme.fg("dim", "pick the point to continue from")}`,
-			],
+			header: [this.#header()],
 			body: {
 				lines: composed.lines,
 				anchor: this.#outlineAnchor(composed),
 			},
-			footer: [theme.fg("dim", `${position}↑/↓ step  ${lateral}  enter rewind  ctrl+o expand  esc cancel`)],
+			footer: [theme.fg("dim", `${position}${keys}`)],
+		};
+	}
+
+	#header(): string {
+		return `${theme.icon.rewind} ${theme.bold("Rewind")}${theme.sep.dot}${theme.fg("dim", "pick the point to continue from")}`;
+	}
+
+	/** Only the matching items of the current path, concatenated; no branch strip. */
+	#filterFrame(
+		query: string,
+		childRows: readonly (readonly string[])[],
+		contentWidth: number,
+	): TranscriptBrowserFrame {
+		const matches = this.#filterMatches();
+		const rows: (readonly string[])[] = [];
+		const targets: OutlineTarget[] = [];
+		for (const index of matches) {
+			const target = this.#targets[index]!;
+			const start = rows.length;
+			rows.push(...childRows.slice(target.start, target.end));
+			targets.push({ ...target, start, end: rows.length });
+		}
+		const selected = matches.indexOf(this.#selected);
+		const composed = composeOutlineColumn(rows, 0, rows.length, targets, selected, contentWidth, undefined);
+		const lines = matches.length > 0 ? composed.lines : [theme.fg("muted", `  No items match "${query}"`)];
+		const count =
+			matches.length === 0
+				? theme.fg("error", "no matches")
+				: theme.fg("dim", `${selected >= 0 ? selected + 1 : "-"}/${matches.length}`);
+		const upDown = editorKeys("tui.select.up", "tui.select.down");
+		const keys = `${upDown} step  ${formatKeyHints(["left", "right"])} user turns  ${formatKeyHint("enter")} rewind  ${editorKey("tui.select.cancel")} show all`;
+		return {
+			header: [this.#header()],
+			body: {
+				lines,
+				anchor:
+					composed.selStart >= 0
+						? {
+								id: `rewind:filter:${query}:${this.#targets[this.#selected]?.turnId ?? this.#selected}`,
+								start: composed.selStart,
+								end: composed.selEnd,
+							}
+						: undefined,
+			},
+			footer: [
+				`${theme.fg("accent", "filter:")} ${query}${theme.fg("accent", "▏")}  ${count}  ${theme.fg("dim", keys)}`,
+			],
 		};
 	}
 

package/src/overlays/session-info-overlay.ts

@@ -2,8 +2,8 @@ import { type Component, Ellipsis, matchesKey, ScrollView, Text, truncateToWidth
 import { theme } from "../theme/theme";
 import { matchesSelectCancel } from "../keybinding-matchers";
 import { OverlayPanel, PanelDivider, PanelRows } from "../chrome/overlay-box";
-
-const FOOTER_HINT = "↑/↓ scroll · Esc close";
+import { formatKeyHints } from "../app-keybindings";
+import { editorKey } from "../chrome/keybinding-hints";
 const PANEL_CHROME_ROWS = 4;
 
 /** Terminal surface needed to size the session info viewport. */
@@ -74,7 +74,8 @@ export class SessionInfoOverlay implements Component {
 
 	render(width: number): readonly string[] {
 		const innerWidth = Math.max(1, width - 4);
-		this.#footer.setLines([theme.fg("dim", truncateToWidth(FOOTER_HINT, innerWidth))]);
+		const footerHint = `${formatKeyHints(["up", "down"])} scroll · ${editorKey("tui.select.cancel")} close`;
+		this.#footer.setLines([theme.fg("dim", truncateToWidth(footerHint, innerWidth))]);
 
 		const maxBodyHeight = Math.max(1, this.#host.terminal.rows - PANEL_CHROME_ROWS);
 		const fullWidthInfoLines = this.#info.render(innerWidth);

package/src/overlays/session-selector.ts

@@ -38,6 +38,8 @@ import { shortenPath } from "../render/render-utils";
 import { HookSelectorComponent } from "./hook-selector";
 import { bottomBorder, OverlayPanel, row, topBorder } from "../chrome/overlay-box";
 import { MenuSelection, getMenuWindow } from "../components/menu-selection";
+import { formatKeyHint, formatKeyHints } from "../app-keybindings";
+import { interruptKey } from "../chrome/keybinding-hints";
 
 /**
  * Themed glyph + colored label for a session's lifecycle status, or `undefined`
@@ -615,7 +617,10 @@ class SessionList<T extends SessionSelectorEntry> implements Component {
 			} else {
 				// "Current folder" scope - hint to try "all"
 				lines.push(
-					truncateToWidth(theme.fg("muted", "No sessions in current folder. Press Tab to view all."), width),
+					truncateToWidth(
+						theme.fg("muted", `No sessions in current folder. Press ${formatKeyHint("tab")} to view all.`),
+						width,
+					),
 				);
 			}
 			return lines;
@@ -1094,7 +1099,12 @@ export class SessionSelectorComponent<T extends SessionSelectorEntry = SessionSe
 	/** Blank · keybinding hint · bottom border. Rendered by {@link render}. */
 	#footerLines(width: number): string[] {
 		const scopeHint = this.#scope === "all" ? "current folder" : "all projects";
-		const hint = theme.fg("muted", `[Del/⌫ delete · Enter select · Tab ${scopeHint} · Esc cancel]`);
+		// Keys mirror SessionList#handleInput; cancel is `app.interrupt` (raw Escape when unbound).
+		const cancel = interruptKey();
+		const hint = theme.fg(
+			"muted",
+			`[${formatKeyHints(["delete", "backspace"])} delete · ${formatKeyHint("enter")} select · ${formatKeyHint("tab")} ${scopeHint} · ${cancel} cancel]`,
+		);
 		return [row("", width), row(hint, width), row("", width), bottomBorder(width)];
 	}
 

package/src/overlays/settings-selector.ts

@@ -48,6 +48,8 @@ import { SnapcompactShapePreview } from "./snapcompact-shape-preview";
 import { getPreset } from "../status-line/presets";
 import { FormField, SelectFormField, TextFormField } from "../components/form";
 import { formTheme } from "../chrome/form-theme";
+import { formatKeyHint, formatKeyHints } from "../app-keybindings";
+import { editorKey, editorKeys } from "../chrome/keybinding-hints";
 
 /**
  * Free-text string setting field backed by the shared text form field.
@@ -70,7 +72,7 @@ function createSettingsTextField(
 		secret,
 		initialValue: currentValue || undefined,
 		empty: "submit",
-		hint: "  Enter to save · Esc to cancel · Clear field to unset",
+		hint: `  ${editorKey("tui.input.submit")} to save · ${editorKey("tui.select.cancel")} to cancel · Clear field to unset`,
 		onSubmit,
 		onCancel,
 		requestRender,
@@ -106,7 +108,7 @@ function createSettingsSelectField(
 		onSelectionChange,
 		onSubmit: onSelect,
 		onCancel,
-		hint: "  Enter to select · Esc to go back",
+		hint: `  ${editorKey("tui.select.confirm")} to select · ${editorKey("tui.select.cancel")} to go back`,
 		footer,
 		requestRender,
 	});
@@ -172,9 +174,10 @@ class MultiSelectSubmenu extends Container {
 			this.#cursor = this.#options.findIndex(option => option.value === item.value);
 		};
 		this.#selectList.onCancel = this.#onClose;
+		const back = `${editorKey("tui.select.cancel")} to go back`;
 		const hint = this.#ordered
-			? "  Click to toggle · drag selected items to reorder · ←/→ move · 1-9 place · Esc to go back"
-			: "  Click/Enter/Space to toggle · Esc to go back";
+			? `  Click to toggle · drag selected items to reorder · ${formatKeyHints(["left", "right"])} move · 1-9 place · ${back}`
+			: `  Click/${editorKey("tui.select.confirm")}/${formatKeyHint("space")} to toggle · ${back}`;
 		this.#field = new FormField(this.#selectList, {
 			theme: formTheme,
 			label: this.#title,
@@ -340,7 +343,7 @@ class ProviderLimitsSubmenu extends Container {
 			items,
 			maxVisible: 12,
 			selectTheme: getSelectListTheme(),
-			hint: "  Enter to edit provider · Esc to go back",
+			hint: `  ${editorKey("tui.select.confirm")} to edit provider · ${editorKey("tui.select.cancel")} to go back`,
 			onSubmit: value => {
 				if (value === "__clear_all") {
 					this.#settings.set("providers.maxInFlightRequests", {});
@@ -369,7 +372,7 @@ class ProviderLimitsSubmenu extends Container {
 					"Enter a positive number. Decimals round down. Clear the field to make this provider unlimited.",
 				initialValue: limits[provider]?.toString() ?? undefined,
 				empty: "submit",
-				hint: "  Enter to save · Esc to cancel · Clear field to unset",
+				hint: `  ${editorKey("tui.input.submit")} to save · ${editorKey("tui.select.cancel")} to cancel · Clear field to unset`,
 				validate: value => {
 					if (value.trim() === "") return undefined;
 					const limit = Number(value.trim());
@@ -567,17 +570,21 @@ export class SettingsSelectorComponent implements Component {
 	}
 
 	#footerHintText(): string {
+		const confirm = editorKey("tui.select.confirm");
+		const cancel = editorKey("tui.select.cancel");
+		const tab = formatKeyHint("tab");
+		const switchTabs = `${formatKeyHints(["left", "right"])} to switch tabs`;
 		if (this.#searchList) {
-			return "Enter to change · Tab to jump tabs · Esc to exit search";
+			return `${confirm} to change · ${tab} to jump tabs · ${cancel} to exit search`;
 		}
 		if (this.#currentTabId === "plugins") {
-			return "Tab to switch tabs · Esc to close";
+			return `${tab} to switch tabs · ${cancel} to close`;
 		}
 		if (this.#currentList?.sectionFocused) {
-			return "↑/↓ to jump sections · Tab/Enter to settings · ←/→ to switch tabs · Esc to close";
+			return `${editorKeys("tui.select.up", "tui.select.down")} to jump sections · ${tab}/${confirm} to settings · ${switchTabs} · ${cancel} to close`;
 		}
-		const nav = this.#hasSectionJump ? "Tab to jump sections · ←/→ to switch tabs" : "Tab to switch tabs";
-		return `Enter/Space to change · ${nav} · Type to search · Esc to close`;
+		const nav = this.#hasSectionJump ? `${tab} to jump sections · ${switchTabs}` : `${tab} to switch tabs`;
+		return `${confirm}/${formatKeyHint("space")} to change · ${nav} · Type to search · ${cancel} to close`;
 	}
 
 	/** Single-line search banner: accent icon, editable query with live cursor, right-aligned match count. */

package/src/overlays/tree-selector.ts

@@ -55,6 +55,8 @@ import { canonicalizeMessage } from "../chat/thinking-display";
 import { resolveAssistantErrorPresentation } from "../chat/transcript-render-helpers";
 import { OverlayPanel, PanelDivider } from "../chrome/overlay-box";
 import { TreeView, type TreeRow } from "../components/tree-view";
+import { formatKeyHint, formatKeyHints } from "../app-keybindings";
+import { editorKeys, interruptKey } from "../chrome/keybinding-hints";
 
 /** Filter mode for tree display */
 type FilterMode = TreeFilterMode;
@@ -523,7 +525,9 @@ class TreeList implements Component {
 				lines.push(truncateToWidth(theme.fg("muted", `(0/0)${this.#getFilterLabel()}`), width));
 			} else if (this.#searchQuery.length > 0) {
 				lines.push(truncateToWidth(theme.fg("muted", `No entries match search "${this.#searchQuery}"`), width));
-				lines.push(truncateToWidth(theme.fg("muted", "Press Backspace to clear the search"), width));
+				lines.push(
+					truncateToWidth(theme.fg("muted", `Press ${formatKeyHint("backspace")} to clear the search`), width),
+				);
 				lines.push(truncateToWidth(theme.fg("muted", `(0/${totalCount})${this.#getFilterLabel()}`), width));
 			} else {
 				const filterLabel = this.#getFilterLabel().trim() || "[default]";
@@ -533,7 +537,15 @@ class TreeList implements Component {
 						width,
 					),
 				);
-				lines.push(truncateToWidth(theme.fg("muted", "Press Alt+A to show all, Alt+D for default"), width));
+				lines.push(
+					truncateToWidth(
+						theme.fg(
+							"muted",
+							`Press ${formatKeyHint("alt+a")} to show all, ${formatKeyHint("alt+d")} for default`,
+						),
+						width,
+					),
+				);
 				lines.push(truncateToWidth(theme.fg("muted", `(0/${totalCount})${this.#getFilterLabel()}`), width));
 			}
 			return lines;
@@ -1010,7 +1022,8 @@ class LabelInput implements Component {
 		const lines: string[] = [];
 		lines.push(truncateToWidth(theme.fg("muted", "Label (empty to remove):"), width));
 		lines.push(...this.#input.render(width));
-		lines.push(truncateToWidth(theme.fg("dim", "enter: save  esc: cancel"), width));
+		const cancel = interruptKey();
+		lines.push(truncateToWidth(theme.fg("dim", `${formatKeyHint("enter")}: save  ${cancel}: cancel`), width));
 		return lines;
 	}
 
@@ -1068,7 +1081,17 @@ export class TreeSelectorComponent extends OverlayPanel {
 			new TruncatedText(
 				theme.fg(
 					"muted",
-					"Enter: switch. Alt+↑/↓: previous/next turn. PgUp/PgDn (←/→): page. Home/End: first/last item. Shift+Enter: summarize & switch. Shift+L: label. Ctrl+O: filter. Alt+D/T/U/L/A: filter. Type to search",
+					[
+						`${formatKeyHint("enter")}: switch.`,
+						`${formatKeyHints(["alt+up", "alt+down"])}: previous/next turn.`,
+						`${editorKeys("tui.select.pageUp", "tui.select.pageDown")} (${formatKeyHints(["left", "right"])}): page.`,
+						`${formatKeyHints(["home", "end"])}: first/last item.`,
+						`${formatKeyHint("shift+enter")}: summarize & switch.`,
+						`${formatKeyHint("shift+l")}: label.`,
+						`${formatKeyHint("ctrl+o")}: filter.`,
+						`${formatKeyHints(["alt+d", "alt+t", "alt+u", "alt+l", "alt+a"])}: filter.`,
+						"Type to search",
+					].join(" "),
 				),
 				0,
 				0,

package/src/overlays/usage-dashboard.ts

@@ -38,6 +38,8 @@ import {
 	matchesSelectUp,
 } from "../keybinding-matchers";
 import { OverlayPanel, PanelDivider, PanelRows } from "../chrome/overlay-box";
+import { formatKeyHint } from "../app-keybindings";
+import { editorKey, editorKeys } from "../chrome/keybinding-hints";
 
 /** Local calendar-day activity consumed by the usage heatmap. */
 export interface DailyActivityPoint {
@@ -725,8 +727,12 @@ export class UsageDashboardComponent implements Component {
 		const checkedText = latestFetchedAt ? `checked ${formatDuration(this.#nowMs - latestFetchedAt)} ago` : "";
 		const title = this.#view === "detail" ? "Usage · Details" : "Usage";
 
-		const scrollHint = maxScroll > 0 ? "↑/↓ scroll · " : "";
-		const hint = this.#view === "detail" ? `${scrollHint}Esc back` : `${scrollHint}↵ details · Esc close`;
+		const scrollHint = maxScroll > 0 ? `${editorKeys("tui.select.up", "tui.select.down")} scroll · ` : "";
+		const cancel = editorKey("tui.select.cancel");
+		const hint =
+			this.#view === "detail"
+				? `${scrollHint}${cancel} back`
+				: `${scrollHint}${formatKeyHint("enter")} details · ${cancel} close`;
 		this.#panel.title = title;
 		this.#header.setLines([checkedText ? theme.fg("dim", checkedText) : ""]);
 		this.#body.setLines(contentSource.slice(this.#scroll, this.#scroll + contentRows));

package/src/prompt/composer-cache.ts

@@ -5,6 +5,7 @@ import { getComposerCacheDir } from "@oh-my-pi/pi-utils/dirs";
 import type { LspServerInfo, RecentSession } from "./welcome";
 import type { ComposerPreferences, ComposerStatusSnapshot } from "./composer";
 import type { SymbolPreset } from "../theme/theme";
+import { isWordCompletionMethod } from "./word-completion";
 
 const CACHE_VERSION = 1;
 const STATUS_CACHE_VERSION = 3;
@@ -204,7 +205,7 @@ function readUiState(file: string): { preferences: ComposerPreferences; theme: C
 		typeof imeSafeCursor !== "boolean" ||
 		typeof autocompleteMaxVisible !== "number" ||
 		typeof spellingTypoDetection !== "boolean" ||
-		typeof spellingAutocomplete !== "boolean" ||
+		!isWordCompletionMethod(spellingAutocomplete) ||
 		typeof spellingAutocorrect !== "boolean"
 	) {
 		return undefined;

package/src/prompt/composer-hints.ts

@@ -0,0 +1,75 @@
+/**
+ * Composer hints: the right-aligned placeholder shown in the empty composer to
+ * surface gestures that matter right now (e.g. background agents are running).
+ *
+ * Hints are checked in priority order; the first one that applies wins. A hint
+ * retires for good once the user has performed its gesture
+ * {@link ComposerHint.learnedAfter} times — the host records each use under the
+ * hint's id and reports counts through {@link ComposerHintContext.uses}.
+ *
+ * Add a hint by appending to {@link COMPOSER_HINTS}, extending
+ * {@link ComposerHintId}, and recording the gesture where it is handled.
+ */
+import { formatDoubleTap, formatKeyHint, type KeybindingsManager } from "../app-keybindings";
+import { theme } from "../theme/theme";
+
+/** Stable hint ids; persisted as usage-counter keys, so never rename one. */
+export type ComposerHintId = "agents" | "effort";
+
+/** Live state that hint conditions read. Built by the host on every render of the empty composer. */
+export interface ComposerHintContext {
+	/** Subagents currently running in the background. */
+	runningAgents: number;
+	/** The view is focused on a subagent session instead of the main one. */
+	focusedOnAgent: boolean;
+	/** The viewed session already has messages. */
+	conversationStarted: boolean;
+	keybindings: KeybindingsManager;
+	/** Times the user has performed the gesture a hint teaches. */
+	uses(id: ComposerHintId): number;
+}
+
+/** A gesture tip: `key` renders highlighted, `label` describes what it does. */
+export interface ComposerHint {
+	id: ComposerHintId;
+	/** Uses of the gesture after which the hint stops showing. */
+	learnedAfter: number;
+	/** Key and label when the hint applies, otherwise `undefined`. */
+	resolve(ctx: ComposerHintContext): { key: string; label: string } | undefined;
+}
+
+/** Registered hints, highest priority first. */
+export const COMPOSER_HINTS: readonly ComposerHint[] = [
+	{
+		// Matches the ←← gesture in the input controller, which opens the agent hub
+		// from the main session (in a focused view it hops to the parent instead).
+		id: "agents",
+		learnedAfter: 3,
+		resolve: ctx => {
+			if (ctx.runningAgents === 0 || ctx.focusedOnAgent) return undefined;
+			return {
+				key: formatDoubleTap("left"),
+				label: `to see ${ctx.runningAgents} running ${ctx.runningAgents === 1 ? "agent" : "agents"}`,
+			};
+		},
+	},
+	{
+		id: "effort",
+		learnedAfter: 3,
+		resolve: ctx => {
+			if (ctx.conversationStarted) return undefined;
+			const key = ctx.keybindings.getKeys("app.thinking.cycle")[0];
+			return key ? { key: formatKeyHint(key), label: "to change thinking effort" } : undefined;
+		},
+	},
+];
+
+/** Render the highest-priority applicable, not-yet-learned hint, if any. */
+export function resolveComposerHint(ctx: ComposerHintContext): string | undefined {
+	for (const hint of COMPOSER_HINTS) {
+		if (ctx.uses(hint.id) >= hint.learnedAfter) continue;
+		const resolved = hint.resolve(ctx);
+		if (resolved) return `${theme.fg("accent", resolved.key)} ${theme.fg("dim", theme.italic(resolved.label))}`;
+	}
+	return undefined;
+}

package/src/prompt/composer.ts

@@ -15,6 +15,7 @@ import {
 import { sliceWithWidth, truncateToWidth, visibleWidth } from "../utils";
 import { postmortem } from "@oh-my-pi/pi-utils";
 import { CustomEditor } from "./custom-editor";
+import type { WordCompletionMethod } from "./word-completion";
 import { type AnimationFrame, TranscriptContainer } from "../chrome/transcript-container";
 import { type LspServerInfo, type RecentSession, WelcomeComponent } from "./welcome";
 import { ensureThemeSync, getEditorTheme, theme } from "../theme/theme";
@@ -31,7 +32,7 @@ export interface ComposerPreferences {
 	readonly imeSafeCursor: boolean;
 	readonly autocompleteMaxVisible: number;
 	readonly spellingTypoDetection: boolean;
-	readonly spellingAutocomplete: boolean;
+	readonly spellingAutocomplete: WordCompletionMethod;
 	readonly spellingAutocorrect: boolean;
 }
 
@@ -45,7 +46,7 @@ export const COMPOSER_DEFAULTS: ComposerPreferences = {
 	imeSafeCursor: false,
 	autocompleteMaxVisible: 10,
 	spellingTypoDetection: true,
-	spellingAutocomplete: true,
+	spellingAutocomplete: "auto",
 	spellingAutocorrect: false,
 };