markform 0.1.6 → 0.1.8

package/dist/{cli-CXjkdym_.mjs → cli-BZh25bvy.mjs}

@@ -1,19 +1,66 @@
-import { L as PatchSchema } from "./coreTypes-pyctKRgc.mjs";
-import { A as SUGGESTED_LLMS, D as deriveReportPath, E as deriveExportPath, F as parseModelIdForDisplay, M as formatSuggestedLlms, O as detectFileType, 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-DMQl-VVd.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, w as parseForm } from "./src-o_5TSoHQ.mjs";
-import { n as serializeSession } from "./session-uF0e6m6k.mjs";
-import { a as formatPath, c as logError, d as logTiming, f as logVerbose, g as writeFile, i as formatOutput, l as logInfo, m as readFile$1, n as createSpinner, o as getCommandContext, p as logWarn, r as ensureFormsDir, s as logDryRun, t as OUTPUT_FORMATS, u as logSuccess } from "./shared-DRlgu2ZJ.mjs";
+
+import { L as PatchSchema } from "./coreTypes-DJtu8OOp.mjs";
+import { A as deriveSchemaPath, D as USER_ROLE, E as REPORT_EXTENSION, F as formatSuggestedLlms, L as hasWebSearchSupport, M as parseRolesFlag, N as SUGGESTED_LLMS, O as deriveExportPath, P as WEB_SEARCH_CONFIG, R as parseModelIdForDisplay, S as DEFAULT_RESEARCH_MAX_PATCHES_PER_TURN, T as MAX_FORMS_IN_MENU, _ as DEFAULT_MAX_PATCHES_PER_TURN, d as serialize, f as serializeRawMarkdown, g as DEFAULT_MAX_ISSUES_PER_TURN, h as DEFAULT_FORMS_DIR, i as inspect, j as detectFileType, k as deriveReportPath, m as AGENT_ROLE, n as getAllFields, p as serializeReportMarkdown, t as applyPatches, v as DEFAULT_MAX_TURNS, x as DEFAULT_RESEARCH_MAX_ISSUES_PER_TURN, y as DEFAULT_PORT } from "./apply-BUU2QcJ2.mjs";
+import { E as parseForm, T as formToJsonSchema, a as resolveHarnessConfig, c as getProviderNames, f as createMockAgent, i as runResearch, l as resolveModel, m as createHarness, n as isResearchForm, o as fillForm, s as getProviderInfo, t as VERSION, u as createLiveAgent } from "./src-kUggXhN1.mjs";
+import { n as serializeSession } from "./session-CmHdAPyg.mjs";
+import { a as formatPath, c as logError, d as logTiming, f as logVerbose, g as writeFile, i as formatOutput, l as logInfo, m as readFile$1, n as createSpinner, o as getCommandContext, p as logWarn, r as ensureFormsDir, s as logDryRun, t as OUTPUT_FORMATS, u as logSuccess } from "./shared-DQ6y3Ggc.mjs";
 import YAML from "yaml";
 import { Command } from "commander";
 import pc from "picocolors";
+import { exec, execSync, spawn } from "node:child_process";
 import { basename, dirname, join, resolve } from "node:path";
-import { existsSync, readFileSync } from "node:fs";
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 import { readFile } from "node:fs/promises";
 import * as p from "@clack/prompts";
-import { exec, spawn } from "node:child_process";
 import { createServer } from "node:http";
 
+//#region src/cli/lib/cliVersion.ts
+/**
+* CLI version helper that computes git version in development mode.
+*
+* When running via tsx (development), __MARKFORM_VERSION__ is not injected,
+* so VERSION from index.ts returns 'development'. This module computes the
+* actual git version dynamically for consistent version display.
+*/
+/**
+* Get version from git tags with format: X.Y.Z-dev.N.hash
+* Only called when running in development mode (via tsx).
+*/
+function getGitVersion() {
+	try {
+		const git = (args) => execSync(`git ${args}`, {
+			encoding: "utf-8",
+			stdio: [
+				"ignore",
+				"pipe",
+				"ignore"
+			]
+		}).trim();
+		const tag = git("describe --tags --abbrev=0");
+		const tagVersion = tag.replace(/^v/, "");
+		const [major, minor, patch] = tagVersion.split(".").map(Number);
+		const commitsSinceTag = parseInt(git(`rev-list ${tag}..HEAD --count`), 10);
+		const hash = git("rev-parse --short=7 HEAD");
+		let dirty = false;
+		try {
+			git("diff --quiet");
+			git("diff --cached --quiet");
+		} catch {
+			dirty = true;
+		}
+		if (commitsSinceTag === 0 && !dirty) return tagVersion;
+		return `${major}.${minor}.${(patch ?? 0) + 1}-dev.${commitsSinceTag}.${dirty ? `${hash}-dirty` : hash}`;
+	} catch {
+		return "development";
+	}
+}
+/**
+* CLI version - uses build-time VERSION if available, otherwise computes from git.
+*/
+const CLI_VERSION = VERSION === "development" ? getGitVersion() : VERSION;
+
+//#endregion
 //#region src/cli/lib/paths.ts
 /**
 * Path utilities for CLI commands.
@@ -145,7 +192,7 @@ function formatState$2(state, useColors) {
 /**
 * Format apply report for console output.
 */
-function formatConsoleReport$2(report, useColors) {
+function formatConsoleReport$3(report, useColors) {
 	const lines = [];
 	const bold = useColors ? pc.bold : (s) => s;
 	const dim = useColors ? pc.dim : (s) => s;
@@ -227,7 +274,7 @@ function registerApplyCommand(program) {
 					structure: result.structureSummary,
 					progress: result.progressSummary,
 					issues: result.issues
-				}, (data, useColors) => formatConsoleReport$2(data, useColors));
+				}, (data, useColors) => formatConsoleReport$3(data, useColors));
 				console.error(output);
 				process.exit(1);
 			}
@@ -239,7 +286,7 @@ function registerApplyCommand(program) {
 					structure: result.structureSummary,
 					progress: result.progressSummary,
 					issues: result.issues
-				}, (data, useColors) => formatConsoleReport$2(data, useColors));
+				}, (data, useColors) => formatConsoleReport$3(data, useColors));
 				if (options.output) {
 					await writeFile(options.output, output);
 					logSuccess(ctx, `Report written to ${options.output}`);
@@ -258,6 +305,357 @@ function registerApplyCommand(program) {
 	});
 }
 
