markform 0.1.3 → 0.1.5

package/README.md

@@ -21,6 +21,8 @@ which makes creating new workflows much easier.
 
 ## Installation
 
+Requires Node.js 20+.
+
 ```bash
 # As a global CLI
 npm install -g markform
@@ -29,8 +31,6 @@ npm install -g markform
 npm install markform
 ```
 
-Requires Node.js 20+ (v24 recommended).
-
 ## Quick Start
 
 ```bash
@@ -39,9 +39,12 @@ 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) to have LLMs fill in forms.
+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.
 
-### A Minimal Form
+## Example: Research a Movie
+
+### Form Definition
 
 A `.form.md` file is simply a Markdoc file.
 It combines YAML frontmatter with Markdoc-tagged content:
@@ -63,105 +66,114 @@ markform:
 ---
 {% form id="movie_research_minimal" title="Movie Research (Minimal)" %}
 
-<!-- The first field group is filled in by the user (role="user"): -->
+## Movie Research Example
+
+{% group id="movie_input" title="Movie Identification" %}
 
-{% field-group id="movie_input" title="Movie Identification" %}
+What movie do you want to research? \[*This field is filled in by the user (`role="user"`).*\]
 
-{% string-field id="movie" label="Movie" role="user" required=true minLength=1 maxLength=300 %}{% /string-field %}
+{% 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-group %}
+{% /group %}
+
+## About the Movie
+
+{% group id="about_the_movie" title="About the Movie" %}
+
+**Title:**
+
+{% field kind="string" id="full_title" label="Full Title" role="agent" required=true %}{% /field %}
+{% instructions ref="full_title" %}Official title, including subtitle if any.{% /instructions %}
 
-<!-- Everything else is filled in by the agent (role="agent"): -->
+**Release year:**
 
-{% field-group id="about_the_movie" title="About the Movie" %}
+{% field kind="number" id="year" label="Release Year" role="agent" required=true min=1888 max=2030 %}{% /field %}
 
-{% string-field id="full_title" label="Full Title" role="agent" required=true %}{% /string-field %}
-{% instructions ref="full_title" %}Official title including subtitle if any.{% /instructions %}
+**IMDB:**
 
-{% number-field id="year" label="Release Year" role="agent" required=true min=1888 max=2030 %}{% /number-field %}
+{% field kind="url" id="imdb_url" label="IMDB URL" role="agent" required=true %}{% /field %}
 
-{% url-field id="imdb_url" label="IMDB URL" role="agent" required=true %}{% /url-field %}
+**MPAA rating:**
 
-{% single-select id="mpaa_rating" label="MPAA Rating" role="agent" %}
+{% field kind="single_select" id="mpaa_rating" label="MPAA Rating" role="agent" %}
 - [ ] G {% #g %}
 - [ ] PG {% #pg %}
 - [ ] PG-13 {% #pg_13 %}
 - [ ] R {% #r %}
 - [ ] NC-17 {% #nc_17 %}
 - [ ] NR/Unrated {% #nr %}
-{% /single-select %}
+{% /field %}
 
-{% number-field id="imdb_rating" label="IMDB Rating" role="agent" min=1.0 max=10.0 %}{% /number-field %}
+**IMDB rating:**
+
+{% field kind="number" id="imdb_rating" label="IMDB Rating" role="agent" min=1.0 max=10.0 %}{% /field %}
 {% instructions ref="imdb_rating" %}IMDB user rating (1.0-10.0 scale).{% /instructions %}
 
-{% string-field id="logline" label="One-Line Summary" role="agent" maxLength=300 %}{% /string-field %}
+**Summary:**
+
+{% field kind="string" id="logline" label="One-Line Summary" role="agent" maxLength=300 %}{% /field %}
 {% instructions ref="logline" %}Brief plot summary in 1-2 sentences, no spoilers.{% /instructions %}
 
-{% /field-group %}
+{% /group %}
 
 {% /form %}
 ```
 
