markform 0.1.1 → 0.1.2

package/dist/{cli-pjOiHgCW.mjs → cli-B3NVm6zL.mjs}

@@ -1,172 +1,19 @@
-import { C as parseRolesFlag, b as USER_ROLE, d as serializeRawMarkdown, et as PatchSchema, f as AGENT_ROLE, g as DEFAULT_PORT, h as DEFAULT_MAX_TURNS, m as DEFAULT_MAX_PATCHES_PER_TURN, p as DEFAULT_MAX_ISSUES, r as inspect, t as applyPatches, u as serialize, x as formatSuggestedLlms, y as SUGGESTED_LLMS } from "./apply-BQdd-fdx.mjs";
-import { _ as parseForm, a as resolveModel, c as createMockAgent, h as serializeSession, i as getProviderNames, o as createLiveAgent, r as getProviderInfo, t as VERSION, u as createHarness } from "./src-Cs4_9lWP.mjs";
+import { N as PatchSchema } from "./coreTypes-Dful87E0.mjs";
+import { A as SUGGESTED_LLMS, D as detectFileType, E as deriveExportPath, M as formatSuggestedLlms, O as getFormsDir, P as hasWebSearchSupport, T as USER_ROLE, _ as DEFAULT_MAX_TURNS, b as DEFAULT_RESEARCH_MAX_ISSUES_PER_TURN, d as serializeRawMarkdown, f as serializeReportMarkdown, g as DEFAULT_MAX_PATCHES_PER_TURN, h as DEFAULT_MAX_ISSUES_PER_TURN, j as WEB_SEARCH_CONFIG, k as parseRolesFlag, m as DEFAULT_FORMS_DIR, p as AGENT_ROLE, r as inspect, t as applyPatches, u as serialize, v as DEFAULT_PORT, w as REPORT_EXTENSION, x as DEFAULT_RESEARCH_MAX_PATCHES_PER_TURN } from "./apply-BfAGTHMh.mjs";
+import { a as resolveHarnessConfig, c as getProviderNames, f as createMockAgent, i as runResearch, l as resolveModel, m as createHarness, s as getProviderInfo, t as VERSION, u as createLiveAgent, v as parseForm } from "./src-BXRkGFpG.mjs";
+import { n as serializeSession } from "./session-Bqnwi9wp.mjs";
+import { a as getCommandContext, c as logInfo, d as logVerbose, f as logWarn, h as writeFile, i as formatPath, l as logSuccess, n as ensureFormsDir, o as logDryRun, p as readFile$1, r as formatOutput, s as logError, t as OUTPUT_FORMATS, u as logTiming } from "./shared-N_s1M-_K.mjs";
 import YAML from "yaml";
+import { basename, dirname, join, resolve } from "node:path";
 import { Command } from "commander";
 import pc from "picocolors";
-import { basename, dirname, join, relative, resolve } from "node:path";
-import * as p from "@clack/prompts";
-import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { existsSync, readFileSync } from "node:fs";
 import { fileURLToPath } from "node:url";
-import { exec } from "node:child_process";
+import * as p from "@clack/prompts";
+import { exec, spawn } from "node:child_process";
 import { createServer } from "node:http";
 
-//#region src/cli/lib/naming.ts
-/**
-* Naming convention utilities for JSON/YAML output.
-*
-* Converts between camelCase (TypeScript internal) and snake_case (JSON/YAML output).
-*/
-/**
-* Convert a camelCase string to snake_case.
-*
-* @example
-* toSnakeCase("fieldCount") // "field_count"
-* toSnakeCase("parentFieldId") // "parent_field_id"
-* toSnakeCase("already_snake") // "already_snake"
-*/
-function toSnakeCase(str) {
-	return str.replace(/([A-Z])/g, "_$1").toLowerCase();
-}
-/**
-* Recursively convert all object keys from camelCase to snake_case.
-*
-* Handles nested objects and arrays. Primitives are returned unchanged.
-*/
-function convertKeysToSnakeCase(obj) {
-	if (obj === null || obj === void 0) return obj;
-	if (Array.isArray(obj)) return obj.map(convertKeysToSnakeCase);
-	if (typeof obj === "object") {
-		const result = {};
-		for (const [key, value] of Object.entries(obj)) {
-			const snakeKey = toSnakeCase(key);
-			result[snakeKey] = convertKeysToSnakeCase(value);
-		}
-		return result;
-	}
-	return obj;
-}
-
-//#endregion
-//#region src/cli/lib/shared.ts
-/**
-* Valid format options for Commander choice validation.
-*/
-const OUTPUT_FORMATS = [
-	"console",
-	"plaintext",
-	"yaml",
-	"json",
-	"markform",
-	"markdown"
-];
-/**
-* Extract command context from Commander options.
-*/
-function getCommandContext(command) {
-	const opts = command.optsWithGlobals();
-	return {
-		dryRun: opts.dryRun ?? false,
-		verbose: opts.verbose ?? false,
-		quiet: opts.quiet ?? false,
-		format: opts.format ?? "console"
-	};
-}
-/**
-* Check if output should use colors.
-* Returns true for console format when stdout is a TTY.
-*/
-function shouldUseColors(ctx) {
-	if (ctx.format === "plaintext" || ctx.format === "yaml" || ctx.format === "json") return false;
-	return process.stdout.isTTY && !process.env.NO_COLOR;
-}
-/**
-* Format structured data according to output format.
-*
-* JSON and YAML outputs are converted to snake_case keys for consistency.
-*/
-function formatOutput(ctx, data, consoleFormatter) {
-	switch (ctx.format) {
-		case "json": return JSON.stringify(convertKeysToSnakeCase(data), null, 2);
-		case "yaml": return YAML.stringify(convertKeysToSnakeCase(data));
-		case "plaintext":
-		case "console":
-		default:
-			if (consoleFormatter) return consoleFormatter(data, shouldUseColors(ctx));
-			return YAML.stringify(convertKeysToSnakeCase(data));
-	}
-}
-/**
-* Log a dry-run message.
-*/
-function logDryRun(message, details) {
-	console.log(pc.yellow(`[DRY RUN] ${message}`));
-	if (details) console.log(pc.dim(JSON.stringify(details, null, 2)));
-}
-/**
-* Log a verbose message (only shown if --verbose is set).
-*/
-function logVerbose(ctx, message) {
-	if (ctx.verbose) console.log(pc.dim(message));
-}
-/**
-* Log an info message (hidden if --quiet is set).
-*/
-function logInfo(ctx, message) {
-	if (!ctx.quiet) console.log(message);
-}
-/**
-* Log an error message (always shown).
-*/
-function logError(message) {
-	console.error(pc.red(`Error: ${message}`));
-}
-/**
-* Log a success message (hidden if --quiet is set).
-*/
-function logSuccess(ctx, message) {
-	if (!ctx.quiet) console.log(pc.green(message));
-}
-/**
-* Log a timing message (hidden if --quiet is set).
-*/
-function logTiming(ctx, label, durationMs) {
-	if (!ctx.quiet) {
-		const seconds = (durationMs / 1e3).toFixed(1);
-		console.log(pc.cyan(`⏰ ${label}: ${seconds}s`));
-	}
-}
-/**
-* Log a warning message (hidden if --quiet is set).
-*/
-function logWarn(ctx, message) {
-	if (!ctx.quiet) console.log(pc.yellow(`⚠️  ${message}`));
-}
-/**
-* Format a file path for display: relative to cwd, colored green.
-* If the path is within the cwd, shows as relative (e.g., "./simple-filled1.form.md")
-* If outside cwd, shows the absolute path.
-*/
-function formatPath(absolutePath, cwd = process.cwd()) {
-	const relativePath = relative(cwd, absolutePath);
-	const displayPath = relativePath.startsWith("..") ? absolutePath : `./${relativePath}`;
-	return pc.green(displayPath);
-}
-/**
-* Read a file and return its contents.
-*/
-async function readFile(filePath) {
-	const { readFile: fsReadFile } = await import("node:fs/promises");
-	return fsReadFile(filePath, "utf-8");
-}
-/**
-* Write contents to a file.
-*/
-async function writeFile(filePath, contents) {
-	const { writeFile: fsWriteFile } = await import("node:fs/promises");
-	await fsWriteFile(filePath, contents, "utf-8");
-}
-
-//#endregion
 //#region src/cli/commands/apply.ts
 /**
 * Format state badge for console output.
@@ -200,9 +47,9 @@ function formatConsoleReport$2(report, useColors) {
 	const counts = report.progress.counts;
 	lines.push(bold("Progress:"));
 	lines.push(`  Total fields: ${counts.totalFields}`);
-	lines.push(`  Complete: ${counts.completeFields}`);
-	lines.push(`  Incomplete: ${counts.incompleteFields}`);
-	lines.push(`  Empty (required): ${counts.emptyRequiredFields}`);
+	lines.push(`  Valid: ${counts.validFields}, Invalid: ${counts.invalidFields}`);
+	lines.push(`  Filled: ${counts.filledFields}, Empty: ${counts.emptyFields}`);
+	lines.push(`  Empty required: ${counts.emptyRequiredFields}`);
 	lines.push("");
 	if (report.issues.length > 0) {
 		lines.push(bold(`Issues (${report.issues.length}):`));
@@ -225,7 +72,7 @@ function registerApplyCommand(program) {
 				process.exit(1);
 			}
 			logVerbose(ctx, `Reading file: ${file}`);
-			const content = await readFile(file);
+			const content = await readFile$1(file);
 			logVerbose(ctx, "Parsing form...");
 			const form = parseForm(content);
 			logVerbose(ctx, "Parsing patches...");
@@ -297,78 +144,92 @@ function registerApplyCommand(program) {
 }
 
 //#endregion
-//#region src/cli/commands/dump.ts
+//#region src/cli/commands/docs.ts
 /**
-* Format a field value for console display.
+* Get the path to the DOCS.md file.
+* Works both during development and when installed as a package.
 */
