markform 0.1.16 → 0.1.18

package/README.md

@@ -1,7 +1,7 @@
 # Markform
 
-[![CI](https://github.com/jlevy/markform/actions/workflows/ci.yml/badge.svg)](https://github.com/jlevy/markform/actions/runs/21077282678)
-[![Coverage](https://raw.githubusercontent.com/jlevy/markform/main/badges/packages/markform/coverage-total.svg)](https://github.com/jlevy/markform/actions/runs/21077282678)
+[![CI](https://github.com/jlevy/markform/actions/workflows/ci.yml/badge.svg)](https://github.com/jlevy/markform/actions/runs/21430430567)
+[![Coverage](https://raw.githubusercontent.com/jlevy/markform/main/badges/packages/markform/coverage-total.svg)](https://github.com/jlevy/markform/actions/runs/21430430567)
 [![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)
 
@@ -24,8 +24,9 @@ in one place.
   UI, agents fill via tool calls ([Vercel AI SDK](https://github.com/vercel/ai)
   integration included).
 
-- Changes are explicit patch operations (`{ "op": "set_string", "fieldId": "name",
-  "value": "Alice" }`) validated against a schema specified in the form.
+- Changes are explicit patch operations
+  (`{ "op": "set_string", "fieldId": "name", "value": "Alice" }`) validated against a
+  schema specified in the form.
   The agent sees validation errors and can self-correct.
 
 - The format extends Markdown with a
@@ -33,121 +34,17 @@ in one place.
   Export Markform syntax to JSON, YAML, JSON Schema, or plain Markdown reports.
 
 Markform syntax is a good source format: token-efficient text you can read, diff, and
-version control.
-Structure is defined with HTML comment tags (`<!-- field -->`) that render invisibly
-on GitHub, so forms look like regular Markdown.
+version control. Structure is defined with HTML comment tags (`<!-- field -->`) that
+render invisibly on GitHub, so forms look like regular Markdown.
 
-## Why Do Agents Need Forms?
-
-For centuries, humans have used paper forms and
-[checklists](https://en.wikipedia.org/wiki/The_Checklist_Manifesto) to systematize
-complex processes. A form with instructions, field definitions, and validations is a
-concise way to share context: goals, background knowledge, process rules, and state
-(memory). I don’t think AI changes this essential aspect of knowledge work.
-
-Most agent frameworks focus on *prompts* and *flow* (the how) over the *structure* of
-results (the what).
-But for deep research or other multi-step workflows, you need precise
-control over intermediate states and final output.
-You don’t want that structure in a GUI (not token-friendly), in code (hard to update),
-or dependent on model whims (changes unpredictably with model updates).
-
-Forms solve this. Forms codify operational excellence.
-They’re easy to read, easy to edit, and enforce standards.
-Because LLMs handle Markdown well, agents can also help create and improve the forms
-themselves—closing the meta-loop.
-
-It’s time to bring bureaucracy to the agents!
-See [the FAQ](#faq) for more on the design.
-
-## 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@latest examples
-
-# 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 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+.
-
-```bash
-# As a global CLI
-npm install -g markform
-
-# Or as a project dependency
-npm install markform
-```
-
-## Example: Research a Movie
+## Simple Example: Research a Movie
 
 ### Form Definition
 
-A `.form.md` file combines YAML frontmatter with HTML comment tags that define structure.
-The text can be any Markdown.
-The tags define things like fields:
-
-```markdown
-<!-- field kind="string" id="movie" label="Movie" role="user"
-   required=true minLength=1 maxLength=300 --><!-- /field -->
-
-<!-- field kind="single_select" id="mpaa_rating" role="agent" label="MPAA Rating" -->
-- [ ] G <!-- #g -->
-- [ ] PG <!-- #pg -->
-- [ ] PG-13 <!-- #pg_13 -->
-- [ ] R <!-- #r -->
-- [ ] NC-17 <!-- #nc_17 -->
-- [ ] NR/Unrated <!-- #nr -->
-<!-- /field -->
-```
-
-Fields have types defined by the attributes.
-Values are filled in incrementally, just like any form.
-Once filled in, values appear directly inside the tags, in Markdown format:
-
-````markdown
-<!-- field kind="string" id="movie" label="Movie" role="user"
-   required=true minLength=1 maxLength=300 -->
-```value
-The Shawshank Redemption
-```
-<!-- /field -->
-
-<!-- field kind="single_select" id="mpaa_rating" role="agent" label="MPAA Rating" -->
-- [ ] G <!-- #g -->
-- [ ] PG <!-- #pg -->
-- [ ] PG-13 <!-- #pg_13 -->
-- [x] R <!-- #r -->
-- [ ] NC-17 <!-- #nc_17 -->
-- [ ] NR/Unrated <!-- #nr -->
-<!-- /field -->
-````
-
-Note fields can have a `role="user"` to indicate they are filled interactively by the
-user, or a `role="agent"` to indicate an agent should fill them in.
-
-There are also tags for user or agent instructions per field or at form level and
-grouping of forms.
-
-Checkboxes and tables as values are supported!
-Checkboxes can be single-select or multi-select.
-
-Here's a full example (using the alternative Markdoc tag syntax, which also works):
-
-<details>
-
-<summary>Markform for Movie Research Demo (click to expand)</summary>
+A `.form.md` file combines YAML frontmatter with HTML comment tags that define
+structure. The text can be any Markdown.
+Here is the
+[movie-research-demo.form.md](https://github.com/jlevy/markform/blob/main/packages/markform/examples/movie-research/movie-research-demo.form.md):
 
 ```markdown
 ---
@@ -164,142 +61,135 @@ markform:
     agent: |
       Identify the movie with web searches and use imdb.com and rottentomatoes.com to fill in the ratings.
 ---
-{% form id="movie_research_demo" %}
-{% group id="movie_input" %}
+
+<!-- form id="movie_research_demo" -->
+<!-- group id="movie_input" -->
 
 ## What movie do you want to research?
 
-{% field kind="string" id="movie" label="Movie" role="user" required=true minLength=1 maxLength=300 %}{% /field %}
-{% instructions ref="movie" %}Enter the movie title (add year or details for disambiguation).{% /instructions %}
+<!-- field kind="string" id="movie" label="Movie" role="user" required=true minLength=1 maxLength=300 --><!-- /field -->
+<!-- instructions ref="movie" -->Enter the movie title (add year or details for disambiguation).<!-- /instructions -->
 
-{% /group %}
+<!-- /group -->
 
-{% group id="about_the_movie" title="About the Movie" %}
+<!-- group id="about_the_movie" title="About the Movie" -->
 
 ## Movie Ratings
 
 Here are the ratings for the movie:
 
-{% field kind="single_select" id="mpaa_rating" role="agent" label="MPAA Rating" %}
-- [ ] G {% #g %}
-- [ ] PG {% #pg %}
-- [ ] PG-13 {% #pg_13 %}
-- [ ] R {% #r %}
-- [ ] NC-17 {% #nc_17 %}
-- [ ] NR/Unrated {% #nr %}
-{% /field %}
-
-{% field kind="table" id="ratings_table" role="agent"
-   label="Ratings" required=true
-   columnIds=["source", "score", "votes"] columnTypes=["string", "number", "number"]
-   minRows=0 maxRows=3 %}
+<!-- field kind="single_select" id="mpaa_rating" role="agent" label="MPAA Rating" -->
+
+- [ ] G <!-- #g -->
+- [ ] PG <!-- #pg -->
+- [ ] PG-13 <!-- #pg_13 -->
+- [ ] R <!-- #r -->
+- [ ] NC-17 <!-- #nc_17 -->
+- [ ] NR/Unrated <!-- #nr -->
+
+<!-- /field -->
+
+<!-- field kind="table" id="ratings_table" role="agent" label="Ratings" required=true columnIds=["source", "score", "votes"] columnTypes=["string", "number", "number"] minRows=0 maxRows=3 -->
+
 | Source | Score | Votes |
 |--------|-------|-------|
-{% /field %}
 
-{% instructions ref="ratings_table" %}
+<!-- /field -->
+
+<!-- instructions ref="ratings_table" -->
 Fill in scores and vote counts from each source:
 - IMDB: Rating (1.0-10.0 scale), vote count
 - RT Critics: Tomatometer (0-100%), review count
 - RT Audience: Audience Score (0-100%), rating count
-{% /instructions %}
 
-{% /group %}
-{% /form %}
+<!-- /instructions -->
+
+<!-- /group -->
+<!-- /form -->
 ```
 
-</details>
+Fields have types defined by the attributes.
+A field can have `role="user"` (filled interactively) or `role="agent"` (filled by an
+agent). Values are filled in incrementally, just like any form.
 
-### Form Report Output
+### Filled Form
 
-Run `npx markform examples` to copy examples, then `npx markform run` and select `Movie
-Research Demo` to fill it.
+The key point is that with this structure **a Markdown file automatically gets a schema
+and a tool API.**
 
-A form can be exported
+Agents or users can fill in values using a TypeScript API or via agent tool calls.
 
-- as the filled form (Markform format, just like the input)
+And agents find this format **highly context efficient**. All information needed to fill
+in the form is right there, not in long conversation history.
+And it can be done incrementally, a few fields at a time.
 
-- as a report (plain Markdown)
+Once filled in, values appear directly inside the tags, in Markdown format:
 
-- as values (YAML or JSON)
+````markdown
+<!-- form id="movie_research_demo" -->
+<!-- group id="movie_input" -->
 
-- as a JSON schema (just the structure)
+<!-- field kind="string" id="movie" label="Movie" role="user" required=true minLength=1 maxLength=300 -->
+```value
+The Shawshank Redemption
+```
+<!-- /field -->
 
-The report output (using `gpt-5-mini` to fill it in) looks like:
+<!-- /group -->
 
-```markdown
-Movie:
-The Shawshank Redemption
+<!-- group id="about_the_movie" title="About the Movie" -->
 
-## About the Movie
+<!-- field kind="single_select" id="mpaa_rating" role="agent" label="MPAA Rating" -->
 
-MPAA Rating:
-R
+- [ ] G <!-- #g -->
+- [ ] PG <!-- #pg -->
+- [ ] PG-13 <!-- #pg_13 -->
+- [x] R <!-- #r -->
+- [ ] NC-17 <!-- #nc_17 -->
+- [ ] NR/Unrated <!-- #nr -->
+
+<!-- /field -->
+
+<!-- field kind="table" id="ratings_table" role="agent" label="Ratings" required=true columnIds=["source", "score", "votes"] columnTypes=["string", "number", "number"] minRows=0 maxRows=3 -->
 
-Ratings:
 | Source | Score | Votes |
 | --- | --- | --- |
 | IMDB | 9.3 | 3100000 |
 | RT Critics | 89 | 146 |
 | RT Audience | 98 | 250000 |
-```
 
-Here is the schema and YAML values for the form above.
+<!-- /field -->
 
-<details> <summary>Filled Markform (click to expand)</summary>
+<!-- /group -->
+<!-- /form -->
+````
 
-````jinja
-{% form id="movie_research_demo" %}
+### Report Output
 
-{% group id="movie_input" %}
+Run `npx markform examples` to copy examples, then `npx markform run` and select
+`Movie Research Demo` to fill it.
 
-{% field kind="string" id="movie" role="user" label="Movie" maxLength=300 minLength=1 required=true %}
-```value
-The Shawshank Redemption
-```
-{% /field %}
+A form can be exported as the filled form (Markform), as a report (plain Markdown), as
+values (YAML or JSON), or as a JSON Schema (just the structure).
 
-{% instructions ref="movie" %}
-Enter the movie title (add year or details for disambiguation).
-{% /instructions %}
+The report output (using `gpt-5-mini` to fill it in) looks like:
 
-{% /group %}
+```markdown
+Movie:
+The Shawshank Redemption
 
-{% group id="about_the_movie" title="About the Movie" %}
+## About the Movie
 
-{% field kind="single_select" id="mpaa_rating" label="MPAA Rating" %}
-- [ ] G {% #g %}
-- [ ] PG {% #pg %}
-- [ ] PG-13 {% #pg_13 %}
-- [x] R {% #r %}
-- [ ] NC-17 {% #nc_17 %}
-- [ ] NR/Unrated {% #nr %}
-{% /field %}
+MPAA Rating:
+R
 
-{% field kind="table" id="ratings_table"
-  columnIds=["source", "score", "votes"] columnLabels=["Source", "Score", "Votes"]
-  columnTypes=["string", "number", "number"]
-  label="Ratings" maxRows=3 minRows=0 required=true %}
+Ratings:
 | Source | Score | Votes |
 | --- | --- | --- |
 | IMDB | 9.3 | 3100000 |
 | RT Critics | 89 | 146 |
 | RT Audience | 98 | 250000 |
-{% /field %}
-
-{% instructions ref="ratings_table" %}
-Fill in scores and vote counts from each source:
-- IMDB: Rating (1.0-10.0 scale), vote count
-- RT Critics: Tomatometer (0-100%), review count
-- RT Audience: Audience Score (0-100%), rating count
-{% /instructions %}
-
-{% /group %}
-
-{% /form %}
-````
-
-</details>
+```
 
 <details> <summary>YAML Export (click to expand)</summary>
 
@@ -367,6 +257,59 @@ values:
 
 </details>
 
+## Why Do Agents Need Forms?
+
+For centuries, humans have used paper forms and
+[checklists](https://en.wikipedia.org/wiki/The_Checklist_Manifesto) to systematize
+complex processes. A form with instructions, field definitions, and validations is a
+concise way to share context: goals, background knowledge, process rules, and state
+(memory). I don’t think AI changes this essential aspect of knowledge work.
+
+Most agent frameworks focus on *prompts* and *flow* (the how) over the *structure* of
+results (the what).
+But for deep research or other multi-step workflows, you need precise
+control over intermediate states and final output.
+You don’t want that structure in a GUI (not token-friendly), in code (hard to update),
+or dependent on model whims (changes unpredictably with model updates).
+
+Forms solve this. Forms codify operational excellence.
+They’re easy to read, easy to edit, and enforce standards.
+Because LLMs handle Markdown well, agents can also help create and improve the forms
+themselves—closing the meta-loop.
+
+It’s time to bring bureaucracy to the agents!
+See [the FAQ](#faq) for more on the design.
+
+## 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@latest examples
+
+# 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 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+.
+
+```bash
+# As a global CLI
+npm install -g markform
+
+# Or as a project dependency
+npm install markform
+```
+
 ### More Example Forms
 
 The package includes example forms.
@@ -583,8 +526,8 @@ markform --help
 
 ## API Key Setup
 
-Set the appropriate environment variable for your provider before running `markform
-fill`:
+Set the appropriate environment variable for your provider before running
+`markform fill`:
 
 | Provider | Env Variable | Native Web Search |
 | --- | --- | :---: |
@@ -659,19 +602,16 @@ const result = await generateText({
 
 ## Other Documentation
 
-- **[Quick
-  Reference](https://github.com/jlevy/markform/blob/main/docs/markform-reference.md)**
+- **[Quick Reference](https://github.com/jlevy/markform/blob/main/docs/markform-reference.md)**
   (or run `markform docs`) — Concise syntax reference (agent-friendly)
 
 - **[Markform Spec](https://github.com/jlevy/markform/blob/main/docs/markform-spec.md)**
   (or run `markform spec`) — Complete syntax and semantics
 
-- **[API
-  Documentation](https://github.com/jlevy/markform/blob/main/docs/markform-apis.md)**
+- **[API Documentation](https://github.com/jlevy/markform/blob/main/docs/markform-apis.md)**
   (or run `markform apis`) — TypeScript and AI SDK APIs
 
-- **[Design
-  Doc](https://github.com/jlevy/markform/blob/main/docs/project/architecture/current/arch-markform-design.md)**
+- **[Design Doc](https://github.com/jlevy/markform/blob/main/docs/project/architecture/current/arch-markform-design.md)**
   — Technical design and roadmap
 
 - **[Development](https://github.com/jlevy/markform/blob/main/docs/development.md)** —
@@ -732,9 +672,9 @@ But it’s not slop. It is written via a strongly spec-driven process, using rul
 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 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.
 
 Although I didn’t write much code, there was a *lot* of management, review, and
 iteration on design decisions.
@@ -824,12 +764,12 @@ This project uses a dual licensing approach:
 
 - **Markform Specification** ([`docs/markform-spec.md`](docs/markform-spec.md),
   [`docs/markform-reference.md`](docs/markform-reference.md)):
-  [CC-BY-4.0](https://creativecommons.org/licenses/by/4.0/).
-  You may freely implement this specification in your own software under any license.
+  [CC-BY-4.0](https://creativecommons.org/licenses/by/4.0/). You may freely implement
+  this specification in your own software under any license.
 
 - **Reference Implementation** (all code in this repository):
-  [AGPL-3.0-or-later](./LICENSE).
-  [Contact me](https://github.com/jlevy) for commercial licensing options.
+  [AGPL-3.0-or-later](./LICENSE). [Contact me](https://github.com/jlevy) for commercial
+  licensing options.
 
 See [CONTRIBUTING.md](CONTRIBUTING.md) for contribution terms.
 

package/dist/ai-sdk.d.mts

@@ -1,5 +1,5 @@
 
-import { At as PatchSchema, Dt as ParsedForm, Ot as Patch, Q as Id, V as FieldResponse, fr as ValidatorRegistry, q as FormSchema, r as ApplyResult, rt as InspectResult } from "./coreTypes-DE6Giau5.mjs";
+import { At as Patch, Mt as PatchSchema, U as FieldResponse, Y as FormSchema, at as InspectResult, et as Id, kt as ParsedForm, mr as ValidatorRegistry, r as ApplyResult } from "./coreTypes-BMEs8h_2.mjs";
 import { z } from "zod";
 
 //#region src/integrations/toolTypes.d.ts

package/dist/ai-sdk.mjs

@@ -1,6 +1,6 @@
 
-import { L as PatchSchema } from "./coreTypes-DiCddBKu.mjs";
-import { d as serializeForm, i as inspect, t as applyPatches } from "./apply-CXsI5N9x.mjs";
+import { L as PatchSchema } from "./coreTypes-SDB3KRRJ.mjs";
+import { d as serializeForm, i as inspect, t as applyPatches } from "./apply-BYgtU64w.mjs";
 import { z } from "zod";
 
 //#region src/integrations/vercelAiSdkTools.ts