markform 0.1.2 → 0.1.4

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

@@ -1,19 +1,113 @@
-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 { L as PatchSchema } from "./coreTypes-pyctKRgc.mjs";
+import { A as parseRolesFlag, D as deriveReportPath, E as deriveExportPath, F as hasWebSearchSupport, I as parseModelIdForDisplay, M as WEB_SEARCH_CONFIG, N as formatSuggestedLlms, O as detectFileType, 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 SUGGESTED_LLMS, k as getFormsDir, 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-C54EMAJ1.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-BNh7Cx9P.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-BqPnYXrn.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 { 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/commands/apis.ts
+/**
+* Get the path to the markform-apis.md file.
+* Works both during development and when installed as a package.
+*/
+function getApisPath() {
+	const thisDir = dirname(fileURLToPath(import.meta.url));
+	if (thisDir.split(/[/\\]/).pop() === "dist") return join(dirname(thisDir), "docs", "markform-apis.md");
+	return join(dirname(dirname(dirname(thisDir))), "docs", "markform-apis.md");
+}
+/**
+* Load the APIs documentation content.
+*/
+function loadApis() {
+	const apisPath = getApisPath();
+	try {
+		return readFileSync(apisPath, "utf-8");
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		throw new Error(`Failed to load API docs from ${apisPath}: ${message}`);
+	}
+}
+/**
+* Apply basic terminal formatting to markdown content.
+* Colorizes headers, code blocks, and other elements for better readability.
+*/
+function formatMarkdown$4(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$4() {
+	return process.stdout.isTTY === true;
+}
+/**
+* Display content.
+*/
+function displayContent$3(content) {
+	console.log(content);
+}
+/**
+* Register the apis command.
+*/
+function registerApisCommand(program) {
+	program.command("apis").description("Display Markform TypeScript and AI SDK API documentation").option("--raw", "Output raw markdown without formatting").action((options, cmd) => {
+		const ctx = getCommandContext(cmd);
+		try {
+			displayContent$3(formatMarkdown$4(loadApis(), !options.raw && isInteractive$4() && !ctx.quiet));
+		} catch (error) {
+			logError(error instanceof Error ? error.message : String(error));
+			process.exit(1);
+		}
+	});
+}
+
+//#endregion
 //#region src/cli/commands/apply.ts
 /**
 * Format state badge for console output.
@@ -146,13 +240,13 @@ function registerApplyCommand(program) {
 //#endregion
 //#region src/cli/commands/docs.ts
 /**
-* Get the path to the DOCS.md file.
+* Get the path to the markform-reference.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");
+	if (thisDir.split(/[/\\]/).pop() === "dist") return join(dirname(thisDir), "docs", "markform-reference.md");
+	return join(dirname(dirname(dirname(thisDir))), "docs", "markform-reference.md");
 }
 /**
 * Load the docs content.
@@ -163,7 +257,7 @@ function loadDocs() {
 		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}`);
+		throw new Error(`Failed to load reference docs from ${docsPath}: ${message}`);
 	}
 }
 /**
@@ -334,23 +428,29 @@ function toNotesArray(form) {
 * Derive export paths from a base form path.
 * Uses centralized extension constants from settings.ts.
 *
+* Standard exports: report, values (yaml), form.
+* Raw markdown is available via CLI but not in standard exports.
+*
 * @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")
+		reportPath: deriveReportPath(basePath),
+		yamlPath: deriveExportPath(basePath, "yaml"),
+		formPath: deriveExportPath(basePath, "form")
 	};
 }
 /**
 * Export form to multiple formats.
 *
-* Writes:
+* Standard exports:
+* - 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
-* - Raw markdown (.raw.md) - plain readable markdown (no directives)
-* - YAML values (.yml) - structured format with state and notes (markform-218, markform-219)
+*
+* Note: Raw markdown (.raw.md) is available via CLI `markform export --raw`
+* but is not included in standard multi-format export.
 *
 * @param form - The parsed form to export
 * @param basePath - Base path for the .form.md file (other paths are derived)
@@ -358,10 +458,8 @@ function deriveExportPaths(basePath) {
 */
 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 reportContent = serializeReportMarkdown(form);
+	await writeFile(paths.reportPath, reportContent);
 	const values = toStructuredValues(form);
 	const notes = toNotesArray(form);
 	const exportData = {
@@ -370,6 +468,8 @@ async function exportMultiFormat(form, basePath) {
 	};
 	const yamlContent = YAML.stringify(exportData);
 	await writeFile(paths.yamlPath, yamlContent);
+	const formContent = serialize(form);
+	await writeFile(paths.formPath, formContent);
 	return paths;
 }
 
@@ -474,6 +574,7 @@ function formatPatchValue(patch) {
 		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})`;
 	}
@@ -496,6 +597,7 @@ function formatPatchType(patch) {
 		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";
 	}
@@ -844,9 +946,10 @@ async function promptSkipOrFill(ctx) {
 async function promptForString(ctx) {
 	const field = ctx.field;
 	const currentVal = ctx.currentValue?.kind === "string" ? ctx.currentValue.value : null;
+	const placeholderText = field.placeholder ?? currentVal ?? (ctx.description ? ctx.description.slice(0, 60) : void 0);
 	const result = await p.text({
 		message: formatFieldLabel(ctx),
-		placeholder: currentVal ?? (ctx.description ? ctx.description.slice(0, 60) : void 0),
+		placeholder: placeholderText,
 		initialValue: currentVal ?? "",
 		validate: (value) => {
 			if (field.required && !value.trim()) return "This field is required";
@@ -869,9 +972,10 @@ async function promptForString(ctx) {
 async function promptForNumber(ctx) {
 	const field = ctx.field;
 	const currentVal = ctx.currentValue?.kind === "number" ? ctx.currentValue.value : null;
+	const placeholderText = field.placeholder ?? (currentVal !== null ? String(currentVal) : void 0);
 	const result = await p.text({
 		message: formatFieldLabel(ctx),
-		placeholder: currentVal !== null ? String(currentVal) : void 0,
+		placeholder: placeholderText,
 		initialValue: currentVal !== null ? String(currentVal) : "",
 		validate: (value) => {
 			if (field.required && !value.trim()) return "This field is required";
@@ -897,7 +1001,10 @@ async function promptForNumber(ctx) {
 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.";
+	let hint;
+	if (field.placeholder) hint = `${field.placeholder} (one item per line)`;
+	else if (ctx.description) hint = `${ctx.description.slice(0, 50)}... (one item per line)`;
+	else hint = "Enter items, one per line. Press Enter twice when done.";
 	const result = await p.text({
 		message: formatFieldLabel(ctx),
 		placeholder: hint,
@@ -1071,9 +1178,10 @@ async function promptForCheckboxes(ctx) {
 async function promptForUrl(ctx) {
 	const field = ctx.field;
 	const currentVal = ctx.currentValue?.kind === "url" ? ctx.currentValue.value : null;
+	const placeholderText = field.placeholder ?? currentVal ?? "https://example.com";
 	const result = await p.text({
 		message: formatFieldLabel(ctx),
-		placeholder: currentVal ?? "https://example.com",
+		placeholder: placeholderText,
 		initialValue: currentVal ?? "",
 		validate: (value) => {
 			if (field.required && !value.trim()) return "This field is required";
@@ -1094,12 +1202,87 @@ async function promptForUrl(ctx) {
 	};
 }
 /**
+* Check if a string is a valid ISO 8601 date (YYYY-MM-DD).
+*/
+function isValidDate(str) {
+	if (!/^\d{4}-\d{2}-\d{2}$/.test(str)) return false;
+	const date = new Date(str);
+	if (isNaN(date.getTime())) return false;
+	const [year, month, day] = str.split("-").map(Number);
+	return date.getUTCFullYear() === year && date.getUTCMonth() + 1 === month && date.getUTCDate() === day;
+}
+/**
+* Prompt for a date field value.
+*/
+async function promptForDate(ctx) {
+	const field = ctx.field;
+	const currentVal = ctx.currentValue?.kind === "date" ? ctx.currentValue.value : null;
+	const constraints = [];
+	if (field.min) constraints.push(`min: ${field.min}`);
+	if (field.max) constraints.push(`max: ${field.max}`);
+	const formatHint = constraints.length > 0 ? ` (${constraints.join(", ")})` : "";
+	const result = await p.text({
+		message: formatFieldLabel(ctx),
+		placeholder: currentVal ?? `YYYY-MM-DD${formatHint}`,
+		initialValue: currentVal ?? "",
+		validate: (value) => {
+			if (field.required && !value.trim()) return "This field is required";
+			if (!value.trim()) return;
+			if (!isValidDate(value)) return "Please enter a valid date in YYYY-MM-DD format";
+			if (field.min && value < field.min) return `Date must be on or after ${field.min}`;
+			if (field.max && value > field.max) return `Date must be on or before ${field.max}`;
+		}
+	});
+	if (p.isCancel(result)) return null;
+	if (!result && !field.required) return null;
+	return {
+		op: "set_date",
+		fieldId: field.id,
+		value: result || null
+	};
+}
+/** Default year range for validation */
+const DEFAULT_MIN_YEAR = 1e3;
+const DEFAULT_MAX_YEAR = 2500;
+/**
+* Prompt for a year field value.
+*/
+async function promptForYear(ctx) {
+	const field = ctx.field;
+	const currentVal = ctx.currentValue?.kind === "year" ? ctx.currentValue.value : null;
+	const minYear = field.min ?? DEFAULT_MIN_YEAR;
+	const maxYear = field.max ?? DEFAULT_MAX_YEAR;
+	const result = await p.text({
+		message: formatFieldLabel(ctx),
+		placeholder: currentVal !== null ? String(currentVal) : `Year (${minYear}-${maxYear})`,
+		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) || !Number.isInteger(num)) return "Please enter a valid year (e.g., 2025)";
+			if (num < minYear) return `Year must be ${minYear} or later`;
+			if (num > maxYear) return `Year must be ${maxYear} or earlier`;
+		}
+	});
+	if (p.isCancel(result)) return null;
+	if (!result && !field.required) return null;
+	return {
+		op: "set_year",
+		fieldId: field.id,
+		value: result ? Number(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.";
+	let hint;
+	if (field.placeholder) hint = `${field.placeholder} (one URL per line)`;
+	else if (ctx.description) hint = `${ctx.description.slice(0, 50)}... (one URL per line)`;
+	else hint = "Enter URLs, one per line. Press Enter twice when done.";
 	const result = await p.text({
 		message: formatFieldLabel(ctx),
 		placeholder: hint,
@@ -1126,7 +1309,7 @@ async function promptForUrlList(ctx) {
 	};
 }
 /**
-* Prompt user for a single field value based on field type.
+* Prompt user for a single field value based on field kind.
 * Returns a Patch to set the value, or null if skipped/cancelled.
 *
 * For optional fields, first offers a choice to skip or fill.
@@ -1145,6 +1328,8 @@ async function promptForField(ctx) {
 		case "checkboxes": return promptForCheckboxes(ctx);
 		case "url": return promptForUrl(ctx);
 		case "url_list": return promptForUrlList(ctx);
+		case "date": return promptForDate(ctx);
+		case "year": return promptForYear(ctx);
 		default: return null;
 	}
 }
@@ -1380,29 +1565,42 @@ async function viewFile(filePath) {
 /**
 * 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.
+* 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$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 = [...files.map((file) => ({
+		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: pc.green(basename(file.path)),
+			label: `Show source: ${pc.green(basename(file.path))}`,
 			hint: file.hint ?? ""
-		})), {
-			value: "skip",
-			label: "Done viewing",
-			hint: "exit file viewer"
-		}];
+		});
+		options.push({
+			value: "quit",
+			label: "Quit",
+			hint: ""
+		});
 		const selection = await p.select({
-			message: "View an output file?",
+			message: "View files:",
 			options
 		});
-		if (p.isCancel(selection) || selection === "skip") break;
+		if (p.isCancel(selection) || selection === "quit") break;
 		await viewFile(selection);
 		console.log("");
 	}
@@ -1534,54 +1732,75 @@ async function promptForWebSearchModel() {
 * Accepts optional harness config overrides - research uses different defaults.
 */
 async function runAgentFill(form, modelId, _outputPath, configOverrides) {
-	const spinner = p.spinner();
+	const { provider: providerName, model: modelName } = parseModelIdForDisplay(modelId);
+	const resolveSpinner = createSpinner({
+		type: "compute",
+		operation: `Resolving model: ${modelId}`
+	});
+	let model, provider;
 	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()
-		};
+		const result = await resolveModel(modelId);
+		model = result.model;
+		provider = result.provider;
+		resolveSpinner.stop(`✓ Model resolved: ${modelId}`);
 	} catch (error) {
-		spinner.stop(pc.red("Agent fill failed"));
+		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();
+	}
+	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()
+	};
 }
 /**
 * Run the interactive example scaffolding and filling flow.
@@ -1682,9 +1901,9 @@ async function runInteractiveFlow(preselectedId, formsDirOverride) {
 		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)")}`);
+		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",
@@ -1710,19 +1929,19 @@ async function runInteractiveFlow(preselectedId, formsDirOverride) {
 			console.log(cliCommand);
 			if (userFillOutputs) await showFileViewerChooser([
 				{
-					path: userFillOutputs.formPath,
-					label: "Markform",
-					hint: "form with tags"
+					path: userFillOutputs.reportPath,
+					label: "Report",
+					hint: "output report"
 				},
 				{
-					path: userFillOutputs.rawPath,
-					label: "Plain Markdown",
-					hint: "rendered output"
+					path: userFillOutputs.yamlPath,
+					label: "Values",
+					hint: "output values"
 				},
 				{
-					path: userFillOutputs.yamlPath,
-					label: "YAML",
-					hint: "extracted values"
+					path: userFillOutputs.formPath,
+					label: "Form",
+					hint: "filled markform source"
 				}
 			]);
 			p.outro("Happy form filling!");
@@ -1760,29 +1979,29 @@ async function runInteractiveFlow(preselectedId, formsDirOverride) {
 				dryRun: false,
 				quiet: false
 			}, timingLabel, Date.now() - agentStartTime);
-			const { formPath, rawPath, yamlPath } = await exportMultiFormat(form, agentOutputPath);
+			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(formPath)}  (markform)`);
-			console.log(`  ${formatPath(rawPath)}  (plain markdown)`);
-			console.log(`  ${formatPath(yamlPath)}  (values as YAML)`);
+			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: formPath,
-					label: "Markform",
-					hint: "form with tags"
+					path: reportPath,
+					label: "Report",
+					hint: "output report"
 				},
 				{
-					path: rawPath,
-					label: "Plain Markdown",
-					hint: "rendered output"
+					path: yamlPath,
+					label: "Values",
+					hint: "output values"
 				},
 				{
-					path: yamlPath,
-					label: "YAML",
-					hint: "extracted values"
+					path: formPath,
+					label: "Form",
+					hint: "filled markform source"
 				}
 			]);
 		} catch (error) {
@@ -1864,7 +2083,9 @@ function registerExportCommand(program) {
 						...field.kind === "single_select" || field.kind === "multi_select" || field.kind === "checkboxes" ? { options: field.options.map((opt) => ({
 							id: opt.id,
 							label: opt.label
-						})) } : {}
+						})) } : {},
+						...field.placeholder ? { placeholder: field.placeholder } : {},
+						...field.examples && field.examples.length > 0 ? { examples: field.examples } : {}
 					}))
 				}))
 			};
@@ -1987,13 +2208,13 @@ function registerFillCommand(program) {
 					logInfo(ctx, `[DRY RUN] Would write form to: ${outputPath$1}`);
 					showInteractiveOutro(patches.length, false);
 				} else {
-					const { formPath, rawPath, yamlPath } = await exportMultiFormat(form, outputPath$1);
+					const { reportPath, yamlPath, formPath } = 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)")}`);
+					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)")}`);
 				}
 				logTiming(ctx, "Fill time", durationMs$1);
 				if (patches.length > 0) {
@@ -2026,14 +2247,18 @@ function registerFillCommand(program) {
 			const harness = createHarness(form, harnessConfig);
 			let agent;
 			let mockPath;
+			let agentProvider;
+			let agentModelName;
 			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);
+				const modelIdString = options.model;
+				logVerbose(ctx, `Resolving model: ${modelIdString}`);
+				const { model, provider, modelId } = await resolveModel(modelIdString);
+				agentProvider = provider;
+				agentModelName = modelId;
 				let systemPrompt;
 				if (options.instructions) {
 					systemPrompt = options.instructions;
@@ -2048,7 +2273,8 @@ function registerFillCommand(program) {
 					model,
 					provider,
 					systemPromptAddition: systemPrompt,
-					targetRole: primaryRole
+					targetRole: primaryRole,
+					enableWebSearch: true
 				});
 				agent = liveAgent;
 				logInfo(ctx, `Available tools: ${liveAgent.getAvailableToolNames().join(", ")}`);
@@ -2064,7 +2290,22 @@ function registerFillCommand(program) {
 			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);
+				let spinner = null;
+				if (!options.mock && agentProvider && agentModelName && process.stdout.isTTY && !ctx.quiet) spinner = createSpinner({
+					type: "api",
+					provider: agentProvider,
+					model: agentModelName,
+					turnNumber: stepResult.turnNumber
+				});
+				let response;
+				try {
+					response = await agent.generatePatches(stepResult.issues, harness.getForm(), harnessConfig.maxPatchesPerTurn);
+					spinner?.stop();
+				} catch (error) {
+					spinner?.error("LLM call failed");
+					throw error;
+				}
+				const { patches, stats } = response;
 				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) {
@@ -2487,13 +2728,13 @@ function registerReportCommand(program) {
 //#endregion
 //#region src/cli/commands/spec.ts
 /**
-* Get the path to the SPEC.md file.
+* Get the path to the markform-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");
+	if (thisDir.split(/[/\\]/).pop() === "dist") return join(dirname(thisDir), "docs", "markform-spec.md");
+	return join(dirname(dirname(dirname(thisDir))), "docs", "markform-spec.md");
 }
 /**
 * Load the spec content.
@@ -2884,6 +3125,34 @@ function formDataToPatches(formData, form) {
 				});
 				break;
 			}
+			case "date": {
+				const value = formData[fieldId];
+				if (typeof value === "string" && value.trim() !== "") patches.push({
+					op: "set_date",
+					fieldId,
+					value: value.trim()
+				});
+				else patches.push({
+					op: "clear_field",
+					fieldId
+				});
+				break;
+			}
+			case "year": {
+				const value = formData[fieldId];
+				if (typeof value === "string" && value.trim() !== "") {
+					const num = parseInt(value, 10);
+					if (!isNaN(num)) patches.push({
+						op: "set_year",
+						fieldId,
+						value: num
+					});
+				} else patches.push({
+					op: "clear_field",
+					fieldId
+				});
+				break;
+			}
 		}
 	}
 	return patches;
@@ -3228,7 +3497,13 @@ function renderFieldHtml(field, value, isSkipped) {
 		case "url_list":
 			inputHtml = renderUrlListInput(field, value, disabledAttr);
 			break;
-		default: inputHtml = "<div class=\"field-help\">(unknown field type)</div>";
+		case "date":
+			inputHtml = renderDateInput(field, value, disabledAttr);
+			break;
+		case "year":
+			inputHtml = renderYearInput(field, value, disabledAttr);
+			break;
+		default: inputHtml = "<div class=\"field-help\">(unknown field kind)</div>";
 	}
 	const skipButton = !field.required && !skipped ? `<div class="field-actions">
         <button type="button" class="btn-skip" data-skip-field="${field.id}">Skip</button>
@@ -3250,7 +3525,8 @@ function renderStringInput(field, value, disabledAttr) {
 	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}>`;
+	const placeholderAttr = field.placeholder ? ` placeholder="${escapeHtml(field.placeholder)}"` : "";
+	return `<input type="text" id="field-${field.id}" name="${field.id}" value="${escapeHtml(currentValue)}"${requiredAttr}${minLengthAttr}${maxLengthAttr}${placeholderAttr}${disabledAttr}>`;
 }
 /**
 * Render a number field as number input.
@@ -3261,7 +3537,8 @@ function renderNumberInput(field, value, disabledAttr) {
 	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}>`;
+	const placeholderAttr = field.placeholder ? ` placeholder="${escapeHtml(field.placeholder)}"` : "";
+	return `<input type="number" id="field-${field.id}" name="${field.id}" value="${escapeHtml(currentValue)}"${requiredAttr}${minAttr}${maxAttr}${stepAttr}${placeholderAttr}${disabledAttr}>`;
 }
 /**
 * Render a string list field as textarea.
@@ -3269,7 +3546,8 @@ function renderNumberInput(field, value, disabledAttr) {
 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>`;
+	const placeholderText = field.placeholder ? `${escapeHtml(field.placeholder)} (one item per line)` : "Enter one item per line";
+	return `<textarea id="field-${field.id}" name="${field.id}" placeholder="${placeholderText}"${requiredAttr}${disabledAttr}>${escapeHtml(currentValue)}</textarea>`;
 }
 /**
 * Render a URL field as url input.
@@ -3277,7 +3555,8 @@ function renderStringListInput(field, value, disabledAttr) {
 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}>`;
+	const placeholderText = field.placeholder ?? "https://example.com";
+	return `<input type="url" id="field-${field.id}" name="${field.id}" value="${escapeHtml(currentValue)}" placeholder="${escapeHtml(placeholderText)}"${requiredAttr}${disabledAttr}>`;
 }
 /**
 * Render a URL list field as textarea.
@@ -3285,7 +3564,28 @@ function renderUrlInput(field, value, disabledAttr) {
 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>`;
+	const placeholderText = field.placeholder ? `${escapeHtml(field.placeholder)} (one URL per line)` : "Enter one URL per line";
+	return `<textarea id="field-${field.id}" name="${field.id}" placeholder="${placeholderText}"${requiredAttr}${disabledAttr}>${escapeHtml(currentValue)}</textarea>`;
+}
+/**
+* Render a date field as date input.
+*/
+function renderDateInput(field, value, disabledAttr) {
+	const currentValue = value?.kind === "date" && value.value !== null ? 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}"` : "";
+	return `<input type="date" id="field-${field.id}" name="${field.id}" value="${escapeHtml(currentValue)}"${requiredAttr}${minAttr}${maxAttr}${disabledAttr}>`;
+}
+/**
+* Render a year field as number input.
+*/
+function renderYearInput(field, value, disabledAttr) {
+	const currentValue = value?.kind === "year" && value.value !== null ? String(value.value) : "";
+	const requiredAttr = field.required ? " required" : "";
+	const minAttr = field.min !== void 0 ? ` min="${field.min}"` : " min=\"1000\"";
+	const maxAttr = field.max !== void 0 ? ` max="${field.max}"` : " max=\"2500\"";
+	return `<input type="number" id="field-${field.id}" name="${field.id}" value="${escapeHtml(currentValue)}" step="1" placeholder="YYYY"${requiredAttr}${minAttr}${maxAttr}${disabledAttr}>`;
 }
 /**
 * Render a single-select field as select element.
@@ -3671,7 +3971,8 @@ function registerResearchCommand(program) {
 				process.exit(1);
 			}
 			const modelId = options.model;
-			if (!hasWebSearchSupport(/^([^/]+)\//.exec(modelId)?.[1] ?? modelId)) {
+			const { provider, model: modelName } = parseModelIdForDisplay(modelId);
+			if (!hasWebSearchSupport(provider)) {
 				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("");
@@ -3709,27 +4010,40 @@ function registerResearchCommand(program) {
 			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"
-			});
+			const spinner = process.stdout.isTTY && !ctx.quiet ? createSpinner({
+				type: "api",
+				provider,
+				model: modelName
+			}) : null;
+			let result;
+			try {
+				result = await runResearch(form, {
+					model: modelId,
+					enableWebSearch: true,
+					maxTurns,
+					maxPatchesPerTurn,
+					maxIssuesPerTurn,
+					targetRoles: [AGENT_ROLE],
+					fillMode: "continue"
+				});
+				spinner?.stop();
+			} catch (error) {
+				spinner?.error("Research failed");
+				throw error;
+			}
 			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);
+			const { reportPath, yamlPath, formPath } = 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)")}`);
+			console.log(`  ${reportPath}  ${pc.dim("(output report)")}`);
+			console.log(`  ${yamlPath}  ${pc.dim("(output values)")}`);
+			console.log(`  ${formPath}  ${pc.dim("(filled markform source)")}`);
 			if (options.transcript && result.transcript) {
-				const { serializeSession: serializeSession$1 } = await import("./session-DdAtY2Ni.mjs");
+				const { serializeSession: serializeSession$1 } = await import("./session-B_stoXQn.mjs");
 				const transcriptPath = outputPath.replace(/\.form\.md$/, ".session.yaml");
-				const { writeFile: writeFile$1 } = await import("./shared-D7gf27Tr.mjs");
+				const { writeFile: writeFile$1 } = await import("./shared-CZsyShck.mjs");
 				await writeFile$1(transcriptPath, serializeSession$1(result.transcript));
 				logInfo(ctx, `Transcript: ${transcriptPath}`);
 			}
@@ -3875,10 +4189,11 @@ function withColoredHelp(cmd) {
 */
 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})`);
+	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})`);
 	registerReadmeCommand(program);
 	registerDocsCommand(program);
 	registerSpecCommand(program);
+	registerApisCommand(program);
 	registerApplyCommand(program);
 	registerDumpCommand(program);
 	registerExamplesCommand(program);