-function formatFieldValue$1(value, useColors) {
-	const dim = useColors ? pc.dim : (s) => s;
-	const green = useColors ? pc.green : (s) => s;
-	if (!value) return dim("(empty)");
-	switch (value.kind) {
-		case "string": return value.value ? green(`"${value.value}"`) : dim("(empty)");
-		case "number": return value.value !== null ? green(String(value.value)) : dim("(empty)");
-		case "string_list": return value.items.length > 0 ? green(`[${value.items.join(", ")}]`) : dim("(empty)");
-		case "single_select": return value.selected ? green(value.selected) : dim("(none selected)");
-		case "multi_select": return value.selected.length > 0 ? green(`[${value.selected.join(", ")}]`) : dim("(none selected)");
-		case "checkboxes": {
-			const entries = Object.entries(value.values);
-			if (entries.length === 0) return dim("(no entries)");
-			return entries.map(([k, v]) => `${k}:${v}`).join(", ");
-		}
-		default: return dim("(unknown)");
-	}
+function getDocsPath() {
+	const thisDir = dirname(fileURLToPath(import.meta.url));
+	if (thisDir.split(/[/\\]/).pop() === "dist") return join(dirname(thisDir), "DOCS.md");
+	return join(dirname(dirname(dirname(thisDir))), "DOCS.md");
 }
 /**
-* Format values for console output.
+* Load the docs content.
 */
-function formatConsoleValues(values, useColors) {
-	const lines = [];
-	const bold = useColors ? pc.bold : (s) => s;
-	for (const [fieldId, value] of Object.entries(values)) {
-		const valueStr = formatFieldValue$1(value, useColors);
-		lines.push(`${bold(fieldId)}: ${valueStr}`);
-	}
-	if (lines.length === 0) {
-		const dim = useColors ? pc.dim : (s) => s;
-		lines.push(dim("(no values)"));
+function loadDocs() {
+	const docsPath = getDocsPath();
+	try {
+		return readFileSync(docsPath, "utf-8");
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		throw new Error(`Failed to load DOCS from ${docsPath}: ${message}`);
 	}
-	return lines.join("\n");
 }
 /**
-* Convert FieldValue to a plain value for JSON/YAML serialization.
+* Apply basic terminal formatting to markdown content.
+* Colorizes headers, code blocks, and other elements for better readability.
 */
-function toPlainValue(value) {
-	switch (value.kind) {
-		case "string": return value.value ?? null;
-		case "number": return value.value ?? null;
-		case "string_list": return value.items;
-		case "single_select": return value.selected ?? null;
-		case "multi_select": return value.selected;
-		case "checkboxes": return value.values;
-		default: return null;
+function formatMarkdown$3(content, useColors) {
+	if (!useColors) return content;
+	const lines = content.split("\n");
+	const formatted = [];
+	let inCodeBlock = false;
+	for (const line of lines) {
+		if (line.startsWith("```")) {
+			inCodeBlock = !inCodeBlock;
+			formatted.push(pc.dim(line));
+			continue;
+		}
+		if (inCodeBlock) {
+			formatted.push(pc.dim(line));
+			continue;
+		}
+		if (line.startsWith("# ")) {
+			formatted.push(pc.bold(pc.cyan(line)));
+			continue;
+		}
+		if (line.startsWith("## ")) {
+			formatted.push(pc.bold(pc.blue(line)));
+			continue;
+		}
+		if (line.startsWith("### ")) {
+			formatted.push(pc.bold(line));
+			continue;
+		}
+		let formattedLine = line.replace(/`([^`]+)`/g, (_match, code) => {
+			return pc.yellow(code);
+		});
+		formattedLine = formattedLine.replace(/\*\*([^*]+)\*\*/g, (_match, text) => {
+			return pc.bold(text);
+		});
+		formattedLine = formattedLine.replace(/\[([^\]]+)\]\(([^)]+)\)/g, (_match, text, url) => {
+			return `${pc.cyan(text)} ${pc.dim(`(${url})`)}`;
+		});
+		formatted.push(formattedLine);
 	}
+	return formatted.join("\n");
 }
 /**
-* Register the dump command.
+* Check if stdout is an interactive terminal.
 */
-function registerDumpCommand(program) {
-	program.command("dump <file>").description("Extract and display form values only (lightweight inspect)").action(async (file, _options, cmd) => {
+function isInteractive$3() {
+	return process.stdout.isTTY === true;
+}
+/**
+* Display content.
+*/
+function displayContent$2(content) {
+	console.log(content);
+}
+/**
+* Register the docs command.
+*/
+function registerDocsCommand(program) {
+	program.command("docs").description("Display concise Markform syntax reference (agent-friendly)").option("--raw", "Output raw markdown without formatting").action((options, cmd) => {
 		const ctx = getCommandContext(cmd);
 		try {
-			logVerbose(ctx, `Reading file: ${file}`);
-			const content = await readFile(file);
-			logVerbose(ctx, "Parsing form...");
-			const form = parseForm(content);
-			if (ctx.format === "json" || ctx.format === "yaml") {
-				const plainValues = {};
-				for (const [fieldId, value] of Object.entries(form.valuesByFieldId)) plainValues[fieldId] = toPlainValue(value);
-				const output = formatOutput(ctx, plainValues, () => "");
-				console.log(output);
-			} else {
-				const output = formatOutput(ctx, form.valuesByFieldId, (data, useColors) => formatConsoleValues(data, useColors));
-				console.log(output);
-			}
+			displayContent$2(formatMarkdown$3(loadDocs(), !options.raw && isInteractive$3() && !ctx.quiet));
 		} catch (error) {
 			logError(error instanceof Error ? error.message : String(error));
 			process.exit(1);
@@ -387,46 +248,100 @@ function registerDumpCommand(program) {
 * - YAML values (.yml) - extracted field values
 */
 /**
-* Convert field values to plain values for YAML export.
+* Convert field responses to structured format for export (markform-218).
 *
-* Extracts the underlying values from the typed FieldValue wrappers
-* for a cleaner YAML representation.
+* Includes state for all fields:
+* - { state: 'unanswered' } for unfilled fields
+* - { state: 'skipped' } for skipped fields
+* - { state: 'aborted' } for aborted fields
+* - { state: 'answered', value: ... } for answered fields
 */
-function toPlainValues(form) {
+function toStructuredValues(form) {
 	const result = {};
-	for (const [fieldId, value] of Object.entries(form.valuesByFieldId)) switch (value.kind) {
-		case "string":
-			result[fieldId] = value.value ?? null;
-			break;
-		case "number":
-			result[fieldId] = value.value ?? null;
-			break;
-		case "string_list":
-			result[fieldId] = value.items;
-			break;
-		case "single_select":
-			result[fieldId] = value.selected ?? null;
-			break;
-		case "multi_select":
-			result[fieldId] = value.selected;
-			break;
-		case "checkboxes":
-			result[fieldId] = value.values;
-			break;
+	for (const [fieldId, response] of Object.entries(form.responsesByFieldId)) {
+		if (!response || response.state === "unanswered") {
+			result[fieldId] = { state: "unanswered" };
+			continue;
+		}
+		if (response.state === "skipped") {
+			result[fieldId] = {
+				state: "skipped",
+				...response.reason && { reason: response.reason }
+			};
+			continue;
+		}
+		if (response.state === "aborted") {
+			result[fieldId] = {
+				state: "aborted",
+				...response.reason && { reason: response.reason }
+			};
+			continue;
+		}
+		if (!response.value) {
+			result[fieldId] = {
+				state: "answered",
+				value: null
+			};
+			continue;
+		}
+		const value = response.value;
+		let exportValue;
+		switch (value.kind) {
+			case "string":
+				exportValue = value.value ?? null;
+				break;
+			case "number":
+				exportValue = value.value ?? null;
+				break;
+			case "string_list":
+				exportValue = value.items;
+				break;
+			case "single_select":
+				exportValue = value.selected ?? null;
+				break;
+			case "multi_select":
+				exportValue = value.selected;
+				break;
+			case "checkboxes":
+				exportValue = value.values;
+				break;
+			case "url":
+				exportValue = value.value ?? null;
+				break;
+			case "url_list":
+				exportValue = value.items;
+				break;
+		}
+		result[fieldId] = {
+			state: "answered",
+			value: exportValue
+		};
 	}
 	return result;
 }
 /**
+* Convert notes to export format (markform-219).
+*/
+function toNotesArray(form) {
+	return form.notes.map((note) => ({
+		id: note.id,
+		ref: note.ref,
+		role: note.role,
+		text: note.text
+	}));
+}
+/**
 * Derive export paths from a base form path.
+* Uses centralized extension constants from settings.ts.
 *
 * @param basePath - Path to the .form.md file
 * @returns Object with paths for all export formats
 */
 function deriveExportPaths(basePath) {
 	return {
-		formPath: basePath,
-		rawPath: basePath.replace(/\.form\.md$/, ".raw.md"),
-		yamlPath: basePath.replace(/\.form\.md$/, ".yml")
+		formPath: deriveExportPath(basePath, "form"),
+		rawPath: deriveExportPath(basePath, "raw"),
+		yamlPath: deriveExportPath(basePath, "yaml")
 	};
 }
 /**
@@ -435,24 +350,101 @@ function deriveExportPaths(basePath) {
 * Writes:
 * - Markform format (.form.md) - canonical form with directives
 * - Raw markdown (.raw.md) - plain readable markdown (no directives)
-* - YAML values (.yml) - extracted field values only
+* - YAML values (.yml) - structured format with state and notes (markform-218, markform-219)
 *
 * @param form - The parsed form to export
 * @param basePath - Base path for the .form.md file (other paths are derived)
 * @returns Paths to all exported files
 */
-function exportMultiFormat(form, basePath) {
+async function exportMultiFormat(form, basePath) {
 	const paths = deriveExportPaths(basePath);
 	const formContent = serialize(form);
-	writeFileSync(paths.formPath, formContent, "utf-8");
+	await writeFile(paths.formPath, formContent);
 	const rawContent = serializeRawMarkdown(form);
-	writeFileSync(paths.rawPath, rawContent, "utf-8");
-	const values = toPlainValues(form);
-	const yamlContent = YAML.stringify(values);
-	writeFileSync(paths.yamlPath, yamlContent, "utf-8");
+	await writeFile(paths.rawPath, rawContent);
+	const values = toStructuredValues(form);
+	const notes = toNotesArray(form);
+	const exportData = {
+		values,
+		...notes.length > 0 && { notes }
+	};
+	const yamlContent = YAML.stringify(exportData);
+	await writeFile(paths.yamlPath, yamlContent);
 	return paths;
 }
 
+//#endregion
+//#region src/cli/commands/dump.ts
+/**
+* Format a field response for console display, including state information.
+*/
+function formatFieldResponse(response, useColors) {
+	const dim = useColors ? pc.dim : (s) => s;
+	const green = useColors ? pc.green : (s) => s;
+	const yellow = useColors ? pc.yellow : (s) => s;
+	if (response.state === "unanswered") return dim("(unanswered)");
+	if (response.state === "skipped") return yellow(`[skipped]${response.reason ? ` ${response.reason}` : ""}`);
+	if (response.state === "aborted") return yellow(`[aborted]${response.reason ? ` ${response.reason}` : ""}`);
+	const value = response.value;
+	if (!value) return dim("(empty)");
+	switch (value.kind) {
+		case "string": return value.value ? green(`"${value.value}"`) : dim("(empty)");
+		case "number": return value.value !== null ? green(String(value.value)) : dim("(empty)");
+		case "string_list": return value.items.length > 0 ? green(`[${value.items.join(", ")}]`) : dim("(empty)");
+		case "single_select": return value.selected ? green(value.selected) : dim("(none selected)");
+		case "multi_select": return value.selected.length > 0 ? green(`[${value.selected.join(", ")}]`) : dim("(none selected)");
+		case "checkboxes": {
+			const entries = Object.entries(value.values);
+			if (entries.length === 0) return dim("(no entries)");
+			return entries.map(([k, v]) => `${k}:${v}`).join(", ");
+		}
+		case "url": return value.value ? green(`"${value.value}"`) : dim("(empty)");
+		case "url_list": return value.items.length > 0 ? green(`[${value.items.join(", ")}]`) : dim("(empty)");
+		default: return dim("(unknown)");
+	}
+}
+/**
+* Format form responses for console output, showing all fields with their states.
+*/
+function formatConsoleResponses(form, useColors) {
+	const lines = [];
+	const bold = useColors ? pc.bold : (s) => s;
+	const dim = useColors ? pc.dim : (s) => s;
+	for (const [fieldId, response] of Object.entries(form.responsesByFieldId)) {
+		const valueStr = formatFieldResponse(response, useColors);
+		lines.push(`${bold(fieldId)}: ${valueStr}`);
+	}
+	if (lines.length === 0) lines.push(dim("(no fields)"));
+	return lines.join("\n");
+}
+/**
+* Register the dump command.
+*/
+function registerDumpCommand(program) {
+	program.command("dump <file>").description("Extract and display form values with state (lightweight inspect)").action(async (file, _options, cmd) => {
+		const ctx = getCommandContext(cmd);
+		try {
+			logVerbose(ctx, `Reading file: ${file}`);
+			const content = await readFile$1(file);
+			logVerbose(ctx, "Parsing form...");
+			const form = parseForm(content);
+			if (ctx.format === "json" || ctx.format === "yaml") {
+				const output = formatOutput(ctx, {
+					values: toStructuredValues(form),
+					...form.notes.length > 0 && { notes: toNotesArray(form) }
+				}, () => "");
+				console.log(output);
+			} else {
+				const output = formatOutput(ctx, form, (data, useColors) => formatConsoleResponses(data, useColors));
+				console.log(output);
+			}
+		} catch (error) {
+			logError(error instanceof Error ? error.message : String(error));
+			process.exit(1);
+		}
+	});
+}
+
 //#endregion
 //#region src/cli/lib/patchFormat.ts
 /** Maximum characters for a patch value display before truncation */
@@ -477,8 +469,13 @@ function formatPatchValue(patch) {
 		case "set_checkboxes": return truncate(Object.entries(patch.values).map(([k, v]) => `${k}:${v}`).join(", "));
 		case "clear_field": return "(cleared)";
 		case "skip_field": return patch.reason ? truncate(`(skipped: ${patch.reason})`) : "(skipped)";
+		case "abort_field": return patch.reason ? truncate(`(aborted: ${patch.reason})`) : "(aborted)";
 		case "set_url": return patch.value ? truncate(`"${patch.value}"`) : "(empty)";
 		case "set_url_list": return patch.items.length > 0 ? truncate(`[${patch.items.join(", ")}]`) : "(empty)";
+		case "set_date": return patch.value ? truncate(`"${patch.value}"`) : "(empty)";
+		case "set_year": return patch.value !== null ? String(patch.value) : "(empty)";
+		case "add_note": return truncate(`note: ${patch.text}`);
+		case "remove_note": return `(remove note ${patch.noteId})`;
 	}
 }
 /**
@@ -494,46 +491,103 @@ function formatPatchType(patch) {
 		case "set_checkboxes": return "checkboxes";
 		case "clear_field": return "clear";
 		case "skip_field": return "skip";
+		case "abort_field": return "abort";
 		case "set_url": return "url";
 		case "set_url_list": return "url_list";
+		case "set_date": return "date";
+		case "set_year": return "year";
+		case "add_note": return "note";
+		case "remove_note": return "remove_note";
 	}
 }
 
+//#endregion
+//#region src/cli/lib/formatting.ts
+/**
+* Get a short status word from an issue reason.
+*/
+function issueReasonToStatus(reason) {
+	switch (reason) {
+		case "required_missing": return "missing";
+		case "validation_error": return "invalid";
+		case "checkbox_incomplete": return "incomplete";
+		case "min_items_not_met": return "too-few";
+		case "optional_empty": return "empty";
+		default: return "issue";
+	}
+}
+/**
+* Format a single issue as "fieldId (status)".
+*/
+function formatIssueBrief(issue) {
+	const status = issueReasonToStatus(issue.reason);
+	return `${issue.ref} (${status})`;
+}
+/**
+* Format issues for turn logging - shows count and brief field list.
+* Example: "5 issue(s): company_name (missing), revenue (invalid), ..."
+*/
+function formatTurnIssues(issues, maxShow = 5) {
+	const count = issues.length;
+	if (count === 0) return "0 issues";
+	return `${count} issue(s): ${issues.slice(0, maxShow).map(formatIssueBrief).join(", ")}${count > maxShow ? `, +${count - maxShow} more` : ""}`;
+}
+
 //#endregion
 //#region src/cli/examples/exampleRegistry.ts
 /**
 * Example form registry.
 * Provides form content from the examples directory for the examples CLI command.
+*
+* Metadata (title, description) is loaded dynamically from the form's YAML frontmatter
+* rather than being duplicated here, following the single source of truth principle.
+*/
+/**
+* Example definitions without content or metadata.
+* Title and description are loaded dynamically from frontmatter.
 */
-/** Example definitions without content - content is loaded lazily. */
 const EXAMPLE_DEFINITIONS = [
 	{
 		id: "simple",
-		title: "Simple Test Form",
-		description: "User and agent roles for testing full workflow. User fills required fields, agent fills optional.",
 		filename: "simple.form.md",
-		path: "simple/simple.form.md"
+		path: "simple/simple.form.md",
+		type: "fill"
 	},
 	{
-		id: "political-research",
-		title: "Political Research",
-		description: "Biographical research form with one user field (name) and agent-filled details. Uses web search.",
-		filename: "political-research.form.md",
-		path: "political-research/political-research.form.md"
+		id: "movie-research-minimal",
+		filename: "movie-research-minimal.form.md",
+		path: "movie-research/movie-research-minimal.form.md",
+		type: "research"
+	},
+	{
+		id: "movie-research-basic",
+		filename: "movie-research-basic.form.md",
+		path: "movie-research/movie-research-basic.form.md",
+		type: "research"
+	},
+	{
+		id: "movie-research-deep",
+		filename: "movie-research-deep.form.md",
+		path: "movie-research/movie-research-deep.form.md",
+		type: "research"
 	},
 	{
 		id: "earnings-analysis",
-		title: "Company Quarterly Analysis",
-		description: "Financial analysis with one user field (company) and agent-filled quarterly analysis sections.",
 		filename: "earnings-analysis.form.md",
-		path: "earnings-analysis/earnings-analysis.form.md"
+		path: "earnings-analysis/earnings-analysis.form.md",
+		type: "research"
 	},
 	{
 		id: "startup-deep-research",
-		title: "Startup Deep Research",
-		description: "Comprehensive startup intelligence gathering with company info, founders, funding, competitors, social media, and community presence.",
 		filename: "startup-deep-research.form.md",
-		path: "startup-deep-research/startup-deep-research.form.md"
+		path: "startup-deep-research/startup-deep-research.form.md",
+		type: "research"
+	},
+	{
+		id: "celebrity-deep-research",
+		filename: "celebrity-deep-research.form.md",
+		path: "celebrity-deep-research/celebrity-deep-research.form.md",
+		type: "research"
 	}
 ];
 /**
@@ -547,7 +601,7 @@ function getExamplesDir() {
 }
 /**
 * Load the content of an example form.
-* @param exampleId - The example ID (e.g., 'simple', 'political-research')
+* @param exampleId - The example ID (e.g., 'simple', 'celebrity-deep-research')
 * @returns The form content as a string
 * @throws Error if the example is not found
 */
@@ -569,7 +623,7 @@ function getExampleById(id) {
 }
 /**
 * Get the absolute path to an example's source file.
-* @param exampleId - The example ID (e.g., 'simple', 'political-research')
+* @param exampleId - The example ID (e.g., 'simple', 'celebrity-deep-research')
 * @returns The absolute path to the example form file
 * @throws Error if the example is not found
 */
@@ -578,6 +632,48 @@ function getExamplePath(exampleId) {
 	if (!example) throw new Error(`Unknown example: ${exampleId}`);
 	return join(getExamplesDir(), example.path);
 }
+/**
+* Extract YAML frontmatter from a markdown file content.
+* @param content - The markdown file content
+* @returns The parsed frontmatter object or null if no frontmatter found
+*/
+function extractFrontmatter(content) {
+	const frontmatterMatch = content.match(/^---\n([\s\S]*?)\n---/);
+	if (!frontmatterMatch || !frontmatterMatch[1]) return null;
+	try {
+		return YAML.parse(frontmatterMatch[1]);
+	} catch {
+		return null;
+	}
+}
+/**
+* Load metadata (title, description) from an example's YAML frontmatter.
+* @param exampleId - The example ID (e.g., 'simple', 'celebrity-deep-research')
+* @returns Object with title and description from frontmatter
+*/
+function loadExampleMetadata(exampleId) {
+	const frontmatter = extractFrontmatter(loadExampleContent(exampleId));
+	if (!frontmatter || !frontmatter.markform) return {};
+	const markform = frontmatter.markform;
+	return {
+		title: typeof markform.title === "string" ? markform.title : void 0,
+		description: typeof markform.description === "string" ? markform.description : void 0
+	};
+}
+/**
+* Get all example definitions with metadata loaded from frontmatter.
+* @returns Array of ExampleDefinition with title and description populated
+*/
+function getAllExamplesWithMetadata() {
+	return EXAMPLE_DEFINITIONS.map((example) => {
+		const metadata = loadExampleMetadata(example.id);
+		return {
+			...example,
+			title: metadata.title,
+			description: metadata.description
+		};
+	});
+}
 
 //#endregion
 //#region src/cli/lib/versioning.ts
@@ -654,6 +750,29 @@ function generateVersionedPath(filePath) {
 	}
 	return candidate;
 }
+/**
+* Generate a versioned filename within the forms directory.
+*
+* Derives the base name from the input path and creates a versioned
+* output path within the specified forms directory.
+*
+* @param inputPath - Original input file path (used to derive basename)
+* @param formsDir - Absolute path to the forms directory
+* @returns Absolute path to a non-existent versioned file in formsDir
+*/
+function generateVersionedPathInFormsDir(inputPath, formsDir) {
+	const inputFilename = basename(inputPath);
+	const parsed = parseVersionedPath(inputFilename);
+	const baseName = parsed?.base ?? inputFilename.replace(/\.form\.md$/i, "");
+	const extension = parsed?.extension ?? ".form.md";
+	let version = 1;
+	let candidate = join(formsDir, `${baseName}-filled${version}${extension}`);
+	while (existsSync(candidate)) {
+		version++;
+		candidate = join(formsDir, `${baseName}-filled${version}${extension}`);
+	}
+	return candidate;
+}
 
 //#endregion
 //#region src/cli/lib/interactivePrompts.ts
@@ -683,7 +802,7 @@ function getFieldById(form, fieldId) {
 */
 function formatFieldLabel(ctx) {
 	const required = ctx.field.required ? pc.red("*") : "";
-	const progress = pc.dim(`(${ctx.index} of ${ctx.total})`);
+	const progress = `(${ctx.index} of ${ctx.total})`;
 	return `${ctx.field.label}${required} ${progress}`;
 }
 /**
@@ -693,6 +812,7 @@ function createSkipPatch(field) {
 	return {
 		op: "skip_field",
 		fieldId: field.id,
+		role: "user",
 		reason: "User skipped in console"
 	};
 }
@@ -1057,9 +1177,10 @@ async function runInteractiveFill(form, issues) {
 		const field = getFieldById(form, issue.ref);
 		if (!field) continue;
 		index++;
+		const response = form.responsesByFieldId[field.id];
 		const patch = await promptForField({
 			field,
-			currentValue: form.valuesByFieldId[field.id],
+			currentValue: response?.state === "answered" ? response.value : void 0,
 			description: getFieldDescription(form, field.id),
 			index,
 			total: uniqueFieldIssues.length
@@ -1110,6 +1231,183 @@ function showInteractiveOutro(patchCount, cancelled) {
 	p.outro(`✓ ${patchCount} field(s) updated.`);
 }
 
+//#endregion
+//#region src/cli/lib/fileViewer.ts
+/**
+* File viewer utility for displaying files with colorization and pagination.
+*
+* Provides a modern console experience:
+* - Syntax highlighting for markdown and YAML
+* - Pagination using system pager (less) when available
+* - Fallback to console output when not interactive
+*/
+/**
+* Check if stdout is an interactive terminal.
+*/
+function isInteractive$2() {
+	return process.stdout.isTTY === true;
+}
+/**
+* Apply terminal formatting to markdown content.
+* Colorizes headers, code blocks, and other elements.
+*/
+function formatMarkdown$2(content) {
+	const lines = content.split("\n");
+	const formatted = [];
+	let inCodeBlock = false;
+	for (const line of lines) {
+		if (line.startsWith("```")) {
+			inCodeBlock = !inCodeBlock;
+			formatted.push(pc.dim(line));
+			continue;
+		}
+		if (inCodeBlock) {
+			formatted.push(pc.cyan(line));
+			continue;
+		}
+		if (line.startsWith("# ")) {
+			formatted.push(pc.bold(pc.magenta(line)));
+			continue;
+		}
+		if (line.startsWith("## ")) {
+			formatted.push(pc.bold(pc.blue(line)));
+			continue;
+		}
+		if (line.startsWith("### ")) {
+			formatted.push(pc.bold(pc.cyan(line)));
+			continue;
+		}
+		if (line.startsWith("#### ")) {
+			formatted.push(pc.bold(line));
+			continue;
+		}
+		let formattedLine = line.replace(/`([^`]+)`/g, (_match, code) => {
+			return pc.yellow(code);
+		});
+		formattedLine = formattedLine.replace(/\*\*([^*]+)\*\*/g, (_match, text) => {
+			return pc.bold(text);
+		});
+		formattedLine = formattedLine.replace(/\[([^\]]+)\]\(([^)]+)\)/g, (_match, text, url) => {
+			return `${pc.cyan(text)} ${pc.dim(`(${url})`)}`;
+		});
+		formattedLine = formattedLine.replace(/\{%\s*(\w+)\s*([^%]*)\s*%\}/g, (_match, tag, attrs) => {
+			return `${pc.dim("{% ")}${pc.green(tag)}${pc.dim(attrs)} ${pc.dim("%}")}`;
+		});
+		formatted.push(formattedLine);
+	}
+	return formatted.join("\n");
+}
+/**
+* Apply terminal formatting to YAML content.
+*/
+function formatYaml(content) {
+	const lines = content.split("\n");
+	const formatted = [];
+	for (const line of lines) {
+		if (line.trim().startsWith("#")) {
+			formatted.push(pc.dim(line));
+			continue;
+		}
+		const match = /^(\s*)([^:]+)(:)(.*)$/.exec(line);
+		if (match) {
+			const [, indent, key, colon, value] = match;
+			formatted.push(`${indent}${pc.cyan(key)}${pc.dim(colon)}${pc.yellow(value)}`);
+			continue;
+		}
+		if (line.trim().startsWith("-")) {
+			formatted.push(pc.green(line));
+			continue;
+		}
+		formatted.push(line);
+	}
+	return formatted.join("\n");
+}
+/**
+* Format file content based on extension.
+*/
+function formatContent(content, filename) {
+	if (filename.endsWith(".yml") || filename.endsWith(".yaml")) return formatYaml(content);
+	if (filename.endsWith(".md")) return formatMarkdown$2(content);
+	return content;
+}
+/**
+* Display content using system pager (less) if available.
+* Falls back to console.log if not interactive or pager unavailable.
+*
+* @returns Promise that resolves when viewing is complete
+*/
+async function displayWithPager(content, title) {
+	if (!isInteractive$2()) {
+		console.log(content);
+		return;
+	}
+	const header = `${pc.bgCyan(pc.black(` ${title} `))}`;
+	return new Promise((resolve$1) => {
+		const pager = spawn("less", [
+			"-R",
+			"-S",
+			"-X",
+			"-F",
+			"-K"
+		], { stdio: [
+			"pipe",
+			"inherit",
+			"inherit"
+		] });
+		pager.on("error", () => {
+			console.log(header);
+			console.log("");
+			console.log(content);
+			console.log("");
+			resolve$1();
+		});
+		pager.on("close", () => {
+			resolve$1();
+		});
+		pager.stdin.write(header + "\n\n");
+		pager.stdin.write(content);
+		pager.stdin.end();
+	});
+}
+/**
+* Load and display a file with formatting and pagination.
+*/
+async function viewFile(filePath) {
+	const content = readFileSync(filePath, "utf-8");
+	const filename = basename(filePath);
+	await displayWithPager(formatContent(content, filename), filename);
+}
+/**
+* Show an interactive file viewer chooser.
+*
+* Presents a list of files to view with descriptions, plus a Skip option.
+* Loops until the user selects Skip.
+*
+* @param files Array of file options to display
+*/
+async function showFileViewerChooser(files) {
+	if (!isInteractive$2()) return;
+	console.log("");
+	while (true) {
+		const options = [...files.map((file) => ({
+			value: file.path,
+			label: pc.green(basename(file.path)),
+			hint: file.hint ?? ""
+		})), {
+			value: "skip",
+			label: "Done viewing",
+			hint: "exit file viewer"
+		}];
+		const selection = await p.select({
+			message: "View an output file?",
+			options
+		});
+		if (p.isCancel(selection) || selection === "skip") break;
+		await viewFile(selection);
+		console.log("");
+	}
+}
+
 //#endregion
 //#region src/cli/commands/examples.ts
 /**
@@ -1117,10 +1415,12 @@ function showInteractiveOutro(patchCount, cancelled) {
 */
 function printExamplesList() {
 	console.log(pc.bold("Available examples:\n"));
-	for (const example of EXAMPLE_DEFINITIONS) {
-		console.log(`  ${pc.cyan(example.id)}`);
-		console.log(`    ${pc.bold(example.title)}`);
-		console.log(`    ${pc.dim(example.description)}`);
+	const examples = getAllExamplesWithMetadata();
+	for (const example of examples) {
+		const typeLabel = example.type === "research" ? pc.magenta("[research]") : pc.blue("[fill]");
+		console.log(`  ${pc.cyan(example.id)} ${typeLabel}`);
+		console.log(`    ${pc.bold(example.title ?? example.id)}`);
+		console.log(`    ${example.description ?? "No description"}`);
 		console.log(`    Source: ${formatPath(getExamplePath(example.id))}`);
 		console.log("");
 	}
@@ -1129,12 +1429,12 @@ function printExamplesList() {
 * Display API availability status at startup.
 */
 function showApiStatus() {
-	console.log(pc.dim("API Status:"));
+	console.log("API Status:");
 	for (const [provider, _models] of Object.entries(SUGGESTED_LLMS)) {
 		const info = getProviderInfo(provider);
 		const hasKey = !!process.env[info.envVar];
-		const status = hasKey ? pc.green("✓") : pc.dim("○");
-		const envVar = hasKey ? pc.dim(info.envVar) : pc.yellow(info.envVar);
+		const status = hasKey ? pc.green("✓") : "○";
+		const envVar = hasKey ? info.envVar : pc.yellow(info.envVar);
 		console.log(`  ${status} ${provider} (${envVar})`);
 	}
 	console.log("");
@@ -1146,7 +1446,7 @@ function buildModelOptions() {
 	const options = [];
 	for (const [provider, models] of Object.entries(SUGGESTED_LLMS)) {
 		const info = getProviderInfo(provider);
-		const keyStatus = !!process.env[info.envVar] ? pc.green("✓") : pc.dim("○");
+		const keyStatus = !!process.env[info.envVar] ? pc.green("✓") : "○";
 		for (const model of models) options.push({
 			value: `${provider}/${model}`,
 			label: `${provider}/${model}`,
@@ -1184,39 +1484,91 @@ async function promptForModel() {
 	return selection;
 }
 /**
+* Build model options filtered to providers with web search support.
+*/
+function buildWebSearchModelOptions() {
+	const options = [];
+	for (const [provider, models] of Object.entries(SUGGESTED_LLMS)) {
+		if (!hasWebSearchSupport(provider)) continue;
+		const info = getProviderInfo(provider);
+		const keyStatus = !!process.env[info.envVar] ? pc.green("✓") : "○";
+		for (const model of models) options.push({
+			value: `${provider}/${model}`,
+			label: `${provider}/${model}`,
+			hint: `${keyStatus} ${info.envVar}`
+		});
+	}
+	options.push({
+		value: "custom",
+		label: "Enter custom model ID...",
+		hint: "provider/model-id format"
+	});
+	return options;
+}
+/**
+* Prompt user to select a model with web search capability for research workflow.
+*/
+async function promptForWebSearchModel() {
+	const modelOptions = buildWebSearchModelOptions();
+	if (modelOptions.length === 1) p.log.warn("No web-search-capable providers found. OpenAI, Google, or xAI API key required.");
+	const selection = await p.select({
+		message: "Select LLM model (web search required):",
+		options: modelOptions
+	});
+	if (p.isCancel(selection)) return null;
+	if (selection === "custom") {
+		const customModel = await p.text({
+			message: "Model ID (provider/model-id):",
+			placeholder: "openai/gpt-5-mini",
+			validate: (value) => {
+				if (!value.includes("/")) return "Format: provider/model-id (e.g., openai/gpt-5-mini)";
+			}
+		});
+		if (p.isCancel(customModel)) return null;
+		return customModel;
+	}
+	return selection;
+}
+/**
 * Run the agent fill workflow.
+* Accepts optional harness config overrides - research uses different defaults.
 */
-async function runAgentFill(form, modelId, _outputPath) {
+async function runAgentFill(form, modelId, _outputPath, configOverrides) {
 	const spinner = p.spinner();
 	try {
 		spinner.start(`Resolving model: ${modelId}`);
-		const { model } = await resolveModel(modelId);
+		const { model, provider } = await resolveModel(modelId);
 		spinner.stop(`Model resolved: ${modelId}`);
 		const harnessConfig = {
-			maxTurns: DEFAULT_MAX_TURNS,
-			maxPatchesPerTurn: DEFAULT_MAX_PATCHES_PER_TURN,
-			maxIssues: DEFAULT_MAX_ISSUES,
+			maxTurns: configOverrides?.maxTurns ?? DEFAULT_MAX_TURNS,
+			maxPatchesPerTurn: configOverrides?.maxPatchesPerTurn ?? DEFAULT_MAX_PATCHES_PER_TURN,
+			maxIssuesPerTurn: configOverrides?.maxIssuesPerTurn ?? DEFAULT_MAX_ISSUES_PER_TURN,
 			targetRoles: [AGENT_ROLE],
 			fillMode: "continue"
 		};
+		console.log("");
+		console.log(`Config: max_turns=${harnessConfig.maxTurns}, max_issues_per_turn=${harnessConfig.maxIssuesPerTurn}, max_patches_per_turn=${harnessConfig.maxPatchesPerTurn}`);
 		const harness = createHarness(form, harnessConfig);
 		const agent = createLiveAgent({
 			model,
+			provider,
 			targetRole: AGENT_ROLE
 		});
-		console.log("");
 		p.log.step(pc.bold("Agent fill in progress..."));
 		let stepResult = harness.step();
 		while (!stepResult.isComplete && !harness.hasReachedMaxTurns()) {
-			console.log(pc.dim(`  Turn ${stepResult.turnNumber}: ${stepResult.issues.length} issue(s) to address`));
-			const { patches } = await agent.generatePatches(stepResult.issues, harness.getForm(), harnessConfig.maxPatchesPerTurn);
+			console.log(`  ${pc.bold(`Turn ${stepResult.turnNumber}:`)} ${formatTurnIssues(stepResult.issues)}`);
+			const { patches, stats } = await agent.generatePatches(stepResult.issues, harness.getForm(), harnessConfig.maxPatchesPerTurn);
 			for (const patch of patches) {
 				const typeName = formatPatchType(patch);
 				const value = formatPatchValue(patch);
-				console.log(pc.dim(`    ${pc.cyan(patch.fieldId)} (${typeName}) = ${pc.green(value)}`));
+				const fieldId = "fieldId" in patch ? patch.fieldId : patch.op === "add_note" ? patch.ref : "";
+				if (fieldId) console.log(`    ${pc.cyan(fieldId)} (${typeName}) = ${pc.green(value)}`);
+				else console.log(`    (${typeName}) = ${pc.green(value)}`);
 			}
 			stepResult = harness.apply(patches, stepResult.issues);
-			console.log(pc.dim(`    ${patches.length} patch(es) applied, ${stepResult.issues.length} remaining`));
+			const tokenInfo = stats ? ` ${pc.dim(`(tokens: ↓${stats.inputTokens ?? 0} ↑${stats.outputTokens ?? 0})`)}` : "";
+			console.log(`    ${patches.length} patch(es) applied, ${stepResult.issues.length} remaining${tokenInfo}`);
 			if (!stepResult.isComplete && !harness.hasReachedMaxTurns()) stepResult = harness.step();
 		}
 		if (stepResult.isComplete) p.log.success(pc.green(`Form completed in ${harness.getTurnNumber()} turn(s)`));
@@ -1233,18 +1585,24 @@ async function runAgentFill(form, modelId, _outputPath) {
 }
 /**
 * Run the interactive example scaffolding and filling flow.
+*
+* @param preselectedId Optional example ID to pre-select
+* @param formsDirOverride Optional forms directory override from CLI option
 */
-async function runInteractiveFlow(preselectedId) {
+async function runInteractiveFlow(preselectedId, formsDirOverride) {
 	const startTime = Date.now();
 	p.intro(pc.bgCyan(pc.black(" markform examples ")));
+	const formsDir = getFormsDir(formsDirOverride);
+	await ensureFormsDir(formsDir);
 	showApiStatus();
 	let selectedId = preselectedId;
 	if (!selectedId) {
+		const examples = getAllExamplesWithMetadata();
 		const selection = await p.select({
 			message: "Select an example form to scaffold:",
-			options: EXAMPLE_DEFINITIONS.map((example$1) => ({
+			options: examples.map((example$1) => ({
 				value: example$1.id,
-				label: example$1.title,
+				label: example$1.title ?? example$1.id,
 				hint: example$1.description
 			}))
 		});
@@ -1259,9 +1617,9 @@ async function runInteractiveFlow(preselectedId) {
 		p.cancel(`Unknown example: ${selectedId}`);
 		process.exit(1);
 	}
-	const defaultFilename = generateVersionedPath(example.filename);
+	const defaultFilename = basename(generateVersionedPathInFormsDir(example.filename, formsDir));
 	const filenameResult = await p.text({
-		message: "Output filename:",
+		message: `Output filename (in ${formatPath(formsDir)}):`,
 		initialValue: defaultFilename,
 		validate: (value) => {
 			if (!value.trim()) return "Filename is required";
@@ -1273,7 +1631,7 @@ async function runInteractiveFlow(preselectedId) {
 		process.exit(0);
 	}
 	const filename = filenameResult;
-	const outputPath = join(process.cwd(), filename);
+	const outputPath = join(formsDir, filename);
 	if (existsSync(outputPath)) {
 		const overwrite = await p.confirm({
 			message: `${filename} already exists. Overwrite?`,
@@ -1287,7 +1645,7 @@ async function runInteractiveFlow(preselectedId) {
 	let content;
 	try {
 		content = loadExampleContent(selectedId);
-		writeFileSync(outputPath, content, "utf-8");
+		await writeFile(outputPath, content);
 	} catch (error) {
 		const message = error instanceof Error ? error.message : String(error);
 		p.cancel(`Failed to write file: ${message}`);
@@ -1296,6 +1654,7 @@ async function runInteractiveFlow(preselectedId) {
 	p.log.success(`Created ${formatPath(outputPath)}`);
 	const form = parseForm(content);
 	const targetRoles = [USER_ROLE];
+	let userFillOutputs = null;
 	const inspectResult = inspect(form, { targetRoles });
 	const fieldIssues = inspectResult.issues.filter((i) => i.scope === "field");
 	const uniqueFieldIds = new Set(fieldIssues.map((i) => i.ref));
@@ -1308,7 +1667,7 @@ async function runInteractiveFlow(preselectedId) {
 				dryRun: false,
 				quiet: false
 			}, "Total time", Date.now() - startTime);
-			p.outro(pc.dim("Form scaffolded with no fields to fill."));
+			p.outro("Form scaffolded with no fields to fill.");
 			return;
 		}
 	} else {
@@ -1319,13 +1678,13 @@ async function runInteractiveFlow(preselectedId) {
 			process.exit(1);
 		}
 		if (patches.length > 0) applyPatches(form, patches);
-		const { formPath, rawPath, yamlPath } = exportMultiFormat(form, outputPath);
+		userFillOutputs = await exportMultiFormat(form, outputPath);
 		showInteractiveOutro(patches.length, false);
 		console.log("");
 		p.log.success("Outputs:");
-		console.log(`  ${formatPath(formPath)}  ${pc.dim("(markform)")}`);
-		console.log(`  ${formatPath(rawPath)}  ${pc.dim("(plain markdown)")}`);
-		console.log(`  ${formatPath(yamlPath)}  ${pc.dim("(values as YAML)")}`);
+		console.log(`  ${formatPath(userFillOutputs.formPath)}  ${pc.dim("(markform)")}`);
+		console.log(`  ${formatPath(userFillOutputs.rawPath)}  ${pc.dim("(plain markdown)")}`);
+		console.log(`  ${formatPath(userFillOutputs.yamlPath)}  ${pc.dim("(values as YAML)")}`);
 		logTiming({
 			verbose: false,
 			format: "console",
@@ -1334,29 +1693,50 @@ async function runInteractiveFlow(preselectedId) {
 		}, "Fill time", Date.now() - startTime);
 	}
 	const agentFieldIssues = inspect(form, { targetRoles: [AGENT_ROLE] }).issues.filter((i) => i.scope === "field");
+	const isResearchExample = example.type === "research";
 	if (agentFieldIssues.length > 0) {
 		console.log("");
+		const workflowLabel = isResearchExample ? "research" : "agent fill";
 		p.log.info(`This form has ${agentFieldIssues.length} agent-role field(s) remaining.`);
+		const confirmMessage = isResearchExample ? "Run research now? (requires web search)" : "Run agent fill now?";
 		const runAgent = await p.confirm({
-			message: "Run agent fill now?",
+			message: confirmMessage,
 			initialValue: true
 		});
 		if (p.isCancel(runAgent) || !runAgent) {
 			console.log("");
-			console.log(pc.dim("You can run agent fill later with:"));
-			console.log(pc.dim(`  markform fill ${formatPath(outputPath)} --model=<provider/model>`));
-			p.outro(pc.dim("Happy form filling!"));
+			const cliCommand = isResearchExample ? `  markform research ${formatPath(outputPath)} --model=<provider/model>` : `  markform fill ${formatPath(outputPath)} --model=<provider/model>`;
+			console.log(`You can run ${workflowLabel} later with:`);
+			console.log(cliCommand);
+			if (userFillOutputs) await showFileViewerChooser([
+				{
+					path: userFillOutputs.formPath,
+					label: "Markform",
+					hint: "form with tags"
+				},
+				{
+					path: userFillOutputs.rawPath,
+					label: "Plain Markdown",
+					hint: "rendered output"
+				},
+				{
+					path: userFillOutputs.yamlPath,
+					label: "YAML",
+					hint: "extracted values"
+				}
+			]);
+			p.outro("Happy form filling!");
 			return;
 		}
-		const modelId = await promptForModel();
+		const modelId = isResearchExample ? await promptForWebSearchModel() : await promptForModel();
 		if (!modelId) {
 			p.cancel("Cancelled.");
 			process.exit(0);
 		}
-		const agentDefaultFilename = generateVersionedPath(outputPath);
+		const agentDefaultFilename = basename(generateVersionedPathInFormsDir(outputPath, formsDir));
 		const agentFilenameResult = await p.text({
-			message: "Agent output filename:",
-			initialValue: basename(agentDefaultFilename),
+			message: `Agent output filename (in ${formatPath(formsDir)}):`,
+			initialValue: agentDefaultFilename,
 			validate: (value) => {
 				if (!value.trim()) return "Filename is required";
 			}
@@ -1365,39 +1745,64 @@ async function runInteractiveFlow(preselectedId) {
 			p.cancel("Cancelled.");
 			process.exit(0);
 		}
-		const agentOutputPath = join(process.cwd(), agentFilenameResult);
+		const agentOutputPath = join(formsDir, agentFilenameResult);
 		const agentStartTime = Date.now();
+		const timingLabel = isResearchExample ? "Research time" : "Agent fill time";
+		const configOverrides = isResearchExample ? {
+			maxIssuesPerTurn: DEFAULT_RESEARCH_MAX_ISSUES_PER_TURN,
+			maxPatchesPerTurn: DEFAULT_RESEARCH_MAX_PATCHES_PER_TURN
+		} : void 0;
 		try {
-			const { success, turnCount: _turnCount } = await runAgentFill(form, modelId, agentOutputPath);
+			const { success } = await runAgentFill(form, modelId, agentOutputPath, configOverrides);
 			logTiming({
 				verbose: false,
 				format: "console",
 				dryRun: false,
 				quiet: false
-			}, "Agent fill time", Date.now() - agentStartTime);
-			const { formPath, rawPath, yamlPath } = exportMultiFormat(form, agentOutputPath);
+			}, timingLabel, Date.now() - agentStartTime);
+			const { formPath, rawPath, yamlPath } = await exportMultiFormat(form, agentOutputPath);
 			console.log("");
-			p.log.success("Agent fill complete. Outputs:");
-			console.log(`  ${formatPath(formPath)}  ${pc.dim("(markform)")}`);
-			console.log(`  ${formatPath(rawPath)}  ${pc.dim("(plain markdown)")}`);
-			console.log(`  ${formatPath(yamlPath)}  ${pc.dim("(values as YAML)")}`);
+			const successMessage = isResearchExample ? "Research complete. Outputs:" : "Agent fill complete. Outputs:";
+			p.log.success(successMessage);
+			console.log(`  ${formatPath(formPath)}  (markform)`);
+			console.log(`  ${formatPath(rawPath)}  (plain markdown)`);
+			console.log(`  ${formatPath(yamlPath)}  (values as YAML)`);
 			if (!success) p.log.warn("Agent did not complete all fields. You may need to run it again.");
+			await showFileViewerChooser([
+				{
+					path: formPath,
+					label: "Markform",
+					hint: "form with tags"
+				},
+				{
+					path: rawPath,
+					label: "Plain Markdown",
+					hint: "rendered output"
+				},
+				{
+					path: yamlPath,
+					label: "YAML",
+					hint: "extracted values"
+				}
+			]);
 		} catch (error) {
 			const message = error instanceof Error ? error.message : String(error);
-			p.log.error(`Agent fill failed: ${message}`);
+			const failMessage = isResearchExample ? "Research failed" : "Agent fill failed";
+			p.log.error(`${failMessage}: ${message}`);
 			console.log("");
-			console.log(pc.dim("You can try again with:"));
-			console.log(pc.dim(`  markform fill ${formatPath(outputPath)} --model=${modelId}`));
+			console.log("You can try again with:");
+			const retryCommand = isResearchExample ? `  markform research ${formatPath(outputPath)} --model=${modelId}` : `  markform fill ${formatPath(outputPath)} --model=${modelId}`;
+			console.log(retryCommand);
 		}
 	}
-	p.outro(pc.dim("Happy form filling!"));
+	p.outro("Happy form filling!");
 }
 /**
 * Register the examples command.
 */
 function registerExamplesCommand(program) {
-	program.command("examples").description("Scaffold an example form and fill it interactively").option("--list", "List available examples without interactive selection").option("--name <example>", "Select example by ID (still prompts for filename)").action(async (options, cmd) => {
-		getCommandContext(cmd);
+	program.command("examples").description("Try out some example forms interactively using the console").option("--list", "List available examples without interactive selection").option("--name <example>", "Select example by ID (still prompts for filename)").action(async (options, cmd) => {
+		const ctx = getCommandContext(cmd);
 		try {
 			if (options.list) {
 				printExamplesList();
@@ -1411,7 +1816,7 @@ function registerExamplesCommand(program) {
 					process.exit(1);
 				}
 			}
-			await runInteractiveFlow(options.name);
+			await runInteractiveFlow(options.name, ctx.formsDir);
 		} catch (error) {
 			logError(error instanceof Error ? error.message : String(error));
 			process.exit(1);
@@ -1434,7 +1839,7 @@ function registerExportCommand(program) {
 		else if (ctx.format === "markform") format = "markform";
 		try {
 			logVerbose(ctx, `Reading file: ${file}`);
-			const content = await readFile(file);
+			const content = await readFile$1(file);
 			logVerbose(ctx, "Parsing form...");
 			const form = parseForm(content);
 			if (format === "markform") {
@@ -1445,26 +1850,30 @@ function registerExportCommand(program) {
 				console.log(serializeRawMarkdown(form));
 				return;
 			}
-			const output = {
-				schema: {
-					id: form.schema.id,
-					title: form.schema.title,
-					groups: form.schema.groups.map((group) => ({
-						id: group.id,
-						title: group.title,
-						children: group.children.map((field) => ({
-							id: field.id,
-							kind: field.kind,
-							label: field.label,
-							required: field.required,
-							...field.kind === "single_select" || field.kind === "multi_select" || field.kind === "checkboxes" ? { options: field.options.map((opt) => ({
-								id: opt.id,
-								label: opt.label
-							})) } : {}
-						}))
+			const schema = {
+				id: form.schema.id,
+				title: form.schema.title,
+				groups: form.schema.groups.map((group) => ({
+					id: group.id,
+					title: group.title,
+					children: group.children.map((field) => ({
+						id: field.id,
+						kind: field.kind,
+						label: field.label,
+						required: field.required,
+						...field.kind === "single_select" || field.kind === "multi_select" || field.kind === "checkboxes" ? { options: field.options.map((opt) => ({
+							id: opt.id,
+							label: opt.label
+						})) } : {}
 					}))
-				},
-				values: form.valuesByFieldId,
+				}))
+			};
+			const values = {};
+			for (const [fieldId, response] of Object.entries(form.responsesByFieldId)) if (response.state === "answered" && response.value) values[fieldId] = response.value;
+			const output = {
+				schema,
+				values,
+				notes: form.notes,
 				markdown: serialize(form)
 			};
 			if (format === "json") if (options.compact) console.log(JSON.stringify(output));
@@ -1498,7 +1907,7 @@ function formatConsoleSession(transcript, useColors) {
 	lines.push(bold("Harness Config:"));
 	lines.push(`  Max turns: ${transcript.harness.maxTurns}`);
 	lines.push(`  Max patches/turn: ${transcript.harness.maxPatchesPerTurn}`);
-	lines.push(`  Max issues: ${transcript.harness.maxIssues}`);
+	lines.push(`  Max issues/turn: ${transcript.harness.maxIssuesPerTurn}`);
 	lines.push("");
 	lines.push(bold(`Turns (${transcript.turns.length}):`));
 	for (const turn of transcript.turns) {
@@ -1517,7 +1926,7 @@ function formatConsoleSession(transcript, useColors) {
 * Register the fill command.
 */
 function registerFillCommand(program) {
-	program.command("fill <file>").description("Run an agent to autonomously fill a form").option("--mock", "Use mock agent (requires --mock-source)").option("--model <id>", "Model ID for live agent (format: provider/model-id, e.g. openai/gpt-4o)").option("--mock-source <file>", "Path to completed form for mock agent").option("--record <file>", "Record session transcript to file").option("--max-turns <n>", `Maximum turns (default: ${DEFAULT_MAX_TURNS})`, String(DEFAULT_MAX_TURNS)).option("--max-patches <n>", `Maximum patches per turn (default: ${DEFAULT_MAX_PATCHES_PER_TURN})`, String(DEFAULT_MAX_PATCHES_PER_TURN)).option("--max-issues <n>", `Maximum issues shown per turn (default: ${DEFAULT_MAX_ISSUES})`, String(DEFAULT_MAX_ISSUES)).option("--max-fields <n>", "Maximum unique fields per turn (applied before --max-issues)").option("--max-groups <n>", "Maximum unique groups per turn (applied before --max-issues)").option("--roles <roles>", "Target roles to fill (comma-separated, or '*' for all; default: 'agent', or 'user' in --interactive mode)").option("--mode <mode>", "Fill mode: continue (skip filled fields) or overwrite (re-fill; default: continue)").option("-o, --output <file>", "Write final form to file").option("--prompt <file>", "Path to custom system prompt file (appends to default)").option("--instructions <text>", "Inline system prompt (appends to default; takes precedence over --prompt)").option("-i, --interactive", "Interactive mode: prompt user for field values (defaults to user role)").action(async (file, options, cmd) => {
+	program.command("fill <file>").description("Run an agent to autonomously fill a form").option("--mock", "Use mock agent (requires --mock-source)").option("--model <id>", "Model ID for live agent (format: provider/model-id, e.g. openai/gpt-5-mini)").option("--mock-source <file>", "Path to completed form for mock agent").option("--record <file>", "Record session transcript to file").option("--max-turns <n>", `Maximum turns (default: ${DEFAULT_MAX_TURNS})`, String(DEFAULT_MAX_TURNS)).option("--max-patches <n>", `Maximum patches per turn (default: ${DEFAULT_MAX_PATCHES_PER_TURN})`, String(DEFAULT_MAX_PATCHES_PER_TURN)).option("--max-issues <n>", `Maximum issues shown per turn (default: ${DEFAULT_MAX_ISSUES_PER_TURN})`, String(DEFAULT_MAX_ISSUES_PER_TURN)).option("--max-fields <n>", "Maximum unique fields per turn (applied before --max-issues)").option("--max-groups <n>", "Maximum unique groups per turn (applied before --max-issues)").option("--roles <roles>", "Target roles to fill (comma-separated, or '*' for all; default: 'agent', or 'user' in --interactive mode)").option("--mode <mode>", "Fill mode: continue (skip filled fields) or overwrite (re-fill; default: continue)").option("-o, --output <file>", "Write final form to file").option("--prompt <file>", "Path to custom system prompt file (appends to default)").option("--instructions <text>", "Inline system prompt (appends to default; takes precedence over --prompt)").option("-i, --interactive", "Interactive mode: prompt user for field values (defaults to user role)").action(async (file, options, cmd) => {
 		const ctx = getCommandContext(cmd);
 		const filePath = resolve(file);
 		try {
@@ -1539,7 +1948,7 @@ function registerFillCommand(program) {
 				fillMode = options.mode;
 			}
 			logVerbose(ctx, `Reading form: ${filePath}`);
-			const formContent = await readFile(filePath);
+			const formContent = await readFile$1(filePath);
 			logVerbose(ctx, "Parsing form...");
 			const form = parseForm(formContent);
 			if (options.interactive) {
@@ -1567,12 +1976,18 @@ function registerFillCommand(program) {
 				}
 				if (patches.length > 0) applyPatches(form, patches);
 				const durationMs$1 = Date.now() - startTime;
-				const outputPath$1 = options.output ? resolve(options.output) : generateVersionedPath(filePath);
+				let outputPath$1;
+				if (options.output) outputPath$1 = resolve(options.output);
+				else {
+					const formsDir = getFormsDir(ctx.formsDir);
+					await ensureFormsDir(formsDir);
+					outputPath$1 = generateVersionedPathInFormsDir(filePath, formsDir);
+				}
 				if (ctx.dryRun) {
 					logInfo(ctx, `[DRY RUN] Would write form to: ${outputPath$1}`);
 					showInteractiveOutro(patches.length, false);
 				} else {
-					const { formPath, rawPath, yamlPath } = exportMultiFormat(form, outputPath$1);
+					const { formPath, rawPath, yamlPath } = await exportMultiFormat(form, outputPath$1);
 					showInteractiveOutro(patches.length, false);
 					console.log("");
 					p.log.success("Outputs:");
@@ -1583,8 +1998,8 @@ function registerFillCommand(program) {
 				logTiming(ctx, "Fill time", durationMs$1);
 				if (patches.length > 0) {
 					console.log("");
-					console.log(pc.dim("Next step: fill remaining fields with agent"));
-					console.log(pc.dim(`  markform fill ${formatPath(outputPath$1)} --model=<provider/model>`));
+					console.log("Next step: fill remaining fields with agent");
+					console.log(`  markform fill ${formatPath(outputPath$1)} --model=<provider/model>`);
 				}
 				process.exit(0);
 			}
@@ -1599,22 +2014,22 @@ function registerFillCommand(program) {
 				process.exit(1);
 			}
 			if (targetRoles.includes("*")) logWarn(ctx, "Warning: Filling all roles including user-designated fields");
-			const harnessConfig = {
-				maxTurns: parseInt(options.maxTurns ?? String(DEFAULT_MAX_TURNS), 10),
-				maxPatchesPerTurn: parseInt(options.maxPatches ?? String(DEFAULT_MAX_PATCHES_PER_TURN), 10),
-				maxIssues: parseInt(options.maxIssues ?? String(DEFAULT_MAX_ISSUES), 10),
-				...options.maxFields && { maxFieldsPerTurn: parseInt(options.maxFields, 10) },
-				...options.maxGroups && { maxGroupsPerTurn: parseInt(options.maxGroups, 10) },
+			const harnessConfig = resolveHarnessConfig(form, {
+				maxTurns: options.maxTurns ? parseInt(options.maxTurns, 10) : void 0,
+				maxPatchesPerTurn: options.maxPatches ? parseInt(options.maxPatches, 10) : void 0,
+				maxIssuesPerTurn: options.maxIssues ? parseInt(options.maxIssues, 10) : void 0,
+				maxFieldsPerTurn: options.maxFields ? parseInt(options.maxFields, 10) : void 0,
+				maxGroupsPerTurn: options.maxGroups ? parseInt(options.maxGroups, 10) : void 0,
 				targetRoles,
 				fillMode
-			};
+			});
 			const harness = createHarness(form, harnessConfig);
 			let agent;
 			let mockPath;
 			if (options.mock) {
 				mockPath = resolve(options.mockSource);
 				logVerbose(ctx, `Reading mock source: ${mockPath}`);
-				agent = createMockAgent(parseForm(await readFile(mockPath)));
+				agent = createMockAgent(parseForm(await readFile$1(mockPath)));
 			} else {
 				const modelId = options.model;
 				logVerbose(ctx, `Resolving model: ${modelId}`);
@@ -1626,7 +2041,7 @@ function registerFillCommand(program) {
 				} else if (options.prompt) {
 					const promptPath = resolve(options.prompt);
 					logVerbose(ctx, `Reading system prompt from: ${promptPath}`);
-					systemPrompt = await readFile(promptPath);
+					systemPrompt = await readFile$1(promptPath);
 				}
 				const primaryRole = targetRoles[0] === "*" ? AGENT_ROLE : targetRoles[0];
 				const liveAgent = createLiveAgent({
@@ -1643,21 +2058,24 @@ function registerFillCommand(program) {
 			logInfo(ctx, `Agent: ${options.mock ? "mock" : "live"}${options.model ? ` (${options.model})` : ""}`);
 			logVerbose(ctx, `Max turns: ${harnessConfig.maxTurns}`);
 			logVerbose(ctx, `Max patches per turn: ${harnessConfig.maxPatchesPerTurn}`);
-			logVerbose(ctx, `Max issues per step: ${harnessConfig.maxIssues}`);
+			logVerbose(ctx, `Max issues per turn: ${harnessConfig.maxIssuesPerTurn}`);
 			logVerbose(ctx, `Target roles: ${targetRoles.includes("*") ? "*" : targetRoles.join(", ")}`);
 			logVerbose(ctx, `Fill mode: ${fillMode}`);
 			let stepResult = harness.step();
-			logInfo(ctx, `Turn ${pc.bold(String(stepResult.turnNumber))}: ${pc.yellow(String(stepResult.issues.length))} issues`);
+			logInfo(ctx, `${pc.bold(`Turn ${stepResult.turnNumber}:`)} ${formatTurnIssues(stepResult.issues)}`);
 			while (!stepResult.isComplete && !harness.hasReachedMaxTurns()) {
 				const { patches, stats } = await agent.generatePatches(stepResult.issues, harness.getForm(), harnessConfig.maxPatchesPerTurn);
-				logInfo(ctx, `  → ${pc.yellow(String(patches.length))} patches:`);
+				const tokenSuffix = stats ? ` ${pc.dim(`(tokens: ↓${stats.inputTokens ?? 0} ↑${stats.outputTokens ?? 0})`)}` : "";
+				logInfo(ctx, `  → ${pc.yellow(String(patches.length))} patches${tokenSuffix}:`);
 				for (const patch of patches) {
 					const typeName = formatPatchType(patch);
 					const value = formatPatchValue(patch);
-					logInfo(ctx, `    ${pc.cyan(patch.fieldId)} ${pc.dim(`(${typeName})`)} ${pc.dim("=")} ${pc.green(value)}`);
+					const fieldId = "fieldId" in patch ? patch.fieldId : patch.op === "add_note" ? patch.ref : "";
+					if (fieldId) logInfo(ctx, `    ${pc.cyan(fieldId)} ${pc.dim(`(${typeName})`)} = ${pc.green(value)}`);
+					else logInfo(ctx, `    ${pc.dim(`(${typeName})`)} = ${pc.green(value)}`);
 				}
 				if (stats) {
-					logVerbose(ctx, `  Stats: ${stats.inputTokens ?? 0} in / ${stats.outputTokens ?? 0} out tokens`);
+					logVerbose(ctx, `  Stats: tokens ↓${stats.inputTokens ?? 0} ↑${stats.outputTokens ?? 0}`);
 					if (stats.toolCalls.length > 0) logVerbose(ctx, `  Tools: ${stats.toolCalls.map((t) => `${t.name}(${t.count})`).join(", ")}`);
 					if (stats.prompts) {
 						logVerbose(ctx, ``);
@@ -1679,14 +2097,20 @@ function registerFillCommand(program) {
 				if (stepResult.isComplete) logInfo(ctx, pc.green(`  ✓ Complete`));
 				else if (!harness.hasReachedMaxTurns()) {
 					stepResult = harness.step();
-					logInfo(ctx, `Turn ${pc.bold(String(stepResult.turnNumber))}: ${pc.yellow(String(stepResult.issues.length))} issues`);
+					logInfo(ctx, `${pc.bold(`Turn ${stepResult.turnNumber}:`)} ${formatTurnIssues(stepResult.issues)}`);
 				}
 			}
 			const durationMs = Date.now() - startTime;
 			if (stepResult.isComplete) logSuccess(ctx, `Form completed in ${harness.getTurnNumber()} turn(s)`);
 			else if (harness.hasReachedMaxTurns()) logWarn(ctx, `Max turns reached (${harnessConfig.maxTurns})`);
 			logTiming(ctx, "Fill time", durationMs);
-			const outputPath = options.output ? resolve(options.output) : generateVersionedPath(filePath);
+			let outputPath;
+			if (options.output) outputPath = resolve(options.output);
+			else {
+				const formsDir = getFormsDir(ctx.formsDir);
+				await ensureFormsDir(formsDir);
+				outputPath = generateVersionedPathInFormsDir(filePath, formsDir);
+			}
 			const formMarkdown = serialize(harness.getForm());
 			if (ctx.dryRun) logInfo(ctx, `[DRY RUN] Would write form to: ${outputPath}`);
 			else {
@@ -1750,6 +2174,18 @@ function formatState$1(state, useColors) {
 	return useColors ? colorFn(text) : text;
 }
 /**
+* Format answer state badge for console output.
+*/
+function formatAnswerState(state, useColors) {
+	const [text, colorFn] = {
+		answered: ["answered", pc.green],
+		skipped: ["skipped", pc.yellow],
+		aborted: ["aborted", pc.red],
+		unanswered: ["unanswered", pc.dim]
+	}[state] ?? [state, (s) => s];
+	return useColors ? colorFn(text) : text;
+}
+/**
 * Format priority badge for console output.
 *
 * Priority tiers and colors:
@@ -1796,6 +2232,8 @@ function formatFieldValue(value, useColors) {
 			if (entries.length === 0) return dim("(no entries)");
 			return entries.map(([k, v]) => `${k}:${v}`).join(", ");
 		}
+		case "url": return value.value ? green(`"${value.value}"`) : dim("(empty)");
+		case "url_list": return value.items.length > 0 ? green(`[${value.items.map((i) => `"${i}"`).join(", ")}]`) : dim("(empty)");
 		default: return dim("(unknown)");
 	}
 }
@@ -1823,13 +2261,11 @@ function formatConsoleReport$1(report, useColors) {
 	lines.push(bold("Progress:"));
 	lines.push(`  Total fields: ${progress.counts.totalFields}`);
 	lines.push(`  Required: ${progress.counts.requiredFields}`);
-	lines.push(`  Answered: ${progress.counts.answeredFields}`);
-	lines.push(`  Skipped: ${progress.counts.skippedFields}`);
-	lines.push(`  Complete: ${progress.counts.completeFields}`);
-	lines.push(`  Incomplete: ${progress.counts.incompleteFields}`);
-	lines.push(`  Invalid: ${progress.counts.invalidFields}`);
-	lines.push(`  Empty (required): ${progress.counts.emptyRequiredFields}`);
-	lines.push(`  Empty (optional): ${progress.counts.emptyOptionalFields}`);
+	lines.push(`  AnswerState: answered=${progress.counts.answeredFields}, skipped=${progress.counts.skippedFields}, aborted=${progress.counts.abortedFields}, unanswered=${progress.counts.unansweredFields}`);
+	lines.push(`  Validity: valid=${progress.counts.validFields}, invalid=${progress.counts.invalidFields}`);
+	lines.push(`  Value: filled=${progress.counts.filledFields}, empty=${progress.counts.emptyFields}`);
+	lines.push(`  Empty required: ${progress.counts.emptyRequiredFields}`);
+	lines.push(`  Total notes: ${progress.counts.totalNotes}`);
 	lines.push("");
 	lines.push(bold("Form Content:"));
 	for (const group of report.groups) {
@@ -1837,13 +2273,25 @@ function formatConsoleReport$1(report, useColors) {
 		for (const field of group.children) {
 			const reqBadge = field.required ? yellow("[required]") : dim("[optional]");
 			const roleBadge = field.role !== "agent" ? cyan(`[${field.role}]`) : "";
+			const fieldProgress = progress.fields[field.id];
+			const responseStateBadge = fieldProgress ? `[${formatAnswerState(fieldProgress.answerState, useColors)}]` : "";
+			const notesBadge = fieldProgress?.hasNotes ? cyan(`[${fieldProgress.noteCount} note${fieldProgress.noteCount > 1 ? "s" : ""}]`) : "";
 			const value = report.values[field.id];
 			const valueStr = formatFieldValue(value, useColors);
-			lines.push(`    ${field.label} ${dim(`(${field.kind})`)} ${reqBadge} ${roleBadge}`.trim());
+			lines.push(`    ${field.label} ${dim(`(${field.kind})`)} ${reqBadge} ${roleBadge} ${responseStateBadge} ${notesBadge}`.trim());
 			lines.push(`      ${dim("→")} ${valueStr}`);
 		}
 	}
 	lines.push("");
+	if (report.notes.length > 0) {
+		lines.push(bold(`Notes (${report.notes.length}):`));
+		for (const note of report.notes) {
+			const roleBadge = cyan(`[${note.role}]`);
+			const refLabel = dim(`${note.ref}:`);
+			lines.push(`  ${note.id} ${roleBadge} ${refLabel} ${note.text}`.trim());
+		}
+		lines.push("");
+	}
 	if (report.issues.length > 0) {
 		lines.push(bold(`Issues (${report.issues.length}):`));
 		for (const issue of report.issues) {
@@ -1871,11 +2319,13 @@ function registerInspectCommand(program) {
 				process.exit(1);
 			}
 			logVerbose(ctx, `Reading file: ${file}`);
-			const content = await readFile(file);
+			const content = await readFile$1(file);
 			logVerbose(ctx, "Parsing form...");
 			const form = parseForm(content);
 			logVerbose(ctx, "Running inspection...");
 			const result = inspect(form, { targetRoles });
+			const values = {};
+			for (const [fieldId, response] of Object.entries(form.responsesByFieldId)) if (response.state === "answered" && response.value) values[fieldId] = response.value;
 			const output = formatOutput(ctx, {
 				title: form.schema.title,
 				structure: result.structureSummary,
@@ -1892,7 +2342,8 @@ function registerInspectCommand(program) {
 						role: field.role
 					}))
 				})),
-				values: form.valuesByFieldId,
+				values,
+				notes: form.notes,
 				issues: result.issues.map((issue) => ({
 					ref: issue.ref,
 					scope: issue.scope,
@@ -1912,7 +2363,7 @@ function registerInspectCommand(program) {
 }
 
 //#endregion
-//#region src/cli/commands/instructions.ts
+//#region src/cli/commands/readme.ts
 /**
 * Get the path to the README.md file.
 * Works both during development and when installed as a package.
@@ -1938,6 +2389,128 @@ function loadReadme() {
 * Apply basic terminal formatting to markdown content.
 * Colorizes headers, code blocks, and other elements for better readability.
 */
+function formatMarkdown$1(content, useColors) {
+	if (!useColors) return content;
+	const lines = content.split("\n");
+	const formatted = [];
+	let inCodeBlock = false;
+	for (const line of lines) {
+		if (line.startsWith("```")) {
+			inCodeBlock = !inCodeBlock;
+			formatted.push(pc.dim(line));
+			continue;
+		}
+		if (inCodeBlock) {
+			formatted.push(pc.dim(line));
+			continue;
+		}
+		if (line.startsWith("# ")) {
+			formatted.push(pc.bold(pc.cyan(line)));
+			continue;
+		}
+		if (line.startsWith("## ")) {
+			formatted.push(pc.bold(pc.blue(line)));
+			continue;
+		}
+		if (line.startsWith("### ")) {
+			formatted.push(pc.bold(line));
+			continue;
+		}
+		let formattedLine = line.replace(/`([^`]+)`/g, (_match, code) => {
+			return pc.yellow(code);
+		});
+		formattedLine = formattedLine.replace(/\*\*([^*]+)\*\*/g, (_match, text) => {
+			return pc.bold(text);
+		});
+		formattedLine = formattedLine.replace(/\[([^\]]+)\]\(([^)]+)\)/g, (_match, text, url) => {
+			return `${pc.cyan(text)} ${pc.dim(`(${url})`)}`;
+		});
+		formatted.push(formattedLine);
+	}
+	return formatted.join("\n");
+}
+/**
+* Check if stdout is an interactive terminal.
+*/
+function isInteractive$1() {
+	return process.stdout.isTTY === true;
+}
+/**
+* Display content. In a future enhancement, could pipe to a pager for long output.
+*/
+function displayContent$1(content) {
+	console.log(content);
+}
+/**
+* Register the readme command.
+*/
+function registerReadmeCommand(program) {
+	program.command("readme").description("✨Display README documentation ← START HERE!").option("--raw", "Output raw markdown without formatting").action((options, cmd) => {
+		const ctx = getCommandContext(cmd);
+		try {
+			displayContent$1(formatMarkdown$1(loadReadme(), !options.raw && isInteractive$1() && !ctx.quiet));
+		} catch (error) {
+			logError(error instanceof Error ? error.message : String(error));
+			process.exit(1);
+		}
+	});
+}
+
+//#endregion
+//#region src/cli/commands/report.ts
+/**
+* Register the report command.
+*/
+function registerReportCommand(program) {
+	program.command("report <file>").description("Generate filtered markdown report (excludes instructions, report=false elements)").option("-o, --output <file>", "Output file path (default: stdout)").action(async (file, options, cmd) => {
+		const ctx = getCommandContext(cmd);
+		try {
+			logVerbose(ctx, `Reading file: ${file}`);
+			const content = await readFile$1(file);
+			logVerbose(ctx, "Parsing form...");
+			const form = parseForm(content);
+			logVerbose(ctx, "Generating report...");
+			const reportContent = serializeReportMarkdown(form);
+			if (options.output) {
+				let outputPath = options.output;
+				if (!outputPath.endsWith(REPORT_EXTENSION) && !outputPath.endsWith(".md")) outputPath = outputPath + REPORT_EXTENSION;
+				await writeFile(outputPath, reportContent);
+				logVerbose(ctx, `Report written to: ${outputPath}`);
+			} else console.log(reportContent);
+		} catch (error) {
+			logError(error instanceof Error ? error.message : String(error));
+			process.exit(1);
+		}
+	});
+}
+
+//#endregion
+//#region src/cli/commands/spec.ts
+/**
+* Get the path to the SPEC.md file.
+* Works both during development and when installed as a package.
+*/
+function getSpecPath() {
+	const thisDir = dirname(fileURLToPath(import.meta.url));
+	if (thisDir.split(/[/\\]/).pop() === "dist") return join(dirname(thisDir), "SPEC.md");
+	return join(dirname(dirname(dirname(thisDir))), "SPEC.md");
+}
+/**
+* Load the spec content.
+*/
+function loadSpec() {
+	const specPath = getSpecPath();
+	try {
+		return readFileSync(specPath, "utf-8");
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		throw new Error(`Failed to load SPEC from ${specPath}: ${message}`);
+	}
+}
+/**
+* Apply basic terminal formatting to markdown content.
+* Colorizes headers, code blocks, and other elements for better readability.
+*/
 function formatMarkdown(content, useColors) {
 	if (!useColors) return content;
 	const lines = content.split("\n");
@@ -1991,13 +2564,13 @@ function displayContent(content) {
 	console.log(content);
 }
 /**
-* Register the instructions command.
+* Register the spec command.
 */
-function registerInstructionsCommand(program) {
-	program.command("instructions").alias("readme").alias("docs").description("Display usage instructions and documentation").option("--raw", "Output raw markdown without formatting").action((options, cmd) => {
+function registerSpecCommand(program) {
+	program.command("spec").description("Display the Markform specification").option("--raw", "Output raw markdown without formatting").action((options, cmd) => {
 		const ctx = getCommandContext(cmd);
 		try {
-			displayContent(formatMarkdown(loadReadme(), !options.raw && isInteractive() && !ctx.quiet));
+			displayContent(formatMarkdown(loadSpec(), !options.raw && isInteractive() && !ctx.quiet));
 		} catch (error) {
 			logError(error instanceof Error ? error.message : String(error));
 			process.exit(1);
@@ -2077,15 +2650,18 @@ function openBrowser(url) {
 * Register the serve command.
 */
 function registerServeCommand(program) {
-	program.command("serve <file>").description("Serve a form as a web page for browsing").option("-p, --port <port>", "Port to serve on", String(DEFAULT_PORT)).option("--no-open", "Don't open browser automatically").action(async (file, options, cmd) => {
+	program.command("serve <file>").description("Serve a file as a web page (forms are interactive, others are read-only)").option("-p, --port <port>", "Port to serve on", String(DEFAULT_PORT)).option("--no-open", "Don't open browser automatically").action(async (file, options, cmd) => {
 		const ctx = getCommandContext(cmd);
 		const port = parseInt(options.port ?? String(DEFAULT_PORT), 10);
 		const filePath = resolve(file);
+		const fileType = detectFileType(filePath);
 		try {
 			logVerbose(ctx, `Reading file: ${filePath}`);
-			let form = parseForm(await readFile(filePath));
+			const content = await readFile$1(filePath);
+			let form = null;
+			if (fileType === "form") form = parseForm(content);
 			const server = createServer((req, res) => {
-				handleRequest(req, res, form, filePath, ctx, (updatedForm) => {
+				handleRequest(req, res, filePath, fileType, form, ctx, (updatedForm) => {
 					form = updatedForm;
 				}).catch((err) => {
 					console.error("Request error:", err);
@@ -2095,7 +2671,8 @@ function registerServeCommand(program) {
 			});
 			server.listen(port, () => {
 				const url = `http://localhost:${port}`;
-				logInfo(ctx, pc.green(`\n✓ Form server running at ${pc.bold(url)}\n`));
+				const typeLabel = fileType === "form" ? "Form" : fileType === "unknown" ? "File" : fileType.toUpperCase();
+				logInfo(ctx, pc.green(`\n✓ ${typeLabel} server running at ${pc.bold(url)}\n`));
 				logInfo(ctx, pc.dim("Press Ctrl+C to stop\n"));
 				if (options.open !== false) openBrowser(url);
 			});
