markform 0.1.0 → 0.1.2

package/dist/cli-B3NVm6zL.mjs

@@ -0,0 +1,3904 @@
+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 { readFile } from "node:fs/promises";
+import { existsSync, readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import * as p from "@clack/prompts";
+import { exec, spawn } from "node:child_process";
+import { createServer } from "node:http";
+
+//#region src/cli/commands/apply.ts
+/**
+* Format state badge for console output.
+*/
+function formatState$2(state, useColors) {
+	const [text, colorFn] = {
+		complete: ["✓ complete", pc.green],
+		incomplete: ["○ incomplete", pc.yellow],
+		empty: ["◌ empty", pc.dim],
+		invalid: ["✗ invalid", pc.red]
+	}[state] ?? [state, (s) => s];
+	return useColors ? colorFn(text) : text;
+}
+/**
+* Format apply report for console output.
+*/
+function formatConsoleReport$2(report, useColors) {
+	const lines = [];
+	const bold = useColors ? pc.bold : (s) => s;
+	const dim = useColors ? pc.dim : (s) => s;
+	const cyan = useColors ? pc.cyan : (s) => s;
+	const green = useColors ? pc.green : (s) => s;
+	const red = useColors ? pc.red : (s) => s;
+	lines.push(bold(cyan("Apply Result")));
+	lines.push("");
+	const statusColor = report.apply_status === "applied" ? green : red;
+	lines.push(`${bold("Status:")} ${statusColor(report.apply_status)}`);
+	lines.push(`${bold("Form State:")} ${formatState$2(report.form_state, useColors)}`);
+	lines.push(`${bold("Complete:")} ${report.is_complete ? green("yes") : dim("no")}`);
+	lines.push("");
+	const counts = report.progress.counts;
+	lines.push(bold("Progress:"));
+	lines.push(`  Total fields: ${counts.totalFields}`);
+	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}):`));
+		for (const issue of report.issues) {
+			const priority = `P${issue.priority}`;
+			lines.push(`  ${dim(priority)} ${dim(issue.ref)}: ${issue.message}`);
+		}
+	} else lines.push(dim("No issues."));
+	return lines.join("\n");
+}
+/**
+* Register the apply command.
+*/
+function registerApplyCommand(program) {
+	program.command("apply <file>").description("Apply patches to a form").option("--patch <json>", "JSON array of patches to apply").option("-o, --output <file>", "Output file (defaults to stdout)").option("--report", "Output apply result report instead of modified form").action(async (file, options, cmd) => {
+		const ctx = getCommandContext(cmd);
+		try {
+			if (!options.patch) {
+				logError("--patch option is required");
+				process.exit(1);
+			}
+			logVerbose(ctx, `Reading file: ${file}`);
+			const content = await readFile$1(file);
+			logVerbose(ctx, "Parsing form...");
+			const form = parseForm(content);
+			logVerbose(ctx, "Parsing patches...");
+			let parsedJson;
+			try {
+				parsedJson = JSON.parse(options.patch);
+			} catch {
+				logError("Invalid JSON in --patch option");
+				process.exit(1);
+			}
+			if (!Array.isArray(parsedJson)) {
+				logError("--patch must be a JSON array");
+				process.exit(1);
+			}
+			const patches = parsedJson;
+			const validatedPatches = [];
+			for (let i = 0; i < patches.length; i++) {
+				const result$1 = PatchSchema.safeParse(patches[i]);
+				if (!result$1.success) {
+					logError(`Invalid patch at index ${i}: ${result$1.error.issues[0]?.message ?? "Unknown error"}`);
+					process.exit(1);
+				}
+				validatedPatches.push(result$1.data);
+			}
+			if (ctx.dryRun) {
+				logDryRun(`Would apply ${validatedPatches.length} patches to ${file}`, { patches: validatedPatches });
+				return;
+			}
+			logVerbose(ctx, `Applying ${validatedPatches.length} patches...`);
+			const result = applyPatches(form, validatedPatches);
+			if (result.applyStatus === "rejected") {
+				logError("Patches rejected - structural validation failed");
+				const output = formatOutput(ctx, {
+					apply_status: result.applyStatus,
+					form_state: result.formState,
+					is_complete: result.isComplete,
+					structure: result.structureSummary,
+					progress: result.progressSummary,
+					issues: result.issues
+				}, (data, useColors) => formatConsoleReport$2(data, useColors));
+				console.error(output);
+				process.exit(1);
+			}
+			if (options.report) {
+				const output = formatOutput(ctx, {
+					apply_status: result.applyStatus,
+					form_state: result.formState,
+					is_complete: result.isComplete,
+					structure: result.structureSummary,
+					progress: result.progressSummary,
+					issues: result.issues
+				}, (data, useColors) => formatConsoleReport$2(data, useColors));
+				if (options.output) {
+					await writeFile(options.output, output);
+					logSuccess(ctx, `Report written to ${options.output}`);
+				} else console.log(output);
+			} else {
+				const output = serialize(form);
+				if (options.output) {
+					await writeFile(options.output, output);
+					logSuccess(ctx, `Modified form written to ${options.output}`);
+				} else console.log(output);
+			}
+		} catch (error) {
+			logError(error instanceof Error ? error.message : String(error));
+			process.exit(1);
+		}
+	});
+}
+
+//#endregion
+//#region src/cli/commands/docs.ts
+/**
+* Get the path to the DOCS.md file.
+* Works both during development and when installed as a package.
+*/
+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");
+}
+/**
+* Load the docs content.
+*/
+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}`);
+	}
+}
+/**
+* Apply basic terminal formatting to markdown content.
+* Colorizes headers, code blocks, and other elements for better readability.
+*/
+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");
+}
+/**
+* Check if stdout is an interactive terminal.
+*/
+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 {
+			displayContent$2(formatMarkdown$3(loadDocs(), !options.raw && isInteractive$3() && !ctx.quiet));
+		} catch (error) {
+			logError(error instanceof Error ? error.message : String(error));
+			process.exit(1);
+		}
+	});
+}
+
+//#endregion
+//#region src/cli/lib/exportHelpers.ts
+/**
+* Export helpers for multi-format form output.
+*
+* Provides reusable functions for exporting forms to multiple formats:
+* - Markform format (.form.md) - canonical form with directives
+* - Raw markdown (.raw.md) - plain readable markdown
+* - YAML values (.yml) - extracted field values
+*/
+/**
+* Convert field responses to structured format for export (markform-218).
+*
+* 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 toStructuredValues(form) {
+	const result = {};
+	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: deriveExportPath(basePath, "form"),
+		rawPath: deriveExportPath(basePath, "raw"),
+		yamlPath: deriveExportPath(basePath, "yaml")
+	};
+}
+/**
+* Export form to multiple formats.
+*
+* Writes:
+* - Markform format (.form.md) - canonical form with directives
+* - Raw markdown (.raw.md) - plain readable markdown (no directives)
+* - 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
+*/
+async function exportMultiFormat(form, basePath) {
+	const paths = deriveExportPaths(basePath);
+	const formContent = serialize(form);
+	await writeFile(paths.formPath, formContent);
+	const rawContent = serializeRawMarkdown(form);
+	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 */
+const PATCH_VALUE_MAX_LENGTH = 1e3;
+/**
+* Truncate a string to max length with ellipsis if needed.
+*/
+function truncate(value, maxLength = PATCH_VALUE_MAX_LENGTH) {
+	if (value.length <= maxLength) return value;
+	return value.slice(0, maxLength) + "…";
+}
+/**
+* Format a patch value for display with truncation.
+*/
+function formatPatchValue(patch) {
+	switch (patch.op) {
+		case "set_string": return patch.value ? truncate(`"${patch.value}"`) : "(empty)";
+		case "set_number": return patch.value !== null ? String(patch.value) : "(empty)";
+		case "set_string_list": return patch.items.length > 0 ? truncate(`[${patch.items.join(", ")}]`) : "(empty)";
+		case "set_single_select": return patch.selected ?? "(none)";
+		case "set_multi_select": return patch.selected.length > 0 ? truncate(`[${patch.selected.join(", ")}]`) : "(none)";
+		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})`;
+	}
+}
+/**
+* Get a short display name for the patch operation type.
+*/
+function formatPatchType(patch) {
+	switch (patch.op) {
+		case "set_string": return "string";
+		case "set_number": return "number";
+		case "set_string_list": return "string_list";
+		case "set_single_select": return "select";
+		case "set_multi_select": return "multi_select";
+		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.
+*/
+const EXAMPLE_DEFINITIONS = [
+	{
+		id: "simple",
+		filename: "simple.form.md",
+		path: "simple/simple.form.md",
+		type: "fill"
+	},
+	{
+		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",
+		filename: "earnings-analysis.form.md",
+		path: "earnings-analysis/earnings-analysis.form.md",
+		type: "research"
+	},
+	{
+		id: "startup-deep-research",
+		filename: "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"
+	}
+];
+/**
+* Get the path to the examples directory.
+* Works both during development and when installed as a package.
+*/
+function getExamplesDir() {
+	const thisDir = dirname(fileURLToPath(import.meta.url));
+	if (thisDir.split(/[/\\]/).pop() === "dist") return join(dirname(thisDir), "examples");
+	return join(dirname(dirname(dirname(thisDir))), "examples");
+}
+/**
+* Load the content of an example form.
+* @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
+*/
+function loadExampleContent(exampleId) {
+	const example = EXAMPLE_DEFINITIONS.find((e) => e.id === exampleId);
+	if (!example) throw new Error(`Unknown example: ${exampleId}`);
+	const filePath = join(getExamplesDir(), example.path);
+	try {
+		return readFileSync(filePath, "utf-8");
+	} catch (error) {
+		throw new Error(`Failed to load example '${exampleId}' from ${filePath}: ${error}`);
+	}
+}
+/**
+* Get an example definition by ID.
+*/
+function getExampleById(id) {
+	return EXAMPLE_DEFINITIONS.find((e) => e.id === id);
+}
+/**
+* Get the absolute path to an example's source file.
+* @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
+*/
+function getExamplePath(exampleId) {
+	const example = EXAMPLE_DEFINITIONS.find((e) => e.id === 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
+/**
+* Versioned filename utilities for form output.
+*
+* Generates versioned filenames to avoid overwriting existing files.
+* Pattern: name.form.md → name-filled1.form.md → name-filled2.form.md
+*/
+/**
+* Version pattern that matches -filledN or _filledN before the extension.
+* Also matches legacy -vN pattern for backwards compatibility.
+*/
+const VERSION_PATTERN = /^(.+?)(?:[-_]?(?:filled|v)(\d+))?(\.form\.md)$/i;
+/**
+* Extension pattern for fallback matching.
+*/
+const EXTENSION_PATTERN = /^(.+)(\.form\.md)$/i;
+/**
+* Parse a versioned filename into its components.
+*
+* @param filePath - Path to parse
+* @returns Parsed components or null if not a valid form file
+*/
+function parseVersionedPath(filePath) {
+	const match = VERSION_PATTERN.exec(filePath);
+	if (match) {
+		const base = match[1];
+		const versionStr = match[2];
+		const ext = match[3];
+		if (base !== void 0 && ext !== void 0) return {
+			base,
+			version: versionStr ? parseInt(versionStr, 10) : null,
+			extension: ext
+		};
+	}
+	const extMatch = EXTENSION_PATTERN.exec(filePath);
+	if (extMatch) {
+		const base = extMatch[1];
+		const ext = extMatch[2];
+		if (base !== void 0 && ext !== void 0) return {
+			base,
+			version: null,
+			extension: ext
+		};
+	}
+	return null;
+}
+/**
+* Generate a versioned filename that doesn't conflict with existing files.
+*
+* Starts from the incremented version and keeps incrementing until
+* a non-existent filename is found.
+*
+* @param filePath - Original file path
+* @returns Path to a non-existent versioned file
+*/
+function generateVersionedPath(filePath) {
+	const parsed = parseVersionedPath(filePath);
+	if (!parsed) {
+		let candidate$1 = `${filePath}-filled1`;
+		let version$1 = 1;
+		while (existsSync(candidate$1)) {
+			version$1++;
+			candidate$1 = `${filePath}-filled${version$1}`;
+		}
+		return candidate$1;
+	}
+	let version = parsed.version !== null ? parsed.version + 1 : 1;
+	let candidate = `${parsed.base}-filled${version}${parsed.extension}`;
+	while (existsSync(candidate)) {
+		version++;
+		candidate = `${parsed.base}-filled${version}${parsed.extension}`;
+	}
+	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
+/**
+* Interactive prompts module for console-based form filling.
+*
+* Uses @clack/prompts to provide a rich terminal UI for users to
+* fill form fields interactively.
+*/
+/**
+* Get field description from form docs.
+*/
+function getFieldDescription(form, fieldId) {
+	return form.docs.find((d) => d.ref === fieldId && (d.tag === "description" || d.tag === "instructions"))?.bodyMarkdown;
+}
+/**
+* Get a field by ID from the form schema.
+*/
+function getFieldById(form, fieldId) {
+	for (const group of form.schema.groups) {
+		const field = group.children.find((f) => f.id === fieldId);
+		if (field) return field;
+	}
+}
+/**
+* Format field label with required indicator and progress.
+*/
+function formatFieldLabel(ctx) {
+	const required = ctx.field.required ? pc.red("*") : "";
+	const progress = `(${ctx.index} of ${ctx.total})`;
+	return `${ctx.field.label}${required} ${progress}`;
+}
+/**
+* Create a skip_field patch for the given field.
+*/
+function createSkipPatch(field) {
+	return {
+		op: "skip_field",
+		fieldId: field.id,
+		role: "user",
+		reason: "User skipped in console"
+	};
+}
+/**
+* For optional fields, prompt user to choose between filling or skipping.
+* Returns "fill" if user wants to enter a value, or a skip_field patch if skipping.
+* Returns null if user cancelled.
+*/
+async function promptSkipOrFill(ctx) {
+	const field = ctx.field;
+	if (field.required) return "fill";
+	const result = await p.select({
+		message: `${formatFieldLabel(ctx)} ${pc.dim("(optional)")}`,
+		options: [{
+			value: "fill",
+			label: "Enter value"
+		}, {
+			value: "skip",
+			label: "Skip this field"
+		}]
+	});
+	if (p.isCancel(result)) return null;
+	if (result === "skip") return createSkipPatch(field);
+	return "fill";
+}
+/**
+* Prompt for a string field value.
+*/
+async function promptForString(ctx) {
+	const field = ctx.field;
+	const currentVal = ctx.currentValue?.kind === "string" ? ctx.currentValue.value : null;
+	const result = await p.text({
+		message: formatFieldLabel(ctx),
+		placeholder: currentVal ?? (ctx.description ? ctx.description.slice(0, 60) : void 0),
+		initialValue: currentVal ?? "",
+		validate: (value) => {
+			if (field.required && !value.trim()) return "This field is required";
+			if (field.minLength && value.length < field.minLength) return `Minimum ${field.minLength} characters required`;
+			if (field.maxLength && value.length > field.maxLength) return `Maximum ${field.maxLength} characters allowed`;
+			if (field.pattern && !new RegExp(field.pattern).test(value)) return `Must match pattern: ${field.pattern}`;
+		}
+	});
+	if (p.isCancel(result)) return null;
+	if (!result && !field.required) return null;
+	return {
+		op: "set_string",
+		fieldId: field.id,
+		value: result || null
+	};
+}
+/**
+* Prompt for a number field value.
+*/
+async function promptForNumber(ctx) {
+	const field = ctx.field;
+	const currentVal = ctx.currentValue?.kind === "number" ? ctx.currentValue.value : null;
+	const result = await p.text({
+		message: formatFieldLabel(ctx),
+		placeholder: currentVal !== null ? String(currentVal) : void 0,
+		initialValue: currentVal !== null ? String(currentVal) : "",
+		validate: (value) => {
+			if (field.required && !value.trim()) return "This field is required";
+			if (!value.trim()) return;
+			const num = Number(value);
+			if (isNaN(num)) return "Please enter a valid number";
+			if (field.integer && !Number.isInteger(num)) return "Please enter a whole number";
+			if (field.min !== void 0 && num < field.min) return `Minimum value is ${field.min}`;
+			if (field.max !== void 0 && num > field.max) return `Maximum value is ${field.max}`;
+		}
+	});
+	if (p.isCancel(result)) return null;
+	if (!result && !field.required) return null;
+	return {
+		op: "set_number",
+		fieldId: field.id,
+		value: result ? Number(result) : null
+	};
+}
+/**
+* Prompt for a string list field value.
+*/
+async function promptForStringList(ctx) {
+	const field = ctx.field;
+	const currentItems = ctx.currentValue?.kind === "string_list" ? ctx.currentValue.items : [];
+	const hint = ctx.description ? `${ctx.description.slice(0, 50)}... (one item per line)` : "Enter items, one per line. Press Enter twice when done.";
+	const result = await p.text({
+		message: formatFieldLabel(ctx),
+		placeholder: hint,
+		initialValue: currentItems.join("\n"),
+		validate: (value) => {
+			const items$1 = value.split("\n").map((s) => s.trim()).filter(Boolean);
+			if (field.required && items$1.length === 0) return "At least one item is required";
+			if (field.minItems && items$1.length < field.minItems) return `Minimum ${field.minItems} items required`;
+			if (field.maxItems && items$1.length > field.maxItems) return `Maximum ${field.maxItems} items allowed`;
+		}
+	});
+	if (p.isCancel(result)) return null;
+	const items = result.split("\n").map((s) => s.trim()).filter(Boolean);
+	if (items.length === 0 && !field.required) return null;
+	return {
+		op: "set_string_list",
+		fieldId: field.id,
+		items
+	};
+}
+/**
+* Prompt for a single-select field value.
+*/
+async function promptForSingleSelect(ctx) {
+	const field = ctx.field;
+	const currentSelected = ctx.currentValue?.kind === "single_select" ? ctx.currentValue.selected : null;
+	const options = field.options.map((opt) => ({
+		value: opt.id,
+		label: opt.label
+	}));
+	const result = await p.select({
+		message: formatFieldLabel(ctx),
+		options,
+		initialValue: currentSelected ?? void 0
+	});
+	if (p.isCancel(result)) return null;
+	return {
+		op: "set_single_select",
+		fieldId: field.id,
+		selected: result
+	};
+}
+/**
+* Prompt for a multi-select field value.
+*/
+async function promptForMultiSelect(ctx) {
+	const field = ctx.field;
+	const currentSelected = ctx.currentValue?.kind === "multi_select" ? ctx.currentValue.selected : [];
+	const options = field.options.map((opt) => ({
+		value: opt.id,
+		label: opt.label
+	}));
+	const result = await p.multiselect({
+		message: formatFieldLabel(ctx),
+		options,
+		initialValues: currentSelected,
+		required: field.required
+	});
+	if (p.isCancel(result)) return null;
+	return {
+		op: "set_multi_select",
+		fieldId: field.id,
+		selected: result
+	};
+}
+/**
+* Prompt for a checkboxes field value.
+*
+* Behavior varies by checkboxMode:
+* - simple: multiselect to pick items marked as done
+* - multi: per-option select with 5 states
+* - explicit: per-option yes/no/skip
+*/
+async function promptForCheckboxes(ctx) {
+	const field = ctx.field;
+	const currentValues = ctx.currentValue?.kind === "checkboxes" ? ctx.currentValue.values : {};
+	if (field.checkboxMode === "simple") {
+		const options = field.options.map((opt) => ({
+			value: opt.id,
+			label: opt.label
+		}));
+		const currentlyDone = field.options.filter((opt) => currentValues[opt.id] === "done").map((opt) => opt.id);
+		const result = await p.multiselect({
+			message: formatFieldLabel(ctx),
+			options,
+			initialValues: currentlyDone,
+			required: field.required && field.minDone !== void 0 && field.minDone > 0
+		});
+		if (p.isCancel(result)) return null;
+		const selected = result;
+		const values$1 = {};
+		for (const opt of field.options) values$1[opt.id] = selected.includes(opt.id) ? "done" : "todo";
+		return {
+			op: "set_checkboxes",
+			fieldId: field.id,
+			values: values$1
+		};
+	}
+	if (field.checkboxMode === "explicit") {
+		const values$1 = {};
+		for (const opt of field.options) {
+			const current = currentValues[opt.id];
+			const result = await p.select({
+				message: `${opt.label}`,
+				options: [
+					{
+						value: "yes",
+						label: "Yes"
+					},
+					{
+						value: "no",
+						label: "No"
+					},
+					{
+						value: "unfilled",
+						label: "Skip"
+					}
+				],
+				initialValue: current === "yes" || current === "no" ? current : "unfilled"
+			});
+			if (p.isCancel(result)) return null;
+			values$1[opt.id] = result;
+		}
+		return {
+			op: "set_checkboxes",
+			fieldId: field.id,
+			values: values$1
+		};
+	}
+	const values = {};
+	for (const opt of field.options) {
+		const current = currentValues[opt.id];
+		const result = await p.select({
+			message: `${opt.label}`,
+			options: [
+				{
+					value: "todo",
+					label: "To do"
+				},
+				{
+					value: "active",
+					label: "In progress"
+				},
+				{
+					value: "done",
+					label: "Done"
+				},
+				{
+					value: "incomplete",
+					label: "Incomplete"
+				},
+				{
+					value: "na",
+					label: "N/A"
+				}
+			],
+			initialValue: current ?? "todo"
+		});
+		if (p.isCancel(result)) return null;
+		values[opt.id] = result;
+	}
+	return {
+		op: "set_checkboxes",
+		fieldId: field.id,
+		values
+	};
+}
+/**
+* Prompt for a URL field value.
+*/
+async function promptForUrl(ctx) {
+	const field = ctx.field;
+	const currentVal = ctx.currentValue?.kind === "url" ? ctx.currentValue.value : null;
+	const result = await p.text({
+		message: formatFieldLabel(ctx),
+		placeholder: currentVal ?? "https://example.com",
+		initialValue: currentVal ?? "",
+		validate: (value) => {
+			if (field.required && !value.trim()) return "This field is required";
+			if (!value.trim()) return;
+			try {
+				new URL(value);
+			} catch {
+				return "Please enter a valid URL (e.g., https://example.com)";
+			}
+		}
+	});
+	if (p.isCancel(result)) return null;
+	if (!result && !field.required) return null;
+	return {
+		op: "set_url",
+		fieldId: field.id,
+		value: result || null
+	};
+}
+/**
+* Prompt for a URL list field value.
+*/
+async function promptForUrlList(ctx) {
+	const field = ctx.field;
+	const currentItems = ctx.currentValue?.kind === "url_list" ? ctx.currentValue.items : [];
+	const hint = ctx.description ? `${ctx.description.slice(0, 50)}... (one URL per line)` : "Enter URLs, one per line. Press Enter twice when done.";
+	const result = await p.text({
+		message: formatFieldLabel(ctx),
+		placeholder: hint,
+		initialValue: currentItems.join("\n"),
+		validate: (value) => {
+			const items$1 = value.split("\n").map((s) => s.trim()).filter(Boolean);
+			if (field.required && items$1.length === 0) return "At least one URL is required";
+			if (field.minItems && items$1.length < field.minItems) return `Minimum ${field.minItems} URLs required`;
+			if (field.maxItems && items$1.length > field.maxItems) return `Maximum ${field.maxItems} URLs allowed`;
+			for (const item of items$1) try {
+				new URL(item);
+			} catch {
+				return `Invalid URL: ${item}`;
+			}
+		}
+	});
+	if (p.isCancel(result)) return null;
+	const items = result.split("\n").map((s) => s.trim()).filter(Boolean);
+	if (items.length === 0 && !field.required) return null;
+	return {
+		op: "set_url_list",
+		fieldId: field.id,
+		items
+	};
+}
+/**
+* Prompt user for a single field value based on field type.
+* Returns a Patch to set the value, or null if skipped/cancelled.
+*
+* For optional fields, first offers a choice to skip or fill.
+*/
+async function promptForField(ctx) {
+	if (ctx.description) p.note(ctx.description, pc.dim("Instructions"));
+	const skipOrFillResult = await promptSkipOrFill(ctx);
+	if (skipOrFillResult === null) return null;
+	if (typeof skipOrFillResult !== "string") return skipOrFillResult;
+	switch (ctx.field.kind) {
+		case "string": return promptForString(ctx);
+		case "number": return promptForNumber(ctx);
+		case "string_list": return promptForStringList(ctx);
+		case "single_select": return promptForSingleSelect(ctx);
+		case "multi_select": return promptForMultiSelect(ctx);
+		case "checkboxes": return promptForCheckboxes(ctx);
+		case "url": return promptForUrl(ctx);
+		case "url_list": return promptForUrlList(ctx);
+		default: return null;
+	}
+}
+/**
+* Run an interactive fill session for a list of field issues.
+* Returns patches for all filled fields.
+*
+* @param form - The parsed form
+* @param issues - The issues indicating fields to fill
+* @returns Array of patches to apply
+*/
+async function runInteractiveFill(form, issues) {
+	const fieldIssues = issues.filter((i) => i.scope === "field");
+	const seenFieldIds = /* @__PURE__ */ new Set();
+	const uniqueFieldIssues = fieldIssues.filter((issue) => {
+		if (seenFieldIds.has(issue.ref)) return false;
+		seenFieldIds.add(issue.ref);
+		return true;
+	});
+	if (uniqueFieldIssues.length === 0) {
+		p.note("No fields to fill for the selected role.", "Info");
+		return {
+			patches: [],
+			cancelled: false
+		};
+	}
+	const patches = [];
+	let index = 0;
+	for (const issue of uniqueFieldIssues) {
+		const field = getFieldById(form, issue.ref);
+		if (!field) continue;
+		index++;
+		const response = form.responsesByFieldId[field.id];
+		const patch = await promptForField({
+			field,
+			currentValue: response?.state === "answered" ? response.value : void 0,
+			description: getFieldDescription(form, field.id),
+			index,
+			total: uniqueFieldIssues.length
+		});
+		if (patch === null && p.isCancel(patch)) {
+			const shouldContinue = await p.confirm({
+				message: "Cancel and discard changes?",
+				initialValue: false
+			});
+			if (p.isCancel(shouldContinue) || shouldContinue) return {
+				patches: [],
+				cancelled: true
+			};
+			index--;
+			continue;
+		}
+		if (patch) patches.push(patch);
+	}
+	return {
+		patches,
+		cancelled: false
+	};
+}
+/**
+* Show intro message for interactive fill session.
+*/
+function showInteractiveIntro(formTitle, role, fieldCount) {
+	p.intro(pc.bgCyan(pc.black(" Markform Interactive Fill ")));
+	const lines = [
+		`${pc.bold("Form:")} ${formTitle}`,
+		`${pc.bold("Role:")} ${role}`,
+		`${pc.bold("Fields:")} ${fieldCount} to fill`
+	];
+	p.note(lines.join("\n"), "Session Info");
+}
+/**
+* Show outro message after interactive fill.
+*/
+function showInteractiveOutro(patchCount, cancelled) {
+	if (cancelled) {
+		p.cancel("Interactive fill cancelled.");
+		return;
+	}
+	if (patchCount === 0) {
+		p.outro(pc.yellow("No changes made."));
+		return;
+	}
+	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
+/**
+* Print non-interactive list of examples.
+*/
+function printExamplesList() {
+	console.log(pc.bold("Available examples:\n"));
+	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("");
+	}
+}
+/**
+* Display API availability status at startup.
+*/
+function showApiStatus() {
+	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("✓") : "○";
+		const envVar = hasKey ? info.envVar : pc.yellow(info.envVar);
+		console.log(`  ${status} ${provider} (${envVar})`);
+	}
+	console.log("");
+}
+/**
+* Build model options for the select prompt.
+*/
+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("✓") : "○";
+		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 for agent fill.
+*/
+async function promptForModel() {
+	const modelOptions = buildModelOptions();
+	const selection = await p.select({
+		message: "Select LLM model:",
+		options: modelOptions
+	});
+	if (p.isCancel(selection)) return null;
+	if (selection === "custom") {
+		const customModel = await p.text({
+			message: "Model ID (provider/model-id):",
+			placeholder: "anthropic/claude-sonnet-4-20250514",
+			validate: (value) => {
+				if (!value.includes("/")) return "Format: provider/model-id (e.g., anthropic/claude-sonnet-4-20250514)";
+			}
+		});
+		if (p.isCancel(customModel)) return null;
+		return customModel;
+	}
+	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, configOverrides) {
+	const spinner = p.spinner();
+	try {
+		spinner.start(`Resolving model: ${modelId}`);
+		const { model, provider } = await resolveModel(modelId);
+		spinner.stop(`Model resolved: ${modelId}`);
+		const harnessConfig = {
+			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
+		});
+		p.log.step(pc.bold("Agent fill in progress..."));
+		let stepResult = harness.step();
+		while (!stepResult.isComplete && !harness.hasReachedMaxTurns()) {
+			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);
+				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);
+			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)`));
+		else p.log.warn(pc.yellow(`Max turns reached (${harnessConfig.maxTurns})`));
+		Object.assign(form, harness.getForm());
+		return {
+			success: stepResult.isComplete,
+			turnCount: harness.getTurnNumber()
+		};
+	} catch (error) {
+		spinner.stop(pc.red("Agent fill failed"));
+		throw error;
+	}
+}
+/**
+* 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, 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: examples.map((example$1) => ({
+				value: example$1.id,
+				label: example$1.title ?? example$1.id,
+				hint: example$1.description
+			}))
+		});
+		if (p.isCancel(selection)) {
+			p.cancel("Cancelled.");
+			process.exit(0);
+		}
+		selectedId = selection;
+	}
+	const example = getExampleById(selectedId);
+	if (!example) {
+		p.cancel(`Unknown example: ${selectedId}`);
+		process.exit(1);
+	}
+	const defaultFilename = basename(generateVersionedPathInFormsDir(example.filename, formsDir));
+	const filenameResult = await p.text({
+		message: `Output filename (in ${formatPath(formsDir)}):`,
+		initialValue: defaultFilename,
+		validate: (value) => {
+			if (!value.trim()) return "Filename is required";
+			if (!value.endsWith(".form.md") && !value.endsWith(".md")) return "Filename should end with .form.md or .md";
+		}
+	});
+	if (p.isCancel(filenameResult)) {
+		p.cancel("Cancelled.");
+		process.exit(0);
+	}
+	const filename = filenameResult;
+	const outputPath = join(formsDir, filename);
+	if (existsSync(outputPath)) {
+		const overwrite = await p.confirm({
+			message: `${filename} already exists. Overwrite?`,
+			initialValue: false
+		});
+		if (p.isCancel(overwrite) || !overwrite) {
+			p.cancel("Cancelled.");
+			process.exit(0);
+		}
+	}
+	let content;
+	try {
+		content = loadExampleContent(selectedId);
+		await writeFile(outputPath, content);
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		p.cancel(`Failed to write file: ${message}`);
+		process.exit(1);
+	}
+	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));
+	if (uniqueFieldIds.size === 0) {
+		p.log.info("No user-role fields to fill in this example.");
+		if (inspect(form, { targetRoles: [AGENT_ROLE] }).issues.filter((i) => i.scope === "field").length === 0) {
+			logTiming({
+				verbose: false,
+				format: "console",
+				dryRun: false,
+				quiet: false
+			}, "Total time", Date.now() - startTime);
+			p.outro("Form scaffolded with no fields to fill.");
+			return;
+		}
+	} else {
+		showInteractiveIntro(form.schema.title ?? form.schema.id, targetRoles.join(", "), uniqueFieldIds.size);
+		const { patches, cancelled } = await runInteractiveFill(form, inspectResult.issues);
+		if (cancelled) {
+			showInteractiveOutro(0, true);
+			process.exit(1);
+		}
+		if (patches.length > 0) applyPatches(form, patches);
+		userFillOutputs = await exportMultiFormat(form, outputPath);
+		showInteractiveOutro(patches.length, false);
+		console.log("");
+		p.log.success("Outputs:");
+		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",
+			dryRun: false,
+			quiet: false
+		}, "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: confirmMessage,
+			initialValue: true
+		});
+		if (p.isCancel(runAgent) || !runAgent) {
+			console.log("");
+			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 = isResearchExample ? await promptForWebSearchModel() : await promptForModel();
+		if (!modelId) {
+			p.cancel("Cancelled.");
+			process.exit(0);
+		}
+		const agentDefaultFilename = basename(generateVersionedPathInFormsDir(outputPath, formsDir));
+		const agentFilenameResult = await p.text({
+			message: `Agent output filename (in ${formatPath(formsDir)}):`,
+			initialValue: agentDefaultFilename,
+			validate: (value) => {
+				if (!value.trim()) return "Filename is required";
+			}
+		});
+		if (p.isCancel(agentFilenameResult)) {
+			p.cancel("Cancelled.");
+			process.exit(0);
+		}
+		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 } = await runAgentFill(form, modelId, agentOutputPath, configOverrides);
+			logTiming({
+				verbose: false,
+				format: "console",
+				dryRun: false,
+				quiet: false
+			}, timingLabel, Date.now() - agentStartTime);
+			const { formPath, rawPath, yamlPath } = await exportMultiFormat(form, agentOutputPath);
+			console.log("");
+			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);
+			const failMessage = isResearchExample ? "Research failed" : "Agent fill failed";
+			p.log.error(`${failMessage}: ${message}`);
+			console.log("");
+			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("Happy form filling!");
+}
+/**
+* Register the examples command.
+*/
+function registerExamplesCommand(program) {
+	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();
+				return;
+			}
+			if (options.name) {
+				if (!getExampleById(options.name)) {
+					logError(`Unknown example: ${options.name}`);
+					console.log("\nAvailable examples:");
+					for (const ex of EXAMPLE_DEFINITIONS) console.log(`  ${ex.id}`);
+					process.exit(1);
+				}
+			}
+			await runInteractiveFlow(options.name, ctx.formsDir);
+		} catch (error) {
+			logError(error instanceof Error ? error.message : String(error));
+			process.exit(1);
+		}
+	});
+}
+
+//#endregion
+//#region src/cli/commands/export.ts
+/**
+* Register the export command.
+*/
+function registerExportCommand(program) {
+	program.command("export <file>").description("Export form as markform (default), markdown (readable), or json/yaml for structured data").option("--compact", "Output compact JSON (no formatting, only for JSON format)").action(async (file, options, cmd) => {
+		const ctx = getCommandContext(cmd);
+		let format = "markform";
+		if (ctx.format === "json") format = "json";
+		else if (ctx.format === "yaml") format = "yaml";
+		else if (ctx.format === "markdown") format = "markdown";
+		else if (ctx.format === "markform") format = "markform";
+		try {
+			logVerbose(ctx, `Reading file: ${file}`);
+			const content = await readFile$1(file);
+			logVerbose(ctx, "Parsing form...");
+			const form = parseForm(content);
+			if (format === "markform") {
+				console.log(serialize(form));
+				return;
+			}
+			if (format === "markdown") {
+				console.log(serializeRawMarkdown(form));
+				return;
+			}
+			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
+						})) } : {}
+					}))
+				}))
+			};
+			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));
+			else console.log(JSON.stringify(output, null, 2));
+			else console.log(YAML.stringify(output));
+		} catch (error) {
+			logError(error instanceof Error ? error.message : String(error));
+			process.exit(1);
+		}
+	});
+}
+
+//#endregion
+//#region src/cli/commands/fill.ts
+/**
+* Format session transcript for console output.
+*/
+function formatConsoleSession(transcript, useColors) {
+	const lines = [];
+	const bold = useColors ? pc.bold : (s) => s;
+	const dim = useColors ? pc.dim : (s) => s;
+	const cyan = useColors ? pc.cyan : (s) => s;
+	const green = useColors ? pc.green : (s) => s;
+	const yellow = useColors ? pc.yellow : (s) => s;
+	lines.push(bold(cyan("Session Transcript")));
+	lines.push("");
+	lines.push(`${bold("Form:")} ${transcript.form.path}`);
+	lines.push(`${bold("Mode:")} ${transcript.mode}`);
+	lines.push(`${bold("Version:")} ${transcript.sessionVersion}`);
+	lines.push("");
+	lines.push(bold("Harness Config:"));
+	lines.push(`  Max turns: ${transcript.harness.maxTurns}`);
+	lines.push(`  Max patches/turn: ${transcript.harness.maxPatchesPerTurn}`);
+	lines.push(`  Max issues/turn: ${transcript.harness.maxIssuesPerTurn}`);
+	lines.push("");
+	lines.push(bold(`Turns (${transcript.turns.length}):`));
+	for (const turn of transcript.turns) {
+		const issueCount = turn.inspect.issues.length;
+		const patchCount = turn.apply.patches.length;
+		const afterIssues = turn.after.requiredIssueCount;
+		lines.push(`  Turn ${turn.turn}: ${dim(`${issueCount} issues`)} → ${yellow(`${patchCount} patches`)} → ${afterIssues === 0 ? green("0 remaining") : dim(`${afterIssues} remaining`)}`);
+	}
+	lines.push("");
+	const expectText = transcript.final.expectComplete ? green("✓ complete") : yellow("○ incomplete");
+	lines.push(`${bold("Expected:")} ${expectText}`);
+	lines.push(`${bold("Completed form:")} ${transcript.final.expectedCompletedForm}`);
+	return lines.join("\n");
+}
+/**
+* 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-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 {
+			const startTime = Date.now();
+			let targetRoles;
+			if (options.roles) try {
+				targetRoles = parseRolesFlag(options.roles);
+			} catch (error) {
+				logError(`Invalid --roles: ${error instanceof Error ? error.message : String(error)}`);
+				process.exit(1);
+			}
+			else targetRoles = options.interactive ? [USER_ROLE] : [AGENT_ROLE];
+			let fillMode = "continue";
+			if (options.mode) {
+				if (options.mode !== "continue" && options.mode !== "overwrite") {
+					logError(`Invalid --mode: ${options.mode}. Valid modes: continue, overwrite`);
+					process.exit(1);
+				}
+				fillMode = options.mode;
+			}
+			logVerbose(ctx, `Reading form: ${filePath}`);
+			const formContent = await readFile$1(filePath);
+			logVerbose(ctx, "Parsing form...");
+			const form = parseForm(formContent);
+			if (options.interactive) {
+				if (options.mock) {
+					logError("--interactive cannot be used with --mock");
+					process.exit(1);
+				}
+				if (options.model) {
+					logError("--interactive cannot be used with --model");
+					process.exit(1);
+				}
+				if (options.mockSource) {
+					logError("--interactive cannot be used with --mock-source");
+					process.exit(1);
+				}
+				const inspectResult = inspect(form, { targetRoles });
+				const formTitle = form.schema.title ?? form.schema.id;
+				const fieldIssues = inspectResult.issues.filter((i) => i.scope === "field");
+				const uniqueFieldIds = new Set(fieldIssues.map((i) => i.ref));
+				showInteractiveIntro(formTitle, targetRoles.join(", "), uniqueFieldIds.size);
+				const { patches, cancelled } = await runInteractiveFill(form, inspectResult.issues);
+				if (cancelled) {
+					showInteractiveOutro(0, true);
+					process.exit(1);
+				}
+				if (patches.length > 0) applyPatches(form, patches);
+				const durationMs$1 = Date.now() - startTime;
+				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 } = await exportMultiFormat(form, outputPath$1);
+					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)")}`);
+				}
+				logTiming(ctx, "Fill time", durationMs$1);
+				if (patches.length > 0) {
+					console.log("");
+					console.log("Next step: fill remaining fields with agent");
+					console.log(`  markform fill ${formatPath(outputPath$1)} --model=<provider/model>`);
+				}
+				process.exit(0);
+			}
+			if (options.mock && !options.mockSource) {
+				logError("--mock requires --mock-source <file>");
+				process.exit(1);
+			}
+			if (!options.mock && !options.model) {
+				logError("Live agent requires --model <provider/model-id>");
+				console.log("");
+				console.log(formatSuggestedLlms());
+				process.exit(1);
+			}
+			if (targetRoles.includes("*")) logWarn(ctx, "Warning: Filling all roles including user-designated fields");
+			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$1(mockPath)));
+			} else {
+				const modelId = options.model;
+				logVerbose(ctx, `Resolving model: ${modelId}`);
+				const { model, provider } = await resolveModel(modelId);
+				let systemPrompt;
+				if (options.instructions) {
+					systemPrompt = options.instructions;
+					logVerbose(ctx, "Using inline system prompt from --instructions");
+				} else if (options.prompt) {
+					const promptPath = resolve(options.prompt);
+					logVerbose(ctx, `Reading system prompt from: ${promptPath}`);
+					systemPrompt = await readFile$1(promptPath);
+				}
+				const primaryRole = targetRoles[0] === "*" ? AGENT_ROLE : targetRoles[0];
+				const liveAgent = createLiveAgent({
+					model,
+					provider,
+					systemPromptAddition: systemPrompt,
+					targetRole: primaryRole
+				});
+				agent = liveAgent;
+				logInfo(ctx, `Available tools: ${liveAgent.getAvailableToolNames().join(", ")}`);
+				logVerbose(ctx, `Using live agent with model: ${modelId}`);
+			}
+			logInfo(ctx, pc.cyan(`Filling form: ${filePath}`));
+			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 turn: ${harnessConfig.maxIssuesPerTurn}`);
+			logVerbose(ctx, `Target roles: ${targetRoles.includes("*") ? "*" : targetRoles.join(", ")}`);
+			logVerbose(ctx, `Fill mode: ${fillMode}`);
+			let stepResult = harness.step();
+			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);
+				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);
+					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: 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, ``);
+						logVerbose(ctx, pc.dim(`  ─── System Prompt ───`));
+						for (const line of stats.prompts.system.split("\n")) logVerbose(ctx, pc.dim(`  ${line}`));
+						logVerbose(ctx, ``);
+						logVerbose(ctx, pc.dim(`  ─── Context Prompt ───`));
+						for (const line of stats.prompts.context.split("\n")) logVerbose(ctx, pc.dim(`  ${line}`));
+						logVerbose(ctx, ``);
+					}
+				}
+				let llmStats;
+				if (stats) llmStats = {
+					inputTokens: stats.inputTokens,
+					outputTokens: stats.outputTokens,
+					toolCalls: stats.toolCalls.length > 0 ? stats.toolCalls : void 0
+				};
+				stepResult = harness.apply(patches, stepResult.issues, llmStats);
+				if (stepResult.isComplete) logInfo(ctx, pc.green(`  ✓ Complete`));
+				else if (!harness.hasReachedMaxTurns()) {
+					stepResult = harness.step();
+					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);
+			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 {
+				await writeFile(outputPath, formMarkdown);
+				logSuccess(ctx, `Form written to: ${outputPath}`);
+			}
+			const transcript = buildSessionTranscript(filePath, options.mock ? "mock" : "live", mockPath, options.model, harnessConfig, harness.getTurns(), stepResult.isComplete, outputPath);
+			if (options.record) {
+				const recordPath = resolve(options.record);
+				const yaml = serializeSession(transcript);
+				if (ctx.dryRun) {
+					logInfo(ctx, `[DRY RUN] Would write session to: ${recordPath}`);
+					console.log(yaml);
+				} else {
+					await writeFile(recordPath, yaml);
+					logSuccess(ctx, `Session recorded to: ${recordPath}`);
+				}
+			} else {
+				const output = formatOutput(ctx, transcript, (data, useColors) => formatConsoleSession(data, useColors));
+				console.log(output);
+			}
+			process.exit(stepResult.isComplete ? 0 : 1);
+		} catch (error) {
+			logError(error instanceof Error ? error.message : String(error));
+			process.exit(1);
+		}
+	});
+}
+/**
+* Build a session transcript from harness execution.
+*/
+function buildSessionTranscript(formPath, mockMode, mockPath, modelId, harnessConfig, turns, expectComplete, outputPath) {
+	const transcript = {
+		sessionVersion: "0.1.0",
+		mode: mockMode,
+		form: { path: formPath },
+		harness: harnessConfig,
+		turns,
+		final: {
+			expectComplete,
+			expectedCompletedForm: mockMode === "mock" ? mockPath ?? outputPath : outputPath
+		}
+	};
+	if (mockMode === "mock" && mockPath) transcript.mock = { completedMock: mockPath };
+	else if (mockMode === "live" && modelId) transcript.live = { modelId };
+	return transcript;
+}
+
+//#endregion
+//#region src/cli/commands/inspect.ts
+/**
+* Format state badge for console output.
+*/
+function formatState$1(state, useColors) {
+	const [text, colorFn] = {
+		complete: ["✓ complete", pc.green],
+		incomplete: ["○ incomplete", pc.yellow],
+		empty: ["◌ empty", pc.dim],
+		invalid: ["✗ invalid", pc.red]
+	}[state] ?? [state, (s) => s];
+	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:
+* - P1: bold red (critical)
+* - P2: yellow (high)
+* - P3: cyan (medium)
+* - P4: blue (low)
+* - P5: dim/gray (minimal)
+*/
+function formatPriority$1(priority, useColors) {
+	const label = `P${priority}`;
+	if (!useColors) return label;
+	switch (priority) {
+		case 1: return pc.red(pc.bold(label));
+		case 2: return pc.yellow(label);
+		case 3: return pc.cyan(label);
+		case 4: return pc.blue(label);
+		case 5:
+		default: return pc.dim(label);
+	}
+}
+/**
+* Format severity badge for console output.
+*/
+function formatSeverity$1(severity, useColors) {
+	if (!useColors) return severity;
+	return severity === "required" ? pc.red(severity) : pc.yellow(severity);
+}
+/**
+* Format a field value for console display.
+*/
+function formatFieldValue(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.map((i) => `"${i}"`).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.map((i) => `"${i}"`).join(", ")}]`) : dim("(empty)");
+		default: return dim("(unknown)");
+	}
+}
+/**
+* Format inspect report for console output.
+*/
+function formatConsoleReport$1(report, useColors) {
+	const lines = [];
+	const bold = useColors ? pc.bold : (s) => s;
+	const dim = useColors ? pc.dim : (s) => s;
+	const cyan = useColors ? pc.cyan : (s) => s;
+	const yellow = useColors ? pc.yellow : (s) => s;
+	lines.push(bold(cyan("Form Inspection Report")));
+	if (report.title) lines.push(`${bold("Title:")} ${report.title}`);
+	lines.push("");
+	lines.push(`${bold("Form State:")} ${formatState$1(report.form_state, useColors)}`);
+	lines.push("");
+	const structure = report.structure;
+	lines.push(bold("Structure:"));
+	lines.push(`  Groups: ${structure.groupCount}`);
+	lines.push(`  Fields: ${structure.fieldCount}`);
+	lines.push(`  Options: ${structure.optionCount}`);
+	lines.push("");
+	const progress = report.progress;
+	lines.push(bold("Progress:"));
+	lines.push(`  Total fields: ${progress.counts.totalFields}`);
+	lines.push(`  Required: ${progress.counts.requiredFields}`);
+	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) {
+		lines.push(`  ${bold(group.title ?? group.id)}`);
+		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} ${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) {
+			const priority = formatPriority$1(issue.priority, useColors);
+			const severity = formatSeverity$1(issue.severity, useColors);
+			const blockedInfo = issue.blockedBy ? ` ${dim(`(blocked by: ${issue.blockedBy})`)}` : "";
+			lines.push(`  ${priority} (${severity}) ${dim(`[${issue.scope}]`)} ${dim(issue.ref)}: ${issue.message}${blockedInfo}`);
+		}
+	} else lines.push(dim("No issues found."));
+	return lines.join("\n");
+}
+/**
+* Register the inspect command.
+*/
+function registerInspectCommand(program) {
+	program.command("inspect <file>").description("Inspect a form and display its structure, progress, and issues").option("--roles <roles>", "Filter issues by target roles (comma-separated, or '*' for all; default: all)").action(async (file, options, cmd) => {
+		const ctx = getCommandContext(cmd);
+		try {
+			let targetRoles;
+			if (options.roles) try {
+				targetRoles = parseRolesFlag(options.roles);
+				if (targetRoles.includes("*")) targetRoles = void 0;
+			} catch (error) {
+				logError(`Invalid --roles: ${error instanceof Error ? error.message : String(error)}`);
+				process.exit(1);
+			}
+			logVerbose(ctx, `Reading file: ${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,
+				progress: result.progressSummary,
+				form_state: result.formState,
+				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,
+						role: field.role
+					}))
+				})),
+				values,
+				notes: form.notes,
+				issues: result.issues.map((issue) => ({
+					ref: issue.ref,
+					scope: issue.scope,
+					reason: issue.reason,
+					message: issue.message,
+					priority: issue.priority,
+					severity: issue.severity,
+					blockedBy: issue.blockedBy
+				}))
+			}, (data, useColors) => formatConsoleReport$1(data, useColors));
+			console.log(output);
+		} catch (error) {
+			logError(error instanceof Error ? error.message : String(error));
+			process.exit(1);
+		}
+	});
+}
+
+//#endregion
+//#region src/cli/commands/readme.ts
+/**
+* Get the path to the README.md file.
+* Works both during development and when installed as a package.
+*/
+function getReadmePath() {
+	const thisDir = dirname(fileURLToPath(import.meta.url));
+	if (thisDir.split(/[/\\]/).pop() === "dist") return join(dirname(thisDir), "README.md");
+	return join(dirname(dirname(dirname(thisDir))), "README.md");
+}
+/**
+* Load the README content.
+*/
+function loadReadme() {
+	const readmePath = getReadmePath();
+	try {
+		return readFileSync(readmePath, "utf-8");
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		throw new Error(`Failed to load README from ${readmePath}: ${message}`);
+	}
+}
+/**
+* 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");
+	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() {
+	return process.stdout.isTTY === true;
+}
+/**
+* Display content. In a future enhancement, could pipe to a pager for long output.
+*/
+function displayContent(content) {
+	console.log(content);
+}
+/**
+* Register the spec command.
+*/
+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(loadSpec(), !options.raw && isInteractive() && !ctx.quiet));
+		} catch (error) {
+			logError(error instanceof Error ? error.message : String(error));
+			process.exit(1);
+		}
+	});
+}
+
+//#endregion
+//#region src/cli/commands/models.ts
+/**
+* Get model info for all providers or a specific one.
+*/
+function getModelInfo(providerFilter) {
+	const providers = getProviderNames();
+	if (providerFilter && !providers.includes(providerFilter)) throw new Error(`Unknown provider: "${providerFilter}". Available: ${providers.join(", ")}`);
+	return (providerFilter ? [providerFilter] : providers).map((provider) => {
+		return {
+			provider,
+			envVar: getProviderInfo(provider).envVar,
+			models: SUGGESTED_LLMS[provider] ?? []
+		};
+	});
+}
+/**
+* Format model info for console output.
+*/
+function formatConsoleOutput(info, useColors) {
+	const lines = [];
+	const bold = useColors ? pc.bold : (s) => s;
+	const cyan = useColors ? pc.cyan : (s) => s;
+	const dim = useColors ? pc.dim : (s) => s;
+	const green = useColors ? pc.green : (s) => s;
+	for (const { provider, envVar, models } of info) {
+		lines.push(bold(cyan(`${provider}/`)));
+		lines.push(`  ${dim("env:")} ${envVar}`);
+		if (models.length > 0) {
+			lines.push(`  ${dim("models:")}`);
+			for (const model of models) lines.push(`    ${green(`${provider}/${model}`)}`);
+		} else lines.push(`  ${dim("(no suggested models)")}`);
+		lines.push("");
+	}
+	if (lines.length > 0 && lines[lines.length - 1] === "") lines.pop();
+	return lines.join("\n");
+}
+/**
+* Register the models command.
+*/
+function registerModelsCommand(program) {
+	program.command("models").description("List available AI providers and example models").option("-p, --provider <name>", "Filter by provider (anthropic, openai, google, xai, deepseek)").action((options, cmd) => {
+		const ctx = getCommandContext(cmd);
+		try {
+			const output = formatOutput(ctx, getModelInfo(options.provider), (data, useColors) => formatConsoleOutput(data, useColors));
+			console.log(output);
+		} catch (error) {
+			logError(error instanceof Error ? error.message : String(error));
+			process.exit(1);
+		}
+	});
+}
+
+//#endregion
+//#region src/cli/commands/serve.ts
+/**
+* Open a URL in the default browser (cross-platform).
+*/
+function openBrowser(url) {
+	const platform = process.platform;
+	let command;
+	if (platform === "darwin") command = `open "${url}"`;
+	else if (platform === "win32") command = `start "" "${url}"`;
+	else command = `xdg-open "${url}"`;
+	exec(command, (error) => {
+		if (error) {}
+	});
+}
+/**
+* Register the serve command.
+*/
+function registerServeCommand(program) {
+	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}`);
+			const content = await readFile$1(filePath);
+			let form = null;
+			if (fileType === "form") form = parseForm(content);
+			const server = createServer((req, res) => {
+				handleRequest(req, res, filePath, fileType, form, ctx, (updatedForm) => {
+					form = updatedForm;
+				}).catch((err) => {
+					console.error("Request error:", err);
+					res.writeHead(500);
+					res.end("Internal Server Error");
+				});
+			});
+			server.listen(port, () => {
+				const url = `http://localhost:${port}`;
+				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);
+			});
+			process.on("SIGINT", () => {
+				logInfo(ctx, "\nShutting down server...");
+				server.close();
+				process.exit(0);
+			});
+		} catch (error) {
+			logError(error instanceof Error ? error.message : String(error));
+			process.exit(1);
+		}
+	});
+}
+/**
+* Handle HTTP requests.
+* Dispatches to appropriate renderer based on file type.
+*/
+async function handleRequest(req, res, filePath, fileType, form, ctx, updateForm) {
+	const url = req.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 (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 {
+		res.writeHead(404);
+		res.end("Not Found");
+	}
+}
+/**
+* Parse form body data.
+*/
+function parseFormBody(body) {
+	const result = {};
+	const params = new URLSearchParams(body);
+	for (const [key, value] of params) {
+		const existing = result[key];
+		if (existing !== void 0) if (Array.isArray(existing)) existing.push(value);
+		else result[key] = [existing, value];
+		else result[key] = value;
+	}
+	return result;
+}
+/**
+* Convert form data to patches.
+*/
+function formDataToPatches(formData, form) {
+	const patches = [];
+	const fields = form.schema.groups.flatMap((g) => g.children);
+	for (const field of fields) {
+		const fieldId = field.id;
+		if (formData[`__skip__${fieldId}`] === "1" && !field.required) {
+			patches.push({
+				op: "skip_field",
+				fieldId,
+				role: "user"
+			});
+			continue;
+		}
+		switch (field.kind) {
+			case "string": {
+				const value = formData[fieldId];
+				if (typeof value === "string" && value.trim() !== "") patches.push({
+					op: "set_string",
+					fieldId,
+					value: value.trim()
+				});
+				else if (!value || typeof value === "string" && value.trim() === "") patches.push({
+					op: "clear_field",
+					fieldId
+				});
+				break;
+			}
+			case "number": {
+				const value = formData[fieldId];
+				if (typeof value === "string" && value.trim() !== "") {
+					const num = parseFloat(value);
+					if (!isNaN(num)) patches.push({
+						op: "set_number",
+						fieldId,
+						value: num
+					});
+				} else patches.push({
+					op: "clear_field",
+					fieldId
+				});
+				break;
+			}
+			case "string_list": {
+				const value = formData[fieldId];
+				if (typeof value === "string" && value.trim() !== "") {
+					const items = value.split("\n").map((s) => s.trim()).filter((s) => s !== "");
+					if (items.length > 0) patches.push({
+						op: "set_string_list",
+						fieldId,
+						items
+					});
+					else patches.push({
+						op: "clear_field",
+						fieldId
+					});
+				} else patches.push({
+					op: "clear_field",
+					fieldId
+				});
+				break;
+			}
+			case "single_select": {
+				const value = formData[fieldId];
+				if (typeof value === "string" && value !== "") patches.push({
+					op: "set_single_select",
+					fieldId,
+					selected: value
+				});
+				else patches.push({
+					op: "clear_field",
+					fieldId
+				});
+				break;
+			}
+			case "multi_select": {
+				const value = formData[fieldId];
+				const selected = Array.isArray(value) ? value : value ? [value] : [];
+				if (selected.length > 0 && selected[0] !== "") patches.push({
+					op: "set_multi_select",
+					fieldId,
+					selected
+				});
+				else patches.push({
+					op: "clear_field",
+					fieldId
+				});
+				break;
+			}
+			case "checkboxes":
+				if ((field.checkboxMode ?? "multi") === "simple") {
+					const value = formData[fieldId];
+					const checked = Array.isArray(value) ? value : value ? [value] : [];
+					const values = {};
+					for (const opt of field.options) values[opt.id] = checked.includes(opt.id) ? "done" : "todo";
+					patches.push({
+						op: "set_checkboxes",
+						fieldId,
+						values
+					});
+				} else {
+					const values = {};
+					for (const opt of field.options) {
+						const selectValue = formData[`${fieldId}.${opt.id}`];
+						if (typeof selectValue === "string" && selectValue !== "") values[opt.id] = selectValue;
+					}
+					if (Object.keys(values).length > 0) patches.push({
+						op: "set_checkboxes",
+						fieldId,
+						values
+					});
+				}
+				break;
+			case "url": {
+				const value = formData[fieldId];
+				if (typeof value === "string" && value.trim() !== "") patches.push({
+					op: "set_url",
+					fieldId,
+					value: value.trim()
+				});
+				else patches.push({
+					op: "clear_field",
+					fieldId
+				});
+				break;
+			}
+			case "url_list": {
+				const value = formData[fieldId];
+				if (typeof value === "string" && value.trim() !== "") {
+					const items = value.split("\n").map((s) => s.trim()).filter((s) => s !== "");
+					if (items.length > 0) patches.push({
+						op: "set_url_list",
+						fieldId,
+						items
+					});
+					else patches.push({
+						op: "clear_field",
+						fieldId
+					});
+				} else patches.push({
+					op: "clear_field",
+					fieldId
+				});
+				break;
+			}
+		}
+	}
+	return patches;
+}
+/**
+* Handle form save request.
+*/
+async function handleSave(req, res, form, filePath, ctx, updateForm) {
+	try {
+		const chunks = [];
+		for await (const chunk of req) chunks.push(chunk);
+		applyPatches(form, formDataToPatches(parseFormBody(Buffer.concat(chunks).toString("utf-8")), form));
+		updateForm(form);
+		const newPath = generateVersionedPath(filePath);
+		const content = serialize(form);
+		if (ctx.dryRun) {
+			logInfo(ctx, `[DRY RUN] Would save to: ${newPath}`);
+			res.writeHead(200, { "Content-Type": "application/json" });
+			res.end(JSON.stringify({
+				success: true,
+				path: newPath,
+				dryRun: true
+			}));
+			return;
+		}
+		await writeFile(newPath, content);
+		logInfo(ctx, pc.green(`Saved to: ${newPath}`));
+		res.writeHead(200, { "Content-Type": "application/json" });
+		res.end(JSON.stringify({
+			success: true,
+			path: newPath
+		}));
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		res.writeHead(500, { "Content-Type": "application/json" });
+		res.end(JSON.stringify({
+			success: false,
+			error: message
+		}));
+	}
+}
+/**
+* Render the form as HTML.
+* @public Exported for testing.
+*/
+function renderFormHtml(form) {
+	const { schema, responsesByFieldId } = form;
+	const formTitle = schema.title ?? schema.id;
+	const groupsHtml = schema.groups.map((group) => renderGroup(group, responsesByFieldId)).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(formTitle)} - Markform</title>
+  <style>
+    * { box-sizing: border-box; }
+    body {
+      font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+      line-height: 1.6;
+      max-width: 800px;
+      margin: 0 auto;
+      padding: 2rem;
+      background: #f8f9fa;
+      color: #212529;
+    }
+    h1 { color: #495057; border-bottom: 2px solid #dee2e6; padding-bottom: 0.5rem; }
+    h2 { color: #6c757d; font-size: 1.25rem; }
+    .group {
+      background: white;
+      border-radius: 8px;
+      padding: 1.5rem;
+      margin-bottom: 1.5rem;
+      box-shadow: 0 1px 3px rgba(0,0,0,0.1);
+    }
+    .field {
+      margin-bottom: 1.5rem;
+      padding-bottom: 1rem;
+      border-bottom: 1px solid #e9ecef;
+    }
+    .field:last-child { border-bottom: none; margin-bottom: 0; padding-bottom: 0; }
+    .field-label {
+      font-weight: 600;
+      color: #495057;
+      display: block;
+      margin-bottom: 0.5rem;
+    }
+    .required { color: #dc3545; }
+    .type-badge {
+      font-size: 0.7rem;
+      padding: 0.1rem 0.3rem;
+      background: #e9ecef;
+      border-radius: 3px;
+      color: #6c757d;
+      margin-left: 0.5rem;
+      font-weight: normal;
+    }
+    input[type="text"],
+    input[type="number"],
+    textarea,
+    select {
+      width: 100%;
+      padding: 0.5rem 0.75rem;
+      font-size: 1rem;
+      border: 1px solid #ced4da;
+      border-radius: 4px;
+      background: #fff;
+      transition: border-color 0.15s ease-in-out;
+    }
+    input[type="text"]:focus,
+    input[type="number"]:focus,
+    textarea:focus,
+    select:focus {
+      outline: none;
+      border-color: #80bdff;
+      box-shadow: 0 0 0 0.2rem rgba(0,123,255,.25);
+    }
+    textarea {
+      min-height: 100px;
+      resize: vertical;
+    }
+    .checkbox-group {
+      display: flex;
+      flex-direction: column;
+      gap: 0.5rem;
+    }
+    .checkbox-item {
+      display: flex;
+      align-items: center;
+      gap: 0.5rem;
+    }
+    .checkbox-item input[type="checkbox"] {
+      width: auto;
+      margin: 0;
+    }
+    .checkbox-item label {
+      margin: 0;
+      font-weight: normal;
+      cursor: pointer;
+    }
+    .checkbox-item select {
+      width: auto;
+      min-width: 120px;
+    }
+    .option-row {
+      display: flex;
+      align-items: center;
+      gap: 0.75rem;
+      margin-bottom: 0.5rem;
+    }
+    .option-row:last-child { margin-bottom: 0; }
+    .option-label {
+      flex: 1;
+    }
+    .toolbar {
+      position: fixed;
+      bottom: 2rem;
+      right: 2rem;
+      display: flex;
+      gap: 0.5rem;
+    }
+    .btn {
+      padding: 0.75rem 1.5rem;
+      border: none;
+      border-radius: 6px;
+      font-size: 1rem;
+      cursor: pointer;
+      transition: all 0.2s;
+    }
+    .btn-primary {
+      background: #0d6efd;
+      color: white;
+    }
+    .btn-primary:hover { background: #0b5ed7; }
+    .field-help {
+      font-size: 0.85rem;
+      color: #6c757d;
+      margin-top: 0.25rem;
+    }
+    .field-actions {
+      display: flex;
+      gap: 0.5rem;
+      margin-top: 0.5rem;
+    }
+    .btn-skip {
+      padding: 0.25rem 0.75rem;
+      font-size: 0.85rem;
+      background: #f8f9fa;
+      border: 1px solid #ced4da;
+      border-radius: 4px;
+      color: #6c757d;
+      cursor: pointer;
+    }
+    .btn-skip:hover {
+      background: #e9ecef;
+      color: #495057;
+    }
+    .field-skipped {
+      opacity: 0.6;
+    }
+    .field-skipped input,
+    .field-skipped textarea,
+    .field-skipped select {
+      background: #f8f9fa;
+    }
+    .skipped-badge {
+      font-size: 0.75rem;
+      padding: 0.15rem 0.4rem;
+      background: #6c757d;
+      color: white;
+      border-radius: 3px;
+      margin-left: 0.5rem;
+    }
+  </style>
+</head>
+<body>
+  <h1>${escapeHtml(formTitle)}</h1>
+  <form method="POST" action="/save" id="markform">
+    ${groupsHtml}
+    <div class="toolbar">
+      <button type="submit" class="btn btn-primary">Save</button>
+    </div>
+  </form>
+  <script>
+    // Track fields marked for skip
+    const skippedFields = new Set();
+
+    // Handle skip button clicks
+    document.querySelectorAll('.btn-skip').forEach(btn => {
+      btn.addEventListener('click', (e) => {
+        const fieldId = e.target.dataset.skipField;
+        if (!fieldId) return;
+
+        // Toggle skip state
+        if (skippedFields.has(fieldId)) {
+          skippedFields.delete(fieldId);
+          e.target.textContent = 'Skip';
+          e.target.classList.remove('btn-skip-active');
+          // Re-enable the field input
+          const fieldDiv = e.target.closest('.field');
+          fieldDiv.classList.remove('field-skipped');
+          fieldDiv.querySelectorAll('input, select, textarea').forEach(input => {
+            input.disabled = false;
+          });
+        } else {
+          skippedFields.add(fieldId);
+          e.target.textContent = 'Unskip';
+          e.target.classList.add('btn-skip-active');
+          // Disable the field input to show it's skipped
+          const fieldDiv = e.target.closest('.field');
+          fieldDiv.classList.add('field-skipped');
+          fieldDiv.querySelectorAll('input, select, textarea').forEach(input => {
+            input.disabled = true;
+          });
+        }
+      });
+    });
+
+    document.getElementById('markform').addEventListener('submit', async (e) => {
+      e.preventDefault();
+      const formData = new FormData(e.target);
+      const params = new URLSearchParams();
+
+      // Add skip markers for skipped fields
+      for (const fieldId of skippedFields) {
+        params.append('__skip__' + fieldId, '1');
+      }
+
+      for (const [key, value] of formData) {
+        params.append(key, value);
+      }
+      try {
+        const res = await fetch('/save', {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+          body: params.toString()
+        });
+        const data = await res.json();
+        if (data.success) {
+          alert('Saved to: ' + data.path);
+          location.reload();
+        } else {
+          alert('Error: ' + data.error);
+        }
+      } catch (err) {
+        alert('Save failed: ' + err.message);
+      }
+    });
+  <\/script>
+</body>
+</html>`;
+}
+/**
+* Render a field group as HTML.
+*/
+function renderGroup(group, responses) {
+	const groupTitle = group.title ?? group.id;
+	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>
+    ${fieldsHtml}
+  </div>`;
+}
+/**
+* Render a field as HTML.
+* @public Exported for testing.
+*/
+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 = 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":
+			inputHtml = renderStringInput(field, value, disabledAttr);
+			break;
+		case "number":
+			inputHtml = renderNumberInput(field, value, disabledAttr);
+			break;
+		case "string_list":
+			inputHtml = renderStringListInput(field, value, disabledAttr);
+			break;
+		case "single_select":
+			inputHtml = renderSingleSelectInput(field, value, disabledAttr);
+			break;
+		case "multi_select":
+			inputHtml = renderMultiSelectInput(field, value, disabledAttr);
+			break;
+		case "checkboxes":
+			inputHtml = renderCheckboxesInput(field, value, disabledAttr);
+			break;
+		case "url":
+			inputHtml = renderUrlInput(field, value, disabledAttr);
+			break;
+		case "url_list":
+			inputHtml = renderUrlListInput(field, value, disabledAttr);
+			break;
+		default: inputHtml = "<div class=\"field-help\">(unknown field type)</div>";
+	}
+	const skipButton = !field.required && !skipped ? `<div class="field-actions">
+        <button type="button" class="btn-skip" data-skip-field="${field.id}">Skip</button>
+      </div>` : "";
+	return `
+    <div class="${fieldClass}">
+      <label class="field-label" for="field-${field.id}">
+        ${escapeHtml(field.label)} ${requiredMark} ${typeLabel} ${skippedBadge}
+      </label>
+      ${inputHtml}
+      ${skipButton}
+    </div>`;
+}
+/**
+* Render a string field as text input.
+*/
+function renderStringInput(field, value, disabledAttr) {
+	const currentValue = value?.kind === "string" && value.value !== null ? value.value : "";
+	const requiredAttr = field.required ? " required" : "";
+	const minLengthAttr = field.minLength !== void 0 ? ` minlength="${field.minLength}"` : "";
+	const maxLengthAttr = field.maxLength !== void 0 ? ` maxlength="${field.maxLength}"` : "";
+	return `<input type="text" id="field-${field.id}" name="${field.id}" value="${escapeHtml(currentValue)}"${requiredAttr}${minLengthAttr}${maxLengthAttr}${disabledAttr}>`;
+}
+/**
+* Render a number field as number input.
+*/
+function renderNumberInput(field, value, disabledAttr) {
+	const currentValue = value?.kind === "number" && value.value !== null ? String(value.value) : "";
+	const requiredAttr = field.required ? " required" : "";
+	const minAttr = field.min !== void 0 ? ` min="${field.min}"` : "";
+	const maxAttr = field.max !== void 0 ? ` max="${field.max}"` : "";
+	const stepAttr = field.integer ? " step=\"1\"" : "";
+	return `<input type="number" id="field-${field.id}" name="${field.id}" value="${escapeHtml(currentValue)}"${requiredAttr}${minAttr}${maxAttr}${stepAttr}${disabledAttr}>`;
+}
+/**
+* Render a string list field as textarea.
+*/
+function renderStringListInput(field, value, disabledAttr) {
+	const currentValue = (value?.kind === "string_list" ? value.items : []).join("\n");
+	const requiredAttr = field.required ? " required" : "";
+	return `<textarea id="field-${field.id}" name="${field.id}" placeholder="Enter one item per line"${requiredAttr}${disabledAttr}>${escapeHtml(currentValue)}</textarea>`;
+}
+/**
+* Render a URL field as url input.
+*/
+function renderUrlInput(field, value, disabledAttr) {
+	const currentValue = value?.kind === "url" && value.value !== null ? value.value : "";
+	const requiredAttr = field.required ? " required" : "";
+	return `<input type="url" id="field-${field.id}" name="${field.id}" value="${escapeHtml(currentValue)}" placeholder="https://example.com"${requiredAttr}${disabledAttr}>`;
+}
+/**
+* Render a URL list field as textarea.
+*/
+function renderUrlListInput(field, value, disabledAttr) {
+	const currentValue = (value?.kind === "url_list" ? value.items : []).join("\n");
+	const requiredAttr = field.required ? " required" : "";
+	return `<textarea id="field-${field.id}" name="${field.id}" placeholder="Enter one URL per line"${requiredAttr}${disabledAttr}>${escapeHtml(currentValue)}</textarea>`;
+}
+/**
+* Render a single-select field as select element.
+*/
+function renderSingleSelectInput(field, value, disabledAttr) {
+	const selected = value?.selected ?? null;
+	const requiredAttr = field.required ? " required" : "";
+	const options = field.options.map((opt) => {
+		const selectedAttr = selected === opt.id ? " selected" : "";
+		return `<option value="${escapeHtml(opt.id)}"${selectedAttr}>${escapeHtml(opt.label)}</option>`;
+	}).join("\n      ");
+	return `<select id="field-${field.id}" name="${field.id}"${requiredAttr}${disabledAttr}>
+      <option value="">-- Select --</option>
+      ${options}
+    </select>`;
+}
+/**
+* Render a multi-select field as checkboxes.
+*/
+function renderMultiSelectInput(field, value, disabledAttr) {
+	const selected = value?.selected ?? [];
+	return `<div class="checkbox-group">
+      ${field.options.map((opt) => {
+		const checkedAttr = selected.includes(opt.id) ? " checked" : "";
+		const checkboxId = `field-${field.id}-${opt.id}`;
+		return `<div class="checkbox-item">
+        <input type="checkbox" id="${checkboxId}" name="${field.id}" value="${escapeHtml(opt.id)}"${checkedAttr}${disabledAttr}>
+        <label for="${checkboxId}">${escapeHtml(opt.label)}</label>
+      </div>`;
+	}).join("\n      ")}
+    </div>`;
+}
+/**
+* Render checkboxes field based on mode.
+*/
+function renderCheckboxesInput(field, value, disabledAttr) {
+	const checkboxValues = value?.values ?? {};
+	const mode = field.checkboxMode ?? "multi";
+	if (mode === "simple") return `<div class="checkbox-group">
+      ${field.options.map((opt) => {
+		const checkedAttr = checkboxValues[opt.id] === "done" ? " checked" : "";
+		const checkboxId = `field-${field.id}-${opt.id}`;
+		return `<div class="checkbox-item">
+        <input type="checkbox" id="${checkboxId}" name="${field.id}" value="${escapeHtml(opt.id)}"${checkedAttr}${disabledAttr}>
+        <label for="${checkboxId}">${escapeHtml(opt.label)}</label>
+      </div>`;
+	}).join("\n      ")}
+    </div>`;
+	if (mode === "explicit") return `<div class="checkbox-group">
+      ${field.options.map((opt) => {
+		const state = checkboxValues[opt.id] ?? "unfilled";
+		const selectId = `field-${field.id}-${opt.id}`;
+		const selectName = `${field.id}.${opt.id}`;
+		return `<div class="option-row">
+        <span class="option-label">${escapeHtml(opt.label)}</span>
+        <select id="${selectId}" name="${selectName}"${disabledAttr}>
+          <option value="unfilled"${state === "unfilled" ? " selected" : ""}>-- Select --</option>
+          <option value="yes"${state === "yes" ? " selected" : ""}>Yes</option>
+          <option value="no"${state === "no" ? " selected" : ""}>No</option>
+        </select>
+      </div>`;
+	}).join("\n      ")}
+    </div>`;
+	return `<div class="checkbox-group">
+      ${field.options.map((opt) => {
+		const state = checkboxValues[opt.id] ?? "todo";
+		const selectId = `field-${field.id}-${opt.id}`;
+		const selectName = `${field.id}.${opt.id}`;
+		return `<div class="option-row">
+        <span class="option-label">${escapeHtml(opt.label)}</span>
+        <select id="${selectId}" name="${selectName}"${disabledAttr}>
+          <option value="todo"${state === "todo" ? " selected" : ""}>To Do</option>
+          <option value="active"${state === "active" ? " selected" : ""}>Active</option>
+          <option value="done"${state === "done" ? " selected" : ""}>Done</option>
+          <option value="incomplete"${state === "incomplete" ? " selected" : ""}>Incomplete</option>
+          <option value="na"${state === "na" ? " selected" : ""}>N/A</option>
+        </select>
+      </div>`;
+	}).join("\n      ")}
+    </div>`;
+}
+/**
+* Escape HTML special characters.
+* @public Exported for testing.
+*/
+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
+/**
+* Generate default output path by replacing .form.md with .form.html.
+*/
+function getDefaultOutputPath(inputPath) {
+	const dir = dirname(inputPath);
+	const base = basename(inputPath);
+	const newBase = base.replace(/\.form\.md$/i, ".form.html");
+	if (newBase === base) return `${inputPath}.html`;
+	return resolve(dir, newBase);
+}
+/**
+* Register the render command.
+*/
+function registerRenderCommand(program) {
+	program.command("render <file>").description("Render a form as static HTML output").option("-o, --output <path>", "Output file path (default: same stem + .html)").action(async (file, options, cmd) => {
+		const ctx = getCommandContext(cmd);
+		const filePath = resolve(file);
+		const outputPath = options.output ? resolve(options.output) : getDefaultOutputPath(filePath);
+		try {
+			logVerbose(ctx, `Reading file: ${filePath}`);
+			const content = await readFile$1(filePath);
+			logVerbose(ctx, "Parsing form...");
+			const form = parseForm(content);
+			logVerbose(ctx, "Rendering HTML...");
+			const html = renderFormHtml(form);
+			if (ctx.dryRun) {
+				logDryRun(`Would write HTML to: ${outputPath}`);
+				return;
+			}
+			await writeFile(outputPath, html);
+			logSuccess(ctx, pc.green(`✓ Rendered to ${outputPath}`));
+		} catch (error) {
+			logError(error instanceof Error ? error.message : String(error));
+			process.exit(1);
+		}
+	});
+}
+
+//#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
+/**
+* Format state badge for console output.
+*/
+function formatState(state, useColors) {
+	const [text, colorFn] = {
+		complete: ["✓ complete", pc.green],
+		incomplete: ["○ incomplete", pc.yellow],
+		empty: ["◌ empty", pc.dim],
+		invalid: ["✗ invalid", pc.red]
+	}[state] ?? [state, (s) => s];
+	return useColors ? colorFn(text) : text;
+}
+/**
+* Format priority badge for console output.
+*/
+function formatPriority(priority, useColors) {
+	const label = `P${priority}`;
+	if (!useColors) return label;
+	switch (priority) {
+		case 1: return pc.red(pc.bold(label));
+		case 2: return pc.yellow(label);
+		case 3: return pc.cyan(label);
+		case 4: return pc.blue(label);
+		case 5:
+		default: return pc.dim(label);
+	}
+}
+/**
+* Format severity badge for console output.
+*/
+function formatSeverity(severity, useColors) {
+	if (!useColors) return severity;
+	return severity === "required" ? pc.red(severity) : pc.yellow(severity);
+}
+/**
+* Format validate report for console output.
+*/
+function formatConsoleReport(report, useColors) {
+	const lines = [];
+	const bold = useColors ? pc.bold : (s) => s;
+	const dim = useColors ? pc.dim : (s) => s;
+	const cyan = useColors ? pc.cyan : (s) => s;
+	lines.push(bold(cyan("Form Validation Report")));
+	if (report.title) lines.push(`${bold("Title:")} ${report.title}`);
+	lines.push("");
+	lines.push(`${bold("Form State:")} ${formatState(report.form_state, useColors)}`);
+	lines.push("");
+	const structure = report.structure;
+	lines.push(bold("Structure:"));
+	lines.push(`  Groups: ${structure.groupCount}`);
+	lines.push(`  Fields: ${structure.fieldCount}`);
+	lines.push(`  Options: ${structure.optionCount}`);
+	lines.push("");
+	const progress = report.progress;
+	lines.push(bold("Progress:"));
+	lines.push(`  Total fields: ${progress.counts.totalFields}`);
+	lines.push(`  Required: ${progress.counts.requiredFields}`);
+	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}):`));
+		for (const issue of report.issues) {
+			const priority = formatPriority(issue.priority, useColors);
+			const severity = formatSeverity(issue.severity, useColors);
+			lines.push(`  ${priority} (${severity}) ${dim(`[${issue.scope}]`)} ${dim(issue.ref)}: ${issue.message}`);
+		}
+	} else lines.push(dim("No issues found."));
+	return lines.join("\n");
+}
+/**
+* Register the validate command.
+*/
+function registerValidateCommand(program) {
+	program.command("validate <file>").description("Validate a form and display summary and issues (no form content)").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, "Running validation...");
+			const result = inspect(form);
+			const output = formatOutput(ctx, {
+				title: form.schema.title,
+				structure: result.structureSummary,
+				progress: result.progressSummary,
+				form_state: result.formState,
+				issues: result.issues.map((issue) => ({
+					ref: issue.ref,
+					scope: issue.scope,
+					reason: issue.reason,
+					message: issue.message,
+					priority: issue.priority,
+					severity: issue.severity
+				}))
+			}, (data, useColors) => formatConsoleReport(data, useColors));
+			console.log(output);
+		} catch (error) {
+			logError(error instanceof Error ? error.message : String(error));
+			process.exit(1);
+		}
+	});
+}
+
+//#endregion
+//#region src/cli/cli.ts
+/**
+* CLI implementation for markform.
+*
+* Provides commands for inspecting, applying patches, exporting,
+* serving, and running harness loops on .form.md files.
+*/
+/**
+* Configure Commander with colored help text and global options display.
+*/
+function withColoredHelp(cmd) {
+	cmd.configureHelp({
+		styleTitle: (str) => pc.bold(pc.cyan(str)),
+		styleCommandText: (str) => pc.green(str),
+		styleOptionText: (str) => pc.yellow(str),
+		showGlobalOptions: true
+	});
+	return cmd;
+}
+/**
+* Create and configure the CLI program.
+*/
+function createProgram() {
+	const program = withColoredHelp(new Command());
+	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);
+	registerDumpCommand(program);
+	registerExamplesCommand(program);
+	registerExportCommand(program);
+	registerFillCommand(program);
+	registerInspectCommand(program);
+	registerModelsCommand(program);
+	registerRenderCommand(program);
+	registerReportCommand(program);
+	registerResearchCommand(program);
+	registerServeCommand(program);
+	registerValidateCommand(program);
+	return program;
+}
+/**
+* Run the CLI.
+*/
+async function runCli() {
+	await createProgram().parseAsync(process.argv);
+}
+
+//#endregion
+export { runCli as t };