markform 0.1.4 → 0.1.6

package/README.md

@@ -1,47 +1,73 @@
 # 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?
 
-## Installation
+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).
 
-```bash
-# As a global CLI
-npm install -g markform
+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.
 
-# Or as a project dependency
-npm install markform
-```
+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.
 
-Requires Node.js 20+ (v24 recommended).
+(For more, see [the FAQ](#faq).)
 
 ## Quick Start
 
 ```bash
-# Try it without installing
+# Try filling in one of a few example forms without installing.
+# First set OPENAI_API_KEY or ANTHROPIC_API_KEY in environment or .env file
+# to try the research examples.
 npx markform examples
+
+# Read the docs
+npx markform  # CLI help
+npx markform readme   # This file
+npx markform docs  # Quick start for humans or agents to write Markforms
+npx markform spec  # Read the full spec
+```
+
+This lets you walk through a form interactively from the CLI, with the option to have an
+agent fill in parts of the form.
+
+## Installation
+
+Requires Node.js 20+.
+
+```bash
+# As a global CLI
+npm install -g markform
+
+# Or as a project dependency
+npm install markform
 ```
 
-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.
+## Example: Research a Movie
 
-### A Minimal Form
+### Form Definition
 
 A `.form.md` file is simply a Markdoc file.
 It combines YAML frontmatter with Markdoc-tagged content:
@@ -65,18 +91,18 @@ markform:
 
 ## Movie Research Example
 
-{% field-group id="movie_input" title="Movie Identification" %}
+{% group id="movie_input" title="Movie Identification" %}
 
 What movie do you want to research? \[*This field is filled in by the user (`role="user"`).*\]
 
 {% 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
 
-{% field-group id="about_the_movie" title="About the Movie" %}
+{% group id="about_the_movie" title="About the Movie" %}
 
 **Title:**
 
@@ -112,11 +138,13 @@ What movie do you want to research? \[*This field is filled in by the user (`rol
 {% 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 %}
 ```
 
+### Form Report Output
+
 Run the `npx markform examples` and select the `Movie Research (Minimal)` example and
 view the report:
 
@@ -149,76 +177,25 @@ 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.
 ```
 
-See the
-[examples/](https://github.com/jlevy/markform/tree/main/packages/markform/examples)
-directory for a few more complex form examples.
-
-**Key concepts:**
-
-- **Roles**: Define who fills what (`user` for humans, `agent` for AI)
-
-- **Field kinds**: `string-field`, `number-field`, `date-field`, `year-field`,
-  `url-field`, `url-list`, `string-list`, `single-select`, `multi-select`, `checkboxes`
-
-- **Validation**: `required`, `min/max`, `minLength/maxLength`, `pattern`
-
-- **Structure**: Fields organized in `field-group` containers
-
-- **Instructions**: Per-field guidance for users or agents
-
 ### More Example Forms
 
-The package includes example forms in
-[`examples/`](https://github.com/jlevy/markform/tree/main/packages/markform/examples):
-
-- [`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)
-
-- [`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
-
-- [`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
-
-- [`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)
-  \- 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.
+The package includes example forms.
+View them with `markform examples --list` or try these interactively:
 
-| 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 |
+- [`simple.form.md`](https://github.com/jlevy/markform/blob/main/packages/markform/examples/simple/simple.form.md)
+  \- Basic form demonstrating all field kinds.
 
-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.
+- [`movie-research-minimal.form.md`](https://github.com/jlevy/markform/blob/main/packages/markform/examples/movie-research/movie-research-minimal.form.md)
+  \- The quick example above.
 
-## Why?
+- [`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.
 
-Many agent workflow frameworks emphasize the *flow* of information (the *how*) over its
-*structure* (the *what*). But the *how* is constantly changing.
+- [`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.
 
-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.
+- [`earnings-analysis.form.md`](https://github.com/jlevy/markform/blob/main/packages/markform/examples/earnings-analysis/earnings-analysis.form.md)
+  \- Financial analysis form.
 
 ## CLI Commands
 
@@ -310,6 +287,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
@@ -317,7 +313,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)"]
@@ -428,6 +424,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.
@@ -480,7 +489,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
@@ -494,13 +504,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,6 @@
 #!/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-cbNTYAcb.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

package/dist/ai-sdk.mjs

@@ -1,5 +1,5 @@
 import { L as PatchSchema } from "./coreTypes-pyctKRgc.mjs";
-import { r as inspect, t as applyPatches, u as serialize } from "./apply-C54EMAJ1.mjs";
+import { r as inspect, t as applyPatches, u as serialize } from "./apply-DMQl-VVd.mjs";
 import { z } from "zod";
 
 //#region src/integrations/vercelAiSdkTools.ts

package/dist/{apply-C54EMAJ1.mjs → apply-DMQl-VVd.mjs}

@@ -1,5 +1,3 @@
-import { resolve } from "node:path";
-
 //#region src/llms.ts
 /**
 * Parse a model ID string into provider and model components for display.
@@ -113,13 +111,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 +156,14 @@ 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
+* The default port for the serve command.
 */
-function getFormsDir(override, cwd = process.cwd()) {
-	return resolve(cwd, override ?? DEFAULT_FORMS_DIR);
-}
+const DEFAULT_PORT = 3344;
 /**
 * Default maximum turns for the fill harness.
 * Prevents runaway loops during agent execution.
@@ -811,7 +791,7 @@ function serializeNotes(notes) {
 /**
 * Serialize a field group.
 * Implicit groups (fields placed directly under the form) are serialized
-* without the field-group wrapper tags.
+* without the group wrapper tags.
 */
 function serializeFieldGroup(group, responses, docs) {
 	const lines = [];
@@ -821,7 +801,7 @@ function serializeFieldGroup(group, responses, docs) {
 		if (group.validate) attrs.validate = group.validate;
 		if (group.report !== void 0) attrs.report = group.report;
 		const attrStr = serializeAttrs(attrs);
-		lines.push(`{% field-group ${attrStr} %}`);
+		lines.push(`{% group ${attrStr} %}`);
 	}
 	const docsByRef = /* @__PURE__ */ new Map();
 	for (const doc of docs) {
@@ -840,7 +820,7 @@ function serializeFieldGroup(group, responses, docs) {
 	}
 	if (!group.implicit) {
 		lines.push("");
-		lines.push("{% /field-group %}");
+		lines.push("{% /group %}");
 	}
 	return lines.join("\n");
 }
@@ -2824,4 +2804,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 { SUGGESTED_LLMS as A, DEFAULT_ROLE_INSTRUCTIONS as C, deriveReportPath as D, deriveExportPath as E, parseModelIdForDisplay as F, formatSuggestedLlms as M, getWebSearchConfig as N, detectFileType as O, hasWebSearchSupport 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, WEB_SEARCH_CONFIG as j, parseRolesFlag 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 };

package/dist/bin.mjs

@@ -1,10 +1,10 @@
 #!/usr/bin/env node
 import "./coreTypes-pyctKRgc.mjs";
-import "./apply-C54EMAJ1.mjs";
-import "./src-BNh7Cx9P.mjs";
+import "./apply-DMQl-VVd.mjs";
+import "./src-o_5TSoHQ.mjs";
 import "./session-uF0e6m6k.mjs";
-import "./shared-BqPnYXrn.mjs";
-import { t as runCli } from "./cli-BhWhn6L9.mjs";
+import { t as runCli } from "./cli-CXjkdym_.mjs";
+import "./shared-DRlgu2ZJ.mjs";
 import { resolve } from "node:path";
 import { existsSync } from "node:fs";
 import { config } from "dotenv";

package/dist/{cli-BhWhn6L9.mjs → cli-CXjkdym_.mjs}

@@ -1,12 +1,12 @@
 import { L as PatchSchema } from "./coreTypes-pyctKRgc.mjs";
-import { A as parseRolesFlag, D as deriveReportPath, E as deriveExportPath, F as hasWebSearchSupport, I as parseModelIdForDisplay, M as WEB_SEARCH_CONFIG, N as formatSuggestedLlms, O as detectFileType, T as USER_ROLE, _ as DEFAULT_MAX_TURNS, b as DEFAULT_RESEARCH_MAX_ISSUES_PER_TURN, d as serializeRawMarkdown, f as serializeReportMarkdown, g as DEFAULT_MAX_PATCHES_PER_TURN, h as DEFAULT_MAX_ISSUES_PER_TURN, j as SUGGESTED_LLMS, k as getFormsDir, m as DEFAULT_FORMS_DIR, p as AGENT_ROLE, r as inspect, t as applyPatches, u as serialize, v as DEFAULT_PORT, w as REPORT_EXTENSION, x as DEFAULT_RESEARCH_MAX_PATCHES_PER_TURN } from "./apply-C54EMAJ1.mjs";
-import { a as resolveHarnessConfig, c as getProviderNames, f as createMockAgent, i as runResearch, l as resolveModel, m as createHarness, s as getProviderInfo, t as VERSION, u as createLiveAgent, w as parseForm } from "./src-BNh7Cx9P.mjs";
+import { A as SUGGESTED_LLMS, D as deriveReportPath, E as deriveExportPath, F as parseModelIdForDisplay, M as formatSuggestedLlms, O as detectFileType, P as hasWebSearchSupport, T as USER_ROLE, _ as DEFAULT_MAX_TURNS, b as DEFAULT_RESEARCH_MAX_ISSUES_PER_TURN, d as serializeRawMarkdown, f as serializeReportMarkdown, g as DEFAULT_MAX_PATCHES_PER_TURN, h as DEFAULT_MAX_ISSUES_PER_TURN, j as WEB_SEARCH_CONFIG, k as parseRolesFlag, m as DEFAULT_FORMS_DIR, p as AGENT_ROLE, r as inspect, t as applyPatches, u as serialize, v as DEFAULT_PORT, w as REPORT_EXTENSION, x as DEFAULT_RESEARCH_MAX_PATCHES_PER_TURN } from "./apply-DMQl-VVd.mjs";
+import { a as resolveHarnessConfig, c as getProviderNames, f as createMockAgent, i as runResearch, l as resolveModel, m as createHarness, s as getProviderInfo, t as VERSION, u as createLiveAgent, w as parseForm } from "./src-o_5TSoHQ.mjs";
 import { n as serializeSession } from "./session-uF0e6m6k.mjs";
-import { a as formatPath, c as logError, d as logTiming, f as logVerbose, g as writeFile, 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-BqPnYXrn.mjs";
+import { a as formatPath, c as logError, d as logTiming, f as logVerbose, g as writeFile, 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-DRlgu2ZJ.mjs";
 import YAML from "yaml";
-import { basename, dirname, join, resolve } from "node:path";
 import { Command } from "commander";
 import pc from "picocolors";
+import { basename, dirname, join, resolve } from "node:path";
 import { existsSync, readFileSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 import { readFile } from "node:fs/promises";
@@ -14,6 +14,27 @@ import * as p from "@clack/prompts";
 import { exec, spawn } from "node:child_process";
 import { createServer } from "node:http";
 
+//#region src/cli/lib/paths.ts
+/**
+* Path utilities for CLI commands.
+*
+* This module contains Node.js-dependent path utilities that are only used
+* by CLI code. Keeping these separate from settings.ts allows the core
+* library to remain Node.js-free.
+*/
+/**
+* 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
+*/
+function getFormsDir(override, cwd = process.cwd()) {
+	return resolve(cwd, override ?? DEFAULT_FORMS_DIR);
+}
+
+//#endregion
 //#region src/cli/commands/apis.ts
 /**
 * Get the path to the markform-apis.md file.
@@ -684,12 +705,6 @@ const EXAMPLE_DEFINITIONS = [
 		filename: "startup-deep-research.form.md",
 		path: "startup-deep-research/startup-deep-research.form.md",
 		type: "research"
-	},
-	{
-		id: "celebrity-deep-research",
-		filename: "celebrity-deep-research.form.md",
-		path: "celebrity-deep-research/celebrity-deep-research.form.md",
-		type: "research"
 	}
 ];
 /**
@@ -703,7 +718,7 @@ function getExamplesDir() {
 }
 /**
 * Load the content of an example form.
-* @param exampleId - The example ID (e.g., 'simple', 'celebrity-deep-research')
+* @param exampleId - The example ID (e.g., 'simple', 'movie-research-deep')
 * @returns The form content as a string
 * @throws Error if the example is not found
 */
@@ -725,7 +740,7 @@ function getExampleById(id) {
 }
 /**
 * Get the absolute path to an example's source file.
-* @param exampleId - The example ID (e.g., 'simple', 'celebrity-deep-research')
+* @param exampleId - The example ID (e.g., 'simple', 'movie-research-deep')
 * @returns The absolute path to the example form file
 * @throws Error if the example is not found
 */
@@ -750,7 +765,7 @@ function extractFrontmatter(content) {
 }
 /**
 * Load metadata (title, description) from an example's YAML frontmatter.
-* @param exampleId - The example ID (e.g., 'simple', 'celebrity-deep-research')
+* @param exampleId - The example ID (e.g., 'simple', 'movie-research-deep')
 * @returns Object with title and description from frontmatter
 */
 function loadExampleMetadata(exampleId) {
@@ -2107,6 +2122,39 @@ function registerExportCommand(program) {
 	});
 }
 
+//#endregion
+//#region src/cli/lib/fillCallbacks.ts
+/**
+* Create FillCallbacks for CLI commands.
+*
+* Provides spinner feedback during tool execution (especially web search).
+* Only implements tool callbacks - turn/LLM callbacks are handled by CLI's
+* own logging which has richer context.
+*
+* @param spinner - Active spinner handle to update
+* @param ctx - Command context for verbose logging
+* @returns FillCallbacks with onToolStart and onToolEnd
+*
+* @example
+* ```typescript
+* const spinner = createSpinner({ type: 'api', provider, model });
+* const callbacks = createCliToolCallbacks(spinner, ctx);
+* const agent = createLiveAgent({ model, callbacks, ... });
+* ```
+*/
+function createCliToolCallbacks(spinner, ctx) {
+	return {
+		onToolStart: ({ name }) => {
+			if (name.includes("search")) spinner.message(`🔍 Web search...`);
+			logVerbose(ctx, `  Tool started: ${name}`);
+		},
+		onToolEnd: ({ name, durationMs, error }) => {
+			if (error) logVerbose(ctx, `  Tool ${name} failed: ${error} (${durationMs}ms)`);
+			else logVerbose(ctx, `  Tool ${name} completed (${durationMs}ms)`);
+		}
+	};
+}
+
 //#endregion
 //#region src/cli/commands/fill.ts
 /**
@@ -2249,6 +2297,7 @@ function registerFillCommand(program) {
 			let mockPath;
 			let agentProvider;
 			let agentModelName;
+			let currentSpinner = null;
 			if (options.mock) {
 				mockPath = resolve(options.mockSource);
 				logVerbose(ctx, `Reading mock source: ${mockPath}`);
@@ -2268,13 +2317,21 @@ function registerFillCommand(program) {
 					logVerbose(ctx, `Reading system prompt from: ${promptPath}`);
 					systemPrompt = await readFile$1(promptPath);
 				}
+				const callbacks = createCliToolCallbacks({
+					message: (msg) => currentSpinner?.message(msg),
+					update: (context) => currentSpinner?.update(context),
+					stop: (msg) => currentSpinner?.stop(msg),
+					error: (msg) => currentSpinner?.error(msg),
+					getElapsedMs: () => currentSpinner?.getElapsedMs() ?? 0
+				}, ctx);
 				const primaryRole = targetRoles[0] === "*" ? AGENT_ROLE : targetRoles[0];
 				const liveAgent = createLiveAgent({
 					model,
 					provider,
 					systemPromptAddition: systemPrompt,
 					targetRole: primaryRole,
-					enableWebSearch: true
+					enableWebSearch: true,
+					callbacks
 				});
 				agent = liveAgent;
 				logInfo(ctx, `Available tools: ${liveAgent.getAvailableToolNames().join(", ")}`);
@@ -2291,18 +2348,23 @@ function registerFillCommand(program) {
 			logInfo(ctx, `${pc.bold(`Turn ${stepResult.turnNumber}:`)} ${formatTurnIssues(stepResult.issues)}`);
 			while (!stepResult.isComplete && !harness.hasReachedMaxTurns()) {
 				let spinner = null;
-				if (!options.mock && agentProvider && agentModelName && process.stdout.isTTY && !ctx.quiet) spinner = createSpinner({
-					type: "api",
-					provider: agentProvider,
-					model: agentModelName,
-					turnNumber: stepResult.turnNumber
-				});
+				if (!options.mock && agentProvider && agentModelName && process.stdout.isTTY && !ctx.quiet) {
+					spinner = createSpinner({
+						type: "api",
+						provider: agentProvider,
+						model: agentModelName,
+						turnNumber: stepResult.turnNumber
+					});
+					currentSpinner = spinner;
+				}
 				let response;
 				try {
 					response = await agent.generatePatches(stepResult.issues, harness.getForm(), harnessConfig.maxPatchesPerTurn);
 					spinner?.stop();
+					currentSpinner = null;
 				} catch (error) {
 					spinner?.error("LLM call failed");
+					currentSpinner = null;
 					throw error;
 				}
 				const { patches, stats } = response;
@@ -4043,7 +4105,7 @@ function registerResearchCommand(program) {
 			if (options.transcript && result.transcript) {
 				const { serializeSession: serializeSession$1 } = await import("./session-B_stoXQn.mjs");
 				const transcriptPath = outputPath.replace(/\.form\.md$/, ".session.yaml");
-				const { writeFile: writeFile$1 } = await import("./shared-CZsyShck.mjs");
+				const { writeFile: writeFile$1 } = await import("./shared-u22MtBRo.mjs");
 				await writeFile$1(transcriptPath, serializeSession$1(result.transcript));
 				logInfo(ctx, `Transcript: ${transcriptPath}`);
 			}

package/dist/cli.mjs

@@ -1,8 +1,8 @@
 import "./coreTypes-pyctKRgc.mjs";
-import "./apply-C54EMAJ1.mjs";
-import "./src-BNh7Cx9P.mjs";
+import "./apply-DMQl-VVd.mjs";
+import "./src-o_5TSoHQ.mjs";
 import "./session-uF0e6m6k.mjs";
-import "./shared-BqPnYXrn.mjs";
-import { t as runCli } from "./cli-BhWhn6L9.mjs";
+import { t as runCli } from "./cli-CXjkdym_.mjs";
+import "./shared-DRlgu2ZJ.mjs";
 
 export { runCli };

package/dist/{coreTypes-cbNTYAcb.d.mts → coreTypes-9XZSNOv6.d.mts}

@@ -195,8 +195,8 @@ interface FieldGroup {
   report?: boolean;
   /**
    * True if this group was implicitly created for fields placed directly
-   * under the form (not wrapped in an explicit field-group).
-   * Implicit groups are serialized without field-group wrapper tags.
+   * under the form (not wrapped in an explicit group).
+   * Implicit groups are serialized without group wrapper tags.
    */
   implicit?: boolean;
 }