@hank-warren/pi-ask-user-question 0.2.2 → 0.4.0

package/README.md

@@ -4,8 +4,9 @@ A structured questionnaire the model can put to you when it would otherwise
 guess. Instead of a free-form "which do you prefer?" in chat, you get a dialog
 with numbered options, digit hotkeys, a typed-answer escape, and Tab-to-comment.
 
-> **v0.1** ships one question per call, single-select, no preview pane. See
-> [the spec](../../docs/specs/pi-ask-user-question.md) §14 for the road to v0.2.
+> **v0.3** ships 1-4 questions per call as cycleable tabs, single-select, with
+> an optional preview pane. See
+> [the spec](../../docs/specs/pi-ask-user-question.md) §14.
 
 ## Install
 
@@ -23,8 +24,28 @@ register a tool named `ask_user_question`.
 | `1`–`9` | Select that option immediately |
 | `↑` / `↓` | Move the highlight |
 | `Enter` | Confirm the highlighted option |
-| `Tab` | Attach a note to your choice, then `Enter` to send both |
-| `Esc` | Decline the question (or leave note/typed-answer mode) |
+| `n` | Attach a note to your choice, then `Enter` to send both |
+| `Tab` / `→` | Next question |
+| `Shift+Tab` / `←` | Previous question |
+| `Esc` | Decline the questionnaire (or leave note/typed-answer mode) |
+
+With several questions, each is a tab you can cycle through in any order;
+answering one jumps to the next unanswered question, and the call returns once
+every question has an answer. Cycling back and re-answering replaces that
+question's answer rather than recording a second one.
+
+## Previews
+
+An option may carry a `preview` field — markdown shown in a pane below the
+options while that option is highlighted. Use it for concrete artifacts worth
+comparing (ASCII mockups, code snippets, configuration variations), not for
+simple preference questions. The pane is stacked rather than side-by-side, and
+long previews are clipped with a `… N more lines` marker so the options always
+stay visible.
+
+**Why `n` and not `Tab` for notes?** Tab cycles questions here, matching
+`@juicesharp/rpiv-ask-user-question`. `pi-auto-permissions` approval prompts
+keep `Tab` for notes — they are single-question and have no tabs to cycle.
 
 Every question gets an appended **`Type something.`** row for a free-text
 answer. The model is not allowed to author that row itself — reserved labels

package/ask-user-question.ts

@@ -6,7 +6,7 @@
  * package replays cleanly. Only one of the two may be installed at a time.
  */
 
