markform 0.1.3 → 0.1.5

package/dist/{cli-D--Lel-e.mjs → cli-D469amuk.mjs}

@@ -1,19 +1,113 @@
-import { N as PatchSchema } from "./coreTypes-Dful87E0.mjs";
-import { A as parseRolesFlag, D as deriveReportPath, E as deriveExportPath, F as hasWebSearchSupport, 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-00UmzDKL.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-Dm8jZ5dl.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-BCCiJzQr.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-Df0XX7UB.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}`);
 	}
 }
 /**
@@ -480,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})`;
 	}
@@ -502,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";
 	}
@@ -588,12 +684,6 @@ const EXAMPLE_DEFINITIONS = [
 		filename: "startup-deep-research.form.md",
 		path: "startup-deep-research/startup-deep-research.form.md",
 		type: "research"
-	},
-	{
-		id: "celebrity-deep-research",
-		filename: "celebrity-deep-research.form.md",
-		path: "celebrity-deep-research/celebrity-deep-research.form.md",
-		type: "research"
 	}
 ];
 /**
@@ -607,7 +697,7 @@ function getExamplesDir() {
 }
 /**
 * Load the content of an example form.
-* @param exampleId - The example ID (e.g., 'simple', 'celebrity-deep-research')
+* @param exampleId - The example ID (e.g., 'simple', 'movie-research-deep')
 * @returns The form content as a string
 * @throws Error if the example is not found
 */
@@ -629,7 +719,7 @@ function getExampleById(id) {
 }
 /**
 * Get the absolute path to an example's source file.
-* @param exampleId - The example ID (e.g., 'simple', 'celebrity-deep-research')
+* @param exampleId - The example ID (e.g., 'simple', 'movie-research-deep')
 * @returns The absolute path to the example form file
 * @throws Error if the example is not found
 */
@@ -654,7 +744,7 @@ function extractFrontmatter(content) {
 }
 /**
 * Load metadata (title, description) from an example's YAML frontmatter.
-* @param exampleId - The example ID (e.g., 'simple', 'celebrity-deep-research')
+* @param exampleId - The example ID (e.g., 'simple', 'movie-research-deep')
 * @returns Object with title and description from frontmatter
 */
 function loadExampleMetadata(exampleId) {
@@ -850,9 +940,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";
@@ -875,9 +966,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";
@@ -903,7 +995,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,
@@ -1077,9 +1172,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";
@@ -1100,12 +1196,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,
@@ -1132,7 +1303,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.
@@ -1151,6 +1322,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;
 	}
 }
@@ -1553,54 +1726,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.
@@ -1883,7 +2077,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 } : {}
 					}))
 				}))
 			};
@@ -2045,14 +2241,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;
@@ -2067,7 +2267,8 @@ function registerFillCommand(program) {
 					model,
 					provider,
 					systemPromptAddition: systemPrompt,
-					targetRole: primaryRole
+					targetRole: primaryRole,
+					enableWebSearch: true
 				});
 				agent = liveAgent;
 				logInfo(ctx, `Available tools: ${liveAgent.getAvailableToolNames().join(", ")}`);
@@ -2083,7 +2284,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) {
@@ -2506,13 +2722,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.
@@ -2903,6 +3119,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;
@@ -3247,7 +3491,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>
@@ -3269,7 +3519,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.
@@ -3280,7 +3531,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.
@@ -3288,7 +3540,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.
@@ -3296,7 +3549,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.
@@ -3304,7 +3558,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.
@@ -3690,7 +3965,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("");
@@ -3728,14 +4004,27 @@ 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}`);
@@ -3746,9 +4035,9 @@ function registerResearchCommand(program) {
 			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}`);
 			}
@@ -3894,10 +4183,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);