markform 0.1.5 → 0.1.7

package/README.md

@@ -1,23 +1,59 @@
 # Markform
 
-***Structured Markdown documents for humans, agents, and APIs***
+**Markform** turns Markdown documents into executable specifications for structured data
+collection.
+Define fields, validation rules, and instructions in a single `.form.md` file
+that is readable by humans, parseable by machines, and fillable by LLM agents.
 
-**Markform** is a **file format**, **data model**, and **editing API** for
-**token-friendly, human-readable text forms**. Markform syntax is a superset of Markdown
-based on [Markdoc](https://github.com/markdoc/markdoc), stored as `.form.md` files.
+The core idea: **a form combines structure, unstructured context, and memory in a simple
+text document**. Users can give inputs via UIs or CLI. Agents can fill fields
+incrementally via tools or APIs.
+Validation catches errors early and humans can review or intervene at any point.
+The entire workflow is visible in a token-friendly text file you can read, diff, and
+version control.
 
-Markform is like if Markdown docs had a customizable API. The idea is to combine the
-simple utility of a Markdown document with structured tags that define typed fields and
-validation rules.
-Fields, validation rules, and instructions are encoded as Markdoc tags.
+Syntax is [Markdoc](https://github.com/markdoc/markdoc), which is Markdown extended with
+`{% tag %}` annotations, so LLMs are already quite good at writing Markform docs.
 
-Markform lets you build powerful agent workflows by structuring and validating *what*
-you want (the form structure and validations) instead of *how* to get it (coding up
-agent workflows). For deep research and other tasks where you want a high level of
-control on intermediate states and final output from an AI pipeline, this approach is a
-compelling alternative to programmatic or UI-based agent workflows.
-Because it’s just Markdown with tags, agents are also very good at writing Markform,
-which makes creating new workflows much easier.
+## Why?
+
+Many agent workflow frameworks emphasize *prompts* and the *flow* of information (the
+*how*) over the desired *structure* of the results (the *what*). Markform lets you build
+agent workflows by structuring and validating *what* you want (the structure of
+information, validations, and reviews encoded in a form) instead of *how* to run a
+workflow as code (via explicit workflows or just an unstructured swarm of agents).
+
+For centuries, humans have used paper forms to systematize and manage processes.
+A well-designed form with instructions, field definitions, and validations is a concise
+way to share context: background knowledge, goals, process rules, and memories.
+I don’t think AI changes this essential aspect of knowledge work.
+It’s time to bring bureaucracy to the agents.
+
+There’s one more key benefit to this approach: LLMs are good at writing forms!
+Because the syntax is just Markdown with Jinja-style tags, agents can convert an
+informal Markdown doc describing a process to a precise Markform process easily.
+
+(For more, see [the FAQ](#faq).)
+
+## Quick Start
+
+```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
+npx markform examples  # Copy examples to ./forms/, then offers to run one
+
+# Or run forms directly
+npx markform run  # Browse and run forms interactively
+
+# Read the docs (tell your agents to run these; they are agent-friendly!)
+npx markform  # CLI help
+npx markform readme   # This file
+npx markform docs  # Quick reference for writing Markforms
+npx markform spec  # Read the full spec
+```
+
+The `markform examples` command copies sample forms locally and prompts you to run one.
+Pick `movie-research-demo.form.md` for a quick example.
 
 ## Installation
 
@@ -31,17 +67,6 @@ npm install -g markform
 npm install markform
 ```
 
-## Quick Start
-
-```bash
-# Try it without installing
-npx markform examples
-```
-
-This walks you through an example form interactively, with optional AI agent filling.
-You’ll need at least one [API key](#supported-providers) form a provider with a model
-that supports web search to have LLMs fill in forms.
-
 ## Example: Research a Movie
 
 ### Form Definition
@@ -53,7 +78,7 @@ It combines YAML frontmatter with Markdoc-tagged content:
 ---
 markform:
   spec: MF/0.1
-  title: Movie Research (Minimal)
+  title: Movie Research (Demo)
   description: Quick movie lookup with just the essentials (title, year, ratings, summary).
   roles:
     - user
@@ -62,9 +87,9 @@ markform:
     user: "Enter the movie title."
     agent: |
       Quickly identify the movie and fill in basic info from IMDB.
-      This is a minimal lookup - just get the core facts.
+      This is a demo lookup - just get the core facts.
 ---
-{% form id="movie_research_minimal" title="Movie Research (Minimal)" %}
+{% form id="movie_research_demo" title="Movie Research (Demo)" %}
 
 ## Movie Research Example
 
@@ -122,11 +147,12 @@ What movie do you want to research? \[*This field is filled in by the user (`rol
 
 ### Form Report Output
 
-Run the `npx markform examples` and select the `Movie Research (Minimal)` example and
-view the report:
+Run `npx markform examples` to copy examples, then `npx markform run` and select `Movie
+Research (Demo)` to fill it.
+The report output looks like:
 
 ```markdown
-# Movie Research (Minimal)
+# Movie Research (Demo)
 
 ## Movie Identification
 
@@ -156,51 +182,55 @@ Convicted banker Andy Dufresne is sent to Shawshank State Penitentiary, where he
 
 ### More Example Forms
 
-The package includes example forms in
-[`examples/`](https://github.com/jlevy/markform/tree/main/packages/markform/examples).
-View them with `markform examples --list` or try these interactively:
+The package includes example forms.
+View them with `markform examples --list`, copy with `markform examples`, and run with
+`markform run`:
+
+- [`simple.form.md`](https://github.com/jlevy/markform/blob/main/packages/markform/examples/simple/simple.form.md)
+  \- Basic form demonstrating all field kinds.
 
-- [`movie-research/movie-research-minimal.form.md`](https://github.com/jlevy/markform/blob/main/packages/markform/examples/movie-research/movie-research-minimal.form.md)
+- [`movie-research-demo.form.md`](https://github.com/jlevy/markform/blob/main/packages/markform/examples/movie-research/movie-research-demo.form.md)
   \- The quick example above.
 
-- [`movie-research/movie-research-basic.form.md`](https://github.com/jlevy/markform/blob/main/packages/markform/examples/movie-research/movie-research-basic.form.md)
+- [`movie-research-basic.form.md`](https://github.com/jlevy/markform/blob/main/packages/markform/examples/movie-research/movie-research-basic.form.md)
   \- Standard movie research with IMDB, Rotten Tomatoes, Metacritic.
 
-- [`movie-research/movie-research-deep.form.md`](https://github.com/jlevy/markform/blob/main/packages/markform/examples/movie-research/movie-research-deep.form.md)
+- [`movie-research-deep.form.md`](https://github.com/jlevy/markform/blob/main/packages/markform/examples/movie-research/movie-research-deep.form.md)
   \- Comprehensive movie analysis with streaming, box office, analysis.
 
-- [`simple/simple.form.md`](https://github.com/jlevy/markform/blob/main/packages/markform/examples/simple/simple.form.md)
-  \- Basic form demonstrating all field kinds.
-
-- [`earnings-analysis/earnings-analysis.form.md`](https://github.com/jlevy/markform/blob/main/packages/markform/examples/earnings-analysis/earnings-analysis.form.md)
+- [`earnings-analysis.form.md`](https://github.com/jlevy/markform/blob/main/packages/markform/examples/earnings-analysis/earnings-analysis.form.md)
   \- Financial analysis form.
 
-## Why?
-
-Many agent workflow frameworks emphasize the *flow* of information (the *how*) over its
-*structure* (the *what*). But the *how* is constantly changing.
-
-What we often really want is to express *desired structure and validation rules* for
-content directly in a way that provides clear context to agents and humans at all times.
-
-Humans have for centuries used paper forms to systematize and manage processes.
-The key insight of Markform is that the most natural way to express the state and
-context for a workflow is often *forms*. Just as Markdown is a transparent format for
-documents, Markform is a transparent text format for structured information.
-
 ## CLI Commands
 
-### Explore Examples
+### Copy and Run Examples
 
 ```bash
-# Interactive: select an example, fill it, optionally run agent
+# Copy all bundled examples to ./forms/
 markform examples
 
 # List available examples
 markform examples --list
 
-# Start with a specific example
-markform examples --name political-research
+# Copy a specific example
+markform examples --name movie-research-demo
+```
+
+### Browse and Run Forms
+
+```bash
+# Browse forms in ./forms/ and run one interactively
+markform run
+
+# Run a specific form directly
+markform run forms/movie-research-demo.form.md
+```
+
+### Check Form Status
+
+```bash
+# Show fill progress with per-role breakdown
+markform status my-form.form.md
 ```
 
 ### Inspect Forms
@@ -415,6 +445,19 @@ const result = await generateText({
 
 ## FAQ
 
+### Can you say more why this is a good idea?
+
+Yes! I’ve come to believe forms are a missing piece of the workflow problem with agents.
+For deep research or complex multi-step workflows, key pieces need to be *precisely
+controlled*, *domain-specific*, and *always improving*. You need precise documentation
+on the key intermediate states and final output from an AI pipeline.
+
+But you don’t want structure in a GUI (not token friendly) or code (hard to update) or
+dependent on the whims of a thinking model (changes all the time).
+Forms define these pieces and are easy to edit.
+All other choices can be left to the agents themselves, with the structure and
+validations enforced by the form-filling tools the agents use.
+
 ### Is this mature?
 
 No! I just wrote it.
@@ -423,10 +466,24 @@ But it’s been useful for me already.
 
 ### Was it Vibe Coded?
 
-It’s all written by LLMs but using a strongly spec-driven process, using rules from
-[Speculate](https://github.com/jlevy/speculate).
-See [the spec](docs/markform-spec.md) and the architecture docs and specs in
-[docs/](docs/).
+This is 100% agent-written code and the planning specs are also 100% agent written,
+using a mix of Opus 4.5, GPT 5.2, GPT-5 Pro, Gemini 3, and occasionally others.
+
+But it’s not slop. It is written via a strongly spec-driven process, using rules from my
+[Speculate](https://github.com/jlevy/speculate) repo and Steve Yegge’s
+[beads](https://github.com/steveyegge/beads) for tracking work.
+
+See
+[my post](https://github.com/jlevy/speculate/blob/main/about/lessons_in_spec_coding.md)
+for more thoughts on how this works.
+And see [the complete history of
+specs](https://github.com/jlevy/markform/tree/main/docs/project/specs/done) for examples
+of how everything is done with specs and with
+
+Although I didn’t have to write much there was a *lot* of management and review by me
+and a lot of thought and iteration for all design decisions.
+And this doc is written by me.
+:)
 
 ### What are the goals of Markform?
 
@@ -467,7 +524,8 @@ This enables powerful AI workflows that assemble information in a defined struct
 
 ### Does anything like this already exist?
 
-Not really. The closest alternatives are:
+Not that I have seen.
+The closest alternatives are:
 
 - Plain Markdown docs can be used as templates and filled in by agents.
   These are more expressive, but it is hard to edit them programmatically or use LLMs to
@@ -481,13 +539,13 @@ Not really. The closest alternatives are:
   human-friendly UI. But these do not have a human-friendly text format for use by
   agents as well as humans.
 
-| Approach | Has GUI | Human-readable text format | Agent-editable | APIs and validation rules |
+| Approach | Has GUI | Human-readable source format | Agent-editable | APIs and validation rules |
 | --- | :---: | :---: | :---: | :---: |
 | Plain Markdown | ☑️ existing tools | ✅ | ⚠️ fragile | ❌ |
-| JSON with schema | ☑️ existing tools | ⚠️ hey it’s JSON | ✅ | ✅ |
+| JSON with schema | ⚠️ in some apps | ⚠️ um it’s JSON | ✅ | ✅ |
 | SaaS tools (Typeform, Docusign, PDF forms) | ✅ | ⚠️ rarely | ⚠️ if they add it | ⚠️ if they add it |
-| Excel/Google Sheets | ✅ | ❌ .xlsx | ⚠️ with tools | ✅ |
-| **Markform** | ☑️ existing tools | ✅ | ✅ | ✅ |
+| Excel/Google Sheets | ✅ | ❌ .csv (poor) or .xlsx (worse) | ⚠️ with tools | ✅ with some coding |
+| **Markform** | ☑️ existing tools | ✅ | ✅ with this package | ✅ with this package |
 
 ### What are example use cases?
 

package/dist/ai-sdk.d.mts

@@ -1,6 +1,5 @@
-#!/usr/bin/env node
 
-import { Dt as PatchSchema, Et as Patch, G as FormSchema, Tt as ParsedForm, X as Id, ar as ValidatorRegistry, r as ApplyResult, tt as InspectResult, z as FieldResponse } from "./coreTypes-9XZSNOv6.mjs";
+import { Dt as ParsedForm, Ot as Patch, Q as Id, V as FieldResponse, kt as PatchSchema, lr as ValidatorRegistry, q as FormSchema, r as ApplyResult, rt as InspectResult } from "./coreTypes-DCvD7feM.mjs";
 import { z } from "zod";
 
 //#region src/integrations/toolTypes.d.ts

package/dist/ai-sdk.mjs

@@ -1,5 +1,6 @@
-import { L as PatchSchema } from "./coreTypes-pyctKRgc.mjs";
-import { r as inspect, t as applyPatches, u as serialize } from "./apply-BCCiJzQr.mjs";
+
+import { L as PatchSchema } from "./coreTypes-__Cwxz5q.mjs";
+import { d as serialize, i as inspect, t as applyPatches } from "./apply-g23rRn7p.mjs";
 import { z } from "zod";
 
 //#region src/integrations/vercelAiSdkTools.ts

package/dist/{apply-BCCiJzQr.mjs → apply-g23rRn7p.mjs}

@@ -1,4 +1,3 @@
-import { resolve } from "node:path";
 
 //#region src/llms.ts
 /**
@@ -113,13 +112,6 @@ function getWebSearchConfig(provider) {
 //#endregion
 //#region src/settings.ts
 /**
-* Global settings and constants for Markform.
-*
-* This file consolidates non-changing default values that were previously
-* scattered across the codebase. These are NOT runtime configurable - they
-* are compile-time constants.
-*/
-/**
 * The current Markform spec version in full notation (e.g., "MF/0.1").
 * This is distinct from npm package version and tracks the format that
 * .form.md files conform to.
@@ -165,25 +157,19 @@ function parseRolesFlag(raw) {
 */
 const DEFAULT_PRIORITY = "medium";
 /**
-* The default port for the serve command.
-*/
-const DEFAULT_PORT = 3344;
-/**
 * Default forms directory for CLI output (relative to cwd).
 * Commands write form outputs here to avoid cluttering the workspace.
 */
 const DEFAULT_FORMS_DIR = "./forms";
 /**
-* Resolve the forms directory path to an absolute path.
-* Uses the provided override or falls back to DEFAULT_FORMS_DIR.
-*
-* @param override Optional override path from CLI --forms-dir option
-* @param cwd Base directory for resolving relative paths (defaults to process.cwd())
-* @returns Absolute path to the forms directory
+* Maximum forms to display in 'markform run' menu.
+* Additional forms are not shown but can be run directly by path.
 */
-function getFormsDir(override, cwd = process.cwd()) {
-	return resolve(cwd, override ?? DEFAULT_FORMS_DIR);
-}
+const MAX_FORMS_IN_MENU = 30;
+/**
+* The default port for the serve command.
+*/
+const DEFAULT_PORT = 3344;
 /**
 * Default maximum turns for the fill harness.
 * Prevents runaway loops during agent execution.
@@ -223,12 +209,18 @@ const EXPORT_EXTENSIONS = {
 */
 const REPORT_EXTENSION = ".report.md";
 /**
+* Schema extension - generated JSON Schema for form structure.
+* Used for validation, code generation, and LLM tooling.
+*/
+const SCHEMA_EXTENSION = ".schema.json";
+/**
 * All recognized markform file extensions.
-* Combines export formats with report format.
+* Combines export formats with report and schema formats.
 */
 const ALL_EXTENSIONS = {
 	...EXPORT_EXTENSIONS,
-	report: REPORT_EXTENSION
+	report: REPORT_EXTENSION,
+	schema: SCHEMA_EXTENSION
 };
 /**
 * Detect file type from path based on extension.
@@ -239,6 +231,7 @@ function detectFileType(filePath) {
 	if (filePath.endsWith(ALL_EXTENSIONS.raw)) return "raw";
 	if (filePath.endsWith(ALL_EXTENSIONS.report)) return "report";
 	if (filePath.endsWith(ALL_EXTENSIONS.yaml)) return "yaml";
+	if (filePath.endsWith(ALL_EXTENSIONS.schema)) return "schema";
 	if (filePath.endsWith(ALL_EXTENSIONS.json)) return "json";
 	if (filePath.endsWith(".md")) return "raw";
 	return "unknown";
@@ -267,6 +260,18 @@ function deriveReportPath(basePath) {
 	}
 	return base + REPORT_EXTENSION;
 }
+/**
+* Derive schema path from any markform file path.
+* Strips known extensions and appends .schema.json.
+*/
+function deriveSchemaPath(basePath) {
+	let base = basePath;
+	for (const ext of Object.values(ALL_EXTENSIONS)) if (base.endsWith(ext)) {
+		base = base.slice(0, -ext.length);
+		break;
+	}
+	return base + SCHEMA_EXTENSION;
+}
 
 //#endregion
 //#region src/utils/keySort.ts
@@ -2824,4 +2829,4 @@ function applyPatches(form, patches) {
 }
 
 //#endregion
-export { parseRolesFlag as A, DEFAULT_ROLE_INSTRUCTIONS as C, deriveReportPath as D, deriveExportPath as E, hasWebSearchSupport as F, parseModelIdForDisplay as I, WEB_SEARCH_CONFIG as M, formatSuggestedLlms as N, detectFileType as O, getWebSearchConfig as P, DEFAULT_ROLES as S, USER_ROLE as T, DEFAULT_MAX_TURNS as _, computeAllSummaries as a, DEFAULT_RESEARCH_MAX_ISSUES_PER_TURN as b, computeStructureSummary as c, serializeRawMarkdown as d, serializeReportMarkdown as f, DEFAULT_MAX_PATCHES_PER_TURN as g, DEFAULT_MAX_ISSUES_PER_TURN as h, validate as i, SUGGESTED_LLMS as j, getFormsDir as k, isFormComplete as l, DEFAULT_FORMS_DIR as m, getFieldsForRoles as n, computeFormState as o, AGENT_ROLE as p, inspect as r, computeProgressSummary as s, applyPatches as t, serialize as u, DEFAULT_PORT as v, REPORT_EXTENSION as w, DEFAULT_RESEARCH_MAX_PATCHES_PER_TURN as x, DEFAULT_PRIORITY as y };
+export { deriveSchemaPath as A, DEFAULT_ROLES as C, USER_ROLE as D, REPORT_EXTENSION as E, formatSuggestedLlms as F, getWebSearchConfig as I, hasWebSearchSupport as L, parseRolesFlag as M, SUGGESTED_LLMS as N, deriveExportPath as O, WEB_SEARCH_CONFIG as P, parseModelIdForDisplay as R, DEFAULT_RESEARCH_MAX_PATCHES_PER_TURN as S, MAX_FORMS_IN_MENU as T, DEFAULT_MAX_PATCHES_PER_TURN as _, validate as a, DEFAULT_PRIORITY as b, computeProgressSummary as c, serialize as d, serializeRawMarkdown as f, DEFAULT_MAX_ISSUES_PER_TURN as g, DEFAULT_FORMS_DIR as h, inspect as i, detectFileType as j, deriveReportPath as k, computeStructureSummary as l, AGENT_ROLE as m, getAllFields as n, computeAllSummaries as o, serializeReportMarkdown as p, getFieldsForRoles as r, computeFormState as s, applyPatches as t, isFormComplete as u, DEFAULT_MAX_TURNS as v, DEFAULT_ROLE_INSTRUCTIONS as w, DEFAULT_RESEARCH_MAX_ISSUES_PER_TURN as x, DEFAULT_PORT as y };

package/dist/bin.d.mts

@@ -1,3 +1,2 @@
-#!/usr/bin/env node
 
 export { };

package/dist/bin.mjs

@@ -1,10 +1,7 @@
 #!/usr/bin/env node
-import "./coreTypes-pyctKRgc.mjs";
-import "./apply-BCCiJzQr.mjs";
-import "./src-Df0XX7UB.mjs";
-import "./session-uF0e6m6k.mjs";
-import "./shared-BqPnYXrn.mjs";
-import { t as runCli } from "./cli-D469amuk.mjs";
+
+
+import { t as runCli } from "./cli-Bqlm-WWw.mjs";
 import { resolve } from "node:path";
 import { existsSync } from "node:fs";
 import { config } from "dotenv";