+//#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$3() {
+	return process.stdout.isTTY === true;
+}
+/**
+* Apply terminal formatting to markdown content.
+* Colorizes headers, code blocks, and other elements.
+*/
+function formatMarkdown$3(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) => {
+			const attrsPart = attrs.trim() ? ` ${pc.dim(attrs.trim())}` : "";
+			return `${pc.dim("{% ")}${pc.green(tag)}${attrsPart} ${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$3(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$3()) {
+		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:
+* - "Show report:" for the report output (.report.md) at the top
+* - "Show source:" for other files (.form.md, .raw.md, .yml)
+* - "Quit" at the bottom
+*
+* Loops until the user selects Quit.
+*
+* @param files Array of file options to display
+*/
+async function showFileViewerChooser(files) {
+	if (!isInteractive$3()) return;
+	console.log("");
+	const reportFile = files.find((f) => f.path.endsWith(".report.md"));
+	const sourceFiles = files.filter((f) => !f.path.endsWith(".report.md"));
+	while (true) {
+		const options = [];
+		if (reportFile) options.push({
+			value: reportFile.path,
+			label: `Show report: ${pc.green(basename(reportFile.path))}`,
+			hint: reportFile.hint ?? ""
+		});
+		for (const file of sourceFiles) options.push({
+			value: file.path,
+			label: `Show source: ${pc.green(basename(file.path))}`,
+			hint: file.hint ?? ""
+		});
+		options.push({
+			value: "quit",
+			label: "Quit",
+			hint: ""
+		});
+		const selection = await p.select({
+			message: "View files:",
+			options
+		});
+		if (p.isCancel(selection) || selection === "quit") break;
+		await viewFile(selection);
+		console.log("");
+	}
+}
+
+//#endregion
+//#region src/cli/commands/browse.ts
+/**
+* Browse command - Interactive file browser for the forms directory.
+*
+* Provides a menu-based interface for viewing files with syntax highlighting
+* and pagination. Shows .form.md, .report.md, .yml, and .schema.json files.
+*
+* Usage:
+*   markform browse              # Browse all files in forms/
+*   markform browse --filter=foo # Only show files matching pattern
+*/
+/** File extensions we support viewing */
+const VIEWABLE_EXTENSIONS = [
+	".form.md",
+	".report.md",
+	".yml",
+	".yaml",
+	".schema.json",
+	".raw.md"
+];
+/**
+* Check if a file has a viewable extension.
+*/
+function isViewableFile(filename) {
+	return VIEWABLE_EXTENSIONS.some((ext) => filename.endsWith(ext));
+}
+/**
+* Get the display extension for sorting/grouping.
+*/
+function getExtension(filename) {
+	for (const ext of VIEWABLE_EXTENSIONS) if (filename.endsWith(ext)) return ext;
+	return "";
+}
+/**
+* Scan forms directory for viewable files.
+*/
+function scanFormsDirectory$1(formsDir, filter) {
+	const entries = [];
+	try {
+		const files = readdirSync(formsDir);
+		for (const file of files) {
+			if (!isViewableFile(file)) continue;
+			if (filter && !file.toLowerCase().includes(filter.toLowerCase())) continue;
+			const fullPath = join(formsDir, file);
+			try {
+				const stat = statSync(fullPath);
+				if (stat.isFile()) entries.push({
+					path: fullPath,
+					filename: file,
+					mtime: stat.mtime,
+					extension: getExtension(file)
+				});
+			} catch {}
+		}
+	} catch {}
+	entries.sort((a, b) => {
+		const timeDiff = b.mtime.getTime() - a.mtime.getTime();
+		if (timeDiff !== 0) return timeDiff;
+		return a.filename.localeCompare(b.filename);
+	});
+	return entries;
+}
+/**
+* Get extension hint for display.
+*/
+function getExtensionHint(ext) {
+	switch (ext) {
+		case ".form.md": return "markform source";
+		case ".report.md": return "output report";
+		case ".yml":
+		case ".yaml": return "YAML values";
+		case ".schema.json": return "JSON Schema";
+		case ".raw.md": return "raw markdown";
+		default: return "";
+	}
+}
+/**
+* Format file entry for menu display.
+*/
+function formatFileLabel(entry) {
+	return `${entry.extension === ".report.md" ? pc.green("*") : " "} ${entry.filename}`;
+}
+/**
+* Browse specific output files after a form run.
+*
+* This is a convenience function for the examples workflow that shows
+* the standard output files (report, yml, form, schema) for a completed form.
+*
+* @param basePath - Base path of the output (e.g., "forms/movie-research-demo-filled1")
+*/
+async function browseOutputFiles(basePath) {
+	const outputExtensions = [
+		".report.md",
+		".yml",
+		".form.md",
+		".schema.json"
+	];
+	const files = [];
+	for (const ext of outputExtensions) {
+		const fullPath = basePath + ext;
+		try {
+			statSync(fullPath);
+			files.push({
+				path: fullPath,
+				label: basename(fullPath),
+				hint: getExtensionHint(ext)
+			});
+		} catch {}
+	}
+	if (files.length === 0) return;
+	await showFileViewerChooser(files);
+}
+/**
+* Register the browse command.
+*/
+function registerBrowseCommand(program) {
+	program.command("browse").description("Browse and view files in the forms directory").option("--filter <pattern>", "Only show files matching pattern").action(async (options, cmd) => {
+		const ctx = getCommandContext(cmd);
+		try {
+			const formsDir = getFormsDir(ctx.formsDir);
+			p.intro(pc.bgCyan(pc.black(" markform browse ")));
+			const entries = scanFormsDirectory$1(formsDir, options.filter);
+			if (entries.length === 0) {
+				if (options.filter) p.log.warn(`No files matching "${options.filter}" found in ${formatPath(formsDir)}`);
+				else p.log.warn(`No viewable files found in ${formatPath(formsDir)}`);
+				console.log("");
+				console.log(`Run ${pc.cyan("'markform examples'")} to get started.`);
+				p.outro("");
+				return;
+			}
+			console.log(pc.dim(`Found ${entries.length} file(s) in ${formatPath(formsDir)}`));
+			const menuOptions = entries.map((entry) => ({
+				value: entry.path,
+				label: formatFileLabel(entry),
+				hint: getExtensionHint(entry.extension)
+			}));
+			menuOptions.push({
+				value: "quit",
+				label: "Quit",
+				hint: ""
+			});
+			while (true) {
+				const selection = await p.select({
+					message: "Select a file to view:",
+					options: menuOptions
+				});
+				if (p.isCancel(selection)) break;
+				if (selection === "quit") break;
+				await viewFile(selection);
+				console.log("");
+			}
+			p.outro("");
+		} catch (error) {
+			logError(error instanceof Error ? error.message : String(error));
+			process.exit(1);
+		}
+	});
+}
+
 //#endregion
 //#region src/cli/commands/docs.ts
 /**
@@ -285,7 +683,7 @@ function loadDocs() {
 * Apply basic terminal formatting to markdown content.
 * Colorizes headers, code blocks, and other elements for better readability.
 */
-function formatMarkdown$3(content, useColors) {
+function formatMarkdown$2(content, useColors) {
 	if (!useColors) return content;
 	const lines = content.split("\n");
 	const formatted = [];
@@ -328,7 +726,7 @@ function formatMarkdown$3(content, useColors) {
 /**
 * Check if stdout is an interactive terminal.
 */
-function isInteractive$3() {
+function isInteractive$2() {
 	return process.stdout.isTTY === true;
 }
 /**
@@ -344,7 +742,7 @@ 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));
+			displayContent$2(formatMarkdown$2(loadDocs(), !options.raw && isInteractive$2() && !ctx.quiet));
 		} catch (error) {
 			logError(error instanceof Error ? error.message : String(error));
 			process.exit(1);
@@ -361,6 +759,7 @@ function registerDocsCommand(program) {
 * - Markform format (.form.md) - canonical form with directives
 * - Raw markdown (.raw.md) - plain readable markdown
 * - YAML values (.yml) - extracted field values
+* - JSON Schema (.schema.json) - form structure for validation/tooling
 */
 /**
 * Convert field responses to structured format for export (markform-218).
@@ -426,6 +825,23 @@ function toStructuredValues(form) {
 			case "url_list":
 				exportValue = value.items;
 				break;
+			case "date":
+				exportValue = value.value ?? null;
+				break;
+			case "year":
+				exportValue = value.value ?? null;
+				break;
+			case "table":
+				exportValue = value.rows.map((row) => {
+					const rowObj = {};
+					for (const [colId, cellResp] of Object.entries(row)) rowObj[colId] = cellResp.value ?? null;
+					return rowObj;
+				});
+				break;
+			default: {
+				const _exhaustive = value;
+				throw new Error(`Unhandled field value kind: ${_exhaustive.kind}`);
+			}
 		}
 		result[fieldId] = {
 			state: "answered",
@@ -449,7 +865,7 @@ function toNotesArray(form) {
 * Derive export paths from a base form path.
 * Uses centralized extension constants from settings.ts.
 *
-* Standard exports: report, values (yaml), form.
+* Standard exports: report, values (yaml), form, schema.
 * Raw markdown is available via CLI but not in standard exports.
 *
 * @param basePath - Path to the .form.md file
@@ -459,7 +875,8 @@ function deriveExportPaths(basePath) {
 	return {
 		reportPath: deriveReportPath(basePath),
 		yamlPath: deriveExportPath(basePath, "yaml"),
-		formPath: deriveExportPath(basePath, "form")
+		formPath: deriveExportPath(basePath, "form"),
+		schemaPath: deriveSchemaPath(basePath)
 	};
 }
 /**
@@ -469,6 +886,7 @@ function deriveExportPaths(basePath) {
 * - Report format (.report.md) - filtered markdown (excludes instructions, report=false)
 * - YAML values (.yml) - structured format with state and notes
 * - Markform format (.form.md) - canonical form with directives
+* - JSON Schema (.schema.json) - form structure for validation/tooling
 *
 * Note: Raw markdown (.raw.md) is available via CLI `markform export --raw`
 * but is not included in standard multi-format export.
@@ -491,6 +909,9 @@ async function exportMultiFormat(form, basePath) {
 	await writeFile(paths.yamlPath, yamlContent);
 	const formContent = serialize(form);
 	await writeFile(paths.formPath, formContent);
+	const schemaResult = formToJsonSchema(form);
+	const schemaContent = JSON.stringify(schemaResult.schema, null, 2) + "\n";
+	await writeFile(paths.schemaPath, schemaContent);
 	return paths;
 }
 
@@ -566,96 +987,6 @@ function registerDumpCommand(program) {
 	});
 }
 
-//#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 "set_table": return patch.rows.length > 0 ? truncate(`[${patch.rows.length} rows]`) : "(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 "set_table": return "table";
-		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
 /**
@@ -670,18 +1001,18 @@ function formatTurnIssues(issues, maxShow = 5) {
 * Title and description are loaded dynamically from frontmatter.
 */
 const EXAMPLE_DEFINITIONS = [
+	{
+		id: "movie-research-demo",
+		filename: "movie-research-demo.form.md",
+		path: "movie-research/movie-research-demo.form.md",
+		type: "research"
+	},
 	{
 		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",
@@ -694,19 +1025,29 @@ const EXAMPLE_DEFINITIONS = [
 		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: "earnings-analysis",
+		filename: "earnings-analysis.form.md",
+		path: "earnings-analysis/earnings-analysis.form.md",
+		type: "research"
 	}
 ];
+/** Default example ID for menus (movie-research-demo, index 0) */
+const DEFAULT_EXAMPLE_ID = "movie-research-demo";
+/**
+* Get the canonical order index for an example by filename.
+* Returns -1 if not found (unknown files sort to the end).
+*/
+function getExampleOrder(filename) {
+	const index = EXAMPLE_DEFINITIONS.findIndex((e) => e.filename === filename);
+	return index >= 0 ? index : EXAMPLE_DEFINITIONS.length;
+}
 /**
 * Get the path to the examples directory.
 * Works both during development and when installed as a package.
@@ -792,6 +1133,160 @@ function getAllExamplesWithMetadata() {
 	});
 }
 
+//#endregion
+//#region src/cli/lib/formatting.ts
+/**
+* Color and output formatting utilities for CLI.
+*/
+/**
+* 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` : ""}`;
+}
+/**
+* Format form info for menu label display.
+* Format: "filename - Title [runMode]"
+* Example: "movie-research-deep.form.md - Movie Research (Deep) [research]"
+*/
+function formatFormLabel(info) {
+	const titlePart = info.title ? ` - ${info.title}` : "";
+	const runModePart = info.runMode ? ` [${info.runMode}]` : "";
+	return `${info.filename}${titlePart}${runModePart}`;
+}
+/**
+* Format form info for menu hint display.
+* Returns description without parentheses (prompts library adds them).
+*/
+function formatFormHint(info) {
+	return info.description ?? "";
+}
+/**
+* Format form info for log line (e.g., after copying).
+* Format: "filename - Title" (dimmed title)
+* Example: "✓ movie-research-deep.form.md - Movie Research (Deep)"
+*/
+function formatFormLogLine(info, prefix) {
+	const titlePart = info.title ? ` - ${info.title}` : "";
+	return `${prefix} ${info.filename}${pc.dim(titlePart)}`;
+}
+
+//#endregion
+//#region src/cli/lib/runMode.ts
+/**
+* Get the set of unique roles present in a form's fields.
+*/
+function getFieldRoles(form) {
+	const allFields = getAllFields(form);
+	return new Set(allFields.map((field) => field.role));
+}
+/**
+* Validate that run_mode is consistent with form structure.
+*
+* Rules:
+* - interactive: Form MUST have at least one role="user" field
+* - fill: Form MUST have at least one role="agent" field
+* - research: Form MUST have at least one role="agent" field
+*/
+function validateRunMode(form, runMode) {
+	const roles = getFieldRoles(form);
+	switch (runMode) {
+		case "interactive":
+			if (!roles.has(USER_ROLE)) return {
+				valid: false,
+				error: `run_mode="interactive" but form has no user-role fields. Available roles: ${[...roles].join(", ") || "(none)"}`
+			};
+			break;
+		case "fill":
+		case "research":
+			if (!roles.has(AGENT_ROLE)) return {
+				valid: false,
+				error: `run_mode="${runMode}" but form has no agent-role fields. Available roles: ${[...roles].join(", ") || "(none)"}`
+			};
+			break;
+	}
+	return { valid: true };
+}
+/**
+* Determine the run mode for a form.
+*
+* 1. If explicit run_mode in frontmatter, validate and use it
+* 2. Otherwise, infer from field roles:
+*    - All user fields → interactive
+*    - All agent fields → fill (or research if isResearchForm)
+*    - Mixed roles → error (require explicit run_mode)
+*/
+function determineRunMode(form) {
+	const explicitMode = form.metadata?.runMode;
+	if (explicitMode) {
+		const validation = validateRunMode(form, explicitMode);
+		if (!validation.valid) return {
+			success: false,
+			error: validation.error
+		};
+		return {
+			success: true,
+			runMode: explicitMode,
+			source: "explicit"
+		};
+	}
+	const roles = getFieldRoles(form);
+	if (roles.size === 0) return {
+		success: false,
+		error: "Form has no fields"
+	};
+	if (roles.size === 1 && roles.has(USER_ROLE)) return {
+		success: true,
+		runMode: "interactive",
+		source: "inferred"
+	};
+	if (roles.size === 1 && roles.has(AGENT_ROLE)) {
+		if (isResearchForm(form)) return {
+			success: true,
+			runMode: "research",
+			source: "inferred"
+		};
+		return {
+			success: true,
+			runMode: "fill",
+			source: "inferred"
+		};
+	}
+	return {
+		success: false,
+		error: `Cannot determine run mode. Form has roles: ${[...roles].join(", ")}. Add 'run_mode' to frontmatter: interactive, fill, or research.`
+	};
+}
+/**
+* Get a human-readable description of the run mode source.
+*/
+function formatRunModeSource(source) {
+	return source === "explicit" ? "from frontmatter" : "inferred from field roles";
+}
+
 //#endregion
 //#region src/cli/lib/versioning.ts
 /**
@@ -1432,277 +1927,216 @@ function showInteractiveOutro(patchCount, cancelled) {
 }
 
 //#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
-*/
+//#region src/cli/lib/patchFormat.ts
+/** Maximum characters for a patch value display before truncation */
+const PATCH_VALUE_MAX_LENGTH = 1e3;
 /**
-* Check if stdout is an interactive terminal.
+* Truncate a string to max length with ellipsis if needed.
 */
-function isInteractive$2() {
-	return process.stdout.isTTY === true;
+function truncate(value, maxLength = PATCH_VALUE_MAX_LENGTH) {
+	if (value.length <= maxLength) return value;
+	return value.slice(0, maxLength) + "…";
 }
 /**
-* Apply terminal formatting to markdown content.
-* Colorizes headers, code blocks, and other elements.
+* Format a patch value for display with truncation.
 */
-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);
+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 "set_table": return patch.rows.length > 0 ? truncate(`[${patch.rows.length} rows]`) : "(empty)";
+		case "add_note": return truncate(`note: ${patch.text}`);
+		case "remove_note": return `(remove note ${patch.noteId})`;
 	}
-	return formatted.join("\n");
 }
 /**
-* Apply terminal formatting to YAML content.
+* Get a short display name for the patch operation type.
 */
-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);
+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 "set_table": return "table";
+		case "add_note": return "note";
+		case "remove_note": return "remove_note";
 	}
-	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;
 }
+
+//#endregion
+//#region src/cli/lib/fillLogging.ts
 /**
-* Display content using system pager (less) if available.
-* Falls back to console.log if not interactive or pager unavailable.
+* Fill Logging Callbacks - Create FillCallbacks for unified CLI logging.
 *
-* @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.
+* Provides consistent turn-by-turn logging across all CLI commands that
+* run form-filling (fill, run, examples). API consumers can also use
+* these callbacks or implement their own.
+*
+* Default output (always shown unless --quiet):
+* - Turn numbers with issues list (field IDs + issue types)
+* - Patches per turn (field ID + value)
+* - Completion status
+*
+* Verbose output (--verbose flag):
+* - Token counts per turn
+* - Tool call start/end with timing
+* - Detailed stats and LLM metadata
 */
-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.
+* Create FillCallbacks that produce standard CLI logging output.
 *
-* Presents a list of files to view:
-* - "Show report:" for the report output (.report.md) at the top
-* - "Show source:" for other files (.form.md, .raw.md, .yml)
-* - "Quit" at the bottom
+* Default output (always shown unless --quiet):
+* - Turn numbers with issues list (field IDs + issue types)
+* - Patches per turn (field ID + value)
+* - Completion status
 *
-* Loops until the user selects Quit.
+* Verbose output (--verbose flag):
+* - Token counts per turn
+* - Tool call start/end with timing
+* - Detailed stats and LLM metadata
 *
-* @param files Array of file options to display
+* This is used by fill, run, and examples commands for consistent output.
+*
+* @param ctx - Command context for verbose/quiet flags
+* @param options - Optional spinner for tool progress
+* @returns FillCallbacks with all logging implemented
+*
+* @example
+* ```typescript
+* const callbacks = createFillLoggingCallbacks(ctx, { spinner });
+* const result = await fillForm({
+*   form: formMarkdown,
+*   model: 'anthropic/claude-sonnet-4-5',
+*   enableWebSearch: true,
+*   callbacks,
+* });
+* ```
 */
-async function showFileViewerChooser(files) {
-	if (!isInteractive$2()) return;
-	console.log("");
-	const reportFile = files.find((f) => f.path.endsWith(".report.md"));
-	const sourceFiles = files.filter((f) => !f.path.endsWith(".report.md"));
-	while (true) {
-		const options = [];
-		if (reportFile) options.push({
-			value: reportFile.path,
-			label: `Show report: ${pc.green(basename(reportFile.path))}`,
-			hint: reportFile.hint ?? ""
-		});
-		for (const file of sourceFiles) options.push({
-			value: file.path,
-			label: `Show source: ${pc.green(basename(file.path))}`,
-			hint: file.hint ?? ""
-		});
-		options.push({
-			value: "quit",
-			label: "Quit",
-			hint: ""
-		});
-		const selection = await p.select({
-			message: "View files:",
-			options
-		});
-		if (p.isCancel(selection) || selection === "quit") break;
-		await viewFile(selection);
-		console.log("");
-	}
+function createFillLoggingCallbacks(ctx, options = {}) {
+	return {
+		onIssuesIdentified: ({ turnNumber, issues }) => {
+			logInfo(ctx, `${pc.bold(`Turn ${turnNumber}:`)} ${formatTurnIssues(issues)}`);
+		},
+		onPatchesGenerated: ({ patches, stats }) => {
+			logInfo(ctx, `  -> ${pc.yellow(String(patches.length))} patch(es):`);
+			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 && ctx.verbose) {
+				logVerbose(ctx, `  Tokens: in=${stats.inputTokens ?? 0} out=${stats.outputTokens ?? 0}`);
+				if (stats.toolCalls && stats.toolCalls.length > 0) logVerbose(ctx, `  Tools: ${stats.toolCalls.map((t) => `${t.name}(${t.count})`).join(", ")}`);
+			}
+		},
+		onTurnComplete: ({ isComplete }) => {
+			if (isComplete) logInfo(ctx, pc.green(`  ✓ Complete`));
+		},
+		onToolStart: ({ name }) => {
+			if (name.includes("search")) options.spinner?.message(`Web search...`);
+			logVerbose(ctx, `  Tool started: ${name}`);
+		},
+		onToolEnd: ({ name, durationMs, error }) => {
+			if (error) logVerbose(ctx, `  Tool ${name} failed: ${error} (${durationMs}ms)`);
+			else logVerbose(ctx, `  Tool ${name} completed (${durationMs}ms)`);
+		},
+		onLlmCallStart: ({ model }) => {
+			logVerbose(ctx, `  LLM call: ${model}`);
+		},
+		onLlmCallEnd: ({ model, inputTokens, outputTokens }) => {
+			logVerbose(ctx, `  LLM response: ${model} (in=${inputTokens} out=${outputTokens})`);
+		}
+	};
 }
 
 //#endregion
-//#region src/cli/commands/examples.ts
+//#region src/cli/commands/run.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.
+* Run command - Interactive launcher for running forms.
+*
+* Provides a menu-based interface for selecting and running forms
+* from the forms directory. Automatically detects run mode based
+* on frontmatter or field roles.
+*
+* Usage:
+*   markform run                   # Browse forms, select, run
+*   markform run movie.form.md     # Run specific form directly
+*   markform run --limit=50        # Override menu limit
 */
-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.
+* Scan forms directory for .form.md files.
 */
-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"
+function scanFormsDirectory(formsDir) {
+	const entries = [];
+	try {
+		const files = readdirSync(formsDir);
+		for (const file of files) {
+			if (!file.endsWith(".form.md")) continue;
+			const fullPath = join(formsDir, file);
+			try {
+				const stat = statSync(fullPath);
+				if (stat.isFile()) entries.push({
+					path: fullPath,
+					filename: file,
+					mtime: stat.mtime
+				});
+			} catch {}
+		}
+	} catch {}
+	entries.sort((a, b) => {
+		const orderDiff = getExampleOrder(a.filename) - getExampleOrder(b.filename);
+		if (orderDiff !== 0) return orderDiff;
+		return a.filename.localeCompare(b.filename);
 	});
-	return options;
+	return entries;
 }
 /**
-* 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;
+* Load form metadata for menu display.
+*/
+async function enrichFormEntry(entry) {
+	try {
+		const form = parseForm(await readFile$1(entry.path));
+		const runModeResult = determineRunMode(form);
+		return {
+			...entry,
+			title: form.schema.title,
+			description: form.schema.description,
+			runMode: runModeResult.success ? runModeResult.runMode : void 0
+		};
+	} catch {
+		return entry;
 	}
-	return selection;
 }
 /**
-* Build model options filtered to providers with web search support.
+* Build model options for the select prompt.
 */
-function buildWebSearchModelOptions() {
+function buildModelOptions(webSearchOnly) {
 	const options = [];
 	for (const [provider, models] of Object.entries(SUGGESTED_LLMS)) {
-		if (!hasWebSearchSupport(provider)) continue;
+		if (webSearchOnly && !hasWebSearchSupport(provider)) continue;
 		const info = getProviderInfo(provider);
 		const keyStatus = !!process.env[info.envVar] ? pc.green("✓") : "○";
 		for (const model of models) options.push({
@@ -1719,22 +2153,23 @@ function buildWebSearchModelOptions() {
 	return options;
 }
 /**
-* Prompt user to select a model with web search capability for research workflow.
+* Prompt user to select a model.
 */
-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.");
+async function promptForModel(webSearchRequired) {
+	const modelOptions = buildModelOptions(webSearchRequired);
+	if (webSearchRequired && modelOptions.length === 1) p.log.warn("No web-search-capable providers found. OpenAI, Google, or xAI API key required.");
+	const message = webSearchRequired ? "Select LLM model (web search required):" : "Select LLM model:";
 	const selection = await p.select({
-		message: "Select LLM model (web search required):",
+		message,
 		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",
+			placeholder: "anthropic/claude-sonnet-4-20250514",
 			validate: (value) => {
-				if (!value.includes("/")) return "Format: provider/model-id (e.g., openai/gpt-5-mini)";
+				if (!value.includes("/")) return "Format: provider/model-id (e.g., anthropic/claude-sonnet-4-20250514)";
 			}
 		});
 		if (p.isCancel(customModel)) return null;
@@ -1743,305 +2178,396 @@ async function promptForWebSearchModel() {
 	return selection;
 }
 /**
-* Run the agent fill workflow.
-* Accepts optional harness config overrides - research uses different defaults.
+* Collect user input interactively (without exporting).
+* Returns true if successful, false if cancelled.
 */
-async function runAgentFill(form, modelId, _outputPath, configOverrides) {
-	const { provider: providerName, model: modelName } = parseModelIdForDisplay(modelId);
-	const resolveSpinner = createSpinner({
-		type: "compute",
-		operation: `Resolving model: ${modelId}`
-	});
-	let model, provider;
-	try {
-		const result = await resolveModel(modelId);
-		model = result.model;
-		provider = result.provider;
-		resolveSpinner.stop(`✓ Model resolved: ${modelId}`);
-	} catch (error) {
-		resolveSpinner.error("Model resolution failed");
-		throw error;
-	}
-	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,
-		enableWebSearch: true
-	});
-	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 llmSpinner = createSpinner({
-			type: "api",
-			provider: providerName,
-			model: modelName,
-			turnNumber: stepResult.turnNumber
-		});
-		let response;
-		try {
-			response = await agent.generatePatches(stepResult.issues, harness.getForm(), harnessConfig.maxPatchesPerTurn);
-			llmSpinner.stop();
-		} catch (error) {
-			llmSpinner.error("LLM call failed");
-			throw error;
-		}
-		const { patches, stats } = response;
-		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();
+async function collectUserInput(form) {
+	const targetRoles = [USER_ROLE];
+	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) return true;
+	showInteractiveIntro(form.schema.title ?? form.schema.id, targetRoles.join(", "), uniqueFieldIds.size);
+	const { patches, cancelled } = await runInteractiveFill(form, inspectResult.issues);
+	if (cancelled) {
+		showInteractiveOutro(0, true);
+		return false;
 	}
-	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()
-	};
+	if (patches.length > 0) applyPatches(form, patches);
+	showInteractiveOutro(patches.length, false);
+	return true;
 }
 /**
-* 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
+* Run interactive fill workflow.
+* @returns ExportResult with paths to output files, or undefined if cancelled/no fields
 */
-async function runInteractiveFlow(preselectedId, formsDirOverride) {
+async function runInteractiveWorkflow(form, filePath, formsDir) {
+	const startTime = Date.now();
+	const targetRoles = [USER_ROLE];
+	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.");
+		return;
+	}
+	showInteractiveIntro(form.schema.title ?? form.schema.id, targetRoles.join(", "), uniqueFieldIds.size);
+	const { patches, cancelled } = await runInteractiveFill(form, inspectResult.issues);
+	if (cancelled) {
+		showInteractiveOutro(0, true);
+		return;
+	}
+	if (patches.length > 0) applyPatches(form, patches);
+	await ensureFormsDir(formsDir);
+	const exportResult = await exportMultiFormat(form, generateVersionedPathInFormsDir(filePath, formsDir));
+	showInteractiveOutro(patches.length, false);
+	console.log("");
+	p.log.success("Outputs:");
+	console.log(`  ${formatPath(exportResult.reportPath)}  ${pc.dim("(output report)")}`);
+	console.log(`  ${formatPath(exportResult.yamlPath)}  ${pc.dim("(output values)")}`);
+	console.log(`  ${formatPath(exportResult.formPath)}  ${pc.dim("(filled markform source)")}`);
+	console.log(`  ${formatPath(exportResult.schemaPath)}  ${pc.dim("(JSON Schema)")}`);
+	logTiming({
+		verbose: false,
+		format: "console",
+		dryRun: false,
+		quiet: false,
+		overwrite: false
+	}, "Fill time", Date.now() - startTime);
+	return exportResult;
+}
+/**
+* Run agent fill workflow using fillForm with logging callbacks.
+* @returns ExportResult with paths to output files
+*/
+async function runAgentFillWorkflow(form, modelId, formsDir, filePath, isResearch, overwrite, ctx) {
 	const startTime = Date.now();
-	p.intro(pc.bgCyan(pc.black(" markform examples ")));
-	const formsDir = getFormsDir(formsDirOverride);
+	const maxTurns = DEFAULT_MAX_TURNS;
+	const maxPatchesPerTurn = isResearch ? DEFAULT_RESEARCH_MAX_PATCHES_PER_TURN : DEFAULT_MAX_PATCHES_PER_TURN;
+	const maxIssuesPerTurn = isResearch ? DEFAULT_RESEARCH_MAX_ISSUES_PER_TURN : DEFAULT_MAX_ISSUES_PER_TURN;
+	logVerbose(ctx, `Config: max_turns=${maxTurns}, max_issues_per_turn=${maxIssuesPerTurn}, max_patches_per_turn=${maxPatchesPerTurn}`);
+	const callbacks = createFillLoggingCallbacks(ctx);
+	const workflowLabel = isResearch ? "Research" : "Agent fill";
+	p.log.step(pc.bold(`${workflowLabel} in progress...`));
+	const result = await fillForm({
+		form,
+		model: modelId,
+		maxTurns,
+		maxPatchesPerTurn,
+		maxIssuesPerTurn,
+		targetRoles: [AGENT_ROLE],
+		fillMode: overwrite ? "overwrite" : "continue",
+		enableWebSearch: isResearch,
+		callbacks
+	});
+	if (result.status.ok) p.log.success(pc.green(`Form completed in ${result.turns} turn(s)`));
+	else if (result.status.reason === "max_turns") p.log.warn(pc.yellow(`Max turns reached (${maxTurns})`));
+	else throw new Error(result.status.message ?? `Fill failed: ${result.status.reason}`);
 	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);
+	const outputPath = generateVersionedPathInFormsDir(filePath, formsDir);
+	const exportResult = await exportMultiFormat(result.form, outputPath);
+	console.log("");
+	p.log.success(`${workflowLabel} complete. Outputs:`);
+	console.log(`  ${formatPath(exportResult.reportPath)}  ${pc.dim("(output report)")}`);
+	console.log(`  ${formatPath(exportResult.yamlPath)}  ${pc.dim("(output values)")}`);
+	console.log(`  ${formatPath(exportResult.formPath)}  ${pc.dim("(filled markform source)")}`);
+	console.log(`  ${formatPath(exportResult.schemaPath)}  ${pc.dim("(JSON Schema)")}`);
+	logTiming(ctx, isResearch ? "Research time" : "Fill time", Date.now() - startTime);
+	return exportResult;
+}
+/**
+* Run a form directly (callable from other commands).
+* This executes the same workflow as `markform run <file>`.
+*
+* @param selectedPath - Path to the form file
+* @param formsDir - Directory for output files
+* @param overwrite - Whether to overwrite existing field values
+* @param ctx - Optional command context for logging (defaults to non-verbose/quiet)
+* @returns ExportResult with paths to output files, or undefined if cancelled/no output
+*/
+async function runForm(selectedPath, formsDir, overwrite, ctx) {
+	const effectiveCtx = ctx ?? {
+		verbose: false,
+		quiet: false,
+		dryRun: false,
+		format: "console",
+		overwrite
+	};
+	const form = parseForm(await readFile$1(selectedPath));
+	const runModeResult = determineRunMode(form);
+	if (!runModeResult.success) throw new Error(runModeResult.error);
+	const { runMode } = runModeResult;
+	switch (runMode) {
+		case "interactive": return runInteractiveWorkflow(form, selectedPath, formsDir);
+		case "fill":
+		case "research": {
+			const isResearch = runMode === "research";
+			if (!await collectUserInput(form)) {
+				p.cancel("Cancelled.");
+				return;
+			}
+			const modelId = await promptForModel(isResearch);
+			if (!modelId) {
+				p.cancel("Cancelled.");
+				return;
+			}
+			return runAgentFillWorkflow(form, modelId, formsDir, selectedPath, isResearch, overwrite, effectiveCtx);
 		}
-		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";
+}
+/**
+* Register the run command.
+*/
+function registerRunCommand(program) {
+	program.command("run [file]").description("Browse and run forms from the forms directory").option("--limit <n>", `Maximum forms to show in menu (default: ${MAX_FORMS_IN_MENU})`, String(MAX_FORMS_IN_MENU)).action(async (file, options, cmd) => {
+		const ctx = getCommandContext(cmd);
+		try {
+			const formsDir = getFormsDir(ctx.formsDir);
+			const limit = options.limit ? parseInt(options.limit, 10) : MAX_FORMS_IN_MENU;
+			let selectedPath;
+			if (file) {
+				selectedPath = file.startsWith("/") ? file : join(formsDir, file);
+				if (!selectedPath.endsWith(".form.md") && !selectedPath.endsWith(".md")) selectedPath = `${selectedPath}.form.md`;
+			} else {
+				p.intro(pc.bgCyan(pc.black(" markform run ")));
+				const entries = scanFormsDirectory(formsDir);
+				if (entries.length === 0) {
+					p.log.warn(`No forms found in ${formatPath(formsDir)}`);
+					console.log("");
+					console.log(`Run ${pc.cyan("'markform examples'")} to get started.`);
+					p.outro("");
+					return;
+				}
+				const entriesToShow = entries.slice(0, limit);
+				const enrichedEntries = await Promise.all(entriesToShow.map(enrichFormEntry));
+				const menuOptions = enrichedEntries.map((entry) => ({
+					value: entry.path,
+					label: formatFormLabel(entry),
+					hint: formatFormHint(entry)
+				}));
+				const defaultExample = getExampleById(DEFAULT_EXAMPLE_ID);
+				const initialValue = enrichedEntries.find((e) => e.filename === defaultExample?.filename)?.path;
+				if (entries.length > limit) console.log(pc.dim(`Showing ${limit} of ${entries.length} forms`));
+				const selection = await p.select({
+					message: "Select a form to run:",
+					options: menuOptions,
+					initialValue
+				});
+				if (p.isCancel(selection)) {
+					p.cancel("Cancelled.");
+					process.exit(0);
+				}
+				selectedPath = selection;
+			}
+			logVerbose(ctx, `Reading form: ${selectedPath}`);
+			const form = parseForm(await readFile$1(selectedPath));
+			const runModeResult = determineRunMode(form);
+			if (!runModeResult.success) {
+				logError(runModeResult.error);
+				process.exit(1);
+			}
+			const { runMode, source } = runModeResult;
+			logInfo(ctx, `Run mode: ${runMode} (${formatRunModeSource(source)})`);
+			switch (runMode) {
+				case "interactive":
+					await runInteractiveWorkflow(form, selectedPath, formsDir);
+					break;
+				case "fill":
+				case "research": {
+					const isResearch = runMode === "research";
+					if (!await collectUserInput(form)) {
+						p.cancel("Cancelled.");
+						process.exit(0);
+					}
+					const modelId = await promptForModel(isResearch);
+					if (!modelId) {
+						p.cancel("Cancelled.");
+						process.exit(0);
+					}
+					await runAgentFillWorkflow(form, modelId, formsDir, selectedPath, isResearch, ctx.overwrite, ctx);
+					break;
+				}
+			}
+			if (!file) p.outro("Happy form filling!");
+		} catch (error) {
+			logError(error instanceof Error ? error.message : String(error));
+			process.exit(1);
 		}
 	});
-	if (p.isCancel(filenameResult)) {
-		p.cancel("Cancelled.");
-		process.exit(0);
+}
+
+//#endregion
+//#region src/cli/commands/examples.ts
+/**
+* Examples command - Copy bundled example forms to the forms directory.
+*
+* This command provides a simple way to get started with markform by
+* copying bundled example forms to your local forms directory.
+*
+* Usage:
+*   markform examples              # Copy all bundled examples to ./forms/
+*   markform examples --list       # List bundled examples (no copy)
+*   markform examples --name=foo   # Copy specific example only
+*/
+/**
+* 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("");
 	}
-	const filename = filenameResult;
-	const outputPath = join(formsDir, filename);
+}
+/**
+* Copy an example form to the forms directory.
+*
+* @returns true if copied, false if skipped
+*/
+async function copyExample(exampleId, formsDir, overwrite, _quiet) {
+	const example = getExampleById(exampleId);
+	if (!example) throw new Error(`Unknown example: ${exampleId}`);
+	const outputPath = join(formsDir, example.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);
-		}
+		if (!overwrite) return {
+			copied: false,
+			skipped: true,
+			path: outputPath
+		};
 	}
-	let content;
+	await writeFile(outputPath, loadExampleContent(exampleId));
+	return {
+		copied: true,
+		skipped: false,
+		path: outputPath
+	};
+}
+/**
+* Scan forms directory and enrich entries with metadata.
+*/
+async function getFormEntries(formsDir) {
+	const entries = [];
 	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);
+		const files = readdirSync(formsDir);
+		for (const file of files) {
+			if (!file.endsWith(".form.md")) continue;
+			const fullPath = join(formsDir, file);
+			try {
+				if (statSync(fullPath).isFile()) {
+					const form = parseForm(await readFile$1(fullPath));
+					const runModeResult = determineRunMode(form);
+					entries.push({
+						path: fullPath,
+						filename: file,
+						title: form.schema.title,
+						description: form.schema.description,
+						runMode: runModeResult.success ? runModeResult.runMode : void 0
+					});
+				}
+			} catch {}
 		}
-		if (patches.length > 0) applyPatches(form, patches);
-		userFillOutputs = await exportMultiFormat(form, outputPath);
-		showInteractiveOutro(patches.length, false);
+	} catch {}
+	return entries;
+}
+/**
+* Copy all examples to the forms directory.
+* Returns { copied, skipped } counts for the caller to handle prompts.
+*/
+async function copyAllExamples(formsDir, overwrite, quiet) {
+	const examples = getAllExamplesWithMetadata();
+	const total = examples.length;
+	if (!quiet) {
+		console.log(`Copying ${total} example forms to ${formatPath(formsDir)}...`);
 		console.log("");
-		p.log.success("Outputs:");
-		console.log(`  ${formatPath(userFillOutputs.reportPath)}  ${pc.dim("(output report)")}`);
-		console.log(`  ${formatPath(userFillOutputs.yamlPath)}  ${pc.dim("(output values)")}`);
-		console.log(`  ${formatPath(userFillOutputs.formPath)}  ${pc.dim("(filled markform source)")}`);
-		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) {
+	let copied = 0;
+	let skipped = 0;
+	for (const example of examples) {
+		const result = await copyExample(example.id, formsDir, overwrite, quiet);
+		if (result.copied) {
+			copied++;
+			if (!quiet) console.log(formatFormLogLine(example, `  ${pc.green("✓")}`));
+		} else if (result.skipped) {
+			skipped++;
+			if (!quiet) console.log(`${formatFormLogLine(example, `  ${pc.yellow("○")}`)} ${pc.dim("(exists, skipped)")}`);
+		}
+	}
+	if (!quiet) {
 		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) {
+		if (skipped > 0) console.log(pc.yellow(`Skipped ${skipped} existing file(s). Use --overwrite to replace them.`));
+		console.log(pc.green(`Done! Copied ${copied} example form(s) to ${formatPath(formsDir)}`));
+	}
+	return {
+		copied,
+		skipped
+	};
+}
+/**
+* Show form selection menu and return the selected path.
+*/
+async function showFormMenu(formsDir) {
+	const entries = await getFormEntries(formsDir);
+	if (entries.length === 0) return null;
+	const sortedEntries = [...entries].sort((a, b) => {
+		return getExampleOrder(a.filename) - getExampleOrder(b.filename);
+	});
+	const defaultExample = getExampleById(DEFAULT_EXAMPLE_ID);
+	const defaultIndex = sortedEntries.findIndex((e) => e.filename === defaultExample?.filename);
+	const menuOptions = sortedEntries.map((entry) => ({
+		value: entry.path,
+		label: formatFormLabel(entry),
+		hint: formatFormHint(entry)
+	}));
+	const initialValue = (defaultIndex >= 0 ? sortedEntries[defaultIndex] : void 0)?.path;
+	const selection = await p.select({
+		message: "Select a form to run:",
+		options: menuOptions,
+		initialValue
+	});
+	if (p.isCancel(selection)) return null;
+	return selection;
+}
+/**
+* Copy a specific example to the forms directory.
+*/
+async function copySingleExample(exampleId, formsDir, overwrite, quiet) {
+	const example = getExampleById(exampleId);
+	if (!example) throw new Error(`Unknown example: ${exampleId}`);
+	if (!quiet) console.log(`Copying ${example.filename} to ${formatPath(formsDir)}...`);
+	const result = await copyExample(exampleId, formsDir, overwrite, quiet);
+	if (result.copied) {
+		if (!quiet) {
+			console.log(formatFormLogLine(example, `  ${pc.green("✓")}`));
 			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.reportPath,
-					label: "Report",
-					hint: "output report"
-				},
-				{
-					path: userFillOutputs.yamlPath,
-					label: "Values",
-					hint: "output values"
-				},
-				{
-					path: userFillOutputs.formPath,
-					label: "Form",
-					hint: "filled markform source"
-				}
-			]);
-			p.outro("Happy form filling!");
-			return;
-		}
-		const modelId = isResearchExample ? await promptForWebSearchModel() : await promptForModel();
-		if (!modelId) {
-			p.cancel("Cancelled.");
-			process.exit(0);
+			console.log(pc.green("Done!"));
+			console.log(`Run ${pc.cyan(`'markform run ${example.filename}'`)} to try it.`);
 		}
-		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 { reportPath, yamlPath, formPath } = await exportMultiFormat(form, agentOutputPath);
-			console.log("");
-			const successMessage = isResearchExample ? "Research complete. Outputs:" : "Agent fill complete. Outputs:";
-			p.log.success(successMessage);
-			console.log(`  ${formatPath(reportPath)}  ${pc.dim("(output report)")}`);
-			console.log(`  ${formatPath(yamlPath)}  ${pc.dim("(output values)")}`);
-			console.log(`  ${formatPath(formPath)}  ${pc.dim("(filled markform source)")}`);
-			if (!success) p.log.warn("Agent did not complete all fields. You may need to run it again.");
-			await showFileViewerChooser([
-				{
-					path: reportPath,
-					label: "Report",
-					hint: "output report"
-				},
-				{
-					path: yamlPath,
-					label: "Values",
-					hint: "output values"
-				},
-				{
-					path: formPath,
-					label: "Form",
-					hint: "filled markform source"
-				}
-			]);
-		} catch (error) {
-			const message = error instanceof Error ? error.message : String(error);
-			const failMessage = isResearchExample ? "Research failed" : "Agent fill failed";
-			p.log.error(`${failMessage}: ${message}`);
+	} else if (result.skipped) {
+		if (!quiet) {
+			console.log(`${formatFormLogLine(example, `  ${pc.yellow("○")}`)} ${pc.dim("(exists, skipped)")}`);
 			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);
+			console.log(pc.yellow(`File already exists. Use --overwrite to replace it.`));
 		}
 	}
-	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) => {
+	program.command("examples").description("Copy bundled example forms to the forms directory").option("--list", "List available examples without copying").option("--name <example>", "Copy specific example by ID").action(async (options, cmd) => {
 		const ctx = getCommandContext(cmd);
 		try {
 			if (options.list) {
 				printExamplesList();
 				return;
 			}
+			const formsDir = getFormsDir(ctx.formsDir);
+			await ensureFormsDir(formsDir);
 			if (options.name) {
 				if (!getExampleById(options.name)) {
 					logError(`Unknown example: ${options.name}`);
@@ -2049,8 +2575,35 @@ function registerExamplesCommand(program) {
 					for (const ex of EXAMPLE_DEFINITIONS) console.log(`  ${ex.id}`);
 					process.exit(1);
 				}
+				await copySingleExample(options.name, formsDir, ctx.overwrite, ctx.quiet);
+			} else {
+				const { copied, skipped } = await copyAllExamples(formsDir, ctx.overwrite, ctx.quiet);
+				if (!ctx.quiet && (copied > 0 || skipped > 0)) {
+					console.log("");
+					const wantToRun = await p.confirm({
+						message: "Do you want to try running a form?",
+						initialValue: true
+					});
+					if (p.isCancel(wantToRun) || !wantToRun) {
+						console.log("");
+						console.log(`Run ${pc.cyan("'markform run'")} to select and run a form later.`);
+					} else {
+						const selectedPath = await showFormMenu(formsDir);
+						if (selectedPath) {
+							console.log("");
+							const exportResult = await runForm(selectedPath, formsDir, ctx.overwrite);
+							if (exportResult) {
+								console.log("");
+								const wantToBrowse = await p.confirm({
+									message: "Would you like to view the output files?",
+									initialValue: true
+								});
+								if (!p.isCancel(wantToBrowse) && wantToBrowse) await browseOutputFiles(exportResult.formPath.replace(/\.form\.md$/, ""));
+							}
+						}
+					}
+				}
 			}
-			await runInteractiveFlow(options.name, ctx.formsDir);
 		} catch (error) {
 			logError(error instanceof Error ? error.message : String(error));
 			process.exit(1);
@@ -2256,13 +2809,14 @@ function registerFillCommand(program) {
 					logInfo(ctx, `[DRY RUN] Would write form to: ${outputPath$1}`);
 					showInteractiveOutro(patches.length, false);
 				} else {
-					const { reportPath, yamlPath, formPath } = await exportMultiFormat(form, outputPath$1);
+					const { reportPath, yamlPath, formPath, schemaPath } = await exportMultiFormat(form, outputPath$1);
 					showInteractiveOutro(patches.length, false);
 					console.log("");
 					p.log.success("Outputs:");
 					console.log(`  ${formatPath(reportPath)}  ${pc.dim("(output report)")}`);
 					console.log(`  ${formatPath(yamlPath)}  ${pc.dim("(output values)")}`);
 					console.log(`  ${formatPath(formPath)}  ${pc.dim("(filled markform source)")}`);
+					console.log(`  ${formatPath(schemaPath)}  ${pc.dim("(JSON Schema)")}`);
 				}
 				logTiming(ctx, "Fill time", durationMs$1);
 				if (patches.length > 0) {
@@ -2543,7 +3097,7 @@ function formatFieldValue(value, useColors) {
 /**
 * Format inspect report for console output.
 */
-function formatConsoleReport$1(report, useColors) {
+function formatConsoleReport$2(report, useColors) {
 	const lines = [];
 	const bold = useColors ? pc.bold : (s) => s;
 	const dim = useColors ? pc.dim : (s) => s;
@@ -2656,7 +3210,7 @@ function registerInspectCommand(program) {
 					severity: issue.severity,
 					blockedBy: issue.blockedBy
 				}))
-			}, (data, useColors) => formatConsoleReport$1(data, useColors));
+			}, (data, useColors) => formatConsoleReport$2(data, useColors));
 			console.log(output);
 		} catch (error) {
 			logError(error instanceof Error ? error.message : String(error));
@@ -4097,15 +4651,16 @@ function registerResearchCommand(program) {
 			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 { reportPath, yamlPath, formPath } = await exportMultiFormat(result.form, outputPath);
+			const { reportPath, yamlPath, formPath, schemaPath } = await exportMultiFormat(result.form, outputPath);
 			logSuccess(ctx, "Outputs:");
 			console.log(`  ${reportPath}  ${pc.dim("(output report)")}`);
 			console.log(`  ${yamlPath}  ${pc.dim("(output values)")}`);
 			console.log(`  ${formPath}  ${pc.dim("(filled markform source)")}`);
+			console.log(`  ${schemaPath}  ${pc.dim("(JSON Schema)")}`);
 			if (options.transcript && result.transcript) {
-				const { serializeSession: serializeSession$1 } = await import("./session-B_stoXQn.mjs");
+				const { serializeSession: serializeSession$1 } = await import("./session-DSTNiHza.mjs");
 				const transcriptPath = outputPath.replace(/\.form\.md$/, ".session.yaml");
-				const { writeFile: writeFile$1 } = await import("./shared-u22MtBRo.mjs");
+				const { writeFile: writeFile$1 } = await import("./shared-C9yW5FLZ.mjs");
 				await writeFile$1(transcriptPath, serializeSession$1(result.transcript));
 				logInfo(ctx, `Transcript: ${transcriptPath}`);
 			}
@@ -4117,6 +4672,195 @@ function registerResearchCommand(program) {
 	});
 }
 
+//#endregion
+//#region src/cli/commands/schema.ts
+const VALID_DRAFTS = [
+	"2020-12",
+	"2019-09",
+	"draft-07"
+];
+/**
+* Register the schema command.
+*/
+function registerSchemaCommand(program) {
+	program.command("schema <file>").description("Export form structure as JSON Schema").option("--pure", "Exclude x-markform extension properties").option("--draft <version>", `JSON Schema draft version: ${VALID_DRAFTS.join(", ")}`, "2020-12").option("--compact", "Output compact JSON (no formatting)").action(async (file, options, cmd) => {
+		const ctx = getCommandContext(cmd);
+		try {
+			const draft = options.draft ?? "2020-12";
+			if (!VALID_DRAFTS.includes(draft)) throw new Error(`Invalid draft version: ${options.draft}. Valid options: ${VALID_DRAFTS.join(", ")}`);
+			logVerbose(ctx, `Reading file: ${file}`);
+			const content = await readFile$1(file);
+			logVerbose(ctx, "Parsing form...");
+			const form = parseForm(content);
+			logVerbose(ctx, "Generating JSON Schema...");
+			const result = formToJsonSchema(form, {
+				includeExtensions: !options.pure,
+				draft
+			});
+			if (ctx.format === "yaml") console.log(YAML.stringify(result.schema));
+			else if (options.compact) console.log(JSON.stringify(result.schema));
+			else console.log(JSON.stringify(result.schema, null, 2));
+		} catch (error) {
+			logError(error instanceof Error ? error.message : String(error));
+			process.exit(1);
+		}
+	});
+}
+
+//#endregion
+//#region src/cli/commands/status.ts
+/**
+* Status command - Display form fill status with per-role breakdown.
+*
+* Provides:
+* - Overall progress counts
+* - Per-role fill statistics
+* - Run mode (explicit or inferred)
+* - Suggested next command
+*/
+/**
+* Compute field statistics from a list of fields.
+*/
+function computeFieldStats(form, fields) {
+	let answered = 0;
+	let skipped = 0;
+	let aborted = 0;
+	let unanswered = 0;
+	for (const field of fields) switch (form.responsesByFieldId[field.id]?.state ?? "unanswered") {
+		case "answered":
+			answered++;
+			break;
+		case "skipped":
+			skipped++;
+			break;
+		case "aborted":
+			aborted++;
+			break;
+		case "unanswered":
+		default:
+			unanswered++;
+			break;
+	}
+	return {
+		total: fields.length,
+		answered,
+		skipped,
+		aborted,
+		unanswered
+	};
+}
+/**
+* Compute statistics grouped by role.
+*/
+function computeStatsByRole(form) {
+	const allFields = getAllFields(form);
+	const roles = getFieldRoles(form);
+	const result = {};
+	for (const role of roles) result[role] = computeFieldStats(form, allFields.filter((f) => f.role === role));
+	return result;
+}
+/**
+* Format percentage with one decimal place.
+*/
+function formatPercent(numerator, denominator) {
+	if (denominator === 0) return "0%";
+	return `${Math.round(numerator / denominator * 100)}%`;
+}
+/**
+* Format status 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 green = useColors ? pc.green : (s) => s;
+	const yellow = useColors ? pc.yellow : (s) => s;
+	const red = useColors ? pc.red : (s) => s;
+	lines.push(bold(cyan(`Form Status: ${basename(report.path)}`)));
+	lines.push("");
+	const overall = report.overall;
+	const overallPercent = formatPercent(overall.answered, overall.total);
+	lines.push(`${bold("Overall:")} ${overall.answered}/${overall.total} fields filled (${overallPercent})`);
+	lines.push(`  ${green("✓")} Complete: ${overall.answered}`);
+	lines.push(`  ${dim("○")} Empty: ${overall.unanswered}`);
+	if (overall.skipped > 0) lines.push(`  ${yellow("⊘")} Skipped: ${overall.skipped}`);
+	if (overall.aborted > 0) lines.push(`  ${red("✗")} Aborted: ${overall.aborted}`);
+	lines.push("");
+	lines.push(bold("By Role:"));
+	const roles = Object.keys(report.byRole).sort((a, b) => {
+		if (a === USER_ROLE) return -1;
+		if (b === USER_ROLE) return 1;
+		if (a === AGENT_ROLE) return -1;
+		if (b === AGENT_ROLE) return 1;
+		return a.localeCompare(b);
+	});
+	for (const role of roles) {
+		const stats = report.byRole[role];
+		if (!stats) continue;
+		const percent = formatPercent(stats.answered, stats.total);
+		const needsAttention = role === USER_ROLE && stats.unanswered > 0 ? yellow(" ← needs attention") : "";
+		lines.push(`  ${role}: ${stats.answered}/${stats.total} filled (${percent})${needsAttention}`);
+	}
+	lines.push("");
+	if (report.runMode) {
+		const source = report.runModeSource === "explicit" ? "explicit" : "inferred";
+		lines.push(`${bold("Run Mode:")} ${report.runMode} (${source})`);
+	} else lines.push(`${bold("Run Mode:")} ${dim("unknown")}`);
+	if (report.suggestedCommand) lines.push(`${bold("Suggested:")} ${cyan(report.suggestedCommand)}`);
+	return lines.join("\n");
+}
+/**
+* Generate a suggested command based on status.
+*/
+function getSuggestedCommand(report) {
+	const { overall, byRole, runMode, path } = report;
+	const filename = basename(path);
+	if (overall.total > 0 && overall.answered === overall.total) return null;
+	const userStats = byRole[USER_ROLE];
+	if (userStats && userStats.unanswered > 0) return `markform fill ${filename} --interactive`;
+	if (runMode === "research") return `markform research ${filename}`;
+	return `markform run ${filename}`;
+}
+/**
+* Register the status command.
+*/
+function registerStatusCommand(program) {
+	program.command("status <file>").description("Display form fill status with per-role breakdown").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, "Computing status...");
+			const overall = computeFieldStats(form, getAllFields(form));
+			const byRole = computeStatsByRole(form);
+			const runModeResult = determineRunMode(form);
+			let runMode = null;
+			let runModeSource = "unknown";
+			if (runModeResult.success) {
+				runMode = runModeResult.runMode;
+				runModeSource = runModeResult.source;
+			}
+			const report = {
+				path: file,
+				runMode,
+				runModeSource,
+				overall,
+				byRole,
+				suggestedCommand: null
+			};
+			report.suggestedCommand = getSuggestedCommand(report);
+			const output = formatOutput(ctx, report, (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/validate.ts
 /**
@@ -4251,12 +4995,13 @@ function withColoredHelp(cmd) {
 */
 function createProgram() {
 	const program = withColoredHelp(new Command());
-	program.name("markform").description("Agent-friendly, human-readable, editable forms").version(VERSION, "--version", "output the version number").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})`);
+	program.name("markform").description("Agent-friendly, human-readable, editable forms").version(CLI_VERSION, "--version", "output the version number").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})`).option("--overwrite", "Overwrite existing field values (default: continue/skip filled)");
 	registerReadmeCommand(program);
 	registerDocsCommand(program);
 	registerSpecCommand(program);
 	registerApisCommand(program);
 	registerApplyCommand(program);
+	registerBrowseCommand(program);
 	registerDumpCommand(program);
 	registerExamplesCommand(program);
 	registerExportCommand(program);
@@ -4266,7 +5011,10 @@ function createProgram() {
 	registerRenderCommand(program);
 	registerReportCommand(program);
 	registerResearchCommand(program);
+	registerRunCommand(program);
+	registerSchemaCommand(program);
 	registerServeCommand(program);
+	registerStatusCommand(program);
 	registerValidateCommand(program);
 	return program;
 }