markform 0.1.24 → 0.1.25

package/README.md

@@ -1,9 +1,8 @@
 # Markform
 
-[![CI](https://github.com/jlevy/markform/actions/workflows/ci.yml/badge.svg)](https://github.com/jlevy/markform/actions/runs/22024451235)
-[![Coverage](https://raw.githubusercontent.com/jlevy/markform/main/badges/packages/markform/coverage-total.svg)](https://github.com/jlevy/markform/actions/runs/22024451235)
+[![Follow @ojoshe on X](https://img.shields.io/badge/follow_%40ojoshe-black?logo=x&logoColor=white)](https://x.com/ojoshe)
+[![CI](https://github.com/jlevy/markform/actions/workflows/ci.yml/badge.svg)](https://github.com/jlevy/markform/actions/workflows/ci.yml)
 [![npm version](https://img.shields.io/npm/v/markform)](https://www.npmjs.com/package/markform)
-[![X Follow](https://img.shields.io/twitter/follow/ojoshe)](https://x.com/ojoshe)
 
 ### What if your Markdown docs had an agent-friendly semantic API?
 
@@ -17,10 +16,10 @@ Humans can review or intervene at any point.
 
 ### Why forms?
 
-For deep research or complex AI tasks, you need more than just prompts or
-flow: you need *structure*, which is precise control over agent output at every stage of
-a workflow. A well-designed form combines instructions, structured data, and validations
-in one place.
+For deep research or complex AI tasks, you need more than just prompts or flow: you need
+*structure*, which is precise control over agent output at every stage of a workflow.
+A well-designed form combines instructions, structured data, and validations in one
+place.
 
 ### How it Works
 
@@ -42,20 +41,24 @@ in one place.
 
 ### Useful details
 
-- Markform syntax is a good source format: it is **token-efficient text** you can read, diff, and
-  version control and it is **ideal for context engineering** because it combines
-  document context, data schema, and memory (data filled so far).
+- Markform syntax is a good source format: it is **token-efficient text** you can read,
+  diff, and version control and it is **ideal for context engineering** because it
+  combines document context, data schema, and memory (data filled so far).
 
-- Structure is defined with HTML comment tags (`<!-- field -->`) that
-  render invisibly on GitHub, so **forms look like regular Markdown**. (Jinja-style
-  tag syntax also works if you prefer.)
+- Structure is defined with HTML comment tags (`<!-- field -->`) that render invisibly
+  on GitHub, so **forms look like regular Markdown**. (Jinja-style tag syntax also works
+  if you prefer.)
 
-- Optionally, **a fill record** of the form-filling process is kept, so you can see
-  and debug exactly how forms are filled by agents, tool usage, LLM call time, etc.
+- Form-filling can scale to **hundreds of fields** in a form filled by **dozens of
+  concurrent LLM requests** which makes it possible to systemetize large, complex
+  research processes or workflows.
+  (And **a fill record** of the form-filling process is kept, so you can see and debug
+  exactly how forms are filled by agents, tool usage, LLM call time, etc.)
 
-- The CLI has a built-in web renderer, **`markform serve`**, for easy viewing and debugging
-  of forms (including a form web UI, the form schema, and a waterfall-style overview of the
-  fill record, including performance details, which is useful for large, concurrently filled forms).
+- The CLI has a built-in web renderer, **`markform serve`**, for easy viewing and
+  debugging of forms (including a form web UI, the form schema, and a waterfall-style
+  overview of the fill record, including performance details, which is useful for large,
+  concurrently filled forms).
 
 ## Simple Example: Research a Movie
 
@@ -302,11 +305,34 @@ See [the FAQ](#faq) for more on the design.
 
 ## Quick Start
 
+There are three ways to get started, from quickest to most thorough:
+
+**1. Run an example automatically** — copy bundled forms and let an LLM fill one:
+
 ```bash
-# Copy example forms to ./forms/ and run one interactively.
-# Set OPENAI_API_KEY or ANTHROPIC_API_KEY (or put in .env) for research examples
+# Set OPENAI_API_KEY or ANTHROPIC_API_KEY (or put in .env)
 npx markform@latest examples
+```
+
+Pick `movie-research-demo.form.md` for a quick demo.
+
+**2. Agent-guided tour** — ask a coding agent (like Claude Code) to walk you through a
+specific example step by step.
+The agent copies the form, explains the structure, fills fields, validates, and exports:
+
+```bash
+# List available examples
+markform examples --list
+# Copy one to work with
+markform examples --name movie-research-demo
+```
 
+**3. End-to-end walkthrough** — have a coding agent follow the
+[demo playbook](packages/markform/examples/markform-demo-playbook.md) to design a
+research form from scratch, fill it with real data, validate, export, and browse.
+This is the most thorough tour of all Markform features.
+
+```bash
 # Read the docs (tell your agents to run these; they are agent-friendly!)
 npx markform  # CLI help
 npx markform readme   # This file
@@ -314,10 +340,6 @@ npx markform docs  # Quick reference for writing Markforms
 npx markform spec  # Read the full spec
 ```
 
-The `markform examples` command copies some sample forms to `./forms` and prompts you to
-fill in a form interactively and then optionally have an agent complete it.
-Pick `movie-research-demo.form.md` for a quick example.
-
 ## Installation
 
 Requires Node.js 20+.
@@ -333,8 +355,9 @@ npm install markform
 ### Use as a Claude Code Skill
 
 If you install markform globally (`npm install -g markform`), you can tell Claude to run
-`markform setup --auto` to install it as a Claude Code skill. This teaches Claude how to
-use markform commands when working with `.form.md` files in your project.
+`markform setup --auto` to install it as a Claude Code skill.
+This teaches Claude how to use markform commands when working with `.form.md` files in
+your project.
 
 ```bash
 # Install as a Claude Code skill (non-interactive, for agents)
@@ -431,7 +454,7 @@ flowchart LR
         subgraph ENGINE["<b>CORE TYPESCRIPT APIS</b><br/>Markdoc parser, serializer,<br/>patch application,<br/>validation (jiti for rules)"]
         end
 
-        subgraph TEST["<b>TESTING FRAMEWORK</b><br/>Golden session testing<br/>(.session.yaml transcripts)"]
+        subgraph PARSER["<b>PARSER</b><br/>Markform language<br/>parser/serializer"]
         end
 
         CLI --> ENGINE
@@ -439,7 +462,7 @@ flowchart LR
         AGENT --> HARNESS
         AGENT --> ENGINE
         HARNESS --> ENGINE
-        ENGINE --> TEST
+        ENGINE --> PARSER
     end
 
     SPEC ~~~ IMPL
@@ -454,7 +477,7 @@ flowchart LR
     style CLI fill:#ffe8cc,stroke:#fb8500
     style AGENT fill:#ffe8cc,stroke:#fb8500
     style HARNESS fill:#ffe8cc,stroke:#fb8500
-    style TEST fill:#ffe8cc,stroke:#fb8500
+    style PARSER fill:#ffe8cc,stroke:#fb8500
 ```
 
 ## CLI Commands
@@ -588,8 +611,8 @@ If unsure, try `gpt-5-mini` first as it’s fast and supports web search.
 
 ## Programmatic Usage
 
-Markform exports a parsing engine, rendering functions, and AI SDK integration for use in
-your own applications.
+Markform exports a parsing engine, rendering functions, and AI SDK integration for use
+in your own applications.
 
 ### Basic Parsing
 

package/dist/ai-sdk.d.mts

@@ -1,5 +1,5 @@
 
-import { At as ParsedForm, Nt as PatchSchema, U as FieldResponse, Y as FormSchema, at as InspectResult, et as Id, gr as ValidatorRegistry, jt as Patch, r as ApplyResult } from "./coreTypes-GxzWNXap.mjs";
+import { At as ParsedForm, Nt as PatchSchema, U as FieldResponse, Y as FormSchema, at as InspectResult, et as Id, gr as ValidatorRegistry, jt as Patch, r as ApplyResult } from "./coreTypes-CxpqKpBA.mjs";
 import { z } from "zod";
 
 //#region src/integrations/toolTypes.d.ts

package/dist/ai-sdk.mjs

@@ -1,6 +1,6 @@
 
-import { R as PatchSchema } from "./coreTypes-CctFK6uE.mjs";
-import { _ as inspect, m as applyPatches, p as findFieldById, s as getPatchFormatHint, u as getFieldIdFromRef, w as serializeForm } from "./prompts-BCnYaH4_.mjs";
+import { R as PatchSchema } from "./coreTypes-DIv9Aabl.mjs";
+import { _ as inspect, m as applyPatches, p as findFieldById, s as getPatchFormatHint, u as getFieldIdFromRef, w as serializeForm } from "./prompts-DaPKumGY.mjs";
 import { z } from "zod";
 
 //#region src/integrations/vercelAiSdkTools.ts

package/dist/bin.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 
-import { t as runCli } from "./cli-B1DhFYBS.mjs";
+import { t as runCli } from "./cli-B1T8kMFt.mjs";
 import { resolve } from "node:path";
 import { existsSync } from "node:fs";
 import { config } from "dotenv";

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

@@ -1,10 +1,10 @@
 
-import { R as PatchSchema } from "./coreTypes-CctFK6uE.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-BCnYaH4_.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-C5OWf1dL.mjs";
-import { n as serializeSession } from "./session-BLjN3BkJ.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-CuSRYcIB.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";
@@ -1026,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",
@@ -2436,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.
@@ -2588,7 +2614,7 @@ function registerExamplesCommand(program) {
 		const ctx = getCommandContext(cmd);
 		try {
 			if (options.list) {
-				printExamplesList();
+				printExamplesList(ctx);
 				return;
 			}
 			const formsDir = getFormsDir(ctx.formsDir);
@@ -4115,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
 		},
 		{
@@ -4134,11 +4165,6 @@ function buildFormTabs(formPath) {
 			label: "Source",
 			path: formPath
 		},
-		{
-			id: "report",
-			label: "Report",
-			path: null
-		},
 		{
 			id: "values",
 			label: "Values",
@@ -5067,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];
@@ -5087,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];
@@ -5098,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() {
@@ -5870,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-D7C7IlEv.mjs");
+				const { serializeSession } = await import("./session-DHyTMP67.mjs");
 				const transcriptPath = outputPath.replace(/\.form\.md$/, ".session.yaml");
-				const { writeFile } = await import("./shared-DtorFV21.mjs");
+				const { writeFile } = await import("./shared-BLh342F5.mjs");
 				await writeFile(transcriptPath, serializeSession(result.transcript));
 				logInfo(ctx, `Transcript: ${transcriptPath}`);
 			}
@@ -6123,6 +6163,11 @@ function registerSetCommand(program) {
 				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,
@@ -6631,4 +6676,4 @@ async function runCli() {
 
 //#endregion
 export { runCli as t };
-//# sourceMappingURL=cli-B1DhFYBS.mjs.map
+//# sourceMappingURL=cli-B1T8kMFt.mjs.map