@@ -2112,15 +2689,33 @@ function registerServeCommand(program) {
 }
 /**
 * Handle HTTP requests.
+* Dispatches to appropriate renderer based on file type.
 */
-async function handleRequest(req, res, form, filePath, ctx, updateForm) {
+async function handleRequest(req, res, filePath, fileType, form, ctx, updateForm) {
 	const url = req.url ?? "/";
-	if (req.method === "GET" && url === "/") {
+	if (req.method === "GET" && url === "/") if (fileType === "form" && form) {
 		const html = renderFormHtml(form);
 		res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
 		res.end(html);
-	} else if (req.method === "POST" && url === "/save") await handleSave(req, res, form, filePath, ctx, updateForm);
-	else if (url === "/api/form") {
+	} else if (fileType === "raw" || fileType === "report") {
+		const html = renderMarkdownHtml(await readFile(filePath, "utf-8"), basename(filePath));
+		res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
+		res.end(html);
+	} else if (fileType === "yaml") {
+		const html = renderYamlHtml(await readFile(filePath, "utf-8"), basename(filePath));
+		res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
+		res.end(html);
+	} else if (fileType === "json") {
+		const html = renderJsonHtml(await readFile(filePath, "utf-8"), basename(filePath));
+		res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
+		res.end(html);
+	} else {
+		const html = renderPlainTextHtml(await readFile(filePath, "utf-8"), basename(filePath));
+		res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
+		res.end(html);
+	}
+	else if (req.method === "POST" && url === "/save" && fileType === "form" && form) await handleSave(req, res, form, filePath, ctx, updateForm);
+	else if (url === "/api/form" && form) {
 		res.writeHead(200, { "Content-Type": "application/json" });
 		res.end(JSON.stringify({ schema: form.schema }));
 	} else {
@@ -2153,7 +2748,8 @@ function formDataToPatches(formData, form) {
 		if (formData[`__skip__${fieldId}`] === "1" && !field.required) {
 			patches.push({
 				op: "skip_field",
-				fieldId
+				fieldId,
+				role: "user"
 			});
 			continue;
 		}
@@ -2334,9 +2930,9 @@ async function handleSave(req, res, form, filePath, ctx, updateForm) {
 * @public Exported for testing.
 */
 function renderFormHtml(form) {
-	const { schema, valuesByFieldId, skipsByFieldId } = form;
+	const { schema, responsesByFieldId } = form;
 	const formTitle = schema.title ?? schema.id;
-	const groupsHtml = schema.groups.map((group) => renderGroup(group, valuesByFieldId, skipsByFieldId ?? {})).join("\n");
+	const groupsHtml = schema.groups.map((group) => renderGroup(group, responsesByFieldId)).join("\n");
 	return `<!DOCTYPE html>
 <html lang="en">
 <head>
@@ -2583,9 +3179,12 @@ function renderFormHtml(form) {
 /**
 * Render a field group as HTML.
 */
-function renderGroup(group, values, skips) {
+function renderGroup(group, responses) {
 	const groupTitle = group.title ?? group.id;
-	const fieldsHtml = group.children.map((field) => renderFieldHtml(field, values[field.id], skips[field.id])).join("\n");
+	const fieldsHtml = group.children.map((field) => {
+		const response = responses[field.id];
+		return renderFieldHtml(field, response?.state === "answered" ? response.value : void 0, response?.state === "skipped");
+	}).join("\n");
 	return `
   <div class="group">
     <h2>${escapeHtml(groupTitle)}</h2>
@@ -2596,13 +3195,13 @@ function renderGroup(group, values, skips) {
 * Render a field as HTML.
 * @public Exported for testing.
 */
-function renderFieldHtml(field, value, skipInfo) {
-	const isSkipped = skipInfo?.skipped === true;
+function renderFieldHtml(field, value, isSkipped) {
+	const skipped = isSkipped === true;
 	const requiredMark = field.required ? "<span class=\"required\">*</span>" : "";
 	const typeLabel = `<span class="type-badge">${field.kind}</span>`;
-	const skippedBadge = isSkipped ? "<span class=\"skipped-badge\">Skipped</span>" : "";
-	const fieldClass = isSkipped ? "field field-skipped" : "field";
-	const disabledAttr = isSkipped ? " disabled" : "";
+	const skippedBadge = skipped ? "<span class=\"skipped-badge\">Skipped</span>" : "";
+	const fieldClass = skipped ? "field field-skipped" : "field";
+	const disabledAttr = skipped ? " disabled" : "";
 	let inputHtml;
 	switch (field.kind) {
 		case "string":
@@ -2631,7 +3230,7 @@ function renderFieldHtml(field, value, skipInfo) {
 			break;
 		default: inputHtml = "<div class=\"field-help\">(unknown field type)</div>";
 	}
-	const skipButton = !field.required && !isSkipped ? `<div class="field-actions">
+	const skipButton = !field.required && !skipped ? `<div class="field-actions">
         <button type="button" class="btn-skip" data-skip-field="${field.id}">Skip</button>
       </div>` : "";
 	return `
@@ -2775,6 +3374,182 @@ function renderCheckboxesInput(field, value, disabledAttr) {
 function escapeHtml(str) {
 	return str.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&#039;");
 }
+/** Common styles for read-only viewers */
+const READ_ONLY_STYLES = `
+    * { box-sizing: border-box; }
+    body {
+      font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+      line-height: 1.6;
+      max-width: 900px;
+      margin: 0 auto;
+      padding: 2rem;
+      background: #f8f9fa;
+      color: #212529;
+    }
+    h1 { color: #495057; border-bottom: 2px solid #dee2e6; padding-bottom: 0.5rem; font-size: 1.5rem; }
+    .content {
+      background: white;
+      border-radius: 8px;
+      padding: 1.5rem;
+      box-shadow: 0 1px 3px rgba(0,0,0,0.1);
+    }
+    pre {
+      background: #1e1e1e;
+      color: #d4d4d4;
+      padding: 1rem;
+      border-radius: 6px;
+      overflow-x: auto;
+      font-family: 'Monaco', 'Menlo', 'Ubuntu Mono', monospace;
+      font-size: 0.9rem;
+      line-height: 1.5;
+    }
+    .badge {
+      font-size: 0.75rem;
+      padding: 0.2rem 0.5rem;
+      background: #e9ecef;
+      border-radius: 4px;
+      color: #6c757d;
+      margin-left: 0.75rem;
+      font-weight: normal;
+    }
+`;
+/**
+* Render markdown content as read-only HTML.
+* Simple rendering without full markdown parsing.
+*/
+function renderMarkdownHtml(content, filename) {
+	const lines = content.split("\n");
+	let html = "";
+	let inParagraph = false;
+	for (const line of lines) {
+		const trimmed = line.trim();
+		if (trimmed.startsWith("# ")) {
+			if (inParagraph) {
+				html += "</p>";
+				inParagraph = false;
+			}
+			html += `<h2>${escapeHtml(trimmed.slice(2))}</h2>`;
+		} else if (trimmed.startsWith("## ")) {
+			if (inParagraph) {
+				html += "</p>";
+				inParagraph = false;
+			}
+			html += `<h3>${escapeHtml(trimmed.slice(3))}</h3>`;
+		} else if (trimmed.startsWith("### ")) {
+			if (inParagraph) {
+				html += "</p>";
+				inParagraph = false;
+			}
+			html += `<h4>${escapeHtml(trimmed.slice(4))}</h4>`;
+		} else if (trimmed === "") {
+			if (inParagraph) {
+				html += "</p>";
+				inParagraph = false;
+			}
+		} else {
+			if (!inParagraph) {
+				html += "<p>";
+				inParagraph = true;
+			} else html += "<br>";
+			html += escapeHtml(trimmed);
+		}
+	}
+	if (inParagraph) html += "</p>";
+	return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>${escapeHtml(filename)} - Markform Viewer</title>
+  <style>${READ_ONLY_STYLES}
+    h2 { color: #495057; font-size: 1.3rem; margin-top: 1.5rem; }
+    h3 { color: #6c757d; font-size: 1.1rem; margin-top: 1.25rem; }
+    h4 { color: #6c757d; font-size: 1rem; margin-top: 1rem; }
+    p { margin: 0.75rem 0; }
+  </style>
+</head>
+<body>
+  <h1>${escapeHtml(filename)}<span class="badge">Markdown</span></h1>
+  <div class="content">
+    ${html}
+  </div>
+</body>
+</html>`;
+}
+/**
+* Render YAML content with syntax highlighting.
+*/
+function renderYamlHtml(content, filename) {
+	const highlighted = content.split("\n").map((line) => {
+		const colonIndex = line.indexOf(":");
+		if (colonIndex > 0 && !line.trim().startsWith("#") && !line.trim().startsWith("-")) return `<span style="color:#9cdcfe">${escapeHtml(line.slice(0, colonIndex))}</span>${escapeHtml(line.slice(colonIndex))}`;
+		if (line.trim().startsWith("#")) return `<span style="color:#6a9955">${escapeHtml(line)}</span>`;
+		return escapeHtml(line);
+	}).join("\n");
+	return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>${escapeHtml(filename)} - Markform Viewer</title>
+  <style>${READ_ONLY_STYLES}</style>
+</head>
+<body>
+  <h1>${escapeHtml(filename)}<span class="badge">YAML</span></h1>
+  <div class="content">
+    <pre>${highlighted}</pre>
+  </div>
+</body>
+</html>`;
+}
+/**
+* Render JSON content with syntax highlighting and formatting.
+*/
+function renderJsonHtml(content, filename) {
+	let formatted;
+	try {
+		const parsed = JSON.parse(content);
+		formatted = JSON.stringify(parsed, null, 2);
+	} catch {
+		formatted = content;
+	}
+	const highlighted = formatted.replace(/"([^"]+)":/g, "<span style=\"color:#9cdcfe\">\"$1\"</span>:").replace(/: "([^"]+)"/g, ": <span style=\"color:#ce9178\">\"$1\"</span>").replace(/: (\d+\.?\d*)/g, ": <span style=\"color:#b5cea8\">$1</span>").replace(/: (true|false|null)/g, ": <span style=\"color:#569cd6\">$1</span>");
+	return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>${escapeHtml(filename)} - Markform Viewer</title>
+  <style>${READ_ONLY_STYLES}</style>
+</head>
+<body>
+  <h1>${escapeHtml(filename)}<span class="badge">JSON</span></h1>
+  <div class="content">
+    <pre>${highlighted}</pre>
+  </div>
+</body>
+</html>`;
+}
+/**
+* Render plain text content.
+*/
+function renderPlainTextHtml(content, filename) {
+	return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>${escapeHtml(filename)} - Markform Viewer</title>
+  <style>${READ_ONLY_STYLES}</style>
+</head>
+<body>
+  <h1>${escapeHtml(filename)}<span class="badge">Text</span></h1>
+  <div class="content">
+    <pre>${escapeHtml(content)}</pre>
+  </div>
+</body>
+</html>`;
+}
 
 //#endregion
 //#region src/cli/commands/render.ts
@@ -2798,7 +3573,7 @@ function registerRenderCommand(program) {
 		const outputPath = options.output ? resolve(options.output) : getDefaultOutputPath(filePath);
 		try {
 			logVerbose(ctx, `Reading file: ${filePath}`);
-			const content = await readFile(filePath);
+			const content = await readFile$1(filePath);
 			logVerbose(ctx, "Parsing form...");
 			const form = parseForm(content);
 			logVerbose(ctx, "Rendering HTML...");
@@ -2816,6 +3591,156 @@ function registerRenderCommand(program) {
 	});
 }
 
+//#endregion
+//#region src/cli/lib/initialValues.ts
+/**
+* Parse initial value inputs from CLI flags.
+*
+* Supports formats:
+* - fieldId=value (string values)
+* - fieldId:number=123 (explicit number)
+* - fieldId:list=a,b,c (comma-separated list)
+*
+* @param inputs Array of input strings in "fieldId=value" format
+* @returns Array of patches to apply as initial values
+*/
+function parseInitialValues(inputs) {
+	const patches = [];
+	for (const input of inputs) {
+		const equalsIndex = input.indexOf("=");
+		if (equalsIndex === -1) throw new Error(`Invalid input format: "${input}" (expected "fieldId=value")`);
+		const fieldSpec = input.slice(0, equalsIndex);
+		const value = input.slice(equalsIndex + 1);
+		const colonIndex = fieldSpec.indexOf(":");
+		let fieldId;
+		let type = null;
+		if (colonIndex !== -1) {
+			fieldId = fieldSpec.slice(0, colonIndex);
+			type = fieldSpec.slice(colonIndex + 1).toLowerCase();
+		} else fieldId = fieldSpec;
+		if (type === "number") {
+			const numValue = parseFloat(value);
+			if (isNaN(numValue)) throw new Error(`Invalid number value for "${fieldId}": "${value}"`);
+			patches.push({
+				op: "set_number",
+				fieldId,
+				value: numValue
+			});
+		} else if (type === "list") {
+			const items = value.split(",").map((s) => s.trim()).filter((s) => s.length > 0);
+			patches.push({
+				op: "set_string_list",
+				fieldId,
+				items
+			});
+		} else patches.push({
+			op: "set_string",
+			fieldId,
+			value
+		});
+	}
+	return patches;
+}
+/**
+* Validate that all initial values reference valid field IDs.
+*
+* @param patches Patches to validate
+* @param validFieldIds Set of valid field IDs from the form
+* @returns Array of invalid field IDs (empty if all valid)
+*/
+function validateInitialValueFields(patches, validFieldIds) {
+	const invalid = [];
+	for (const patch of patches) if ("fieldId" in patch && patch.fieldId && !validFieldIds.has(patch.fieldId)) invalid.push(patch.fieldId);
+	return invalid;
+}
+
+//#endregion
+//#region src/cli/commands/research.ts
+/**
+* Register the research command.
+*/
+function registerResearchCommand(program) {
+	program.command("research <input>").description("Fill a form using a web-search-enabled model").option("--model <provider/model>", "LLM model to use (e.g., google/gemini-2.5-flash). Required.").option("--output <path>", "Output path for filled form (default: auto-generated in forms directory)").option("--input <fieldId=value>", "Set initial field value (can be used multiple times)", (value, previous) => previous.concat([value]), []).option("--max-turns <n>", `Maximum turns (default: ${DEFAULT_MAX_TURNS})`, String(DEFAULT_MAX_TURNS)).option("--max-patches <n>", `Maximum patches per turn (default: ${DEFAULT_RESEARCH_MAX_PATCHES_PER_TURN})`, String(DEFAULT_RESEARCH_MAX_PATCHES_PER_TURN)).option("--max-issues <n>", `Maximum issues per turn (default: ${DEFAULT_RESEARCH_MAX_ISSUES_PER_TURN})`, String(DEFAULT_RESEARCH_MAX_ISSUES_PER_TURN)).option("--transcript", "Save session transcript").action(async (input, options, cmd) => {
+		const ctx = getCommandContext(cmd);
+		const startTime = Date.now();
+		try {
+			if (!options.model) {
+				logError("--model is required");
+				console.log("");
+				console.log(formatSuggestedLlms());
+				process.exit(1);
+			}
+			const modelId = options.model;
+			if (!hasWebSearchSupport(/^([^/]+)\//.exec(modelId)?.[1] ?? modelId)) {
+				const webSearchProviders = Object.entries(WEB_SEARCH_CONFIG).filter(([, config]) => config.supported).map(([p$1]) => p$1);
+				logError(`Model "${modelId}" does not support web search.`);
+				console.log("");
+				console.log(pc.yellow("Research forms require web search capabilities."));
+				console.log(`Use a model from: ${webSearchProviders.join(", ")}`);
+				console.log("");
+				console.log("Examples:");
+				console.log("  --model openai/gpt-5-mini");
+				console.log("  --model anthropic/claude-sonnet-4-5");
+				console.log("  --model google/gemini-2.5-flash");
+				console.log("  --model xai/grok-4");
+				process.exit(1);
+			}
+			const inputPath = resolve(input);
+			logVerbose(ctx, `Input: ${inputPath}`);
+			const form = parseForm(await readFile$1(inputPath));
+			logVerbose(ctx, `Parsed form: ${form.schema.id}`);
+			const initialInputs = options.input ?? [];
+			if (initialInputs.length > 0) {
+				const patches = parseInitialValues(initialInputs);
+				const invalidFields = validateInitialValueFields(patches, new Set(form.orderIndex));
+				if (invalidFields.length > 0) logWarn(ctx, `Unknown field IDs: ${invalidFields.join(", ")}`);
+				applyPatches(form, patches);
+				logInfo(ctx, `Applied ${patches.length} initial value(s)`);
+			}
+			const formsDir = getFormsDir(ctx.formsDir);
+			let outputPath;
+			if (options.output) outputPath = resolve(options.output);
+			else outputPath = generateVersionedPathInFormsDir(inputPath, formsDir);
+			logVerbose(ctx, `Output: ${outputPath}`);
+			const maxTurns = parseInt(options.maxTurns, 10);
+			const maxPatchesPerTurn = parseInt(options.maxPatches, 10);
+			const maxIssuesPerTurn = parseInt(options.maxIssues, 10);
+			logInfo(ctx, `Research fill with model: ${modelId}`);
+			logVerbose(ctx, `Max turns: ${maxTurns}`);
+			logVerbose(ctx, `Max patches/turn: ${maxPatchesPerTurn}`);
+			logVerbose(ctx, `Max issues/turn: ${maxIssuesPerTurn}`);
+			const result = await runResearch(form, {
+				model: modelId,
+				maxTurns,
+				maxPatchesPerTurn,
+				maxIssuesPerTurn,
+				targetRoles: [AGENT_ROLE],
+				fillMode: "continue"
+			});
+			if (result.availableTools) logInfo(ctx, `Tools: ${result.availableTools.join(", ")}`);
+			logInfo(ctx, `Status: ${(result.status === "completed" ? pc.green : result.status === "max_turns_reached" ? pc.yellow : pc.red)(result.status)}`);
+			logInfo(ctx, `Turns: ${result.totalTurns}`);
+			if (result.inputTokens || result.outputTokens) logVerbose(ctx, `Tokens: ${result.inputTokens ?? 0} in, ${result.outputTokens ?? 0} out`);
+			const { formPath, rawPath, yamlPath } = await exportMultiFormat(result.form, outputPath);
+			logSuccess(ctx, "Outputs:");
+			console.log(`  ${formPath}  ${pc.dim("(markform)")}`);
+			console.log(`  ${rawPath}  ${pc.dim("(plain markdown)")}`);
+			console.log(`  ${yamlPath}  ${pc.dim("(values as YAML)")}`);
+			if (options.transcript && result.transcript) {
+				const { serializeSession: serializeSession$1 } = await import("./session-DdAtY2Ni.mjs");
+				const transcriptPath = outputPath.replace(/\.form\.md$/, ".session.yaml");
+				const { writeFile: writeFile$1 } = await import("./shared-D7gf27Tr.mjs");
+				await writeFile$1(transcriptPath, serializeSession$1(result.transcript));
+				logInfo(ctx, `Transcript: ${transcriptPath}`);
+			}
+			logTiming(ctx, "Research fill", Date.now() - startTime);
+		} catch (error) {
+			logError(error instanceof Error ? error.message : String(error));
+			process.exit(1);
+		}
+	});
+}
+
 //#endregion
 //#region src/cli/commands/validate.ts
 /**
@@ -2875,12 +3800,10 @@ function formatConsoleReport(report, useColors) {
 	lines.push(bold("Progress:"));
 	lines.push(`  Total fields: ${progress.counts.totalFields}`);
 	lines.push(`  Required: ${progress.counts.requiredFields}`);
-	lines.push(`  Submitted: ${progress.counts.submittedFields}`);
-	lines.push(`  Complete: ${progress.counts.completeFields}`);
-	lines.push(`  Incomplete: ${progress.counts.incompleteFields}`);
-	lines.push(`  Invalid: ${progress.counts.invalidFields}`);
-	lines.push(`  Empty (required): ${progress.counts.emptyRequiredFields}`);
-	lines.push(`  Empty (optional): ${progress.counts.emptyOptionalFields}`);
+	lines.push(`  AnswerState: answered=${progress.counts.answeredFields}, skipped=${progress.counts.skippedFields}, aborted=${progress.counts.abortedFields}, unanswered=${progress.counts.unansweredFields}`);
+	lines.push(`  Validity: valid=${progress.counts.validFields}, invalid=${progress.counts.invalidFields}`);
+	lines.push(`  Value: filled=${progress.counts.filledFields}, empty=${progress.counts.emptyFields}`);
+	lines.push(`  Empty required: ${progress.counts.emptyRequiredFields}`);
 	lines.push("");
 	if (report.issues.length > 0) {
 		lines.push(bold(`Issues (${report.issues.length}):`));
@@ -2900,7 +3823,7 @@ function registerValidateCommand(program) {
 		const ctx = getCommandContext(cmd);
 		try {
 			logVerbose(ctx, `Reading file: ${file}`);
-			const content = await readFile(file);
+			const content = await readFile$1(file);
 			logVerbose(ctx, "Parsing form...");
 			const form = parseForm(content);
 			logVerbose(ctx, "Running validation...");
@@ -2952,18 +3875,22 @@ function withColoredHelp(cmd) {
 */
 function createProgram() {
 	const program = withColoredHelp(new Command());
-	program.name("markform").description("Agent-friendly, human-readable, editable forms").version(VERSION).option("--verbose", "Enable verbose output").option("--quiet", "Suppress non-essential output").option("--dry-run", "Show what would be done without making changes").option("--format <format>", `Output format: ${OUTPUT_FORMATS.join(", ")}`, "console");
-	registerInspectCommand(program);
-	registerValidateCommand(program);
+	program.name("markform").description("Agent-friendly, human-readable, editable forms").version(VERSION).showHelpAfterError().option("--verbose", "Enable verbose output").option("--quiet", "Suppress non-essential output").option("--dry-run", "Show what would be done without making changes").option("--format <format>", `Output format: ${OUTPUT_FORMATS.join(", ")}`, "console").option("--forms-dir <dir>", `Directory for form output (default: ${DEFAULT_FORMS_DIR})`);
+	registerReadmeCommand(program);
+	registerDocsCommand(program);
+	registerSpecCommand(program);
 	registerApplyCommand(program);
-	registerExportCommand(program);
 	registerDumpCommand(program);
-	registerRenderCommand(program);
-	registerServeCommand(program);
+	registerExamplesCommand(program);
+	registerExportCommand(program);
 	registerFillCommand(program);
+	registerInspectCommand(program);
 	registerModelsCommand(program);
-	registerExamplesCommand(program);
-	registerInstructionsCommand(program);
+	registerRenderCommand(program);
+	registerReportCommand(program);
+	registerResearchCommand(program);
+	registerServeCommand(program);
+	registerValidateCommand(program);
 	return program;
 }
 /**