-This is the minimal movie research form.
-See the
-[examples/](https://github.com/jlevy/markform/tree/main/packages/markform/examples)
-directory for forms with more fields, including multiple rating sources (IMDB, Rotten
-Tomatoes, Metacritic) and comprehensive analysis.
+### Form Report Output
+
+Run the `npx markform examples` and select the `Movie Research (Minimal)` example and
+view the report:
+
+```markdown
+# Movie Research (Minimal)
+
+## Movie Identification
+
+Movie:
+shawshank redemption
 
-**Key concepts:**
+## About the Movie
 
-- **Roles**: Define who fills what (`user` for humans, `agent` for AI)
+Full Title:
+The Shawshank Redemption
 
-- **Field types**: `string-field`, `number-field`, `url-field`, `string-list`,
-  `single-select`, `multi-select`, `checkboxes`
+Release Year:
+1994
 
-- **Validation**: `required`, `min/max`, `minLength/maxLength`, `pattern`
+IMDB URL:
+https://www.imdb.com/title/tt0111161/
 
-- **Structure**: Fields organized in `field-group` containers
+MPAA Rating:
+R
 
-- **Instructions**: Per-field guidance for users or agents
+IMDB Rating:
+9.3
+
+One-Line Summary:
+Convicted banker Andy Dufresne is sent to Shawshank State Penitentiary, where he forms an unexpected friendship with inmate Red while holding onto hope and striving to maintain his dignity in a corrupt prison system.
+```
 
 ### More Example Forms
 
 The package includes example forms in
-[`examples/`](https://github.com/jlevy/markform/tree/main/packages/markform/examples):
+[`examples/`](https://github.com/jlevy/markform/tree/main/packages/markform/examples).
+View them with `markform examples --list` or try these interactively:
 
 - [`movie-research/movie-research-minimal.form.md`](https://github.com/jlevy/markform/blob/main/packages/markform/examples/movie-research/movie-research-minimal.form.md)
-  \- Quick movie lookup (title, year, rating)
+  \- 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)
-  \- Standard research with IMDB, Rotten Tomatoes, Metacritic
+  \- 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)
-  \- Comprehensive analysis with streaming, box office
+  \- 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 types
+  \- 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)
-  \- Financial analysis form
-
-View them with `markform examples --list` or try them interactively.
-
-## Supported Providers
-
-Standard LLMs can be used to fill in forms or create research reports from form
-templates. The package currently has support for these models built in, and enables web
-search tools for them if possible.
-
-| Provider | Env Variable | Example Models |
-| --- | --- | --- |
-| openai | `OPENAI_API_KEY` | gpt-5-mini, gpt-5.1, gpt-5.2 |
-| anthropic | `ANTHROPIC_API_KEY` | claude-sonnet-4-5, claude-opus-4-5 |
-| google | `GOOGLE_API_KEY` | gemini-2.5-pro, gemini-2.5-flash |
-| xai | `XAI_API_KEY` | grok-4, grok-4-fast |
-| deepseek | `DEEPSEEK_API_KEY` | deepseek-chat, deepseek-reasoner |
-
-Set the appropriate environment variable for your provider before running `markform
-fill`. See
-[`src/settings.ts`](https://github.com/jlevy/markform/blob/main/packages/markform/src/settings.ts)
-for the full list of models.
+  \- Financial analysis form.
 
 ## Why?
 
@@ -250,9 +262,12 @@ markform serve my-form.form.md
 # Quick reference for writing forms (agent-friendly)
 markform docs
 
-# Full specification (SPEC.md)
+# Full specification
 markform spec
 
+# TypeScript and AI SDK API documentation
+markform apis
+
 # This README
 markform readme
 
@@ -263,6 +278,25 @@ markform models
 markform --help
 ```
 
+## Supported Providers
+
+Standard LLMs can be used to fill in forms or create research reports from form
+templates. The package currently has support for these models built in, and enables web
+search tools for them if possible.
+
+| Provider | Env Variable | Example Models |
+| --- | --- | --- |
+| openai | `OPENAI_API_KEY` | gpt-5-mini, gpt-5.1, gpt-5.2 |
+| anthropic | `ANTHROPIC_API_KEY` | claude-sonnet-4-5, claude-opus-4-5 |
+| google | `GOOGLE_API_KEY` | gemini-2.5-pro, gemini-2.5-flash |
+| xai | `XAI_API_KEY` | grok-4, grok-4-fast |
+| deepseek | `DEEPSEEK_API_KEY` | deepseek-chat, deepseek-reasoner |
+
+Set the appropriate environment variable for your provider before running `markform
+fill`. See
+[`src/settings.ts`](https://github.com/jlevy/markform/blob/main/packages/markform/src/settings.ts)
+for the full list of models.
+
 ## Architecture
 
 ```mermaid
@@ -270,7 +304,7 @@ flowchart LR
     subgraph SPEC["<b>MARKFORM SPEC</b>"]
         direction TB
 
-        subgraph L1["<b>LAYER 1: SYNTAX</b><br/>Markdoc tag syntax and frontmatter (form, field-group, string-field, checkboxes, etc.)"]
+        subgraph L1["<b>LAYER 1: SYNTAX</b><br/>Markdoc tag syntax and frontmatter (form, group, string-field, checkboxes, etc.)"]
         end
 
         subgraph L2["<b>LAYER 2: FORM DATA MODEL</b><br/>Schema definitions for forms, fields, values (in Zod but mappable to JSON Schema or Pydantic)"]
@@ -391,7 +425,8 @@ But it’s been useful for me already.
 
 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](SPEC.md) and the architecture docs and specs in [docs/](docs/).
+See [the spec](docs/markform-spec.md) and the architecture docs and specs in
+[docs/](docs/).
 
 ### What are the goals of Markform?
 
@@ -446,12 +481,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 | Human-readable | Agent-editable | Custom validations |
-| --- | :---: | :---: | :---: |
-| Plain Markdown | ✅ | ⚠️ fragile | ❌ |
-| JSON Schema | ❌ | ✅ | ✅ |
-| PDF Forms, SaaS tools | ⚠️ | ❌ | ⚠️ |
-| **Markform** | ✅ | ✅ | ✅ |
+| Approach | Has GUI | Human-readable text format | Agent-editable | APIs and validation rules |
+| --- | :---: | :---: | :---: | :---: |
+| Plain Markdown | ☑️ existing tools | ✅ | ⚠️ fragile | ❌ |
+| JSON with schema | ☑️ existing tools | ⚠️ hey 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 | ✅ | ✅ | ✅ |
 
 ### What are example use cases?
 
@@ -496,11 +532,15 @@ Or see [markdoc/language-server](https://github.com/markdoc/language-server).
 ## Documentation
 
 - **[Quick
-  Reference](https://github.com/jlevy/markform/blob/main/packages/markform/DOCS.md)**
+  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/SPEC.md)** (or run
-  `markform spec`) - Complete syntax and semantics
+- **[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)**
+  (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)**

package/dist/ai-sdk.d.mts

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 
-import { H as Id, L as FormSchema, Sn as ValidatorRegistry, _t as ParsedForm, j as FieldResponse, q as InspectResult, r as ApplyResult, vt as Patch, yt as PatchSchema } from "./coreTypes-BXhhz9Iq.mjs";
+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 { z } from "zod";
 
 //#region src/integrations/toolTypes.d.ts
@@ -62,7 +62,7 @@ interface MarkformToolSet {
   markform_get_markdown?: MarkformTool<Record<string, never>, GetMarkdownToolResult>;
 }
 //#endregion
-//#region src/integrations/ai-sdk.d.ts
+//#region src/integrations/vercelAiSdkTools.d.ts
 /**
  * Session store for managing form state during AI interactions.
  *

package/dist/ai-sdk.mjs

@@ -1,8 +1,8 @@
-import { N as PatchSchema } from "./coreTypes-Dful87E0.mjs";
-import { r as inspect, t as applyPatches, u as serialize } from "./apply-00UmzDKL.mjs";
+import { L as PatchSchema } from "./coreTypes-pyctKRgc.mjs";
+import { r as inspect, t as applyPatches, u as serialize } from "./apply-BCCiJzQr.mjs";
 import { z } from "zod";
 
-//#region src/integrations/ai-sdk.ts
+//#region src/integrations/vercelAiSdkTools.ts
 /**
 * AI SDK Integration for Markform.
 *
@@ -63,7 +63,7 @@ const InspectInputSchema = z.object({}).describe("No input parameters required.
 /**
 * Input schema for markform_apply tool.
 */
-const ApplyInputSchema = z.object({ patches: z.array(PatchSchema).min(1).max(20).describe("Array of patches to apply to the form. Each patch sets or clears a field value. Operations: set_string, set_number, set_string_list, set_single_select, set_multi_select, set_checkboxes, clear_field. Example: [{ \"op\": \"set_string\", \"fieldId\": \"name\", \"value\": \"Alice\" }]") }).describe("Apply patches to update form field values.");
+const ApplyInputSchema = z.object({ patches: z.array(PatchSchema).min(1).max(20).describe("Array of patches to apply to the form. Each patch sets or clears a field value. Operations: set_string, set_number, set_string_list, set_single_select, set_multi_select, set_checkboxes, set_url, set_url_list, set_date, set_year, set_table, clear_field, skip_field, abort_field. Example: [{ \"op\": \"set_string\", \"fieldId\": \"name\", \"value\": \"Alice\" }]") }).describe("Apply patches to update form field values.");
 /**
 * Input schema for markform_export tool (no parameters).
 */
@@ -115,7 +115,7 @@ function createMarkformTools(options) {
 			}
 		},
 		markform_apply: {
-			description: "Apply patches to update form field values. Use this after inspecting the form to set values for fields that need to be filled. Patches are applied as a transaction - all succeed or all fail. Returns the updated form state and any remaining issues. Patch operations: set_string, set_number, set_string_list, set_single_select, set_multi_select, set_checkboxes, clear_field.",
+			description: "Apply patches to update form field values. Use this after inspecting the form to set values for fields that need to be filled. Patches are applied as a transaction - all succeed or all fail. Returns the updated form state and any remaining issues. Patch operations: set_string, set_number, set_string_list, set_single_select, set_multi_select, set_checkboxes, set_url, set_url_list, set_date, set_year, set_table, clear_field, skip_field, abort_field.",
 			inputSchema: ApplyInputSchema,
 			execute: ({ patches }) => {
 				const form = sessionStore.getForm();