markform 0.1.23 → 0.1.25

package/dist/{cli-ZcOC47KK.mjs → cli-B1T8kMFt.mjs}

@@ -1,19 +1,19 @@
 
-import { R as PatchSchema } from "./coreTypes-CTLr-NGd.mjs";
-import { $ as WEB_SEARCH_CONFIG, A as DEFAULT_FORMS_DIR, F as DEFAULT_MAX_TURNS, G as deriveExportPath, H as MAX_FORMS_IN_MENU, I as DEFAULT_PORT, J as deriveSchemaPath, K as deriveFillRecordPath, N as DEFAULT_MAX_PATCHES_PER_TURN, Q as SUGGESTED_LLMS, R as DEFAULT_RESEARCH_MAX_ISSUES_PER_TURN, U as REPORT_EXTENSION, W as USER_ROLE, X as parseRolesFlag, Y as detectFileType, c as computeProgressSummary, d as serializeForm, et as formatSuggestedLlms, f as serializeRawMarkdown, g as validateSyntaxConsistency, i as inspect, j as DEFAULT_MAX_ISSUES_PER_TURN, k as AGENT_ROLE, l as computeStructureSummary, n as getAllFields, nt as hasWebSearchSupport, p as serializeReport, q as deriveReportPath, rt as parseModelIdForDisplay, t as applyPatches, z as DEFAULT_RESEARCH_MAX_PATCHES_PER_TURN } from "./apply-KzQztrDV.mjs";
-import { A as createMockAgent, C as getProviderNames, D as FillRecordCollector, E as createLiveAgent, M as createHarness, O as computeExecutionPlan, S as getProviderInfo, T as buildMockWireFormat, U as formToJsonSchema, W as parseForm, _ as fillForm, g as resolveHarnessConfig, h as formatFillRecordSummary, i as runResearch, m as stripUnstableFillRecordFields, n as isResearchForm, t as VERSION, w as resolveModel } from "./src-B2uFvGli.mjs";
-import { n as serializeSession } from "./session-BCcltrLA.mjs";
-import { _ as writeFile, a as formatPath, c as logError, d as logTiming, f as logVerbose, g as stripHtmlComments, h as shouldUseColors, 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-CsdT2T7k.mjs";
-import { a as renderJsonContent, c as renderViewContent, i as highlightYamlValue, l as renderYamlContent, o as renderMarkdownContent, r as renderFillRecordContent, s as renderSourceContent, u as escapeHtml } from "./fillRecordRenderer-VBQ2vwPV.mjs";
+import { R as PatchSchema } from "./coreTypes-DIv9Aabl.mjs";
+import { $ as DEFAULT_RESEARCH_MAX_PATCHES_PER_TURN, E as serializeReport, H as AGENT_ROLE, K as DEFAULT_MAX_PATCHES_PER_TURN, Q as DEFAULT_RESEARCH_MAX_ISSUES_PER_TURN, S as computeStructureSummary, T as serializeRawMarkdown, U as DEFAULT_FORMS_DIR, W as DEFAULT_MAX_ISSUES_PER_TURN, X as DEFAULT_PORT, Y as DEFAULT_MAX_TURNS, _ as inspect, _t as parseModelIdForDisplay, at as deriveExportPath, c as filterIssuesByOrder, ct as deriveSchemaPath, d as coerceInputContext, f as coerceToFieldPatch, ft as SUGGESTED_LLMS, gt as hasWebSearchSupport, h as getAllFields, it as USER_ROLE, k as validateSyntaxConsistency, l as filterIssuesByScope, lt as detectFileType, m as applyPatches, mt as formatSuggestedLlms, nt as MAX_FORMS_IN_MENU, ot as deriveFillRecordPath, p as findFieldById, pt as WEB_SEARCH_CONFIG, rt as REPORT_EXTENSION, st as deriveReportPath, u as getFieldIdFromRef, ut as parseRolesFlag, w as serializeForm, x as computeProgressSummary } from "./prompts-DaPKumGY.mjs";
+import { C as getProviderInfo, D as createLiveAgent, E as buildMockWireFormat, H as parseForm, N as createHarness, O as FillRecordCollector, T as resolveModel, V as formToJsonSchema, _ as resolveHarnessConfig, g as formatFillRecordSummary, h as stripUnstableFillRecordFields, i as runResearch, j as createMockAgent, k as computeExecutionPlan, m as isEmptyFillRecord, n as isResearchForm, t as VERSION, v as fillForm, w as getProviderNames } from "./src-DrXmaOWl.mjs";
+import { n as serializeSession } from "./session-BW9jtYNV.mjs";
+import { _ as writeFile$1, a as formatPath, c as logError, d as logTiming, f as logVerbose, g as stripHtmlComments, h as shouldUseColors, 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-BszoSkAO.mjs";
+import { a as renderJsonContent, c as renderViewContent, i as highlightYamlValue, l as renderYamlContent, o as renderMarkdownContent, r as renderFillRecordContent, s as renderSourceContent, u as escapeHtml } from "./fillRecordRenderer-BqRPHPmE.mjs";
 import Markdoc from "@markdoc/markdoc";
 import YAML from "yaml";
 import { Command } from "commander";
 import pc from "picocolors";
 import { exec, execSync, spawn } from "node:child_process";
 import { basename, dirname, join, resolve } from "node:path";
-import { existsSync, readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
 import { fileURLToPath } from "node:url";
-import { readFile } from "node:fs/promises";
+import { existsSync, readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
 import * as p from "@clack/prompts";
 import { createServer } from "node:http";
 
@@ -72,6 +72,21 @@ const CLI_VERSION = VERSION === "development" ? getGitVersion() : VERSION;
 * library to remain Node.js-free.
 */
 /**
+* Resolve a path relative to the package root, handling both dev and dist modes.
+*
+* In dist mode, commands run from `<pkg>/dist/` (1 level below root).
+* In dev mode, commands run from `<pkg>/src/cli/commands/` or `<pkg>/src/cli/examples/`
+* (3 levels below root).
+*
+* @param callerMetaUrl - The `import.meta.url` of the calling module
+* @param relativePath - Path relative to the package root (e.g. 'docs/markform-reference.md')
+*/
+function resolvePackagePath(callerMetaUrl, relativePath) {
+	const thisDir = dirname(fileURLToPath(callerMetaUrl));
+	if (thisDir.split(/[/\\]/).pop() === "dist") return join(dirname(thisDir), relativePath);
+	return join(dirname(dirname(dirname(thisDir))), relativePath);
+}
+/**
 * Resolve the forms directory path to an absolute path.
 * Uses the provided override or falls back to DEFAULT_FORMS_DIR.
 *
@@ -86,19 +101,10 @@ function getFormsDir(override, cwd = process.cwd()) {
 //#endregion
 //#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();
+	const apisPath = resolvePackagePath(import.meta.url, "docs/markform-apis.md");
 	try {
 		return readFileSync(apisPath, "utf-8");
 	} catch (error) {
@@ -178,7 +184,7 @@ function registerApisCommand(program) {
 }
 
 //#endregion
-//#region src/cli/commands/apply.ts
+//#region src/cli/commands/patch.ts
 /**
 * Format state badge for console output.
 */
@@ -192,16 +198,16 @@ function formatState$2(state, useColors) {
 	return useColors ? colorFn(text) : text;
 }
 /**
-* Format apply report for console output.
+* Format patch report for console output.
 */
-function formatConsoleReport$3(report, useColors) {
+function formatConsoleReport$5(report, useColors) {
 	const lines = [];
 	const bold = useColors ? pc.bold : (s) => s;
 	const dim = useColors ? pc.dim : (s) => s;
 	const cyan = useColors ? pc.cyan : (s) => s;
 	const green = useColors ? pc.green : (s) => s;
 	const red = useColors ? pc.red : (s) => s;
-	lines.push(bold(cyan("Apply Result")));
+	lines.push(bold(cyan("Patch Result")));
 	lines.push("");
 	const statusColor = report.apply_status === "applied" ? green : red;
 	lines.push(`${bold("Status:")} ${statusColor(report.apply_status)}`);
@@ -225,16 +231,12 @@ function formatConsoleReport$3(report, useColors) {
 	return lines.join("\n");
 }
 /**
-* Register the apply command.
+* Register the patch command.
 */
-function registerApplyCommand(program) {
-	program.command("apply <file>").description("Apply patches to a form").option("--patch <json>", "JSON array of patches to apply").option("-o, --output <file>", "Output file (defaults to stdout)").option("--report", "Output apply result report instead of modified form").option("--normalize", "Regenerate form without preserving external content").action(async (file, options, cmd) => {
+function registerPatchCommand(program) {
+	program.command("patch <file> <json>").description("Apply raw typed patches to a form").option("-o, --output <file>", "Output file (defaults to stdout)").option("--report", "Output patch result report instead of modified form").option("--normalize", "Regenerate form without preserving external content").action(async (file, json, options, cmd) => {
 		const ctx = getCommandContext(cmd);
 		try {
-			if (!options.patch) {
-				logError("--patch option is required");
-				process.exit(1);
-			}
 			logVerbose(ctx, `Reading file: ${file}`);
 			const content = await readFile$1(file);
 			logVerbose(ctx, "Parsing form...");
@@ -242,13 +244,13 @@ function registerApplyCommand(program) {
 			logVerbose(ctx, "Parsing patches...");
 			let parsedJson;
 			try {
-				parsedJson = JSON.parse(options.patch);
+				parsedJson = JSON.parse(json);
 			} catch {
-				logError("Invalid JSON in --patch option");
+				logError("Invalid JSON in patch argument");
 				process.exit(1);
 			}
 			if (!Array.isArray(parsedJson)) {
-				logError("--patch must be a JSON array");
+				logError("Patch argument must be a JSON array");
 				process.exit(1);
 			}
 			const patches = parsedJson;
@@ -276,7 +278,7 @@ function registerApplyCommand(program) {
 					structure: result.structureSummary,
 					progress: result.progressSummary,
 					issues: result.issues
-				}, (data, useColors) => formatConsoleReport$3(data, useColors));
+				}, (data, useColors) => formatConsoleReport$5(data, useColors));
 				console.error(output);
 				process.exit(1);
 			}
@@ -288,15 +290,15 @@ function registerApplyCommand(program) {
 					structure: result.structureSummary,
 					progress: result.progressSummary,
 					issues: result.issues
-				}, (data, useColors) => formatConsoleReport$3(data, useColors));
+				}, (data, useColors) => formatConsoleReport$5(data, useColors));
 				if (options.output) {
-					await writeFile(options.output, output);
+					await writeFile$1(options.output, output);
 					logSuccess(ctx, `Report written to ${options.output}`);
 				} else console.log(output);
 			} else {
 				const output = serializeForm(form, { preserveContent: !options.normalize });
 				if (options.output) {
-					await writeFile(options.output, output);
+					await writeFile$1(options.output, output);
 					logSuccess(ctx, `Modified form written to ${options.output}`);
 				} else console.log(output);
 			}
@@ -670,19 +672,10 @@ function registerBrowseCommand(program) {
 //#endregion
 //#region src/cli/commands/docs.ts
 /**
-* 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", "markform-reference.md");
-	return join(dirname(dirname(dirname(thisDir))), "docs", "markform-reference.md");
-}
-/**
 * Load the docs content.
 */
 function loadDocs() {
-	const docsPath = getDocsPath();
+	const docsPath = resolvePackagePath(import.meta.url, "docs/markform-reference.md");
 	try {
 		return readFileSync(docsPath, "utf-8");
 	} catch (error) {
@@ -909,7 +902,7 @@ function deriveExportPaths(basePath) {
 async function exportMultiFormat(form, basePath) {
 	const paths = deriveExportPaths(basePath);
 	const reportContent = serializeReport(form);
-	await writeFile(paths.reportPath, reportContent);
+	await writeFile$1(paths.reportPath, reportContent);
 	const values = toStructuredValues(form);
 	const notes = toNotesArray(form);
 	const exportData = {
@@ -917,12 +910,12 @@ async function exportMultiFormat(form, basePath) {
 		...notes.length > 0 && { notes }
 	};
 	const yamlContent = YAML.stringify(exportData);
-	await writeFile(paths.yamlPath, yamlContent);
+	await writeFile$1(paths.yamlPath, yamlContent);
 	const formContent = serializeForm(form);
-	await writeFile(paths.formPath, formContent);
+	await writeFile$1(paths.formPath, formContent);
 	const schemaResult = formToJsonSchema(form);
 	const schemaContent = JSON.stringify(schemaResult.schema, null, 2) + "\n";
-	await writeFile(paths.schemaPath, schemaContent);
+	await writeFile$1(paths.schemaPath, schemaContent);
 	return paths;
 }
 
@@ -1033,6 +1026,12 @@ const EXAMPLE_DEFINITIONS = [
 		path: "simple/simple.form.md",
 		type: "fill"
 	},
+	{
+		id: "twitter-thread",
+		filename: "twitter-thread.form.md",
+		path: "twitter-thread/twitter-thread.form.md",
+		type: "fill"
+	},
 	{
 		id: "movie-deep-research",
 		filename: "movie-deep-research.form.md",
@@ -1061,9 +1060,7 @@ function getExampleOrder(filename) {
 * Works both during development and when installed as a package.
 */
 function getExamplesDir() {
-	const thisDir = dirname(fileURLToPath(import.meta.url));
-	if (thisDir.split(/[/\\]/).pop() === "dist") return join(dirname(thisDir), "examples");
-	return join(dirname(dirname(dirname(thisDir))), "examples");
+	return resolvePackagePath(import.meta.url, "examples");
 }
 /**
 * Load the content of an example form.
@@ -1967,6 +1964,12 @@ function formatPatchValue(patch) {
 			const rowCount = patch.value?.length ?? 0;
 			return rowCount > 0 ? truncate(`[${rowCount} rows]`) : "(empty)";
 		}
+		case "append_table": return truncate(`+[${patch.value?.length ?? 0} rows]`);
+		case "delete_table": return `(delete row ${patch.value})`;
+		case "append_string_list": return truncate(`+[${patch.value.join(", ")}]`);
+		case "delete_string_list": return `(delete item ${patch.value})`;
+		case "append_url_list": return truncate(`+[${patch.value.join(", ")}]`);
+		case "delete_url_list": return `(delete item ${patch.value})`;
 		case "add_note": return truncate(`note: ${patch.text}`);
 		case "remove_note": return `(remove note ${patch.noteId})`;
 	}
@@ -1990,6 +1993,12 @@ function formatPatchType(patch) {
 		case "set_date": return "date";
 		case "set_year": return "year";
 		case "set_table": return "table";
+		case "append_table": return "append_table";
+		case "delete_table": return "delete_table";
+		case "append_string_list": return "append_string_list";
+		case "delete_string_list": return "delete_string_list";
+		case "append_url_list": return "append_url_list";
+		case "delete_url_list": return "delete_url_list";
 		case "add_note": return "note";
 		case "remove_note": return "remove_note";
 	}
@@ -2433,18 +2442,38 @@ function registerRunCommand(program) {
 */
 /**
 * Print non-interactive list of examples.
+* Supports --format=json and --format=yaml via formatOutput().
 */
-function printExamplesList() {
-	console.log(pc.bold("Available examples:\n"));
+function printExamplesList(ctx) {
 	const examples = getAllExamplesWithMetadata();
-	for (const example of examples) {
-		const typeLabel = example.type === "research" ? pc.magenta("[research]") : pc.blue("[fill]");
-		console.log(`  ${pc.cyan(example.id)} ${typeLabel}`);
-		console.log(`    ${pc.bold(example.title ?? example.id)}`);
-		console.log(`    ${example.description ?? "No description"}`);
-		console.log(`    Source: ${formatPath(getExamplePath(example.id))}`);
-		console.log("");
-	}
+	const output = formatOutput(ctx, examples.map((example) => ({
+		id: example.id,
+		filename: example.filename,
+		type: example.type,
+		title: example.title ?? example.id,
+		description: example.description ?? ""
+	})), (_data, useColors) => {
+		const c = useColors ? pc : {
+			bold: (s) => s,
+			cyan: (s) => s,
+			magenta: (s) => s,
+			blue: (s) => s,
+			dim: (s) => s
+		};
+		const lines = [c.bold("Available examples:"), ""];
+		for (const example of examples) {
+			const typeLabel = example.type === "research" ? c.magenta("[research]") : c.blue("[fill]");
+			lines.push(`  ${c.cyan(example.id)} ${typeLabel}`);
+			lines.push(`    ${c.bold(example.title ?? example.id)}`);
+			lines.push(`    ${example.description ?? "No description"}`);
+			lines.push(`    Source: ${formatPath(getExamplePath(example.id))}`);
+			lines.push("");
+		}
+		lines.push(c.dim("Tip: For a comprehensive end-to-end walkthrough, ask your coding agent"));
+		lines.push(c.dim("to run the Markform QA playbook (tests/qa/markform-full-walkthrough.qa.md)."));
+		return lines.join("\n");
+	});
+	console.log(output);
 }
 /**
 * Copy an example form to the forms directory.
@@ -2462,7 +2491,7 @@ async function copyExample(exampleId, formsDir, overwrite, _quiet) {
 			path: outputPath
 		};
 	}
-	await writeFile(outputPath, loadExampleContent(exampleId));
+	await writeFile$1(outputPath, loadExampleContent(exampleId));
 	return {
 		copied: true,
 		skipped: false,
@@ -2585,7 +2614,7 @@ function registerExamplesCommand(program) {
 		const ctx = getCommandContext(cmd);
 		try {
 			if (options.list) {
-				printExamplesList();
+				printExamplesList(ctx);
 				return;
 			}
 			const formsDir = getFormsDir(ctx.formsDir);
@@ -2920,7 +2949,7 @@ function registerFillCommand(program) {
 				logTiming(ctx, "Fill time", durationMs);
 				if (ctx.dryRun) logInfo(ctx, `[DRY RUN] Would write form to: ${outputPath}`);
 				else {
-					await writeFile(outputPath, result.markdown);
+					await writeFile$1(outputPath, result.markdown);
 					logSuccess(ctx, `Form written to: ${outputPath}`);
 				}
 				if (result.record && !ctx.quiet) {
@@ -2928,7 +2957,8 @@ function registerFillCommand(program) {
 					const summary = formatFillRecordSummary(result.record, { verbose: ctx.verbose });
 					console.error(summary);
 				}
-				if ((options.recordFill || options.recordFillStable) && result.record) {
+				if ((options.recordFill || options.recordFillStable) && result.record) if (isEmptyFillRecord(result.record)) logVerbose(ctx, "Skipping fill record: no turns were executed");
+				else {
 					const sidecarPath = deriveFillRecordPath(outputPath);
 					const recordToWrite = options.recordFillStable ? stripUnstableFillRecordFields(result.record) : result.record;
 					if (ctx.dryRun) logInfo(ctx, `[DRY RUN] Would write fill record to: ${sidecarPath}`);
@@ -3142,6 +3172,7 @@ function registerFillCommand(program) {
 					requiredIssuesRemaining: stepResult.issues.filter((i) => i.severity === "required").length,
 					isComplete: stepResult.isComplete,
 					rejectedPatches,
+					coercionWarnings: stepResult.coercionWarnings,
 					issues: stepResult.issues,
 					patches
 				});
@@ -3172,7 +3203,7 @@ function registerFillCommand(program) {
 			const formMarkdown = serializeForm(harness.getForm(), { preserveContent: !options.normalize });
 			if (ctx.dryRun) logInfo(ctx, `[DRY RUN] Would write form to: ${outputPath}`);
 			else {
-				await writeFile(outputPath, formMarkdown);
+				await writeFile$1(outputPath, formMarkdown);
 				logSuccess(ctx, `Form written to: ${outputPath}`);
 			}
 			const finalInspect = inspect(harness.getForm(), { targetRoles });
@@ -3184,7 +3215,8 @@ function registerFillCommand(program) {
 				const summary = formatFillRecordSummary(fillRecord, { verbose: ctx.verbose });
 				console.error(summary);
 			}
-			if (options.recordFill || options.recordFillStable) {
+			if (options.recordFill || options.recordFillStable) if (isEmptyFillRecord(fillRecord)) logVerbose(ctx, "Skipping fill record: no turns were executed");
+			else {
 				const sidecarPath = deriveFillRecordPath(outputPath);
 				const recordToWrite = options.recordFillStable ? stripUnstableFillRecordFields(fillRecord) : fillRecord;
 				if (ctx.dryRun) logInfo(ctx, `[DRY RUN] Would write fill record to: ${sidecarPath}`);
@@ -3201,7 +3233,7 @@ function registerFillCommand(program) {
 					logInfo(ctx, `[DRY RUN] Would write session to: ${recordPath}`);
 					console.log(yaml);
 				} else {
-					await writeFile(recordPath, yaml);
+					await writeFile$1(recordPath, yaml);
 					logSuccess(ctx, `Session recorded to: ${recordPath}`);
 				}
 			} else if (!ctx.quiet) {
@@ -3218,10 +3250,12 @@ function registerFillCommand(program) {
 				const progressSummary = computeProgressSummary(form.schema, currentForm.responsesByFieldId, currentForm.notes, finalInspect.issues);
 				collector.setStatus("failed", message);
 				const fillRecord = collector.getRecord(progressSummary.counts);
-				const sidecarPath = deriveFillRecordPath(resolve(options.output));
-				const recordToWrite = options.recordFillStable ? stripUnstableFillRecordFields(fillRecord) : fillRecord;
-				writeFileSync(sidecarPath, JSON.stringify(recordToWrite, null, 2));
-				logWarn(ctx, `Partial fill record written to: ${sidecarPath}`);
+				if (!isEmptyFillRecord(fillRecord)) {
+					const sidecarPath = deriveFillRecordPath(resolve(options.output));
+					const recordToWrite = options.recordFillStable ? stripUnstableFillRecordFields(fillRecord) : fillRecord;
+					writeFileSync(sidecarPath, JSON.stringify(recordToWrite, null, 2));
+					logWarn(ctx, `Partial fill record written to: ${sidecarPath}`);
+				}
 			} catch {}
 			process.exit(1);
 		}
@@ -3336,7 +3370,7 @@ function formatFieldValue(value, useColors) {
 /**
 * Format inspect report for console output.
 */
-function formatConsoleReport$2(report, useColors) {
+function formatConsoleReport$4(report, useColors) {
 	const lines = [];
 	const bold = useColors ? pc.bold : (s) => s;
 	const dim = useColors ? pc.dim : (s) => s;
@@ -3449,7 +3483,7 @@ function registerInspectCommand(program) {
 					severity: issue.severity,
 					blockedBy: issue.blockedBy
 				}))
-			}, (data, useColors) => formatConsoleReport$2(data, useColors));
+			}, (data, useColors) => formatConsoleReport$4(data, useColors));
 			console.log(output);
 		} catch (error) {
 			logError(error instanceof Error ? error.message : String(error));
@@ -3461,19 +3495,10 @@ function registerInspectCommand(program) {
 //#endregion
 //#region src/cli/commands/readme.ts
 /**
-* Get the path to the README.md file.
-* Works both during development and when installed as a package.
-*/
-function getReadmePath() {
-	const thisDir = dirname(fileURLToPath(import.meta.url));
-	if (thisDir.split(/[/\\]/).pop() === "dist") return join(dirname(thisDir), "README.md");
-	return join(dirname(dirname(dirname(thisDir))), "README.md");
-}
-/**
 * Load the README content.
 */
 function loadReadme() {
-	const readmePath = getReadmePath();
+	const readmePath = resolvePackagePath(import.meta.url, "README.md");
 	try {
 		return readFileSync(readmePath, "utf-8");
 	} catch (error) {
@@ -3570,7 +3595,7 @@ function registerReportCommand(program) {
 			if (options.output) {
 				let outputPath = options.output;
 				if (!outputPath.endsWith(REPORT_EXTENSION) && !outputPath.endsWith(".md")) outputPath = outputPath + REPORT_EXTENSION;
-				await writeFile(outputPath, reportContent);
+				await writeFile$1(outputPath, reportContent);
 				logVerbose(ctx, `Report written to: ${outputPath}`);
 			} else console.log(reportContent);
 		} catch (error) {
@@ -3583,19 +3608,10 @@ function registerReportCommand(program) {
 //#endregion
 //#region src/cli/commands/spec.ts
 /**
-* 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), "docs", "markform-spec.md");
-	return join(dirname(dirname(dirname(thisDir))), "docs", "markform-spec.md");
-}
-/**
 * Load the spec content.
 */
 function loadSpec() {
-	const specPath = getSpecPath();
+	const specPath = resolvePackagePath(import.meta.url, "docs/markform-spec.md");
 	try {
 		return readFileSync(specPath, "utf-8");
 	} catch (error) {
@@ -3727,6 +3743,201 @@ function registerModelsCommand(program) {
 	});
 }
 
+//#endregion
+//#region src/cli/commands/next.ts
+/**
+* Build field metadata for an issue's field.
+*/
+function buildFieldMeta(field) {
+	const meta = {
+		kind: field.kind,
+		label: field.label,
+		required: field.required
+	};
+	if (field.kind === "single_select" || field.kind === "multi_select") meta.options = field.options.map((o) => o.id);
+	else if (field.kind === "checkboxes") {
+		meta.options = field.options.map((o) => o.id);
+		meta.checkbox_mode = field.checkboxMode;
+	} else if (field.kind === "table") {
+		meta.columns = field.columns.map((c) => ({
+			id: c.id,
+			type: c.type,
+			required: c.required
+		}));
+		if (field.minRows !== void 0) meta.min_rows = field.minRows;
+		if (field.maxRows !== void 0) meta.max_rows = field.maxRows;
+	}
+	return meta;
+}
+/**
+* Generate a concrete `markform set` example for a field.
+*/
+function generateSetExample(file, field) {
+	const base = `markform set ${file} ${field.id}`;
+	switch (field.kind) {
+		case "string": return `${base} "example text"`;
+		case "number": return `${base} 42`;
+		case "string_list": return `${base} '["item1", "item2"]'`;
+		case "single_select": return field.options.length > 0 ? `${base} ${field.options[0].id}` : `${base} option_id`;
+		case "multi_select": return field.options.length > 0 ? `${base} '["${field.options.map((o) => o.id).join("\", \"")}"]'` : `${base} '["option1"]'`;
+		case "checkboxes":
+			if (field.checkboxMode === "simple") return `${base} '${JSON.stringify(Object.fromEntries(field.options.map((o) => [o.id, true])))}'`;
+			return `${base} '${JSON.stringify(Object.fromEntries(field.options.map((o) => [o.id, "done"])))}'`;
+		case "url": return `${base} "https://example.com"`;
+		case "url_list": return `${base} '["https://example.com"]'`;
+		case "date": return `${base} "2024-01-15"`;
+		case "year": return `${base} 2024`;
+		case "table":
+			if (field.columns.length > 0) {
+				const example = Object.fromEntries(field.columns.map((c) => [c.id, `example_${c.type}`]));
+				return `${base} --append '${JSON.stringify(example)}'`;
+			}
+			return `${base} --append '{}'`;
+	}
+}
+/**
+* Generate a skip example for optional fields, or null for required fields.
+*/
+function generateSkipExample(file, fieldId, required) {
+	if (required) return null;
+	return `markform set ${file} ${fieldId} --skip --reason "Not applicable"`;
+}
+/**
+* Convert a FieldValue to a serializable current_value for the report.
+*/
+function serializeCurrentValue(value) {
+	switch (value.kind) {
+		case "string":
+		case "url":
+		case "date": return value.value;
+		case "number":
+		case "year": return value.value;
+		case "string_list":
+		case "url_list": return value.items;
+		case "single_select": return value.selected;
+		case "multi_select": return value.selected;
+		case "checkboxes": return value.values;
+		case "table": return value.rows;
+	}
+}
+/**
+* Enrich an InspectIssue into a NextIssue with field metadata and examples.
+*/
+function enrichIssue(issue, form, file) {
+	const fieldId = getFieldIdFromRef(issue.ref, issue.scope);
+	const field = fieldId ? findFieldById(form, fieldId) : void 0;
+	const enriched = {
+		ref: issue.ref,
+		scope: issue.scope,
+		reason: issue.reason,
+		message: issue.message,
+		severity: issue.severity,
+		priority: issue.priority,
+		set_example: field ? generateSetExample(file, field) : `markform set ${file} ${issue.ref} "value"`,
+		skip_example: field ? generateSkipExample(file, field.id, field.required) : null
+	};
+	if (field) {
+		enriched.field = buildFieldMeta(field);
+		const response = form.responsesByFieldId[field.id];
+		if (response?.state === "answered" && response.value) enriched.current_value = serializeCurrentValue(response.value);
+	}
+	return enriched;
+}
+/**
+* Format next report for console output.
+*/
+function formatConsoleReport$3(report, useColors) {
+	const lines = [];
+	const bold = useColors ? pc.bold : (s) => s;
+	const dim = useColors ? pc.dim : (s) => s;
+	const cyan = useColors ? pc.cyan : (s) => s;
+	const green = useColors ? pc.green : (s) => s;
+	const yellow = useColors ? pc.yellow : (s) => s;
+	const red = useColors ? pc.red : (s) => s;
+	const stateColor = report.form_state === "complete" ? green : report.form_state === "invalid" ? red : yellow;
+	const progressStr = `${report.progress.filled_fields}/${report.progress.total_fields} fields filled, ${report.progress.empty_required_fields} required remaining`;
+	lines.push(`${bold("State:")} ${stateColor(report.form_state)} ${dim(`(${progressStr})`)}`);
+	if (report.is_complete) {
+		lines.push("");
+		lines.push(green(bold("Form is complete!")));
+		return lines.join("\n");
+	}
+	lines.push("");
+	lines.push(bold(`Next fields to fill (${report.issues.length} issues, budget: ${report.step_budget}):`));
+	lines.push("");
+	for (const issue of report.issues) {
+		const prioLabel = `P${issue.priority}`;
+		const prioColor = issue.priority <= 1 ? red : issue.priority <= 2 ? yellow : cyan;
+		const sevLabel = issue.severity === "required" ? "required" : "recommended";
+		const kindStr = issue.field ? ` ${dim(`(${issue.field.kind})`)}` : "";
+		let optionsStr = "";
+		if (issue.field?.options && issue.field.options.length > 0) optionsStr = ` ${dim(`[${issue.field.options.join(", ")}]`)}`;
+		lines.push(`  ${prioColor(prioLabel)} ${dim(`[${sevLabel}]`)} ${bold(issue.ref)}${kindStr}${optionsStr}`);
+		lines.push(`     ${issue.message}`);
+		lines.push(`     ${dim("->")} ${cyan(issue.set_example)}`);
+		if (issue.skip_example) lines.push(`     ${dim("->")} ${dim(issue.skip_example)}`);
+		lines.push("");
+	}
+	return lines.join("\n").trimEnd();
+}
+const DEFAULT_MAX_ISSUES = 10;
+/**
+* Register the next command.
+*/
+function registerNextCommand(program) {
+	program.command("next <file>").description("Show prioritized next fields to fill (field advisor for CLI form filling)").option("--roles <roles>", "Target roles (comma-separated, or '*' for all; default: all)").option("--max-fields <n>", "Max distinct fields per batch").option("--max-groups <n>", "Max distinct groups per batch").option("--max-issues <n>", `Max issues to return (default: ${DEFAULT_MAX_ISSUES})`).action(async (file, options, cmd) => {
+		const ctx = getCommandContext(cmd);
+		try {
+			let targetRoles;
+			if (options.roles) try {
+				targetRoles = parseRolesFlag(options.roles);
+				if (targetRoles.includes("*")) targetRoles = void 0;
+			} catch (error) {
+				logError(`Invalid --roles: ${error instanceof Error ? error.message : String(error)}`);
+				process.exit(1);
+			}
+			const maxFields = options.maxFields ? parseInt(options.maxFields, 10) : void 0;
+			const maxGroups = options.maxGroups ? parseInt(options.maxGroups, 10) : void 0;
+			const maxIssuesParsed = options.maxIssues ? parseInt(options.maxIssues, 10) : void 0;
+			if (maxFields !== void 0 && isNaN(maxFields) || maxGroups !== void 0 && isNaN(maxGroups) || maxIssuesParsed !== void 0 && isNaN(maxIssuesParsed)) {
+				logError("--max-fields, --max-groups, and --max-issues must be numeric");
+				process.exit(1);
+			}
+			logVerbose(ctx, `Reading file: ${file}`);
+			const content = await readFile$1(file);
+			logVerbose(ctx, "Parsing form...");
+			const form = parseForm(content);
+			const harnessConfig = form.metadata?.harnessConfig;
+			const effectiveMaxIssues = maxIssuesParsed ?? harnessConfig?.maxIssuesPerTurn ?? DEFAULT_MAX_ISSUES;
+			const effectiveMaxFields = maxFields ?? void 0;
+			const effectiveMaxGroups = maxGroups ?? void 0;
+			logVerbose(ctx, "Running inspection...");
+			const result = inspect(form, { targetRoles });
+			const limitedIssues = filterIssuesByScope(filterIssuesByOrder(result.issues, form), form, effectiveMaxFields, effectiveMaxGroups).slice(0, effectiveMaxIssues);
+			const maxPatches = harnessConfig?.maxPatchesPerTurn ?? limitedIssues.length;
+			const stepBudget = Math.min(maxPatches, limitedIssues.length);
+			const enrichedIssues = limitedIssues.map((issue) => enrichIssue(issue, form, file));
+			const counts = result.progressSummary.counts;
+			const output = formatOutput(ctx, {
+				is_complete: result.isComplete,
+				form_state: result.formState,
+				step_budget: stepBudget,
+				progress: {
+					total_fields: counts.totalFields,
+					required_fields: counts.requiredFields,
+					filled_fields: counts.filledFields,
+					empty_required_fields: counts.emptyRequiredFields
+				},
+				issues: enrichedIssues
+			}, (data, useColors) => formatConsoleReport$3(data, useColors));
+			console.log(output);
+		} catch (error) {
+			logError(error instanceof Error ? error.message : String(error));
+			process.exit(1);
+		}
+	});
+}
+
 //#endregion
 //#region src/cli/commands/plan.ts
 /**
@@ -3930,13 +4141,18 @@ function openBrowser(url) {
 /**
 * Build tabs for a form file.
 * All tabs are always present - content is generated dynamically from the form.
-* Tab order: View, Edit, Source, Report, Values, Schema, Fill Record (if sidecar exists)
+* Tab order: Form, Report, Edit, Source, Values, Schema, Fill Record (if sidecar exists)
 */
 function buildFormTabs(formPath) {
 	const tabs = [
 		{
 			id: "view",
-			label: "View",
+			label: "Form",
+			path: null
+		},
+		{
+			id: "report",
+			label: "Report",
 			path: null
 		},
 		{
@@ -3949,11 +4165,6 @@ function buildFormTabs(formPath) {
 			label: "Source",
 			path: formPath
 		},
-		{
-			id: "report",
-			label: "Report",
-			path: null
-		},
 		{
 			id: "values",
 			label: "Values",
@@ -4326,7 +4537,7 @@ async function handleSave(req, res, form, filePath, ctx, updateForm) {
 			}));
 			return;
 		}
-		await writeFile(newPath, content);
+		await writeFile$1(newPath, content);
 		logInfo(ctx, pc.green(`Saved to: ${newPath}`));
 		res.writeHead(200, { "Content-Type": "application/json" });
 		res.end(JSON.stringify({
@@ -4882,10 +5093,10 @@ function renderFormHtml(form, tabs) {
               if (response.ok) {
                 tabCache[tabId] = await response.text();
               } else {
-                tabCache[tabId] = '<div class="error">Failed to load content</div>';
+                tabCache[tabId] = '<div class="error">No content available for this tab.</div>';
               }
             } catch (err) {
-              tabCache[tabId] = '<div class="error">Failed to load content</div>';
+              tabCache[tabId] = '<div class="error">No content available for this tab.</div>';
             }
           }
           tabViewContent.innerHTML = tabCache[tabId];
@@ -4902,10 +5113,10 @@ function renderFormHtml(form, tabs) {
               if (response.ok) {
                 tabCache[tabId] = await response.text();
               } else {
-                tabCache[tabId] = '<div class="error">Failed to load content</div>';
+                tabCache[tabId] = '<div class="error">No content available for this tab.</div>';
               }
             } catch (err) {
-              tabCache[tabId] = '<div class="error">Failed to load content</div>';
+              tabCache[tabId] = '<div class="error">No content available for this tab.</div>';
             }
           }
           tabOtherContent.innerHTML = tabCache[tabId];
@@ -4913,20 +5124,34 @@ function renderFormHtml(form, tabs) {
       }
     }
 
+    // Navigate to a tab by id, updating the button state and hash
+    let navigating = false;
+    async function navigateToTab(tabId) {
+      navigating = true;
+      tabButtons.forEach(b => b.classList.remove('active'));
+      const btn = document.querySelector('[data-tab="' + tabId + '"]');
+      if (btn) btn.classList.add('active');
+      location.hash = tabId;
+      await showTab(tabId);
+      navigating = false;
+    }
+
     tabButtons.forEach(btn => {
       btn.addEventListener('click', async () => {
-        const tabId = btn.dataset.tab;
-
-        // Update active button
-        tabButtons.forEach(b => b.classList.remove('active'));
-        btn.classList.add('active');
-
-        await showTab(tabId);
+        await navigateToTab(btn.dataset.tab);
       });
     });
 
-    // Load View tab on page load (it's the default tab)
-    showTab('view');
+    // Handle hash-based navigation (back/forward, direct URL)
+    window.addEventListener('hashchange', () => {
+      if (navigating) return;
+      const hash = window.location.hash.slice(1);
+      if (hash) navigateToTab(hash);
+    });
+
+    // Load initial tab from hash or default to Form (view) tab
+    const initialTab = window.location.hash.slice(1) || 'view';
+    navigateToTab(initialTab);
 
     // URL copy tooltip functionality - initialize once
     (function initUrlCopyTooltip() {
@@ -5523,7 +5748,7 @@ function registerRenderCommand(program) {
 				logDryRun(`Would write HTML to: ${outputPath}`);
 				return;
 			}
-			await writeFile(outputPath, html);
+			await writeFile$1(outputPath, html);
 			logSuccess(ctx, pc.green(`✓ Rendered to ${outputPath}`));
 		} catch (error) {
 			logError(error instanceof Error ? error.message : String(error));
@@ -5685,9 +5910,9 @@ function registerResearchCommand(program) {
 			console.log(`  ${formPath}  ${pc.dim("(filled markform source)")}`);
 			console.log(`  ${schemaPath}  ${pc.dim("(JSON Schema)")}`);
 			if (options.transcript && result.transcript) {
-				const { serializeSession } = await import("./session-VeSkVrck.mjs");
+				const { serializeSession } = await import("./session-DHyTMP67.mjs");
 				const transcriptPath = outputPath.replace(/\.form\.md$/, ".session.yaml");
-				const { writeFile } = await import("./shared-fb0nkzQi.mjs");
+				const { writeFile } = await import("./shared-BLh342F5.mjs");
 				await writeFile(transcriptPath, serializeSession(result.transcript));
 				logInfo(ctx, `Transcript: ${transcriptPath}`);
 			}
@@ -5734,6 +5959,354 @@ function registerSchemaCommand(program) {
 	});
 }
 
+//#endregion
+//#region src/cli/commands/set.ts
+/**
+* Parse a CLI value string into a RawFieldValue.
+*
+* Only detects JSON arrays/objects ([ or { prefix). Everything else
+* is passed through as a string — the coercion layer handles
+* type conversion based on the field's kind.
+*/
+function parseCliValue(raw) {
+	if (raw.startsWith("[") || raw.startsWith("{")) try {
+		return JSON.parse(raw);
+	} catch {
+		return raw;
+	}
+	return raw;
+}
+/**
+* Format set report for console output.
+*/
+function formatConsoleReport$2(report, useColors) {
+	const lines = [];
+	const bold = useColors ? pc.bold : (s) => s;
+	const dim = useColors ? pc.dim : (s) => s;
+	const cyan = useColors ? pc.cyan : (s) => s;
+	const green = useColors ? pc.green : (s) => s;
+	const red = useColors ? pc.red : (s) => s;
+	lines.push(bold(cyan("Set Result")));
+	lines.push("");
+	const statusColor = report.apply_status === "applied" ? green : red;
+	lines.push(`${bold("Status:")} ${statusColor(report.apply_status)}`);
+	lines.push(`${bold("Form State:")} ${report.form_state}`);
+	lines.push(`${bold("Complete:")} ${report.is_complete ? green("yes") : dim("no")}`);
+	lines.push("");
+	const counts = report.progress.counts;
+	lines.push(bold("Progress:"));
+	lines.push(`  Total fields: ${counts.totalFields}`);
+	lines.push(`  Filled: ${counts.filledFields}, Empty: ${counts.emptyFields}`);
+	lines.push(`  Empty required: ${counts.emptyRequiredFields}`);
+	lines.push("");
+	if (report.issues.length > 0) {
+		lines.push(bold(`Issues (${report.issues.length}):`));
+		for (const issue of report.issues) lines.push(`  P${issue.priority} ${dim(issue.ref)}: ${issue.message}`);
+	} else lines.push(dim("No issues."));
+	return lines.join("\n");
+}
+/**
+* Register the set command.
+*/
+function registerSetCommand(program) {
+	program.command("set <file> [fieldId] [value]").description("Set field values with auto-coercion").option("--values <json>", "Batch set: JSON object of {fieldId: rawValue} pairs").option("--append <value>", "Append item/row to a collection field").option("--delete <n>", "Delete item/row at index (0-based) from a collection field").option("--clear", "Clear the field value").option("--skip", "Skip the field (marks as skipped)").option("--abort", "Abort the field (marks as unable to complete)").option("--role <role>", "Role for skip/abort (default: \"user\")", "user").option("--reason <text>", "Reason for skip/abort").option("-o, --output <file>", "Output file (default: modify in place)").option("--report", "Output JSON report after applying (issues, progress)").option("--normalize", "Regenerate form without preserving external content").action(async (file, fieldId, value, options, cmd) => {
+		const ctx = getCommandContext(cmd);
+		try {
+			logVerbose(ctx, `Reading file: ${file}`);
+			const content = await readFile$1(file);
+			logVerbose(ctx, "Parsing form...");
+			const form = parseForm(content);
+			let patches;
+			if (options.values) {
+				if (fieldId) {
+					logError("Cannot use --values with positional fieldId/value arguments");
+					process.exit(1);
+				}
+				if (options.clear || options.skip || options.abort || options.append !== void 0 || options.delete !== void 0) {
+					logError("Cannot use --values with --clear, --skip, --abort, --append, or --delete");
+					process.exit(1);
+				}
+				let inputContext;
+				try {
+					inputContext = JSON.parse(options.values);
+				} catch {
+					logError("Invalid JSON in --values option");
+					process.exit(1);
+				}
+				if (typeof inputContext !== "object" || Array.isArray(inputContext)) {
+					logError("--values must be a JSON object");
+					process.exit(1);
+				}
+				const result = coerceInputContext(form, inputContext);
+				for (const w of result.warnings) logVerbose(ctx, `Warning: ${w}`);
+				if (result.errors.length > 0) {
+					for (const e of result.errors) logError(e);
+					process.exit(1);
+				}
+				patches = result.patches;
+			} else if (!fieldId) {
+				logError("Either <fieldId> or --values is required");
+				process.exit(1);
+			} else if (options.clear) {
+				if (!findFieldById(form, fieldId)) {
+					logError(`Field "${fieldId}" not found in form`);
+					process.exit(1);
+				}
+				patches = [{
+					op: "clear_field",
+					fieldId
+				}];
+			} else if (options.skip) {
+				if (!findFieldById(form, fieldId)) {
+					logError(`Field "${fieldId}" not found in form`);
+					process.exit(1);
+				}
+				patches = [{
+					op: "skip_field",
+					fieldId,
+					role: options.role,
+					...options.reason && { reason: options.reason }
+				}];
+			} else if (options.abort) {
+				if (!findFieldById(form, fieldId)) {
+					logError(`Field "${fieldId}" not found in form`);
+					process.exit(1);
+				}
+				patches = [{
+					op: "abort_field",
+					fieldId,
+					role: options.role,
+					...options.reason && { reason: options.reason }
+				}];
+			} else if (options.append !== void 0) {
+				const field = findFieldById(form, fieldId);
+				if (!field) {
+					logError(`Field "${fieldId}" not found in form`);
+					process.exit(1);
+				}
+				const rawValue = parseCliValue(options.append);
+				if (field.kind === "table") {
+					const rows = Array.isArray(rawValue) ? rawValue : typeof rawValue === "object" && rawValue !== null ? [rawValue] : null;
+					if (!rows) {
+						logError(`--append for table field "${fieldId}" requires a JSON object or array of row objects`);
+						process.exit(1);
+					}
+					patches = [{
+						op: "append_table",
+						fieldId,
+						value: rows
+					}];
+				} else if (field.kind === "string_list") patches = [{
+					op: "append_string_list",
+					fieldId,
+					value: Array.isArray(rawValue) ? rawValue : [typeof rawValue === "string" ? rawValue : JSON.stringify(rawValue)]
+				}];
+				else if (field.kind === "url_list") patches = [{
+					op: "append_url_list",
+					fieldId,
+					value: Array.isArray(rawValue) ? rawValue : [typeof rawValue === "string" ? rawValue : JSON.stringify(rawValue)]
+				}];
+				else {
+					logError(`--append is not supported for ${field.kind} fields (only table, string_list, url_list)`);
+					process.exit(1);
+				}
+			} else if (options.delete !== void 0) {
+				const field = findFieldById(form, fieldId);
+				if (!field) {
+					logError(`Field "${fieldId}" not found in form`);
+					process.exit(1);
+				}
+				const index = parseInt(options.delete, 10);
+				if (isNaN(index) || index < 0) {
+					logError(`--delete requires a non-negative integer index, got "${options.delete}"`);
+					process.exit(1);
+				}
+				if (field.kind === "table") patches = [{
+					op: "delete_table",
+					fieldId,
+					value: index
+				}];
+				else if (field.kind === "string_list") patches = [{
+					op: "delete_string_list",
+					fieldId,
+					value: index
+				}];
+				else if (field.kind === "url_list") patches = [{
+					op: "delete_url_list",
+					fieldId,
+					value: index
+				}];
+				else {
+					logError(`--delete is not supported for ${field.kind} fields (only table, string_list, url_list)`);
+					process.exit(1);
+				}
+			} else if (value !== void 0) {
+				const result = coerceToFieldPatch(form, fieldId, parseCliValue(value));
+				if (!result.ok) {
+					logError(result.error);
+					process.exit(1);
+				}
+				if ("warning" in result && result.warning) logVerbose(ctx, `Warning: ${result.warning}`);
+				patches = [result.patch];
+			} else {
+				logError("No value provided. Use <value>, --clear, --skip, --abort, --append, or --delete");
+				process.exit(1);
+			}
+			if (ctx.dryRun) {
+				logDryRun(`Would apply ${patches.length} patches to ${file}`, { patches });
+				return;
+			}
+			logVerbose(ctx, `Applying ${patches.length} patches...`);
+			const applyResult = applyPatches(form, patches);
+			if (applyResult.applyStatus === "rejected") {
+				logError("Patches rejected");
+				for (const rp of applyResult.rejectedPatches) logError(`  ${rp.message}`);
+				process.exit(1);
+			}
+			if (!(Boolean(options.clear) || Boolean(options.skip) || Boolean(options.abort) || options.delete !== void 0)) {
+				const patchedFieldIds = new Set(patches.map((p) => "fieldId" in p ? p.fieldId : "").filter(Boolean));
+				const relevantIssues = applyResult.issues.filter((i) => i.reason === "validation_error" && patchedFieldIds.has(i.ref));
+				for (const issue of relevantIssues) logWarn(ctx, issue.message);
+			}
+			if (options.report) {
+				const output = formatOutput(ctx, {
+					apply_status: applyResult.applyStatus,
+					form_state: applyResult.formState,
+					is_complete: applyResult.isComplete,
+					structure: applyResult.structureSummary,
+					progress: applyResult.progressSummary,
+					issues: applyResult.issues
+				}, (data, useColors) => formatConsoleReport$2(data, useColors));
+				if (options.output) {
+					await writeFile$1(options.output, output);
+					logSuccess(ctx, `Report written to ${options.output}`);
+				} else console.log(output);
+			} else {
+				const output = serializeForm(form, { preserveContent: !options.normalize });
+				const target = options.output ?? file;
+				await writeFile$1(target, output);
+				logSuccess(ctx, `Form updated: ${target}`);
+			}
+		} catch (error) {
+			logError(error instanceof Error ? error.message : String(error));
+			process.exit(1);
+		}
+	});
+}
+
+//#endregion
+//#region src/cli/commands/setup.ts
+const DO_NOT_EDIT_MARKER = `<!-- DO NOT EDIT: Generated by markform setup.
+Run 'markform setup' to update.
+-->`;
+/**
+* Load SKILL.md content and insert the DO NOT EDIT marker after frontmatter.
+*/
+function loadSkillWithMarker() {
+	const lines = readFileSync(resolvePackagePath(import.meta.url, "docs/skill/SKILL.md"), "utf-8").split("\n");
+	let endOfFrontmatter = -1;
+	if (lines[0] === "---") {
+		for (let i = 1; i < lines.length; i++) if (lines[i] === "---") {
+			endOfFrontmatter = i;
+			break;
+		}
+	}
+	if (endOfFrontmatter >= 0) lines.splice(endOfFrontmatter + 1, 0, "", DO_NOT_EDIT_MARKER);
+	return lines.join("\n");
+}
+/**
+* Install the skill file to .claude/skills/markform/SKILL.md.
+*/
+async function installSkill(projectDir, ctx) {
+	const skillDir = join(projectDir, ".claude", "skills", "markform");
+	const skillPath = join(skillDir, "SKILL.md");
+	const isUpdate = existsSync(skillPath);
+	const content = loadSkillWithMarker();
+	await mkdir(skillDir, { recursive: true });
+	await writeFile(skillPath, content, "utf-8");
+	logSuccess(ctx, `${isUpdate ? "Updated" : "Installed"} ${pc.bold(".claude/skills/markform/SKILL.md")}`);
+}
+/**
+* Run setup in auto mode (non-interactive, for agents).
+*/
+async function setupAuto(ctx) {
+	logInfo(ctx, "Installing Markform skill for Claude Code...");
+	await installSkill(process.cwd(), ctx);
+	logInfo(ctx, `Run ${pc.cyan("markform skill")} to view the installed skill content.`);
+}
+/**
+* Run setup in interactive mode (guided, for humans).
+*/
+async function setupInteractive(ctx) {
+	p.intro(pc.bgCyan(pc.black(" markform setup ")));
+	p.log.info([
+		"This will install Markform as a Claude Code skill in your project.",
+		"",
+		`  ${pc.dim("Creates:")} .claude/skills/markform/SKILL.md`,
+		"",
+		"This teaches Claude Code how to use markform commands when working",
+		"with .form.md files in this project."
+	].join("\n"));
+	const shouldContinue = await p.confirm({
+		message: "Install the Markform skill?",
+		initialValue: true
+	});
+	if (p.isCancel(shouldContinue) || !shouldContinue) {
+		p.outro("Setup cancelled.");
+		return;
+	}
+	await installSkill(process.cwd(), ctx);
+	p.outro("Markform skill installed! Claude Code will now know how to use markform.");
+}
+/**
+* Register the setup command.
+*/
+function registerSetupCommand(program) {
+	const cmd = program.command("setup").description("Install Markform as a Claude Code skill in the current project").option("--auto", "Non-interactive setup (for agents and scripts)").option("--interactive", "Guided setup with prompts (for humans)").action(async (options, command) => {
+		const ctx = getCommandContext(command);
+		try {
+			if (!options.auto && !options.interactive) {
+				cmd.help();
+				return;
+			}
+			if (options.auto) await setupAuto(ctx);
+			else await setupInteractive(ctx);
+		} catch (error) {
+			logError(error instanceof Error ? error.message : String(error));
+			process.exit(1);
+		}
+	});
+}
+
+//#endregion
+//#region src/cli/commands/skill.ts
+/**
+* Load the SKILL.md content.
+*/
+function loadSkillContent() {
+	const skillPath = resolvePackagePath(import.meta.url, "docs/skill/SKILL.md");
+	try {
+		return readFileSync(skillPath, "utf-8");
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		throw new Error(`Failed to load SKILL.md from ${skillPath}: ${message}`);
+	}
+}
+/**
+* Register the skill command.
+*/
+function registerSkillCommand(program) {
+	program.command("skill").description("Output SKILL.md content for Claude Code integration").action(() => {
+		try {
+			const content = loadSkillContent();
+			process.stdout.write(content);
+		} catch (error) {
+			logError(error instanceof Error ? error.message : String(error));
+			process.exit(1);
+		}
+	});
+}
+
 //#endregion
 //#region src/cli/commands/status.ts
 /**
@@ -6039,7 +6612,7 @@ function registerValidateCommand(program) {
 /**
 * CLI implementation for markform.
 *
-* Provides commands for inspecting, applying patches, exporting,
+* Provides commands for inspecting, patching, exporting,
 * serving, and running harness loops on .form.md files.
 */
 /**
@@ -6047,6 +6620,7 @@ function registerValidateCommand(program) {
 */
 function withColoredHelp(cmd) {
 	cmd.configureHelp({
+		helpWidth: 88,
 		styleTitle: (str) => pc.bold(pc.cyan(str)),
 		styleCommandText: (str) => pc.green(str),
 		styleOptionText: (str) => pc.yellow(str),
@@ -6059,12 +6633,18 @@ function withColoredHelp(cmd) {
 */
 function createProgram() {
 	const program = withColoredHelp(new Command());
-	program.name("markform").description("Agent-friendly, human-readable, editable forms").version(CLI_VERSION, "--version", "output the version number").showHelpAfterError().option("--verbose", "Enable verbose output").option("--quiet", "Suppress non-essential output").option("--dry-run", "Show what would be done without making changes").option("--format <format>", `Output format: ${OUTPUT_FORMATS.join(", ")}`, "console").option("--forms-dir <dir>", `Directory for form output (default: ${DEFAULT_FORMS_DIR})`).option("--overwrite", "Overwrite existing field values (default: continue/skip filled)");
+	program.name("markform").description("Agent-friendly, human-readable, editable forms").version(CLI_VERSION, "--version", "output the version number").showHelpAfterError().option("--verbose", "Enable verbose output").option("--quiet", "Suppress non-essential output").option("--dry-run", "Show what would be done without making changes").option("--format <format>", `Output format: ${OUTPUT_FORMATS.join(", ")}`, "console").option("--forms-dir <dir>", `Directory for form output (default: ${DEFAULT_FORMS_DIR})`).option("--overwrite", "Overwrite existing field values (default: continue/skip filled)").addHelpText("after", `
+Skill Setup:
+  To use Markform as a Claude Code skill, run: markform setup --auto
+  To view the skill content: markform skill
+
+Getting Started:
+  npm install -g markform && markform setup --auto`);
 	registerReadmeCommand(program);
 	registerDocsCommand(program);
 	registerSpecCommand(program);
 	registerApisCommand(program);
-	registerApplyCommand(program);
+	registerPatchCommand(program);
 	registerBrowseCommand(program);
 	registerDumpCommand(program);
 	registerExamplesCommand(program);
@@ -6072,6 +6652,7 @@ function createProgram() {
 	registerFillCommand(program);
 	registerInspectCommand(program);
 	registerModelsCommand(program);
+	registerNextCommand(program);
 	registerPlanCommand(program);
 	registerRenderCommand(program);
 	registerReportCommand(program);
@@ -6079,6 +6660,9 @@ function createProgram() {
 	registerRunCommand(program);
 	registerSchemaCommand(program);
 	registerServeCommand(program);
+	registerSetCommand(program);
+	registerSetupCommand(program);
+	registerSkillCommand(program);
 	registerStatusCommand(program);
 	registerValidateCommand(program);
 	return program;
@@ -6092,4 +6676,4 @@ async function runCli() {
 
 //#endregion
 export { runCli as t };
-//# sourceMappingURL=cli-ZcOC47KK.mjs.map
+//# sourceMappingURL=cli-B1T8kMFt.mjs.map