-import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { type ExtensionAPI, getMarkdownTheme } from "@earendil-works/pi-coding-agent";
 import {
 	ASK_USER_BLOCKED_EVENT,
 	ASK_USER_PROMPT_EVENT,
@@ -35,16 +35,19 @@ const ERROR_NO_UI = "Error: UI not available (running in non-interactive mode)";
 const ERROR_NO_CUSTOM_UI =
 	"Error: this client cannot render the questionnaire (custom UI is unavailable). The user never saw the questions — do NOT treat this as a decline. Ask the questions as plain chat text instead, without using this tool.";
 
-const DESCRIPTION = `Ask the user a structured question during execution. Use when you need to:
+const DESCRIPTION = `Ask the user one or more structured questions during execution. Use when you need to:
 1. Gather user preferences or requirements
 2. Clarify ambiguous instructions
 3. Get decisions on implementation choices as you work
 4. Offer choices to the user about what direction to take
 
+Preview feature:
+Use the optional \`preview\` field on an option when presenting a concrete artifact the user needs to compare visually: an ASCII mockup, a code snippet, a diagram or configuration variation. It renders as markdown in a pane below the options while that option is highlighted. Do not use it for simple preference questions where the label and description already say enough.
+
 Usage notes:
-- The user can pick an option with the number keys, type a custom answer via the automatically appended "Type something." row, attach a note to their choice with Tab, or press Esc to decline. Do NOT author "Other" or "Type something." labels yourself — reserved labels are rejected at runtime.
+- The user can pick an option with the number keys, type a custom answer via the automatically appended "Type something." row, attach a note to their choice by pressing n, or press Esc to decline. Do NOT author "Other" or "Type something." labels yourself — reserved labels are rejected at runtime.
 - If you recommend a specific option, make it the first option and add "(Recommended)" at the end of the label.
-- This version accepts exactly one question per call with 2-4 options.`;
+- Ask 1-4 questions per call, each with 2-4 options. Multiple questions render as tabs the user cycles with Tab; every question must be answered before the call returns. Group questions that belong to one decision rather than asking them in separate calls, but do not pad a single decision into several questions.`;
 
 function emitPrompt(pi: ExtensionAPI, params: AskUserParams): void {
 	const payload: AskUserPromptEventPayload = {
@@ -96,6 +99,9 @@ export function registerTool(pi: ExtensionAPI): void {
 						new QuestionnaireDialog({
 							session,
 							theme,
+							// Reuse pi's own markdown theme so previews match the
+							// transcript rather than inventing a second code style.
+							markdownTheme: getMarkdownTheme(),
 							done,
 							requestRender: () => tui.requestRender(),
 						}),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hank-warren/pi-ask-user-question",
-  "version": "0.2.2",
+  "version": "0.4.0",
   "description": "Structured questionnaire tool for Pi with numbered options, digit hotkeys and Tab-to-comment, composed from the shared permission-selector component.",
   "type": "module",
   "keywords": [
@@ -45,7 +45,7 @@
     "LICENSE"
   ],
   "dependencies": {
-    "@hank-warren/pi-permission-selector": "^0.2.0"
+    "@hank-warren/pi-permission-selector": "^0.3.2"
   },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": "*",

package/questionnaire.ts

@@ -2,9 +2,15 @@
  * Questionnaire session state — a plain mutable object, no reducer.
  *
  * @juicesharp/rpiv-ask-user-question spends ~1,500 lines on a Redux-style
- * reducer plus four selector modules for this. The state here is one question
- * index, one answer list, and a custom-answer buffer; a reducer would add
- * indirection without adding a single testable guarantee.
+ * reducer plus four selector modules for this. The state here is a cursor and
+ * a sparse answer array; a reducer would add indirection without adding a
+ * single testable guarantee.
+ *
+ * NAVIGATION MODEL. Questions are tabs, not a queue. The cursor moves freely
+ * (Tab / Shift+Tab, wrapping), answers are stored BY QUESTION INDEX so
+ * revisiting a question replaces its answer rather than appending a second
+ * one, and the questionnaire is complete only when every question has an
+ * answer. This mirrors the tab model of rpiv-ask-user-question.
  *
  * Pure: no pi imports, no rendering. The dialog drives it; tests drive it the
  * same way.
@@ -22,15 +28,19 @@ export interface SelectableRow {
 	value: string;
 	label: string;
 	description?: string;
+	/** Markdown shown in the preview pane while this row is highlighted. */
+	preview?: string;
 }
 
 export class QuestionnaireSession {
 	private readonly params: AskUserParams;
 	private index = 0;
-	private readonly answers: QuestionAnswer[] = [];
+	/** Sparse by design: `answers[i]` is undefined until question i is answered. */
+	private readonly answers: Array<QuestionAnswer | undefined>;
 
 	constructor(params: AskUserParams) {
 		this.params = params;
+		this.answers = new Array(params.questions.length).fill(undefined);
 	}
 
 	get questionIndex(): number {
@@ -45,16 +55,54 @@ export class QuestionnaireSession {
 		return this.params.questions[this.index];
 	}
 
-	/** True once every question has been answered. */
+	/** Move the cursor, wrapping at both ends. */
+	goTo(index: number): void {
+		if (this.total === 0) return;
+		this.index = ((index % this.total) + this.total) % this.total;
+	}
+
+	next(): void {
+		this.goTo(this.index + 1);
+	}
+
+	previous(): void {
+		this.goTo(this.index - 1);
+	}
+
+	/** True once every question has an answer. */
 	isComplete(): boolean {
-		return this.index >= this.total;
+		return this.answers.every((answer) => answer !== undefined);
+	}
+
+	isAnswered(index: number): boolean {
+		return this.answers[index] !== undefined;
+	}
+
+	answeredCount(): number {
+		return this.answers.filter((answer) => answer !== undefined).length;
+	}
+
+	/**
+	 * Move to the next question without an answer, searching forward from the
+	 * cursor and wrapping. Returns false when everything is answered, which the
+	 * dialog treats as "submit".
+	 */
+	advanceToUnanswered(): boolean {
+		for (let step = 1; step <= this.total; step++) {
+			const candidate = (this.index + step) % this.total;
+			if (!this.isAnswered(candidate)) {
+				this.index = candidate;
+				return true;
+			}
+		}
+		return false;
 	}
 
 	/**
 	 * Rows for the current question: the authored options plus the appended
 	 * custom-answer sentinel. The sentinel is never an authored option — it is
-	 * added here and stripped in `recordAnswer`, which is why validation
-	 * rejects models that try to author it themselves.
+	 * added here and stripped when recording, which is why validation rejects
+	 * models that try to author it themselves.
 	 */
 	rows(): SelectableRow[] {
 		const question = this.current;
@@ -63,6 +111,7 @@ export class QuestionnaireSession {
 			value: option.label,
 			label: option.label,
 			description: option.description,
+			...(option.preview ? { preview: option.preview } : {}),
 		}));
 		rows.push({ value: CUSTOM_ANSWER_VALUE, label: CUSTOM_ANSWER_LABEL });
 		return rows;
@@ -74,23 +123,38 @@ export class QuestionnaireSession {
 	}
 
 	/**
-	 * Record an answer for the current question and advance. `custom` marks a
-	 * typed free-text answer; `notes` is the Tab-to-comment note.
+	 * Record (or replace) the answer for the current question. Replacement is
+	 * the point: cycling back to a question and picking again must not leave
+	 * two answers for one question in the envelope.
 	 */
 	recordAnswer(answer: string, opts: { custom?: boolean; notes?: string } = {}): void {
 		const question = this.current;
 		if (!question) return;
-		this.answers.push({
+		// A custom typed answer never carries a preview; only a chosen option can.
+		const preview = opts.custom
+			? undefined
+			: question.options.find((option) => option.label === answer)?.preview;
+		this.answers[this.index] = {
 			questionIndex: this.index,
 			question: question.question,
 			answer,
 			custom: opts.custom === true,
 			...(opts.notes ? { notes: opts.notes } : {}),
-		});
-		this.index += 1;
+			...(preview ? { preview } : {}),
+		};
+	}
+
+	/** The recorded answer for a question, if any. */
+	answerAt(index: number): QuestionAnswer | undefined {
+		return this.answers[index];
+	}
+
+	/** Header for question `index`, used by the tab strip. */
+	headerAt(index: number): string {
+		return this.params.questions[index]?.header ?? "";
 	}
 
-	/** Title line for the dialog: `Header` or `2 of 3 · Header` when multiple. */
+	/** Title line: `Header` alone, or `2 of 3 · Header` when there are tabs. */
 	title(): string {
 		const question = this.current;
 		if (!question) return "";
@@ -99,13 +163,17 @@ export class QuestionnaireSession {
 			: question.header;
 	}
 
+	private collected(): QuestionAnswer[] {
+		return this.answers.filter((answer): answer is QuestionAnswer => answer !== undefined);
+	}
+
 	/** Successful outcome. */
 	result(): QuestionnaireResult {
-		return { answers: [...this.answers], cancelled: false };
+		return { answers: this.collected(), cancelled: false };
 	}
 
 	/** Declined outcome, preserving any answers given before the cancel. */
 	cancelledResult(): QuestionnaireResult {
-		return { answers: [...this.answers], cancelled: true };
+		return { answers: this.collected(), cancelled: true };
 	}
 }

package/tool/envelope.ts

@@ -23,9 +23,14 @@ export function buildToolResult(text: string, details: QuestionnaireResult): Too
 	return { content: [{ type: "text" as const, text }], details };
 }
 
-/** Format a single answer as `"question"="answer"`, with an optional note. */
+/**
+ * Format a single answer as `"question"="answer"`, with the chosen option's
+ * preview and the user's note appended when present. Order and wording match
+ * rpiv's envelope and are pinned by tests.
+ */
 export function buildAnswerSegment(a: QuestionAnswer): string {
 	const parts: string[] = [`"${a.question}"="${a.answer}"`];
+	if (a.preview && a.preview.length > 0) parts.push(`selected preview: ${a.preview}`);
 	if (a.notes && a.notes.length > 0) parts.push(`user notes: ${a.notes}`);
 	return `${parts.join(". ")}.`;
 }

package/tool/schema.ts

@@ -1,11 +1,9 @@
 /**
  * Tool parameter schema and shared types for `ask_user_question`.
  *
- * v0.1 scope (docs/specs/pi-ask-user-question.md §14): a SINGLE question,
- * single-select, no preview. The schema still accepts the `questions` array
- * shape so that v0.2 can lift the count limit without changing the wire
- * contract the model has already learned, and so session history recorded
- * against the array shape keeps replaying.
+ * v0.2 scope (docs/specs/pi-ask-user-question.md §14): up to four questions,
+ * single-select, no preview. Questions render as tabs the user cycles with
+ * Tab / Shift+Tab.
  */
 
 import { Type } from "typebox";
@@ -16,8 +14,7 @@ export const TOOL_NAME = "ask_user_question";
 export const MIN_OPTIONS = 2;
 export const MAX_OPTIONS = 4;
 export const MIN_QUESTIONS = 1;
-/** v0.1 ships single-question only; v0.2 raises this to 4. */
-export const MAX_QUESTIONS = 1;
+export const MAX_QUESTIONS = 4;
 
 export const MAX_HEADER_LENGTH = 16;
 export const MAX_LABEL_LENGTH = 60;
@@ -42,6 +39,12 @@ export const OptionSchema = Type.Object({
 		description:
 			"Explanation of what this option means or what will happen if chosen. Useful for providing context about trade-offs or implications.",
 	}),
+	preview: Type.Optional(
+		Type.String({
+			description:
+				"Optional markdown shown in a pane below the options while this option is highlighted. Use for concrete artifacts the user needs to compare: ASCII mockups, code snippets, diagram or configuration variations. Do NOT use it for simple preference questions where the label and description already say enough.",
+		}),
+	),
 });
 
 export const QuestionSchema = Type.Object({
@@ -63,7 +66,8 @@ export const QuestionSchema = Type.Object({
 
 export const QuestionParamsSchema = Type.Object({
 	questions: Type.Array(QuestionSchema, {
-		description: "Questions to ask the user. Exactly one question is supported in this version.",
+		description:
+			"Questions to ask the user. 1-4 questions; the user cycles between them with Tab and answers each one.",
 		minItems: MIN_QUESTIONS,
 		maxItems: MAX_QUESTIONS,
 	}),
@@ -72,6 +76,7 @@ export const QuestionParamsSchema = Type.Object({
 export interface OptionParams {
 	label: string;
 	description: string;
+	preview?: string;
 }
 
 export interface QuestionParams {
@@ -90,8 +95,10 @@ export interface QuestionAnswer {
 	question: string;
 	answer: string;
 	custom: boolean;
-	/** Trimmed Tab-to-comment note, when the user attached one. */
+	/** Trimmed note, when the user attached one. */
 	notes?: string;
+	/** Preview text of the chosen option, when it carried one. */
+	preview?: string;
 }
 
 export interface QuestionnaireResult {

package/tool/validate.ts

@@ -49,10 +49,7 @@ export function validateParams(params: AskUserParams): ValidationError | undefin
 	if (!Array.isArray(questions) || questions.length < MIN_QUESTIONS || questions.length > MAX_QUESTIONS) {
 		return {
 			code: "bad_question_count",
-			message:
-				MAX_QUESTIONS === 1
-					? `This version supports exactly ${MAX_QUESTIONS} question per call; received ${questions?.length ?? 0}. Ask the most important question first, then follow up.`
-					: `questions must contain ${MIN_QUESTIONS}-${MAX_QUESTIONS} entries; received ${questions?.length ?? 0}.`,
+			message: `questions must contain ${MIN_QUESTIONS}-${MAX_QUESTIONS} entries; received ${questions?.length ?? 0}. Group questions that belong to one decision; ask further questions in a follow-up call.`,
 		};
 	}
 

package/view/dialog.ts

@@ -2,13 +2,27 @@
  * The questionnaire dialog: a pi-tui component driven by QuestionnaireSession
  * and rendered through `ctx.ui.custom()`.
  *
- * NO MONKEY PATCHING. The numbered options, digit hotkeys and Tab-to-comment
+ * NO MONKEY PATCHING. The numbered options, digit hotkeys and the note editor
  * come from `OptionSelector`, imported from the PUBLISHED sibling package
  * `@hank-warren/pi-permission-selector` (plain `dependencies`, never
  * `bundledDependencies` — AGENTS.md §Structure). See
  * docs/specs/pi-ask-user-question.md §9.
  *
- * TWO RULES, both learned from v0.2.0 shipping broken:
+ * KEY MAP (matches @juicesharp/rpiv-ask-user-question):
+ *
+ *   1-9         select an option
+ *   ↑ / ↓       move the highlight
+ *   enter       confirm the highlight
+ *   n           open the note editor for the highlighted option
+ *   tab / →     next question      shift+tab / ←   previous question
+ *   esc         decline the questionnaire
+ *
+ * Note that `n`, not Tab, opens notes here. Tab is reserved for cycling
+ * questions. pi-auto-permissions approval prompts keep Tab-to-comment, because
+ * they are single-question and have no tabs to cycle — `OptionSelector`
+ * defaults to Tab and this dialog overrides it.
+ *
+ * THREE RULES, all learned from shipping bugs:
  *
  * 1. NEVER compare key data with `===`. Every key check goes through the
  *    shared predicates in `.../keys.ts`. Under the Kitty keyboard protocol
@@ -16,8 +30,7 @@
  *    trapped the user in the custom-answer field with no way out.
  * 2. ALWAYS pad rendered lines to the full overlay width. pi composites an
  *    overlay onto the chat line by line and only overwrites the columns the
- *    overlay actually emits; short lines let chat text show through and the
- *    dialog renders as garbage interleaved with the transcript.
+ *    overlay actually emits; short lines let chat text show through.
  * 3. ALWAYS clamp lines to the inner width. A single over-long line breaks the
  *    right border and spills into the transcript, so `render` truncates as a
  *    last-resort invariant no matter what any content source produces.
@@ -25,9 +38,14 @@
 
 import {
 	isBackspaceKey,
+	isCharKey,
 	isEnterKey,
 	isEscapeKey,
+	isLeftKey,
 	isPrintable,
+	isRightKey,
+	isShiftTabKey,
+	isTabKey,
 } from "@hank-warren/pi-permission-selector/keys.ts";
 import { OptionSelector, type SelectorOption } from "@hank-warren/pi-permission-selector/selector.ts";
 import {
@@ -37,6 +55,7 @@ import {
 	visibleWidth,
 	wrapTextWithAnsi,
 } from "@earendil-works/pi-tui";
+import { Markdown, type MarkdownTheme } from "@earendil-works/pi-tui";
 import type { QuestionnaireSession } from "../questionnaire.ts";
 import type { QuestionnaireResult } from "../tool/schema.ts";
 
@@ -57,71 +76,101 @@ export interface DialogOptions {
 	 * the transcript show through to its right.
 	 */
 	maxWidth?: number;
+	/**
+	 * Markdown theme for the preview pane. Hosts pass pi's `getMarkdownTheme()`;
+	 * when omitted the preview renders as plain wrapped text, which keeps this
+	 * component unit-testable without constructing a 14-function theme.
+	 */
+	markdownTheme?: MarkdownTheme;
 }
 
 /** Left/right border plus one space of padding on each side. */
 const CHROME_COLUMNS = 4;
 /** Indent for the custom-answer field, in columns. */
 const FIELD_INDENT = "  ";
+/** Opens the note editor. Tab is taken by question cycling. */
+const NOTE_KEY = "n";
+const isNoteKey = isCharKey(NOTE_KEY);
+/** Maximum rows the preview pane may occupy before it is clipped. */
+const PREVIEW_MAX_ROWS = 12;
+
+/** Per-question UI state, preserved while cycling between tabs. */
+interface TabState {
+	selector: OptionSelector;
+	customText?: string;
+	pendingNotes?: string;
+}
 
 export class QuestionnaireDialog {
 	/** Focusable — set by the TUI when focus changes. Drives CURSOR_MARKER. */
 	focused = false;
 
 	private readonly opts: DialogOptions;
-	private selector: OptionSelector;
-	private customText: string | undefined;
-	private pendingNotes: string | undefined;
+	private readonly tabs: TabState[] = [];
 	private finished = false;
 
 	constructor(opts: DialogOptions) {
 		this.opts = opts;
-		this.selector = this.buildSelector();
+		for (let i = 0; i < this.session.total; i++) this.tabs.push({ selector: this.buildSelector(i) });
 	}
 
 	private get session() {
 		return this.opts.session;
 	}
 
+	private get tab(): TabState {
+		return this.tabs[this.session.questionIndex];
+	}
+
 	private repaint(): void {
 		this.opts.requestRender?.();
 	}
 
-	private buildSelector(): OptionSelector {
+	private buildSelector(index: number): OptionSelector {
 		const session = this.session;
+		const previous = session.goTo.bind(session);
+		// rows() reads the cursor, so snapshot this tab's rows at build time.
+		const restore = session.questionIndex;
+		previous(index);
 		const options: SelectorOption[] = session.rows().map((row) => ({
 			value: row.value,
 			label: row.label,
 			description: row.description,
 		}));
+		previous(restore);
 
 		return new OptionSelector({
 			options,
 			theme: this.opts.theme,
+			// `n` instead of Tab; Tab must stay free for question cycling. Tab is
+			// left unconsumed by the selector so this dialog can intercept it.
+			commentTrigger: isNoteKey,
+			commentKeyHint: NOTE_KEY,
 			onSelect: (option, comment) => {
+				session.goTo(index);
 				if (session.isCustomRow(option.value)) {
 					// Enter free-text mode. A note typed on the sentinel row is
 					// carried across so it is not silently lost.
-					this.pendingNotes = comment;
-					this.customText = "";
+					this.tabs[index].pendingNotes = comment;
+					this.tabs[index].customText = "";
 					this.repaint();
 					return;
 				}
 				session.recordAnswer(option.value, { notes: comment });
-				this.advance();
+				this.afterAnswer();
 			},
 			onCancel: () => this.finish(session.cancelledResult()),
 			requestRender: () => this.repaint(),
 		});
 	}
 
-	private advance(): void {
+	/** Submit when everything is answered, else jump to the next gap. */
+	private afterAnswer(): void {
 		if (this.session.isComplete()) {
 			this.finish(this.session.result());
 			return;
 		}
-		// v0.2: multi-question calls rebind the selector to the next question.
-		this.selector = this.buildSelector();
+		this.session.advanceToUnanswered();
 		this.repaint();
 	}
 
@@ -133,11 +182,16 @@ export class QuestionnaireDialog {
 
 	/** True while the free-text custom-answer editor is open. */
 	isTypingCustom(): boolean {
-		return this.customText !== undefined;
+		return this.tab?.customText !== undefined;
+	}
+
+	/** True while any text-entry mode owns the keyboard. */
+	private isTyping(): boolean {
+		return this.isTypingCustom() || this.tab.selector.isCommenting();
 	}
 
 	invalidate(): void {
-		this.selector.invalidate();
+		for (const tab of this.tabs) tab.selector.invalidate();
 	}
 
 	private style(role: string, text: string): string {
@@ -145,19 +199,34 @@ export class QuestionnaireDialog {
 		return role === "dim" ? `\x1b[2m${text}\x1b[0m` : text;
 	}
 
+	/** `✓ Database   ▸ Cache   ○ Queue` — one line, only when tabs exist. */
+	private tabStrip(): string {
+		const parts: string[] = [];
+		for (let i = 0; i < this.session.total; i++) {
+			const current = i === this.session.questionIndex;
+			const mark = this.session.isAnswered(i) ? "✓" : current ? "▸" : "○";
+			const label = `${mark} ${this.session.headerAt(i)}`;
+			parts.push(current ? this.style("accent", label) : this.style("dim", label));
+		}
+		return parts.join("   ");
+	}
+
 	/** Inner content lines, before the box is drawn around them. */
 	private contentLines(inner: number): string[] {
 		const session = this.session;
-		const lines: string[] = [this.style("accent", session.title()), ""];
+		const lines: string[] = [this.style("accent", session.title())];
+		if (session.total > 1) lines.push(this.tabStrip());
+		lines.push("");
 		lines.push(...wrapTextWithAnsi(session.current?.question ?? "", inner));
 		lines.push("");
 
-		if (this.customText !== undefined) {
+		const tab = this.tab;
+		if (tab.customText !== undefined) {
 			// Wrap the typed answer. Without this a long answer ran past the right
 			// border and off the screen forever, because an input field renders as
 			// one line unless something breaks it up.
 			const avail = Math.max(1, inner - FIELD_INDENT.length - 1); // -1 reserves the caret cell
-			const wrapped = wrapTextWithAnsi(this.customText, avail);
+			const wrapped = wrapTextWithAnsi(tab.customText, avail);
 			// CURSOR_MARKER is a zero-width APC sequence: the TUI strips it and
 			// parks the hardware cursor there, so the caret lands in the field
 			// instead of at the bottom of the screen.
@@ -171,10 +240,64 @@ export class QuestionnaireDialog {
 			return lines;
 		}
 
-		lines.push(...this.selector.render(inner));
+		lines.push(...tab.selector.render(inner));
+		lines.push(...this.previewLines(inner));
+		if (session.total > 1 && !tab.selector.isCommenting()) {
+			lines.push(this.style("dim", "  tab next · shift+tab prev question"));
+		}
 		return lines;
 	}
 
+	/** Preview markdown for the highlighted row, if it carries any. */
+	private currentPreview(): string | undefined {
+		const selected = this.tab.selector.getSelected();
+		if (!selected) return undefined;
+		return this.session.rows().find((row) => row.value === selected.value)?.preview;
+	}
+
+	/**
+	 * The preview pane: markdown between two rules, below the options.
+	 *
+	 * Stacked, not side-by-side. rpiv spent ~712 lines largely on making a
+	 * two-column layout behave at narrow widths; stacking needs none of it
+	 * (docs/specs/pi-ask-user-question.md §6.2).
+	 */
+	private previewLines(inner: number): string[] {
+		const preview = this.currentPreview();
+		if (!preview) return [];
+
+		const rendered = this.renderMarkdown(preview, inner);
+
+		// Cap the pane so a long preview cannot push the options off screen.
+		const clipped = rendered.slice(0, PREVIEW_MAX_ROWS);
+		if (rendered.length > PREVIEW_MAX_ROWS) {
+			clipped.push(this.style("dim", `… ${rendered.length - PREVIEW_MAX_ROWS} more lines`));
+		}
+
+		const rule = this.style("dim", "─".repeat(Math.max(1, inner)));
+		return ["", rule, ...clipped, rule];
+	}
+
+	/**
+	 * Render preview markdown, falling back to plain wrapped text.
+	 *
+	 * The fallback is not just for hosts that pass no theme. pi's
+	 * `getMarkdownTheme()` returns lazily-bound functions that throw
+	 * "Theme not initialized" until `initTheme()` has run, and a throw inside
+	 * `render()` would take down the entire dialog rather than one pane. A
+	 * preview is a nicety; it must never be able to do that.
+	 */
+	private renderMarkdown(preview: string, inner: number): string[] {
+		if (this.opts.markdownTheme) {
+			try {
+				return new Markdown(preview, 0, 0, this.opts.markdownTheme).render(inner);
+			} catch {
+				// fall through to plain text
+			}
+		}
+		return preview.split("\n").flatMap((line) => wrapTextWithAnsi(line, inner));
+	}
+
 	render(width: number): string[] {
 		const cap = this.opts.maxWidth ?? width;
 		const outer = Math.max(20, Math.min(width, cap));
@@ -196,43 +319,62 @@ export class QuestionnaireDialog {
 	}
 
 	handleInput(keyData: string): void {
-		if (this.customText === undefined) {
-			this.selector.handleInput(keyData);
+		const tab = this.tab;
+
+		// Question cycling. Deliberately NOT active while typing: Tab inside the
+		// note editor means "back to options", and inside the custom-answer field
+		// a stray Tab must never teleport the user to another question and strand
+		// their half-typed text.
+		if (this.session.total > 1 && !this.isTyping()) {
+			if (isTabKey(keyData) || isRightKey(keyData)) {
+				this.session.next();
+				this.repaint();
+				return;
+			}
+			if (isShiftTabKey(keyData) || isLeftKey(keyData)) {
+				this.session.previous();
+				this.repaint();
+				return;
+			}
+		}
+
+		if (tab.customText === undefined) {
+			tab.selector.handleInput(keyData);
 			return;
 		}
 
 		// Free-text mode. Every check below MUST use a shared predicate — see
-		// the header comment. Esc unwinds to the option list rather than
-		// cancelling the dialog: one Esc never discards more than one layer.
+		// rule 1. Esc unwinds to the option list rather than cancelling the
+		// dialog: one Esc never discards more than one layer.
 		if (isEscapeKey(keyData)) {
-			this.customText = undefined;
-			this.pendingNotes = undefined;
+			tab.customText = undefined;
+			tab.pendingNotes = undefined;
 			this.repaint();
 			return;
 		}
 		if (isEnterKey(keyData)) {
-			const text = this.customText.trim();
+			const text = tab.customText.trim();
 			if (text.length === 0) return; // Empty custom answers are not submittable.
-			this.session.recordAnswer(text, { custom: true, notes: this.pendingNotes });
-			this.customText = undefined;
-			this.pendingNotes = undefined;
-			this.advance();
+			this.session.recordAnswer(text, { custom: true, notes: tab.pendingNotes });
+			tab.customText = undefined;
+			tab.pendingNotes = undefined;
+			this.afterAnswer();
 			return;
 		}
 		if (isBackspaceKey(keyData)) {
-			this.customText = this.customText.slice(0, -1);
+			tab.customText = tab.customText.slice(0, -1);
 			this.repaint();
 			return;
 		}
 		if (isPrintable(keyData)) {
-			this.customText += keyData;
+			tab.customText += keyData;
 			this.repaint();
 			return;
 		}
 		// Kitty/modifyOtherKeys terminals encode plain printables as CSI-u.
 		const decoded = decodeKittyPrintable(keyData);
 		if (decoded !== undefined && isPrintable(decoded)) {
-			this.customText += decoded;
+			tab.customText += decoded;
 			this.repaint();
 		}
 		// Anything else (arrows, unhandled chords) is inert — never inserted