markform 0.0.1 → 0.1.1

package/dist/{cli-9fvFySww.mjs → cli-pjOiHgCW.mjs}

@@ -1,5 +1,5 @@
-import { $ as PatchSchema, S as parseRolesFlag, b as USER_ROLE, d as serializeRawMarkdown, f as AGENT_ROLE, g as DEFAULT_PORT, h as DEFAULT_MAX_TURNS, m as DEFAULT_MAX_PATCHES_PER_TURN, p as DEFAULT_MAX_ISSUES, r as inspect, t as applyPatches, u as serialize, x as formatSuggestedLlms, y as SUGGESTED_LLMS } from "./apply-C0vjijlP.mjs";
-import { _ as parseForm, a as resolveModel, c as createMockAgent, h as serializeSession, i as getProviderNames, o as createLiveAgent, r as getProviderInfo, t as VERSION, u as createHarness } from "./src-DBD3Dt4f.mjs";
+import { C as parseRolesFlag, b as USER_ROLE, d as serializeRawMarkdown, et as PatchSchema, f as AGENT_ROLE, g as DEFAULT_PORT, h as DEFAULT_MAX_TURNS, m as DEFAULT_MAX_PATCHES_PER_TURN, p as DEFAULT_MAX_ISSUES, r as inspect, t as applyPatches, u as serialize, x as formatSuggestedLlms, y as SUGGESTED_LLMS } from "./apply-BQdd-fdx.mjs";
+import { _ as parseForm, a as resolveModel, c as createMockAgent, h as serializeSession, i as getProviderNames, o as createLiveAgent, r as getProviderInfo, t as VERSION, u as createHarness } from "./src-Cs4_9lWP.mjs";
 import YAML from "yaml";
 import { Command } from "commander";
 import pc from "picocolors";
@@ -453,6 +453,52 @@ function exportMultiFormat(form, basePath) {
 	return paths;
 }
 
+//#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 "set_url": return patch.value ? truncate(`"${patch.value}"`) : "(empty)";
+		case "set_url_list": return patch.items.length > 0 ? truncate(`[${patch.items.join(", ")}]`) : "(empty)";
+	}
+}
+/**
+* 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 "set_url": return "url";
+		case "set_url_list": return "url_list";
+	}
+}
+
 //#endregion
 //#region src/cli/examples/exampleRegistry.ts
 /**
@@ -481,6 +527,13 @@ const EXAMPLE_DEFINITIONS = [
 		description: "Financial analysis with one user field (company) and agent-filled quarterly analysis sections.",
 		filename: "earnings-analysis.form.md",
 		path: "earnings-analysis/earnings-analysis.form.md"
+	},
+	{
+		id: "startup-deep-research",
+		title: "Startup Deep Research",
+		description: "Comprehensive startup intelligence gathering with company info, founders, funding, competitors, social media, and community presence.",
+		filename: "startup-deep-research.form.md",
+		path: "startup-deep-research/startup-deep-research.form.md"
 	}
 ];
 /**
@@ -514,6 +567,17 @@ function loadExampleContent(exampleId) {
 function getExampleById(id) {
 	return EXAMPLE_DEFINITIONS.find((e) => e.id === id);
 }
+/**
+* Get the absolute path to an example's source file.
+* @param exampleId - The example ID (e.g., 'simple', 'political-research')
+* @returns The absolute path to the example form file
+* @throws Error if the example is not found
+*/
+function getExamplePath(exampleId) {
+	const example = EXAMPLE_DEFINITIONS.find((e) => e.id === exampleId);
+	if (!example) throw new Error(`Unknown example: ${exampleId}`);
+	return join(getExamplesDir(), example.path);
+}
 
 //#endregion
 //#region src/cli/lib/versioning.ts
@@ -623,6 +687,38 @@ function formatFieldLabel(ctx) {
 	return `${ctx.field.label}${required} ${progress}`;
 }
 /**
+* Create a skip_field patch for the given field.
+*/
+function createSkipPatch(field) {
+	return {
+		op: "skip_field",
+		fieldId: field.id,
+		reason: "User skipped in console"
+	};
+}
+/**
+* For optional fields, prompt user to choose between filling or skipping.
+* Returns "fill" if user wants to enter a value, or a skip_field patch if skipping.
+* Returns null if user cancelled.
+*/
+async function promptSkipOrFill(ctx) {
+	const field = ctx.field;
+	if (field.required) return "fill";
+	const result = await p.select({
+		message: `${formatFieldLabel(ctx)} ${pc.dim("(optional)")}`,
+		options: [{
+			value: "fill",
+			label: "Enter value"
+		}, {
+			value: "skip",
+			label: "Skip this field"
+		}]
+	});
+	if (p.isCancel(result)) return null;
+	if (result === "skip") return createSkipPatch(field);
+	return "fill";
+}
+/**
 * Prompt for a string field value.
 */
 async function promptForString(ctx) {
@@ -850,11 +946,76 @@ async function promptForCheckboxes(ctx) {
 	};
 }
 /**
+* Prompt for a URL field value.
+*/
+async function promptForUrl(ctx) {
+	const field = ctx.field;
+	const currentVal = ctx.currentValue?.kind === "url" ? ctx.currentValue.value : null;
+	const result = await p.text({
+		message: formatFieldLabel(ctx),
+		placeholder: currentVal ?? "https://example.com",
+		initialValue: currentVal ?? "",
+		validate: (value) => {
+			if (field.required && !value.trim()) return "This field is required";
+			if (!value.trim()) return;
+			try {
+				new URL(value);
+			} catch {
+				return "Please enter a valid URL (e.g., https://example.com)";
+			}
+		}
+	});
+	if (p.isCancel(result)) return null;
+	if (!result && !field.required) return null;
+	return {
+		op: "set_url",
+		fieldId: field.id,
+		value: result || null
+	};
+}
+/**
+* Prompt for a URL list field value.
+*/
+async function promptForUrlList(ctx) {
+	const field = ctx.field;
+	const currentItems = ctx.currentValue?.kind === "url_list" ? ctx.currentValue.items : [];
+	const hint = ctx.description ? `${ctx.description.slice(0, 50)}... (one URL per line)` : "Enter URLs, one per line. Press Enter twice when done.";
+	const result = await p.text({
+		message: formatFieldLabel(ctx),
+		placeholder: hint,
+		initialValue: currentItems.join("\n"),
+		validate: (value) => {
+			const items$1 = value.split("\n").map((s) => s.trim()).filter(Boolean);
+			if (field.required && items$1.length === 0) return "At least one URL is required";
+			if (field.minItems && items$1.length < field.minItems) return `Minimum ${field.minItems} URLs required`;
+			if (field.maxItems && items$1.length > field.maxItems) return `Maximum ${field.maxItems} URLs allowed`;
+			for (const item of items$1) try {
+				new URL(item);
+			} catch {
+				return `Invalid URL: ${item}`;
+			}
+		}
+	});
+	if (p.isCancel(result)) return null;
+	const items = result.split("\n").map((s) => s.trim()).filter(Boolean);
+	if (items.length === 0 && !field.required) return null;
+	return {
+		op: "set_url_list",
+		fieldId: field.id,
+		items
+	};
+}
+/**
 * Prompt user for a single field value based on field type.
 * Returns a Patch to set the value, or null if skipped/cancelled.
+*
+* For optional fields, first offers a choice to skip or fill.
 */
 async function promptForField(ctx) {
 	if (ctx.description) p.note(ctx.description, pc.dim("Instructions"));
+	const skipOrFillResult = await promptSkipOrFill(ctx);
+	if (skipOrFillResult === null) return null;
+	if (typeof skipOrFillResult !== "string") return skipOrFillResult;
 	switch (ctx.field.kind) {
 		case "string": return promptForString(ctx);
 		case "number": return promptForNumber(ctx);
@@ -862,6 +1023,8 @@ async function promptForField(ctx) {
 		case "single_select": return promptForSingleSelect(ctx);
 		case "multi_select": return promptForMultiSelect(ctx);
 		case "checkboxes": return promptForCheckboxes(ctx);
+		case "url": return promptForUrl(ctx);
+		case "url_list": return promptForUrlList(ctx);
 		default: return null;
 	}
 }
@@ -935,7 +1098,7 @@ function showInteractiveIntro(formTitle, role, fieldCount) {
 /**
 * Show outro message after interactive fill.
 */
-function showInteractiveOutro(patchCount, outputPath, cancelled) {
+function showInteractiveOutro(patchCount, cancelled) {
 	if (cancelled) {
 		p.cancel("Interactive fill cancelled.");
 		return;
@@ -944,7 +1107,7 @@ function showInteractiveOutro(patchCount, outputPath, cancelled) {
 		p.outro(pc.yellow("No changes made."));
 		return;
 	}
-	p.outro(`✓ ${patchCount} field(s) updated. Saved to ${formatPath(outputPath)}`);
+	p.outro(`✓ ${patchCount} field(s) updated.`);
 }
 
 //#endregion
@@ -958,7 +1121,7 @@ function printExamplesList() {
 		console.log(`  ${pc.cyan(example.id)}`);
 		console.log(`    ${pc.bold(example.title)}`);
 		console.log(`    ${pc.dim(example.description)}`);
-		console.log(`    Default filename: ${example.filename}`);
+		console.log(`    Source: ${formatPath(getExamplePath(example.id))}`);
 		console.log("");
 	}
 }
@@ -984,7 +1147,7 @@ function buildModelOptions() {
 	for (const [provider, models] of Object.entries(SUGGESTED_LLMS)) {
 		const info = getProviderInfo(provider);
 		const keyStatus = !!process.env[info.envVar] ? pc.green("✓") : pc.dim("○");
-		for (const model of models.slice(0, 2)) options.push({
+		for (const model of models) options.push({
 			value: `${provider}/${model}`,
 			label: `${provider}/${model}`,
 			hint: `${keyStatus} ${info.envVar}`
@@ -1046,14 +1209,15 @@ async function runAgentFill(form, modelId, _outputPath) {
 		let stepResult = harness.step();
 		while (!stepResult.isComplete && !harness.hasReachedMaxTurns()) {
 			console.log(pc.dim(`  Turn ${stepResult.turnNumber}: ${stepResult.issues.length} issue(s) to address`));
-			const patches = await agent.generatePatches(stepResult.issues, harness.getForm(), harnessConfig.maxPatchesPerTurn);
+			const { patches } = await agent.generatePatches(stepResult.issues, harness.getForm(), harnessConfig.maxPatchesPerTurn);
 			for (const patch of patches) {
-				const fieldId = patch.fieldId;
-				console.log(pc.dim(`    → ${patch.op} ${fieldId}`));
+				const typeName = formatPatchType(patch);
+				const value = formatPatchValue(patch);
+				console.log(pc.dim(`    ${pc.cyan(patch.fieldId)} (${typeName}) = ${pc.green(value)}`));
 			}
 			stepResult = harness.apply(patches, stepResult.issues);
 			console.log(pc.dim(`    ${patches.length} patch(es) applied, ${stepResult.issues.length} remaining`));
-			if (!stepResult.isComplete) stepResult = harness.step();
+			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})`));
@@ -1151,12 +1315,12 @@ async function runInteractiveFlow(preselectedId) {
 		showInteractiveIntro(form.schema.title ?? form.schema.id, targetRoles.join(", "), uniqueFieldIds.size);
 		const { patches, cancelled } = await runInteractiveFill(form, inspectResult.issues);
 		if (cancelled) {
-			showInteractiveOutro(0, "", true);
+			showInteractiveOutro(0, true);
 			process.exit(1);
 		}
 		if (patches.length > 0) applyPatches(form, patches);
 		const { formPath, rawPath, yamlPath } = exportMultiFormat(form, outputPath);
-		showInteractiveOutro(patches.length, outputPath, false);
+		showInteractiveOutro(patches.length, false);
 		console.log("");
 		p.log.success("Outputs:");
 		console.log(`  ${formatPath(formPath)}  ${pc.dim("(markform)")}`);
@@ -1180,7 +1344,7 @@ async function runInteractiveFlow(preselectedId) {
 		if (p.isCancel(runAgent) || !runAgent) {
 			console.log("");
 			console.log(pc.dim("You can run agent fill later with:"));
-			console.log(pc.dim(`  markform fill ${formatPath(outputPath)} --agent=live --model=<provider/model>`));
+			console.log(pc.dim(`  markform fill ${formatPath(outputPath)} --model=<provider/model>`));
 			p.outro(pc.dim("Happy form filling!"));
 			return;
 		}
@@ -1223,7 +1387,7 @@ async function runInteractiveFlow(preselectedId) {
 			p.log.error(`Agent fill failed: ${message}`);
 			console.log("");
 			console.log(pc.dim("You can try again with:"));
-			console.log(pc.dim(`  markform fill ${formatPath(outputPath)} --agent=live --model=${modelId}`));
+			console.log(pc.dim(`  markform fill ${formatPath(outputPath)} --model=${modelId}`));
 		}
 	}
 	p.outro(pc.dim("Happy form filling!"));
@@ -1315,22 +1479,6 @@ function registerExportCommand(program) {
 
 //#endregion
 //#region src/cli/commands/fill.ts
-/** Supported agent types */
-const AGENT_TYPES = ["mock", "live"];
-/**
-* Format a patch value for display.
-*/
-function formatPatchValue(patch) {
-	switch (patch.op) {
-		case "set_string": return patch.value ? `"${patch.value}"` : "(empty)";
-		case "set_number": return patch.value !== null ? String(patch.value) : "(empty)";
-		case "set_string_list": return patch.items.length > 0 ? `[${patch.items.join(", ")}]` : "(empty)";
-		case "set_single_select": return patch.selected ?? "(none)";
-		case "set_multi_select": return patch.selected.length > 0 ? `[${patch.selected.join(", ")}]` : "(none)";
-		case "set_checkboxes": return Object.entries(patch.values).map(([k, v]) => `${k}:${v}`).join(", ");
-		case "clear_field": return "(cleared)";
-	}
-}
 /**
 * Format session transcript for console output.
 */
@@ -1369,7 +1517,7 @@ function formatConsoleSession(transcript, useColors) {
 * Register the fill command.
 */
 function registerFillCommand(program) {
-	program.command("fill <file>").description("Run an agent to autonomously fill a form").option("--agent <type>", `Agent type: ${AGENT_TYPES.join(", ")} (default: live)`, "live").option("--model <id>", "Model ID for live agent (format: provider/model-id, e.g. openai/gpt-4o)").option("--mock-source <file>", "Path to completed form for mock agent").option("--record <file>", "Record session transcript to file").option("--max-turns <n>", `Maximum turns (default: ${DEFAULT_MAX_TURNS})`, String(DEFAULT_MAX_TURNS)).option("--max-patches <n>", `Maximum patches per turn (default: ${DEFAULT_MAX_PATCHES_PER_TURN})`, String(DEFAULT_MAX_PATCHES_PER_TURN)).option("--max-issues <n>", `Maximum issues shown per turn (default: ${DEFAULT_MAX_ISSUES})`, String(DEFAULT_MAX_ISSUES)).option("--max-fields <n>", "Maximum unique fields per turn (applied before --max-issues)").option("--max-groups <n>", "Maximum unique groups per turn (applied before --max-issues)").option("--roles <roles>", "Target roles to fill (comma-separated, or '*' for all; default: 'agent' in agent mode, 'user' in --interactive mode)").option("--mode <mode>", "Fill mode: continue (skip filled fields) or overwrite (re-fill; default: continue)").option("-o, --output <file>", "Write final form to file").option("--prompt <file>", "Path to custom system prompt file (appends to default)").option("--instructions <text>", "Inline system prompt (appends to default; takes precedence over --prompt)").option("-i, --interactive", "Interactive mode: prompt user for field values (defaults to user role)").action(async (file, options, cmd) => {
+	program.command("fill <file>").description("Run an agent to autonomously fill a form").option("--mock", "Use mock agent (requires --mock-source)").option("--model <id>", "Model ID for live agent (format: provider/model-id, e.g. openai/gpt-4o)").option("--mock-source <file>", "Path to completed form for mock agent").option("--record <file>", "Record session transcript to file").option("--max-turns <n>", `Maximum turns (default: ${DEFAULT_MAX_TURNS})`, String(DEFAULT_MAX_TURNS)).option("--max-patches <n>", `Maximum patches per turn (default: ${DEFAULT_MAX_PATCHES_PER_TURN})`, String(DEFAULT_MAX_PATCHES_PER_TURN)).option("--max-issues <n>", `Maximum issues shown per turn (default: ${DEFAULT_MAX_ISSUES})`, String(DEFAULT_MAX_ISSUES)).option("--max-fields <n>", "Maximum unique fields per turn (applied before --max-issues)").option("--max-groups <n>", "Maximum unique groups per turn (applied before --max-issues)").option("--roles <roles>", "Target roles to fill (comma-separated, or '*' for all; default: 'agent', or 'user' in --interactive mode)").option("--mode <mode>", "Fill mode: continue (skip filled fields) or overwrite (re-fill; default: continue)").option("-o, --output <file>", "Write final form to file").option("--prompt <file>", "Path to custom system prompt file (appends to default)").option("--instructions <text>", "Inline system prompt (appends to default; takes precedence over --prompt)").option("-i, --interactive", "Interactive mode: prompt user for field values (defaults to user role)").action(async (file, options, cmd) => {
 		const ctx = getCommandContext(cmd);
 		const filePath = resolve(file);
 		try {
@@ -1395,8 +1543,8 @@ function registerFillCommand(program) {
 			logVerbose(ctx, "Parsing form...");
 			const form = parseForm(formContent);
 			if (options.interactive) {
-				if (options.agent && options.agent !== "live") {
-					logError("--interactive cannot be used with --agent");
+				if (options.mock) {
+					logError("--interactive cannot be used with --mock");
 					process.exit(1);
 				}
 				if (options.model) {
@@ -1414,35 +1562,38 @@ function registerFillCommand(program) {
 				showInteractiveIntro(formTitle, targetRoles.join(", "), uniqueFieldIds.size);
 				const { patches, cancelled } = await runInteractiveFill(form, inspectResult.issues);
 				if (cancelled) {
-					showInteractiveOutro(0, "", true);
+					showInteractiveOutro(0, true);
 					process.exit(1);
 				}
 				if (patches.length > 0) applyPatches(form, patches);
 				const durationMs$1 = Date.now() - startTime;
 				const outputPath$1 = options.output ? resolve(options.output) : generateVersionedPath(filePath);
-				const formMarkdown$1 = serialize(form);
-				if (ctx.dryRun) logInfo(ctx, `[DRY RUN] Would write form to: ${outputPath$1}`);
-				else await writeFile(outputPath$1, formMarkdown$1);
-				showInteractiveOutro(patches.length, outputPath$1, false);
+				if (ctx.dryRun) {
+					logInfo(ctx, `[DRY RUN] Would write form to: ${outputPath$1}`);
+					showInteractiveOutro(patches.length, false);
+				} else {
+					const { formPath, rawPath, yamlPath } = exportMultiFormat(form, outputPath$1);
+					showInteractiveOutro(patches.length, false);
+					console.log("");
+					p.log.success("Outputs:");
+					console.log(`  ${formatPath(formPath)}  ${pc.dim("(markform)")}`);
+					console.log(`  ${formatPath(rawPath)}  ${pc.dim("(plain markdown)")}`);
+					console.log(`  ${formatPath(yamlPath)}  ${pc.dim("(values as YAML)")}`);
+				}
 				logTiming(ctx, "Fill time", durationMs$1);
 				if (patches.length > 0) {
 					console.log("");
 					console.log(pc.dim("Next step: fill remaining fields with agent"));
-					console.log(pc.dim(`  markform fill ${outputPath$1} --agent=live --model=<provider/model>`));
+					console.log(pc.dim(`  markform fill ${formatPath(outputPath$1)} --model=<provider/model>`));
 				}
 				process.exit(0);
 			}
-			const agentType = options.agent ?? "live";
-			if (!AGENT_TYPES.includes(agentType)) {
-				logError(`Invalid agent type '${options.agent}'. Valid types: ${AGENT_TYPES.join(", ")}`);
+			if (options.mock && !options.mockSource) {
+				logError("--mock requires --mock-source <file>");
 				process.exit(1);
 			}
-			if (agentType === "mock" && !options.mockSource) {
-				logError("--agent=mock requires --mock-source <file>");
-				process.exit(1);
-			}
-			if (agentType === "live" && !options.model) {
-				logError("--agent=live requires --model <provider/model-id>");
+			if (!options.mock && !options.model) {
+				logError("Live agent requires --model <provider/model-id>");
 				console.log("");
 				console.log(formatSuggestedLlms());
 				process.exit(1);
@@ -1460,14 +1611,14 @@ function registerFillCommand(program) {
 			const harness = createHarness(form, harnessConfig);
 			let agent;
 			let mockPath;
-			if (agentType === "mock") {
+			if (options.mock) {
 				mockPath = resolve(options.mockSource);
 				logVerbose(ctx, `Reading mock source: ${mockPath}`);
 				agent = createMockAgent(parseForm(await readFile(mockPath)));
 			} else {
 				const modelId = options.model;
 				logVerbose(ctx, `Resolving model: ${modelId}`);
-				const { model } = await resolveModel(modelId);
+				const { model, provider } = await resolveModel(modelId);
 				let systemPrompt;
 				if (options.instructions) {
 					systemPrompt = options.instructions;
@@ -1478,15 +1629,18 @@ function registerFillCommand(program) {
 					systemPrompt = await readFile(promptPath);
 				}
 				const primaryRole = targetRoles[0] === "*" ? AGENT_ROLE : targetRoles[0];
-				agent = createLiveAgent({
+				const liveAgent = createLiveAgent({
 					model,
+					provider,
 					systemPromptAddition: systemPrompt,
 					targetRole: primaryRole
 				});
+				agent = liveAgent;
+				logInfo(ctx, `Available tools: ${liveAgent.getAvailableToolNames().join(", ")}`);
 				logVerbose(ctx, `Using live agent with model: ${modelId}`);
 			}
 			logInfo(ctx, pc.cyan(`Filling form: ${filePath}`));
-			logInfo(ctx, `Agent: ${agentType}${options.model ? ` (${options.model})` : ""}`);
+			logInfo(ctx, `Agent: ${options.mock ? "mock" : "live"}${options.model ? ` (${options.model})` : ""}`);
 			logVerbose(ctx, `Max turns: ${harnessConfig.maxTurns}`);
 			logVerbose(ctx, `Max patches per turn: ${harnessConfig.maxPatchesPerTurn}`);
 			logVerbose(ctx, `Max issues per step: ${harnessConfig.maxIssues}`);
@@ -1495,15 +1649,35 @@ function registerFillCommand(program) {
 			let stepResult = harness.step();
 			logInfo(ctx, `Turn ${pc.bold(String(stepResult.turnNumber))}: ${pc.yellow(String(stepResult.issues.length))} issues`);
 			while (!stepResult.isComplete && !harness.hasReachedMaxTurns()) {
-				const patches = await agent.generatePatches(stepResult.issues, harness.getForm(), harnessConfig.maxPatchesPerTurn);
-				logInfo(ctx, `  → ${pc.yellow(String(patches.length))} patches`);
+				const { patches, stats } = await agent.generatePatches(stepResult.issues, harness.getForm(), harnessConfig.maxPatchesPerTurn);
+				logInfo(ctx, `  → ${pc.yellow(String(patches.length))} patches:`);
 				for (const patch of patches) {
+					const typeName = formatPatchType(patch);
 					const value = formatPatchValue(patch);
-					logVerbose(ctx, `    ${pc.cyan(patch.fieldId)} ${pc.dim("=")} ${pc.green(value)}`);
+					logInfo(ctx, `    ${pc.cyan(patch.fieldId)} ${pc.dim(`(${typeName})`)} ${pc.dim("=")} ${pc.green(value)}`);
+				}
+				if (stats) {
+					logVerbose(ctx, `  Stats: ${stats.inputTokens ?? 0} in / ${stats.outputTokens ?? 0} out tokens`);
+					if (stats.toolCalls.length > 0) logVerbose(ctx, `  Tools: ${stats.toolCalls.map((t) => `${t.name}(${t.count})`).join(", ")}`);
+					if (stats.prompts) {
+						logVerbose(ctx, ``);
+						logVerbose(ctx, pc.dim(`  ─── System Prompt ───`));
+						for (const line of stats.prompts.system.split("\n")) logVerbose(ctx, pc.dim(`  ${line}`));
+						logVerbose(ctx, ``);
+						logVerbose(ctx, pc.dim(`  ─── Context Prompt ───`));
+						for (const line of stats.prompts.context.split("\n")) logVerbose(ctx, pc.dim(`  ${line}`));
+						logVerbose(ctx, ``);
+					}
 				}
-				stepResult = harness.apply(patches, stepResult.issues);
+				let llmStats;
+				if (stats) llmStats = {
+					inputTokens: stats.inputTokens,
+					outputTokens: stats.outputTokens,
+					toolCalls: stats.toolCalls.length > 0 ? stats.toolCalls : void 0
+				};
+				stepResult = harness.apply(patches, stepResult.issues, llmStats);
 				if (stepResult.isComplete) logInfo(ctx, pc.green(`  ✓ Complete`));
-				else {
+				else if (!harness.hasReachedMaxTurns()) {
 					stepResult = harness.step();
 					logInfo(ctx, `Turn ${pc.bold(String(stepResult.turnNumber))}: ${pc.yellow(String(stepResult.issues.length))} issues`);
 				}
@@ -1519,7 +1693,7 @@ function registerFillCommand(program) {
 				await writeFile(outputPath, formMarkdown);
 				logSuccess(ctx, `Form written to: ${outputPath}`);
 			}
-			const transcript = buildSessionTranscript(filePath, agentType, mockPath, options.model, harnessConfig, harness.getTurns(), stepResult.isComplete, outputPath);
+			const transcript = buildSessionTranscript(filePath, options.mock ? "mock" : "live", mockPath, options.model, harnessConfig, harness.getTurns(), stepResult.isComplete, outputPath);
 			if (options.record) {
 				const recordPath = resolve(options.record);
 				const yaml = serializeSession(transcript);
@@ -1544,20 +1718,20 @@ function registerFillCommand(program) {
 /**
 * Build a session transcript from harness execution.
 */
-function buildSessionTranscript(formPath, agentType, mockPath, modelId, harnessConfig, turns, expectComplete, outputPath) {
+function buildSessionTranscript(formPath, mockMode, mockPath, modelId, harnessConfig, turns, expectComplete, outputPath) {
 	const transcript = {
 		sessionVersion: "0.1.0",
-		mode: agentType,
+		mode: mockMode,
 		form: { path: formPath },
 		harness: harnessConfig,
 		turns,
 		final: {
 			expectComplete,
-			expectedCompletedForm: agentType === "mock" ? mockPath ?? outputPath : outputPath
+			expectedCompletedForm: mockMode === "mock" ? mockPath ?? outputPath : outputPath
 		}
 	};
-	if (agentType === "mock" && mockPath) transcript.mock = { completedMock: mockPath };
-	else if (agentType === "live" && modelId) transcript.live = { modelId };
+	if (mockMode === "mock" && mockPath) transcript.mock = { completedMock: mockPath };
+	else if (mockMode === "live" && modelId) transcript.live = { modelId };
 	return transcript;
 }
 
@@ -1649,7 +1823,8 @@ function formatConsoleReport$1(report, useColors) {
 	lines.push(bold("Progress:"));
 	lines.push(`  Total fields: ${progress.counts.totalFields}`);
 	lines.push(`  Required: ${progress.counts.requiredFields}`);
-	lines.push(`  Submitted: ${progress.counts.submittedFields}`);
+	lines.push(`  Answered: ${progress.counts.answeredFields}`);
+	lines.push(`  Skipped: ${progress.counts.skippedFields}`);
 	lines.push(`  Complete: ${progress.counts.completeFields}`);
 	lines.push(`  Incomplete: ${progress.counts.incompleteFields}`);
 	lines.push(`  Invalid: ${progress.counts.invalidFields}`);
@@ -1736,6 +1911,100 @@ function registerInspectCommand(program) {
 	});
 }
 
+//#endregion
+//#region src/cli/commands/instructions.ts
+/**
+* Get the path to the README.md file.
+* Works both during development and when installed as a package.
+*/
+function getReadmePath() {
+	const thisDir = dirname(fileURLToPath(import.meta.url));
+	if (thisDir.split(/[/\\]/).pop() === "dist") return join(dirname(thisDir), "README.md");
+	return join(dirname(dirname(dirname(thisDir))), "README.md");
+}
+/**
+* Load the README content.
+*/
+function loadReadme() {
+	const readmePath = getReadmePath();
+	try {
+		return readFileSync(readmePath, "utf-8");
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		throw new Error(`Failed to load README from ${readmePath}: ${message}`);
+	}
+}
+/**
+* Apply basic terminal formatting to markdown content.
+* Colorizes headers, code blocks, and other elements for better readability.
+*/
+function formatMarkdown(content, useColors) {
+	if (!useColors) return content;
+	const lines = content.split("\n");
+	const formatted = [];
+	let inCodeBlock = false;
+	for (const line of lines) {
+		if (line.startsWith("```")) {
+			inCodeBlock = !inCodeBlock;
+			formatted.push(pc.dim(line));
+			continue;
+		}
+		if (inCodeBlock) {
+			formatted.push(pc.dim(line));
+			continue;
+		}
+		if (line.startsWith("# ")) {
+			formatted.push(pc.bold(pc.cyan(line)));
+			continue;
+		}
+		if (line.startsWith("## ")) {
+			formatted.push(pc.bold(pc.blue(line)));
+			continue;
+		}
+		if (line.startsWith("### ")) {
+			formatted.push(pc.bold(line));
+			continue;
+		}
+		let formattedLine = line.replace(/`([^`]+)`/g, (_match, code) => {
+			return pc.yellow(code);
+		});
+		formattedLine = formattedLine.replace(/\*\*([^*]+)\*\*/g, (_match, text) => {
+			return pc.bold(text);
+		});
+		formattedLine = formattedLine.replace(/\[([^\]]+)\]\(([^)]+)\)/g, (_match, text, url) => {
+			return `${pc.cyan(text)} ${pc.dim(`(${url})`)}`;
+		});
+		formatted.push(formattedLine);
+	}
+	return formatted.join("\n");
+}
+/**
+* Check if stdout is an interactive terminal.
+*/
+function isInteractive() {
+	return process.stdout.isTTY === true;
+}
+/**
+* Display content. In a future enhancement, could pipe to a pager for long output.
+*/
+function displayContent(content) {
+	console.log(content);
+}
+/**
+* Register the instructions command.
+*/
+function registerInstructionsCommand(program) {
+	program.command("instructions").alias("readme").alias("docs").description("Display usage instructions and documentation").option("--raw", "Output raw markdown without formatting").action((options, cmd) => {
+		const ctx = getCommandContext(cmd);
+		try {
+			displayContent(formatMarkdown(loadReadme(), !options.raw && isInteractive() && !ctx.quiet));
+		} catch (error) {
+			logError(error instanceof Error ? error.message : String(error));
+			process.exit(1);
+		}
+	});
+}
+
 //#endregion
 //#region src/cli/commands/models.ts
 /**
@@ -1881,6 +2150,13 @@ function formDataToPatches(formData, form) {
 	const fields = form.schema.groups.flatMap((g) => g.children);
 	for (const field of fields) {
 		const fieldId = field.id;
+		if (formData[`__skip__${fieldId}`] === "1" && !field.required) {
+			patches.push({
+				op: "skip_field",
+				fieldId
+			});
+			continue;
+		}
 		switch (field.kind) {
 			case "string": {
 				const value = formData[fieldId];
@@ -1980,6 +2256,38 @@ function formDataToPatches(formData, form) {
 					});
 				}
 				break;
+			case "url": {
+				const value = formData[fieldId];
+				if (typeof value === "string" && value.trim() !== "") patches.push({
+					op: "set_url",
+					fieldId,
+					value: value.trim()
+				});
+				else patches.push({
+					op: "clear_field",
+					fieldId
+				});
+				break;
+			}
+			case "url_list": {
+				const value = formData[fieldId];
+				if (typeof value === "string" && value.trim() !== "") {
+					const items = value.split("\n").map((s) => s.trim()).filter((s) => s !== "");
+					if (items.length > 0) patches.push({
+						op: "set_url_list",
+						fieldId,
+						items
+					});
+					else patches.push({
+						op: "clear_field",
+						fieldId
+					});
+				} else patches.push({
+					op: "clear_field",
+					fieldId
+				});
+				break;
+			}
 		}
 	}
 	return patches;
@@ -2026,9 +2334,9 @@ async function handleSave(req, res, form, filePath, ctx, updateForm) {
 * @public Exported for testing.
 */
 function renderFormHtml(form) {
-	const { schema, valuesByFieldId } = form;
+	const { schema, valuesByFieldId, skipsByFieldId } = form;
 	const formTitle = schema.title ?? schema.id;
-	const groupsHtml = schema.groups.map((group) => renderGroup(group, valuesByFieldId)).join("\n");
+	const groupsHtml = schema.groups.map((group) => renderGroup(group, valuesByFieldId, skipsByFieldId ?? {})).join("\n");
 	return `<!DOCTYPE html>
 <html lang="en">
 <head>
@@ -2047,7 +2355,7 @@ function renderFormHtml(form) {
       color: #212529;
     }
     h1 { color: #495057; border-bottom: 2px solid #dee2e6; padding-bottom: 0.5rem; }
-    h2 { color: #6c757d; margin-top: 2rem; font-size: 1.25rem; }
+    h2 { color: #6c757d; font-size: 1.25rem; }
     .group {
       background: white;
       border-radius: 8px;
@@ -2159,6 +2467,40 @@ function renderFormHtml(form) {
       color: #6c757d;
       margin-top: 0.25rem;
     }
+    .field-actions {
+      display: flex;
+      gap: 0.5rem;
+      margin-top: 0.5rem;
+    }
+    .btn-skip {
+      padding: 0.25rem 0.75rem;
+      font-size: 0.85rem;
+      background: #f8f9fa;
+      border: 1px solid #ced4da;
+      border-radius: 4px;
+      color: #6c757d;
+      cursor: pointer;
+    }
+    .btn-skip:hover {
+      background: #e9ecef;
+      color: #495057;
+    }
+    .field-skipped {
+      opacity: 0.6;
+    }
+    .field-skipped input,
+    .field-skipped textarea,
+    .field-skipped select {
+      background: #f8f9fa;
+    }
+    .skipped-badge {
+      font-size: 0.75rem;
+      padding: 0.15rem 0.4rem;
+      background: #6c757d;
+      color: white;
+      border-radius: 3px;
+      margin-left: 0.5rem;
+    }
   </style>
 </head>
 <body>
@@ -2170,10 +2512,50 @@ function renderFormHtml(form) {
     </div>
   </form>
   <script>
+    // Track fields marked for skip
+    const skippedFields = new Set();
+
+    // Handle skip button clicks
+    document.querySelectorAll('.btn-skip').forEach(btn => {
+      btn.addEventListener('click', (e) => {
+        const fieldId = e.target.dataset.skipField;
+        if (!fieldId) return;
+
+        // Toggle skip state
+        if (skippedFields.has(fieldId)) {
+          skippedFields.delete(fieldId);
+          e.target.textContent = 'Skip';
+          e.target.classList.remove('btn-skip-active');
+          // Re-enable the field input
+          const fieldDiv = e.target.closest('.field');
+          fieldDiv.classList.remove('field-skipped');
+          fieldDiv.querySelectorAll('input, select, textarea').forEach(input => {
+            input.disabled = false;
+          });
+        } else {
+          skippedFields.add(fieldId);
+          e.target.textContent = 'Unskip';
+          e.target.classList.add('btn-skip-active');
+          // Disable the field input to show it's skipped
+          const fieldDiv = e.target.closest('.field');
+          fieldDiv.classList.add('field-skipped');
+          fieldDiv.querySelectorAll('input, select, textarea').forEach(input => {
+            input.disabled = true;
+          });
+        }
+      });
+    });
+
     document.getElementById('markform').addEventListener('submit', async (e) => {
       e.preventDefault();
       const formData = new FormData(e.target);
       const params = new URLSearchParams();
+
+      // Add skip markers for skipped fields
+      for (const fieldId of skippedFields) {
+        params.append('__skip__' + fieldId, '1');
+      }
+
       for (const [key, value] of formData) {
         params.append(key, value);
       }
@@ -2201,9 +2583,9 @@ function renderFormHtml(form) {
 /**
 * Render a field group as HTML.
 */
-function renderGroup(group, values) {
+function renderGroup(group, values, skips) {
 	const groupTitle = group.title ?? group.id;
-	const fieldsHtml = group.children.map((field) => renderFieldHtml(field, values[field.id])).join("\n");
+	const fieldsHtml = group.children.map((field) => renderFieldHtml(field, values[field.id], skips[field.id])).join("\n");
 	return `
   <div class="group">
     <h2>${escapeHtml(groupTitle)}</h2>
@@ -2214,79 +2596,109 @@ function renderGroup(group, values) {
 * Render a field as HTML.
 * @public Exported for testing.
 */
-function renderFieldHtml(field, value) {
+function renderFieldHtml(field, value, skipInfo) {
+	const isSkipped = skipInfo?.skipped === true;
 	const requiredMark = field.required ? "<span class=\"required\">*</span>" : "";
 	const typeLabel = `<span class="type-badge">${field.kind}</span>`;
+	const skippedBadge = isSkipped ? "<span class=\"skipped-badge\">Skipped</span>" : "";
+	const fieldClass = isSkipped ? "field field-skipped" : "field";
+	const disabledAttr = isSkipped ? " disabled" : "";
 	let inputHtml;
 	switch (field.kind) {
 		case "string":
-			inputHtml = renderStringInput(field, value);
+			inputHtml = renderStringInput(field, value, disabledAttr);
 			break;
 		case "number":
-			inputHtml = renderNumberInput(field, value);
+			inputHtml = renderNumberInput(field, value, disabledAttr);
 			break;
 		case "string_list":
-			inputHtml = renderStringListInput(field, value);
+			inputHtml = renderStringListInput(field, value, disabledAttr);
 			break;
 		case "single_select":
-			inputHtml = renderSingleSelectInput(field, value);
+			inputHtml = renderSingleSelectInput(field, value, disabledAttr);
 			break;
 		case "multi_select":
-			inputHtml = renderMultiSelectInput(field, value);
+			inputHtml = renderMultiSelectInput(field, value, disabledAttr);
 			break;
 		case "checkboxes":
-			inputHtml = renderCheckboxesInput(field, value);
+			inputHtml = renderCheckboxesInput(field, value, disabledAttr);
+			break;
+		case "url":
+			inputHtml = renderUrlInput(field, value, disabledAttr);
+			break;
+		case "url_list":
+			inputHtml = renderUrlListInput(field, value, disabledAttr);
 			break;
 		default: inputHtml = "<div class=\"field-help\">(unknown field type)</div>";
 	}
+	const skipButton = !field.required && !isSkipped ? `<div class="field-actions">
+        <button type="button" class="btn-skip" data-skip-field="${field.id}">Skip</button>
+      </div>` : "";
 	return `
-    <div class="field">
+    <div class="${fieldClass}">
       <label class="field-label" for="field-${field.id}">
-        ${escapeHtml(field.label)} ${requiredMark} ${typeLabel}
+        ${escapeHtml(field.label)} ${requiredMark} ${typeLabel} ${skippedBadge}
       </label>
       ${inputHtml}
+      ${skipButton}
     </div>`;
 }
 /**
 * Render a string field as text input.
 */
-function renderStringInput(field, value) {
+function renderStringInput(field, value, disabledAttr) {
 	const currentValue = value?.kind === "string" && value.value !== null ? value.value : "";
 	const requiredAttr = field.required ? " required" : "";
 	const minLengthAttr = field.minLength !== void 0 ? ` minlength="${field.minLength}"` : "";
 	const maxLengthAttr = field.maxLength !== void 0 ? ` maxlength="${field.maxLength}"` : "";
-	return `<input type="text" id="field-${field.id}" name="${field.id}" value="${escapeHtml(currentValue)}"${requiredAttr}${minLengthAttr}${maxLengthAttr}>`;
+	return `<input type="text" id="field-${field.id}" name="${field.id}" value="${escapeHtml(currentValue)}"${requiredAttr}${minLengthAttr}${maxLengthAttr}${disabledAttr}>`;
 }
 /**
 * Render a number field as number input.
 */
-function renderNumberInput(field, value) {
+function renderNumberInput(field, value, disabledAttr) {
 	const currentValue = value?.kind === "number" && value.value !== null ? String(value.value) : "";
 	const requiredAttr = field.required ? " required" : "";
 	const minAttr = field.min !== void 0 ? ` min="${field.min}"` : "";
 	const maxAttr = field.max !== void 0 ? ` max="${field.max}"` : "";
 	const stepAttr = field.integer ? " step=\"1\"" : "";
-	return `<input type="number" id="field-${field.id}" name="${field.id}" value="${escapeHtml(currentValue)}"${requiredAttr}${minAttr}${maxAttr}${stepAttr}>`;
+	return `<input type="number" id="field-${field.id}" name="${field.id}" value="${escapeHtml(currentValue)}"${requiredAttr}${minAttr}${maxAttr}${stepAttr}${disabledAttr}>`;
 }
 /**
 * Render a string list field as textarea.
 */
-function renderStringListInput(field, value) {
+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}>${escapeHtml(currentValue)}</textarea>`;
+	return `<textarea id="field-${field.id}" name="${field.id}" placeholder="Enter one item per line"${requiredAttr}${disabledAttr}>${escapeHtml(currentValue)}</textarea>`;
+}
+/**
+* Render a URL field as url input.
+*/
+function renderUrlInput(field, value, disabledAttr) {
+	const currentValue = value?.kind === "url" && value.value !== null ? value.value : "";
+	const requiredAttr = field.required ? " required" : "";
+	return `<input type="url" id="field-${field.id}" name="${field.id}" value="${escapeHtml(currentValue)}" placeholder="https://example.com"${requiredAttr}${disabledAttr}>`;
+}
+/**
+* Render a URL list field as textarea.
+*/
+function renderUrlListInput(field, value, disabledAttr) {
+	const currentValue = (value?.kind === "url_list" ? value.items : []).join("\n");
+	const requiredAttr = field.required ? " required" : "";
+	return `<textarea id="field-${field.id}" name="${field.id}" placeholder="Enter one URL per line"${requiredAttr}${disabledAttr}>${escapeHtml(currentValue)}</textarea>`;
 }
 /**
 * Render a single-select field as select element.
 */
-function renderSingleSelectInput(field, value) {
+function renderSingleSelectInput(field, value, disabledAttr) {
 	const selected = value?.selected ?? null;
 	const requiredAttr = field.required ? " required" : "";
 	const options = field.options.map((opt) => {
 		const selectedAttr = selected === opt.id ? " selected" : "";
 		return `<option value="${escapeHtml(opt.id)}"${selectedAttr}>${escapeHtml(opt.label)}</option>`;
 	}).join("\n      ");
-	return `<select id="field-${field.id}" name="${field.id}"${requiredAttr}>
+	return `<select id="field-${field.id}" name="${field.id}"${requiredAttr}${disabledAttr}>
       <option value="">-- Select --</option>
       ${options}
     </select>`;
@@ -2294,14 +2706,14 @@ function renderSingleSelectInput(field, value) {
 /**
 * Render a multi-select field as checkboxes.
 */
-function renderMultiSelectInput(field, value) {
+function renderMultiSelectInput(field, value, disabledAttr) {
 	const selected = value?.selected ?? [];
 	return `<div class="checkbox-group">
       ${field.options.map((opt) => {
 		const checkedAttr = selected.includes(opt.id) ? " checked" : "";
 		const checkboxId = `field-${field.id}-${opt.id}`;
 		return `<div class="checkbox-item">
-        <input type="checkbox" id="${checkboxId}" name="${field.id}" value="${escapeHtml(opt.id)}"${checkedAttr}>
+        <input type="checkbox" id="${checkboxId}" name="${field.id}" value="${escapeHtml(opt.id)}"${checkedAttr}${disabledAttr}>
         <label for="${checkboxId}">${escapeHtml(opt.label)}</label>
       </div>`;
 	}).join("\n      ")}
@@ -2310,7 +2722,7 @@ function renderMultiSelectInput(field, value) {
 /**
 * Render checkboxes field based on mode.
 */
-function renderCheckboxesInput(field, value) {
+function renderCheckboxesInput(field, value, disabledAttr) {
 	const checkboxValues = value?.values ?? {};
 	const mode = field.checkboxMode ?? "multi";
 	if (mode === "simple") return `<div class="checkbox-group">
@@ -2318,7 +2730,7 @@ function renderCheckboxesInput(field, value) {
 		const checkedAttr = checkboxValues[opt.id] === "done" ? " checked" : "";
 		const checkboxId = `field-${field.id}-${opt.id}`;
 		return `<div class="checkbox-item">
-        <input type="checkbox" id="${checkboxId}" name="${field.id}" value="${escapeHtml(opt.id)}"${checkedAttr}>
+        <input type="checkbox" id="${checkboxId}" name="${field.id}" value="${escapeHtml(opt.id)}"${checkedAttr}${disabledAttr}>
         <label for="${checkboxId}">${escapeHtml(opt.label)}</label>
       </div>`;
 	}).join("\n      ")}
@@ -2330,7 +2742,7 @@ function renderCheckboxesInput(field, value) {
 		const selectName = `${field.id}.${opt.id}`;
 		return `<div class="option-row">
         <span class="option-label">${escapeHtml(opt.label)}</span>
-        <select id="${selectId}" name="${selectName}">
+        <select id="${selectId}" name="${selectName}"${disabledAttr}>
           <option value="unfilled"${state === "unfilled" ? " selected" : ""}>-- Select --</option>
           <option value="yes"${state === "yes" ? " selected" : ""}>Yes</option>
           <option value="no"${state === "no" ? " selected" : ""}>No</option>
@@ -2345,7 +2757,7 @@ function renderCheckboxesInput(field, value) {
 		const selectName = `${field.id}.${opt.id}`;
 		return `<div class="option-row">
         <span class="option-label">${escapeHtml(opt.label)}</span>
-        <select id="${selectId}" name="${selectName}">
+        <select id="${selectId}" name="${selectName}"${disabledAttr}>
           <option value="todo"${state === "todo" ? " selected" : ""}>To Do</option>
           <option value="active"${state === "active" ? " selected" : ""}>Active</option>
           <option value="done"${state === "done" ? " selected" : ""}>Done</option>
@@ -2551,6 +2963,7 @@ function createProgram() {
 	registerFillCommand(program);
 	registerModelsCommand(program);
 	registerExamplesCommand(program);
+	registerInstructionsCommand(program);
 	return program;
 }
 /**
@@ -2561,5 +2974,4 @@ async function runCli() {
 }
 
 //#endregion
-export { runCli as t };
-//# sourceMappingURL=cli-9fvFySww.mjs.map
+export { runCli as t };