pi-design-deck 0.2.0 → 0.3.0

package/index.ts

@@ -6,10 +6,11 @@ import * as os from "node:os";
 import * as fs from "node:fs";
 import { randomUUID } from "node:crypto";
 import { loadSettings } from "./settings.js";
-import { startDeckServer, type DeckServerHandle, type ModelInfo } from "./deck-server.js";
-import { isDeckOption, validateDeckConfig, validateSavedDeck } from "./deck-schema.js";
+import { getDefaultSnapshotDir, startDeckServer, type DeckServerHandle, type ModelInfo } from "./deck-server.js";
+import { deriveDeckStatusFromFolderName, isDeckOption, validateDeckConfig, validateSavedDeck, type SavedDeckData, type SavedDeckStatus } from "./deck-schema.js";
 import { buildGenerateMoreResult, buildRegenerateResult } from "./generate-prompts.js";
 import { generateWithModel } from "./model-runner.js";
+import { buildStandaloneDeckHtml } from "./export-html.js";
 
 async function openUrl(pi: ExtensionAPI, url: string, browser?: string): Promise<void> {
 	const platform = os.platform();
@@ -64,6 +65,24 @@ let restoreDeckThinking: (() => void) | null = null;
 
 const DECK_IDLE_TIMEOUT_MS = 5 * 60 * 1000;
 
+interface SavedDeckListItem {
+	id: string;
+	title: string;
+	savedAt: string;
+	modifiedAt: string;
+	status: SavedDeckStatus;
+	cwd?: string;
+	branch?: string | null;
+	slideCount: number;
+}
+
+interface LoadedDeckSource {
+	configData: unknown;
+	savedSelections?: Record<string, string>;
+	savedNotes?: Record<string, { label: string; notes: string }>;
+	savedFinalNotes?: string;
+}
+
 const DeckParams = Type.Object(
 	{
 		slides: Type.Optional(
@@ -78,11 +97,15 @@ const DeckParams = Type.Object(
 		action: Type.Optional(
 			Type.Union([
 				Type.Literal("add-option", { description: "Push a single generated option into a running deck session" }),
+				Type.Literal("add-options", { description: "Push multiple generated options into a running deck session (blocks until next user action)" }),
 				Type.Literal("replace-options", { description: "Replace all options for a slide with fresh alternatives" }),
+				Type.Literal("list", { description: "List saved decks from the snapshot directory" }),
+				Type.Literal("open", { description: "Open a saved deck by deck ID" }),
+				Type.Literal("export", { description: "Export a saved deck as standalone HTML" }),
 			])
 		),
 		slideId: Type.Optional(
-			Type.String({ description: "Target slide ID (required with action: 'add-option' or 'replace-options')" })
+			Type.String({ description: "Target slide ID (required with action: 'add-option', 'add-options', or 'replace-options')" })
 		),
 		option: Type.Optional(
 			Type.String({
@@ -93,9 +116,15 @@ const DeckParams = Type.Object(
 		options: Type.Optional(
 			Type.String({
 				description:
-					"JSON string of array of deck options (required with action: 'replace-options')",
+					"JSON string of array of deck options (required with action: 'add-options' or 'replace-options')",
 			})
 		),
+		deckId: Type.Optional(
+			Type.String({ description: "Deck ID for open/export actions (folder name from list)" })
+		),
+		format: Type.Optional(
+			Type.String({ description: "Export format: 'html' (default)" })
+		),
 	},
 	{ additionalProperties: false }
 );
@@ -111,6 +140,104 @@ function expandHome(value: string): string {
 	return value;
 }
 
+function resolveSnapshotDir(snapshotDir?: string): string {
+	return snapshotDir ? expandHome(snapshotDir) : getDefaultSnapshotDir();
+}
+
+function listSavedDecks(snapshotDir: string): { decks: SavedDeckListItem[]; warnings: string[] } {
+	if (!fs.existsSync(snapshotDir)) {
+		return { decks: [], warnings: [] };
+	}
+
+	const entries = fs.readdirSync(snapshotDir, { withFileTypes: true });
+	const decks: SavedDeckListItem[] = [];
+	const warnings: string[] = [];
+
+	for (const entry of entries) {
+		if (!entry.isDirectory()) continue;
+		const deckJsonPath = path.join(snapshotDir, entry.name, "deck.json");
+		if (!fs.existsSync(deckJsonPath)) continue;
+
+		try {
+			const raw = JSON.parse(fs.readFileSync(deckJsonPath, "utf-8"));
+			const saved = validateSavedDeck(raw);
+			decks.push({
+				id: saved.id ?? entry.name,
+				title: saved.config.title || "Design Deck",
+				savedAt: saved.savedAt,
+				modifiedAt: saved.modifiedAt ?? saved.savedAt,
+				status: saved.status ?? deriveDeckStatusFromFolderName(entry.name),
+				cwd: saved.savedFrom?.cwd,
+				branch: saved.savedFrom?.branch,
+				slideCount: saved.config.slides.length,
+			});
+		} catch (err) {
+			const message = err instanceof Error ? err.message : String(err);
+			warnings.push(`${entry.name}: ${message}`);
+		}
+	}
+
+	return { decks, warnings };
+}
+
+function resolveDeckFilePath(snapshotDir: string, deckId: string): string | null {
+	if (!deckId || deckId === "." || deckId === ".." || deckId.includes("/") || deckId.includes("\\")) {
+		return null;
+	}
+	const root = path.resolve(snapshotDir);
+	const deckDir = path.resolve(snapshotDir, deckId);
+	if (deckDir !== root && !deckDir.startsWith(root + path.sep)) {
+		return null;
+	}
+	return path.join(deckDir, "deck.json");
+}
+
+function buildSavedNotesForClient(saved: SavedDeckData): Record<string, { label: string; notes: string }> | undefined {
+	const savedNotesForClient: Record<string, { label: string; notes: string }> = {};
+	for (const [slideId, noteString] of Object.entries(saved.notes ?? {})) {
+		const label = saved.selections[slideId];
+		if (label && noteString) {
+			savedNotesForClient[slideId] = { label, notes: noteString };
+		}
+	}
+	return Object.keys(savedNotesForClient).length > 0 ? savedNotesForClient : undefined;
+}
+
+function loadDeckFile(absolutePath: string): LoadedDeckSource {
+	const content = fs.readFileSync(absolutePath, "utf-8");
+	let fileData: unknown;
+	try {
+		fileData = JSON.parse(content);
+	} catch (parseErr) {
+		const message = parseErr instanceof Error ? parseErr.message : String(parseErr);
+		throw new Error(`Invalid JSON in saved deck file: ${message}`);
+	}
+
+	const raw = fileData as Record<string, unknown>;
+	if (raw.config && typeof raw.config === "object") {
+		const saved = validateSavedDeck(fileData);
+		const snapshotDir = path.dirname(absolutePath);
+		for (const slide of saved.config.slides) {
+			for (const option of slide.options) {
+				if (!option.previewBlocks) continue;
+				for (const block of option.previewBlocks) {
+					if (block.type === "image" && !path.isAbsolute(block.src)) {
+						block.src = path.join(snapshotDir, block.src);
+					}
+				}
+			}
+		}
+		return {
+			configData: saved.config,
+			savedSelections: Object.keys(saved.selections).length > 0 ? saved.selections : undefined,
+			savedNotes: buildSavedNotesForClient(saved),
+			savedFinalNotes: saved.finalNotes,
+		};
+	}
+
+	return { configData: fileData };
+}
+
 const DEFAULT_THEME_HOTKEY = "mod+shift+l";
 
 function clearDeckIdleTimer(): void {
@@ -207,19 +334,32 @@ export default function (pi: ExtensionAPI) {
 			"Present a multi-slide design deck with visual options for decisions. " +
 			"Slides JSON: { title?, slides: [{ id, title, context?, columns?, options }] }. " +
 			"When the user requests more options, tool returns generate-more instructions — " +
-			'call design_deck with action:"add-option" to push into the live deck. ' +
+			'call design_deck with action:"add-options" to push all new options at once. ' +
 			"previewBlocks for code/architecture comparisons, previewHtml for custom UI mockups.",
 		parameters: DeckParams,
 
 		async execute(_toolCallId, params, signal, onUpdate, ctx) {
-			if (!ctx.hasUI) {
+			const p = params as Record<string, unknown>;
+
+			if (!ctx.hasUI && p.action !== "list" && p.action !== "export") {
 				throw new Error(
 					"design_deck requires interactive mode with browser support. " +
 						"Cannot run in headless/RPC/print mode."
 				);
 			}
 
-			const p = params as Record<string, unknown>;
+			if (p.action === "list") {
+				const settings = loadSettings();
+				const snapshotDir = resolveSnapshotDir(settings.snapshotDir);
+				const { decks, warnings } = listSavedDecks(snapshotDir);
+				const content: Array<{ type: "text"; text: string }> = [
+					{ type: "text", text: JSON.stringify(decks, null, 2) },
+				];
+				if (warnings.length > 0) {
+					content.push({ type: "text", text: `Warnings:\n${warnings.map((w) => `- ${w}`).join("\n")}` });
+				}
+				return { content };
+			}
 
 			if (p.action === "add-option") {
 				if (typeof p.slideId !== "string" || p.slideId.trim() === "") {
@@ -236,6 +376,21 @@ export default function (pi: ExtensionAPI) {
 						details: { status: "error", url: activeDeckServer?.handle.url ?? "" },
 					};
 				}
+			} else if (p.action === "add-options") {
+				if (typeof p.slideId !== "string" || p.slideId.trim() === "") {
+					activeDeckServer?.handle.cancelGenerate();
+					return {
+						content: [{ type: "text", text: 'add-options requires slideId (string).' }],
+						details: { status: "error", url: activeDeckServer?.handle.url ?? "" },
+					};
+				}
+				if (typeof p.options !== "string" || p.options.trim() === "") {
+					activeDeckServer?.handle.cancelGenerate();
+					return {
+						content: [{ type: "text", text: 'add-options requires options (JSON array string).' }],
+						details: { status: "error", url: activeDeckServer?.handle.url ?? "" },
+					};
+				}
 			} else if (p.action === "replace-options") {
 				if (typeof p.slideId !== "string" || p.slideId.trim() === "") {
 					activeDeckServer?.handle.cancelGenerate();
@@ -251,6 +406,13 @@ export default function (pi: ExtensionAPI) {
 						details: { status: "error", url: activeDeckServer?.handle.url ?? "" },
 					};
 				}
+			} else if (p.action === "open" || p.action === "export") {
+				if (typeof p.deckId !== "string" || p.deckId.trim() === "") {
+					return {
+						content: [{ type: "text", text: `${p.action} requires deckId (string). Example: { action: "${p.action}", deckId: "tabs-component-myapp-main-2026-03-01-103045-submitted" }` }],
+						details: { status: "error", url: activeDeckServer?.handle.url ?? "" },
+					};
+				}
 			} else if (typeof p.slides !== "string" || p.slides.trim() === "") {
 				return {
 					content: [{
@@ -258,7 +420,10 @@ export default function (pi: ExtensionAPI) {
 						text:
 							"design_deck requires one of:\n\n" +
 							'1. Start a new deck: { slides: "<JSON string of { title?, slides: [{ id, title, options }] }>" }\n' +
-							'2. Add option to running deck: { action: "add-option", slideId: "...", option: "<JSON string>" }\n\n' +
+							'2. Open a saved deck: { action: "open", deckId: "..." }\n' +
+							'3. Export a saved deck: { action: "export", deckId: "...", format: "html" }\n' +
+							'4. Add options to running deck: { action: "add-options", slideId: "...", options: "[<JSON array>]" }\n' +
+							'5. Add single option: { action: "add-option", slideId: "...", option: "<JSON string>" }\n\n' +
 							"Each option needs label + either previewHtml (raw HTML) or previewBlocks (array of {type, ...} blocks).\n" +
 							"Block types: html, mermaid, code, image.",
 					}],
@@ -332,6 +497,83 @@ export default function (pi: ExtensionAPI) {
 				};
 			}
 
+			if (p.action === "add-options") {
+				if (pendingDeckResult) {
+					const result = pendingDeckResult;
+					pendingDeckResult = null;
+					return result;
+				}
+
+				if (!activeDeckServer) {
+					return {
+						content: [{ type: "text", text: "No active design deck session. Start a new deck before adding options." }],
+						details: { status: "error", url: "" },
+					};
+				}
+
+				if (activeDeckServer.currentResolve !== null) {
+					return {
+						content: [{ type: "text", text: "Design deck is not waiting for new options right now." }],
+						details: { status: "error", url: activeDeckServer.handle.url },
+					};
+				}
+
+				const slideId = p.slideId as string;
+				const optionsStr = p.options as string;
+
+				let parsedOptions: unknown;
+				try {
+					parsedOptions = JSON.parse(optionsStr);
+				} catch (err) {
+					activeDeckServer.handle.cancelGenerate();
+					const message = err instanceof Error ? err.message : String(err);
+					const snippet = optionsStr.length > 300 ? optionsStr.slice(0, 300) + "..." : optionsStr;
+					return {
+						content: [{ type: "text", text: `Invalid options JSON: ${message}\n\nReceived:\n${snippet}\n\nFix the JSON and call design_deck add-options again.` }],
+						details: { status: "error", url: activeDeckServer.handle.url },
+					};
+				}
+
+				if (!Array.isArray(parsedOptions)) {
+					activeDeckServer.handle.cancelGenerate();
+					return {
+						content: [{ type: "text", text: "options must be a JSON array of deck options. Fix and call design_deck add-options again." }],
+						details: { status: "error", url: activeDeckServer.handle.url },
+					};
+				}
+
+				for (const opt of parsedOptions) {
+					if (!isDeckOption(opt)) {
+						activeDeckServer.handle.cancelGenerate();
+						return {
+							content: [{ type: "text", text: "One or more options in the array are invalid — each needs label and either previewHtml or previewBlocks. Fix and call design_deck add-options again." }],
+							details: { status: "error", url: activeDeckServer.handle.url },
+						};
+					}
+				}
+
+				try {
+					for (const opt of parsedOptions) {
+						activeDeckServer.handle.pushOption(slideId, opt);
+					}
+				} catch (err) {
+					const message = err instanceof Error ? err.message : String(err);
+					return {
+						content: [{ type: "text", text: `Failed to push options: ${message}` }],
+						details: { status: "error", url: activeDeckServer.handle.url },
+					};
+				}
+
+				if (onUpdate) {
+					onUpdate({
+						content: [{ type: "text", text: `Pushed ${parsedOptions.length} options to slide ${slideId}.` }],
+						details: { status: "generate-more", url: activeDeckServer.handle.url, slideId },
+					});
+				}
+				attachDeckAbortHandler(signal);
+				return blockOnDeck();
+			}
+
 			if (p.action === "replace-options") {
 				if (pendingDeckResult) {
 					const result = pendingDeckResult;
@@ -409,7 +651,7 @@ export default function (pi: ExtensionAPI) {
 
 			pendingDeckResult = null;
 
-			if (activeDeckServer) {
+			if (activeDeckServer && p.action !== "export") {
 				return {
 					content: [
 						{
@@ -421,10 +663,61 @@ export default function (pi: ExtensionAPI) {
 				};
 			}
 
-			const slides = p.slides as string;
+			const settings = loadSettings();
+			const snapshotDir = resolveSnapshotDir(settings.snapshotDir);
+			let slides = p.slides as string;
+			if (p.action === "open" || p.action === "export") {
+				const deckId = (p.deckId as string).trim();
+				const deckPath = resolveDeckFilePath(snapshotDir, deckId);
+				if (!deckPath || !fs.existsSync(deckPath)) {
+					const { decks } = listSavedDecks(snapshotDir);
+					const availableHint = decks.length > 0
+						? ` Available deck IDs: ${decks.slice(0, 10).map((deck) => deck.id).join(", ")}`
+						: " Snapshot directory is empty.";
+					return {
+						content: [{ type: "text", text: `Saved deck "${deckId}" not found in ${snapshotDir}.${availableHint}` }],
+						details: { status: "error", url: "" },
+					};
+				}
+				if (p.action === "export") {
+					const format = typeof p.format === "string" && p.format.trim() !== "" ? p.format.trim().toLowerCase() : "html";
+					if (format !== "html") {
+						return {
+							content: [{ type: "text", text: `Unsupported export format: ${format}` }],
+							details: { status: "error", url: "" },
+						};
+					}
+					try {
+						const saved = validateSavedDeck(JSON.parse(fs.readFileSync(deckPath, "utf-8")));
+						const enrichedSaved: SavedDeckData = {
+							...saved,
+							id: saved.id ?? deckId,
+							status: saved.status ?? deriveDeckStatusFromFolderName(deckId),
+						};
+						const html = buildStandaloneDeckHtml(deckPath, enrichedSaved);
+						const exportPath = path.join(path.dirname(deckPath), "export.html");
+						fs.writeFileSync(exportPath, html, "utf-8");
+						const relativePath = exportPath.startsWith(os.homedir())
+							? "~" + exportPath.slice(os.homedir().length)
+							: exportPath;
+						return {
+							content: [{ type: "text", text: `Exported HTML to ${relativePath}` }],
+						};
+					} catch (err) {
+						const message = err instanceof Error ? err.message : String(err);
+						return {
+							content: [{ type: "text", text: `Failed to export deck "${deckId}": ${message}` }],
+							details: { status: "error", url: "" },
+						};
+					}
+				}
+				slides = deckPath;
+			}
 
 			let configData: unknown;
 			let savedSelections: Record<string, string> | undefined;
+			let savedNotes: Record<string, { label: string; notes: string }> | undefined;
+			let savedFinalNotes: string | undefined;
 			try {
 				configData = JSON.parse(slides);
 			} catch {
@@ -433,37 +726,13 @@ export default function (pi: ExtensionAPI) {
 				if (!fs.existsSync(absolutePath)) {
 					throw new Error(`Invalid slides: not valid JSON and file not found at ${absolutePath}`);
 				}
-				const content = fs.readFileSync(absolutePath, "utf-8");
-				let fileData: unknown;
-				try {
-					fileData = JSON.parse(content);
-				} catch (parseErr) {
-					const message = parseErr instanceof Error ? parseErr.message : String(parseErr);
-					throw new Error(`Invalid JSON in saved deck file: ${message}`);
-				}
-				const raw = fileData as Record<string, unknown>;
-				if (raw.config && typeof raw.config === "object") {
-					const saved = validateSavedDeck(fileData);
-					configData = saved.config;
-					savedSelections = Object.keys(saved.selections).length > 0 ? saved.selections : undefined;
-					const snapshotDir = path.dirname(absolutePath);
-					for (const slide of saved.config.slides) {
-						for (const option of slide.options) {
-							if (!option.previewBlocks) continue;
-							for (const block of option.previewBlocks) {
-								if (block.type === "image" && !path.isAbsolute(block.src)) {
-									block.src = path.join(snapshotDir, block.src);
-								}
-							}
-						}
-					}
-				} else {
-					configData = fileData;
-				}
+				const loaded = loadDeckFile(absolutePath);
+				configData = loaded.configData;
+				savedSelections = loaded.savedSelections;
+				savedNotes = loaded.savedNotes;
+				savedFinalNotes = loaded.savedFinalNotes;
 			}
 			const config = validateDeckConfig(configData);
-
-			const settings = loadSettings();
 			const sessionId = randomUUID();
 			const sessionToken = randomUUID();
 
@@ -567,8 +836,6 @@ export default function (pi: ExtensionAPI) {
 			};
 
 			const themeConfig = settings.theme ?? {};
-			const snapshotDir = settings.snapshotDir ? expandHome(settings.snapshotDir) : undefined;
-
 			const currentModelStr = ctx.model ? `${ctx.model.provider}/${ctx.model.id}` : null;
 			const availableModels: ModelInfo[] = ctx.modelRegistry.getAvailable().map((m) => ({
 				provider: m.provider,
@@ -592,6 +859,8 @@ export default function (pi: ExtensionAPI) {
 						toggleHotkey: themeConfig.toggleHotkey ?? DEFAULT_THEME_HOTKEY,
 					},
 					savedSelections,
+					savedNotes,
+					savedFinalNotes,
 					snapshotDir,
 					autoSaveOnSubmit: settings.autoSaveOnSubmit ?? true,
 					models: {
@@ -640,6 +909,13 @@ export default function (pi: ExtensionAPI) {
 					0
 				);
 			}
+			if (data.action === "add-options") {
+				return new Text(
+					theme.fg("toolTitle", theme.bold(`Design Deck: add options (${data.slideId || "unknown"})`)),
+					0,
+					0
+				);
+			}
 			if (data.action === "replace-options") {
 				return new Text(
 					theme.fg("toolTitle", theme.bold(`Design Deck: replace options (${data.slideId || "unknown"})`)),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-design-deck",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Visual design deck for presenting multi-slide options with high-fidelity previews",
   "author": "Nico Bailon",
   "license": "MIT",
@@ -16,6 +16,7 @@
     "model-runner.ts",
     "server-utils.ts",
     "settings.ts",
+    "export-html.ts",
     "index.ts"
   ],
   "scripts": {

package/prompts/deck-discover.md

@@ -1,7 +1,9 @@
 ---
 description: Interview to gather requirements, then present design options
 ---
-Load the `design-deck` skill for the full format reference. This is a two-phase flow.
+Load the `design-deck` skill for the full format reference. If presenting UI component options (tabs, trees, buttons, accordions, etc.), also read the relevant file from the skill's `references/component-gallery/` directory — it has visual vocabulary across design systems plus guidance on when to use distinct systems vs variations of the same approach.
+
+This is a two-phase flow.
 
 **Phase 1 — Discovery.** Before proposing anything, interview me in depth. Read relevant codebase context first so your questions are informed. Then hit me with detailed questions about goals, constraints, audience, aesthetics, technical requirements, trade-offs, edge cases, and anything else that would affect the design options. No obvious questions. Keep interviewing in multiple rounds if earlier answers surface new dimensions worth exploring — only move on when you have enough to generate genuinely distinct options.
 

package/prompts/deck-plan.md

@@ -1,7 +1,9 @@
 ---
 description: Analyze a plan/PRD and present design & architecture options
 ---
-Load the `design-deck` skill for the full format reference. Then read and analyze the plan or PRD at `$1`. Also read the actual codebase files it references — in full — to understand the real state of the code, not just what the plan assumes.
+Load the `design-deck` skill for the full format reference. If presenting UI component options (tabs, trees, buttons, accordions, etc.), also read the relevant file from the skill's `references/component-gallery/` directory — it has visual vocabulary across design systems plus guidance on when to use distinct systems vs variations of the same approach.
+
+Then read and analyze the plan or PRD at `$1`. Also read the actual codebase files it references — in full — to understand the real state of the code, not just what the plan assumes.
 
 Identify the key design and architecture decisions embedded in the plan. For each decision point, build a slide with 2-4 concrete options that are faithful to the plan's goals but offer genuinely different approaches. Mix preview types as appropriate: mermaid diagrams for architecture, code blocks for API design, HTML for UI mockups, images if available.
 

package/prompts/deck.md

@@ -1,7 +1,9 @@
 ---
 description: Present visual design options via design deck
 ---
-Load the `design-deck` skill for the full format reference. Analyze the current codebase and context, and present concrete visual options using `design_deck`.
+Load the `design-deck` skill for the full format reference. If presenting UI component options (tabs, trees, buttons, accordions, etc.), also read the relevant file from the skill's `references/component-gallery/` directory — it has visual vocabulary across design systems plus guidance on when to use distinct systems vs variations of the same approach.
+
+Analyze the current codebase and context, and present concrete visual options using `design_deck`.
 
 Read relevant files aggressively first so you understand the real constraints before generating options. If there's a plan or PRD, read it in full along with every codebase file it references — understand the actual state of the code, not just what the document assumes. Then identify the key design and architecture decisions and present options for each.
 

package/skills/design-deck/SKILL.md

@@ -3,6 +3,8 @@ name: design-deck
 description: Present visual options for architecture, UI, and code decisions with high-fidelity side-by-side previews. For comparing approaches visually — code diffs, diagrams, UI mockups, images — not for gathering structured input (use interview for that). Supports previewBlocks (code, mermaid, image, html), previewHtml, generate-more loops, and plan/PRD-driven flows.
 ---
 
+> **`design_deck` is a direct tool — call it directly, not via MCP.**
+
 # Design Deck Workflow
 
 Use this skill when the task requires presenting multiple visual directions and collecting explicit user choices. Load this skill before building any deck to get the full format reference.
@@ -201,6 +203,40 @@ surf gemini "isometric database cluster, dark theme, blue nodes" \
 **Combine images with other blocks:**
 An image showing the visual direction paired with a code block showing the implementation approach, or a mermaid diagram showing data flow alongside a generated image showing the UI that flow produces.
 
+### Component Gallery Reference
+
+When generating UI component options (tabs, accordions, tree views, buttons, etc.), read `./references/component-gallery/components.md` for best practices, common layouts, and aliases for 60 UI components.
+
+The reference enables three things:
+- **Discovery** — list, find, and suggest components for a use case ("I need expandable content" → accordion, disclosure, details)
+- **Cross-referencing** — connect related terms (collapse = accordion = disclosure = expander; notification = alert = banner)
+- **Design vocabulary** — know what design systems look like (Blueprint = dense, dark-native; Ant = clean, blue primary)
+
+The `INDEX.md` provides a design system vocabulary table (Ant Design, Blueprint, Carbon, Material, etc.) and guidance on when to use distinct systems vs variations.
+
+**Decide based on context:**
+- **Distinct systems** (Blueprint vs Ant vs 98.css) when exploring the design space with no established aesthetic
+- **Variations within a system** when the project already has a design direction or the user specifies a style
+
+See `./references/component-gallery/INDEX.md` for the decision table and examples.
+
+**Proactively browse real examples:** When you need visual inspiration for a component, fetch the component.gallery page directly:
+
+- https://component.gallery/components/tabs/ — 80+ real tab implementations
+- https://component.gallery/components/accordion/ — 100+ accordion examples
+- https://component.gallery/components/button/ — 120+ button styles
+
+Each page shows real screenshots from Ant Design, Blueprint, Carbon, Material, Shopify Polaris, and 90+ other design systems. Useful when you need concrete visual references — not required for every deck.
+
+**When user vocabulary is unclear or ambiguous:** Read `./references/component-gallery/LOOKUP.md` to resolve user terms to canonical component names. The lookup file provides:
+
+1. **Alias Index** — Direct mappings like `collapse → Accordion`, `snackbar → Toast`
+2. **Disambiguation** — Rules for ambiguous terms like `dropdown` (Select? Combobox? Dropdown menu?) or `popup` (Modal? Popover? Tooltip?)
+3. **Intent Clusters** — When users describe what they're trying to do ("I need users to pick from options"), maps constraints to components
+4. **Clarification Templates** — Suggested questions when disambiguation is needed
+
+Use the lookup before generating options if the user's component vocabulary seems imprecise or you're unsure which component they mean.
+
 ### For Mixed Previews
 
 Many slides benefit from combining block types — a mermaid diagram showing structure alongside a code block showing usage, or an HTML mockup with a code block showing the component API.
@@ -220,27 +256,27 @@ Use these selections as the implementation contract for the final build.
 
 ## Generate-More Loop
 
-When the user clicks generate-more, `design_deck` returns a result instructing which slide needs another option and listing existing option labels.
+When the user clicks generate-more, `design_deck` returns a result instructing which slide needs options and how many, along with the existing option labels.
 
-Generate one new option that is meaningfully distinct from the listed options.
+Generate the requested number of new options, each meaningfully distinct from the existing ones.
 
-Re-invoke:
+Re-invoke with all options in a single call:
 
-`design_deck({ action: "add-option", slideId: "...", option: "{...json string...}" })`
+`design_deck({ action: "add-options", slideId: "...", options: "[{...}, {...}]" })`
 
-The `add-option` call pushes the new option into the live deck and blocks again for the next user action.
+The `add-options` call pushes all options into the live deck and blocks for the next user action. Use `add-options` (plural) for generate-more requests — it takes an array and handles blocking automatically.
 
 ### Model Override
 
 The deck shows a model dropdown below the header (when 2+ models are available). Users can pick which model generates new options and optionally save it as the default.
 
-When the generate-more result includes a model instruction (e.g. "Generate using model X via deck_generate"), use the built-in `deck_generate` tool to generate the option with that model:
+When the generate-more result includes a model instruction (e.g. "Generate using model X via deck_generate"), use the built-in `deck_generate` tool to generate the options with that model:
 
 ```
-deck_generate({ model: "google/gemini-3.1-pro", task: "Generate a JSON deck option..." })
+deck_generate({ model: "google/gemini-3.1-pro", task: "Generate JSON deck options..." })
 ```
 
-Parse the output as the option JSON and pass it to `add-option`.
+Parse the output as the options JSON array and pass it to `add-options`.
 
 The default model can also be set in `~/.pi/agent/settings.json`: