markform 0.1.4 → 0.1.6

package/dist/index.d.mts

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 
-import { $ as InspectIssue, $n as ValidationIssue, $t as SetStringListPatch, A as ExplicitCheckboxValueSchema, An as StringListValueSchema, At as ProgressState, B as FieldResponseSchema, Bn as TableRowPatchSchema, Bt as SessionTurn, C as DateValue, Cn as StepResult, Ct as OptionIdSchema, D as DocumentationTag, Dn as StringListField, Dt as PatchSchema, E as DocumentationBlockSchema, En as StringFieldSchema, Et as Patch, F as FieldKind, Fn as TableColumn, Ft as QualifiedOptionRef, G as FormSchema, Gn as UrlField, Gt as SetDatePatch, H as FieldValue, Hn as TableRowResponseSchema, Ht as SessionTurnStats, I as FieldKindSchema, In as TableColumnSchema, It as SessionFinal, J as HarnessConfig, Jn as UrlListFieldSchema, Jt as SetMultiSelectPatchSchema, K as FormSchemaSchema, Kn as UrlFieldSchema, Kt as SetDatePatchSchema, L as FieldProgress, Ln as TableField, Lt as SessionFinalSchema, M as FieldBase, Mn as StringValueSchema, Mt as ProgressSummary, N as FieldGroup, Nn as StructureSummary, Nt as ProgressSummarySchema, O as DocumentationTagSchema, On as StringListFieldSchema, Ot as ProgressCounts, P as FieldGroupSchema, Pn as StructureSummarySchema, Pt as QualifiedColumnRef, Q as IdSchema, Qn as UrlValueSchema, Qt as SetSingleSelectPatchSchema, R as FieldProgressSchema, Rn as TableFieldSchema, Rt as SessionTranscript, S as DateFieldSchema, Sn as SourceRangeSchema, St as OptionId, T as DocumentationBlock, Tn as StringField, Tt as ParsedForm, U as FieldValueSchema, Un as TableValue, Ut as SetCheckboxesPatch, V as FieldSchema, Vn as TableRowResponse, Vt as SessionTurnSchema, W as FillMode, Wn as TableValueSchema, Wt as SetCheckboxesPatchSchema, X as Id, Xn as UrlListValueSchema, Xt as SetNumberPatchSchema, Y as HarnessConfigSchema, Yn as UrlListValue, Yt as SetNumberPatch, Z as IdIndexEntry, Zn as UrlValue, Zt as SetSingleSelectPatch, _ as ClearFieldPatch, _n as SingleSelectValue, _t as NumberField, a as CellResponse, an as SetUrlListPatch, ar as ValidatorRegistry, at as IssueScope, b as ColumnTypeNameSchema, bn as SourcePositionSchema, bt as NumberValueSchema, c as CheckboxModeSchema, cn as SetUrlPatchSchema, cr as YearValue, ct as MarkformFrontmatterSchema, d as CheckboxValue, dn as Severity, dt as MultiSelectField, en as SetStringListPatchSchema, er as ValidationIssueSchema, et as InspectIssueSchema, f as CheckboxValueSchema, fn as SeveritySchema, ft as MultiSelectFieldSchema, g as CheckboxesValueSchema, gn as SingleSelectFieldSchema, gt as Note, h as CheckboxesValue, hn as SingleSelectField, ht as NodeType, i as ApplyResultSchema, in as SetTablePatchSchema, ir as ValidatorRefSchema, it as IssueReasonSchema, j as Field, jn as StringValue, jt as ProgressStateSchema, k as ExplicitCheckboxValue, kn as StringListValue, kt as ProgressCountsSchema, l as CheckboxProgressCounts, ln as SetYearPatch, lr as YearValueSchema, lt as MultiCheckboxState, m as CheckboxesFieldSchema, mn as SimpleCheckboxStateSchema, mt as MultiSelectValueSchema, n as AnswerStateSchema, nn as SetStringPatchSchema, nr as ValidatorFn, nt as InspectResultSchema, o as CellResponseSchema, on as SetUrlListPatchSchema, or as YearField, ot as IssueScopeSchema, p as CheckboxesField, pn as SimpleCheckboxState, pt as MultiSelectValue, q as FrontmatterHarnessConfig, qn as UrlListField, qt as SetMultiSelectPatch, r as ApplyResult, rn as SetTablePatch, rr as ValidatorRef, rt as IssueReason, s as CheckboxMode, sn as SetUrlPatch, sr as YearFieldSchema, st as MarkformFrontmatter, t as AnswerState, tn as SetStringPatch, tr as ValidatorContext, tt as InspectResult, u as CheckboxProgressCountsSchema, un as SetYearPatchSchema, ut as MultiCheckboxStateSchema, v as ClearFieldPatchSchema, vn as SingleSelectValueSchema, vt as NumberFieldSchema, w as DateValueSchema, wn as StepResultSchema, wt as OptionSchema, x as DateField, xn as SourceRange, xt as Option, y as ColumnTypeName, yn as SourcePosition, yt as NumberValue, z as FieldResponse, zn as TableRowPatch, zt as SessionTranscriptSchema } from "./coreTypes-cbNTYAcb.mjs";
+import { $ as InspectIssue, $n as ValidationIssue, $t as SetStringListPatch, A as ExplicitCheckboxValueSchema, An as StringListValueSchema, At as ProgressState, B as FieldResponseSchema, Bn as TableRowPatchSchema, Bt as SessionTurn, C as DateValue, Cn as StepResult, Ct as OptionIdSchema, D as DocumentationTag, Dn as StringListField, Dt as PatchSchema, E as DocumentationBlockSchema, En as StringFieldSchema, Et as Patch, F as FieldKind, Fn as TableColumn, Ft as QualifiedOptionRef, G as FormSchema, Gn as UrlField, Gt as SetDatePatch, H as FieldValue, Hn as TableRowResponseSchema, Ht as SessionTurnStats, I as FieldKindSchema, In as TableColumnSchema, It as SessionFinal, J as HarnessConfig, Jn as UrlListFieldSchema, Jt as SetMultiSelectPatchSchema, K as FormSchemaSchema, Kn as UrlFieldSchema, Kt as SetDatePatchSchema, L as FieldProgress, Ln as TableField, Lt as SessionFinalSchema, M as FieldBase, Mn as StringValueSchema, Mt as ProgressSummary, N as FieldGroup, Nn as StructureSummary, Nt as ProgressSummarySchema, O as DocumentationTagSchema, On as StringListFieldSchema, Ot as ProgressCounts, P as FieldGroupSchema, Pn as StructureSummarySchema, Pt as QualifiedColumnRef, Q as IdSchema, Qn as UrlValueSchema, Qt as SetSingleSelectPatchSchema, R as FieldProgressSchema, Rn as TableFieldSchema, Rt as SessionTranscript, S as DateFieldSchema, Sn as SourceRangeSchema, St as OptionId, T as DocumentationBlock, Tn as StringField, Tt as ParsedForm, U as FieldValueSchema, Un as TableValue, Ut as SetCheckboxesPatch, V as FieldSchema, Vn as TableRowResponse, Vt as SessionTurnSchema, W as FillMode, Wn as TableValueSchema, Wt as SetCheckboxesPatchSchema, X as Id, Xn as UrlListValueSchema, Xt as SetNumberPatchSchema, Y as HarnessConfigSchema, Yn as UrlListValue, Yt as SetNumberPatch, Z as IdIndexEntry, Zn as UrlValue, Zt as SetSingleSelectPatch, _ as ClearFieldPatch, _n as SingleSelectValue, _t as NumberField, a as CellResponse, an as SetUrlListPatch, ar as ValidatorRegistry, at as IssueScope, b as ColumnTypeNameSchema, bn as SourcePositionSchema, bt as NumberValueSchema, c as CheckboxModeSchema, cn as SetUrlPatchSchema, cr as YearValue, ct as MarkformFrontmatterSchema, d as CheckboxValue, dn as Severity, dt as MultiSelectField, en as SetStringListPatchSchema, er as ValidationIssueSchema, et as InspectIssueSchema, f as CheckboxValueSchema, fn as SeveritySchema, ft as MultiSelectFieldSchema, g as CheckboxesValueSchema, gn as SingleSelectFieldSchema, gt as Note, h as CheckboxesValue, hn as SingleSelectField, ht as NodeType, i as ApplyResultSchema, in as SetTablePatchSchema, ir as ValidatorRefSchema, it as IssueReasonSchema, j as Field, jn as StringValue, jt as ProgressStateSchema, k as ExplicitCheckboxValue, kn as StringListValue, kt as ProgressCountsSchema, l as CheckboxProgressCounts, ln as SetYearPatch, lr as YearValueSchema, lt as MultiCheckboxState, m as CheckboxesFieldSchema, mn as SimpleCheckboxStateSchema, mt as MultiSelectValueSchema, n as AnswerStateSchema, nn as SetStringPatchSchema, nr as ValidatorFn, nt as InspectResultSchema, o as CellResponseSchema, on as SetUrlListPatchSchema, or as YearField, ot as IssueScopeSchema, p as CheckboxesField, pn as SimpleCheckboxState, pt as MultiSelectValue, q as FrontmatterHarnessConfig, qn as UrlListField, qt as SetMultiSelectPatch, r as ApplyResult, rn as SetTablePatch, rr as ValidatorRef, rt as IssueReason, s as CheckboxMode, sn as SetUrlPatch, sr as YearFieldSchema, st as MarkformFrontmatter, t as AnswerState, tn as SetStringPatch, tr as ValidatorContext, tt as InspectResult, u as CheckboxProgressCountsSchema, un as SetYearPatchSchema, ut as MultiCheckboxStateSchema, v as ClearFieldPatchSchema, vn as SingleSelectValueSchema, vt as NumberFieldSchema, w as DateValueSchema, wn as StepResultSchema, wt as OptionSchema, x as DateField, xn as SourceRange, xt as Option, y as ColumnTypeName, yn as SourcePosition, yt as NumberValue, z as FieldResponse, zn as TableRowPatch, zt as SessionTranscriptSchema } from "./coreTypes-9XZSNOv6.mjs";
 import "@markdoc/markdoc";
 import { LanguageModel, Tool } from "ai";
 
@@ -519,6 +519,57 @@ interface Agent {
    */
   generatePatches(issues: InspectIssue[], form: ParsedForm, maxPatches: number): Promise<AgentResponse>;
 }
+/**
+ * Callbacks for observing form-filling execution in real-time.
+ *
+ * All callbacks are optional - implement only what you need.
+ * Callback errors are caught and ignored (won't abort fill).
+ *
+ * @example
+ * ```typescript
+ * await fillForm({
+ *   form: formMarkdown,
+ *   model: 'anthropic/claude-sonnet-4-5',
+ *   enableWebSearch: true,
+ *   callbacks: {
+ *     onTurnStart: ({ turnNumber }) => console.log(`Starting turn ${turnNumber}`),
+ *     onToolStart: ({ name }) => spinner.message(`🔧 ${name}...`),
+ *     onTurnComplete: (progress) => console.log(`Turn ${progress.turnNumber} done`),
+ *   },
+ * });
+ * ```
+ */
+interface FillCallbacks {
+  /** Called when a turn begins */
+  onTurnStart?(turn: {
+    turnNumber: number;
+    issuesCount: number;
+  }): void;
+  /** Called when a turn completes */
+  onTurnComplete?(progress: TurnProgress): void;
+  /** Called before a tool executes */
+  onToolStart?(call: {
+    name: string;
+    input: unknown;
+  }): void;
+  /** Called after a tool completes */
+  onToolEnd?(call: {
+    name: string;
+    output: unknown;
+    durationMs: number;
+    error?: string;
+  }): void;
+  /** Called before an LLM request */
+  onLlmCallStart?(call: {
+    model: string;
+  }): void;
+  /** Called after an LLM response */
+  onLlmCallEnd?(call: {
+    model: string;
+    inputTokens: number;
+    outputTokens: number;
+  }): void;
+}
 /**
  * Options for the fillForm function.
  */
@@ -544,8 +595,8 @@ interface FillOptions {
   targetRoles?: string[];
   /** Fill mode: 'continue' (skip filled) or 'overwrite' (re-fill) */
   fillMode?: FillMode;
-  /** Progress callback called after each turn */
-  onTurnComplete?: (progress: TurnProgress) => void;
+  /** Callbacks for observing form-filling execution */
+  callbacks?: FillCallbacks;
   /** AbortSignal for cancellation */
   signal?: AbortSignal;
   /**
@@ -673,6 +724,7 @@ declare function createMockAgent(completedForm: ParsedForm): MockAgent;
  * const result = await fillForm({
  *   form: formMarkdown,
  *   model: 'anthropic/claude-sonnet-4-5',
+ *   enableWebSearch: true,
  *   inputContext: {
  *     company_name: 'Apple Inc.',
  *   },
@@ -680,8 +732,10 @@ declare function createMockAgent(completedForm: ParsedForm): MockAgent;
  *     ## Additional Context
  *     ${backgroundInfo}
  *   `,
- *   onTurnComplete: (progress) => {
- *     console.log(`Turn ${progress.turnNumber}: ${progress.requiredIssuesRemaining} remaining`);
+ *   callbacks: {
+ *     onTurnComplete: (progress) => {
+ *       console.log(`Turn ${progress.turnNumber}: ${progress.requiredIssuesRemaining} remaining`);
+ *     },
  *   },
  * });
  *
@@ -791,7 +845,7 @@ declare function validateResearchForm(form: ParsedForm): {
  * This is the main library entry point that exports the core engine,
  * types, and utilities for working with .form.md files.
  */
-/** Markform version (read from package.json). */
+/** Markform version (injected at build time). */
 declare const VERSION: string;
 //#endregion
-export { type AgentResponse, type AnswerState, AnswerStateSchema, type ApplyResult, ApplyResultSchema, type CellResponse, CellResponseSchema, type CellScopeRef, type CheckboxMode, CheckboxModeSchema, type CheckboxProgressCounts, CheckboxProgressCountsSchema, type CheckboxValue, CheckboxValueSchema, type CheckboxesField, CheckboxesFieldSchema, type CheckboxesValue, CheckboxesValueSchema, type ClearFieldPatch, ClearFieldPatchSchema, type CoerceInputContextResult, type CoercionResult, type ColumnTypeName, ColumnTypeNameSchema, type ComputedSummaries, type DateField, DateFieldSchema, type DateValue, DateValueSchema, type DocumentationBlock, DocumentationBlockSchema, type DocumentationTag, DocumentationTagSchema, type ExplicitCheckboxValue, ExplicitCheckboxValueSchema, type Field, type FieldBase, type FieldGroup, FieldGroupSchema, type FieldKind, FieldKindSchema, type FieldProgress, FieldProgressSchema, type FieldResponse, FieldResponseSchema, FieldSchema, type FieldScopeRef, type FieldValue, FieldValueSchema, type FillOptions, type FillResult, type FillStatus, FormHarness, type FormSchema, FormSchemaSchema, type FrontmatterHarnessConfig, type HarnessConfig, HarnessConfigSchema, type Id, type IdIndexEntry, IdSchema, type InputContext, type InspectIssue, InspectIssueSchema, type InspectOptions, type InspectResult, InspectResultSchema, type IssueReason, IssueReasonSchema, type IssueScope, IssueScopeSchema, type MarkformFrontmatter, MarkformFrontmatterSchema, MockAgent, type MultiCheckboxState, MultiCheckboxStateSchema, type MultiSelectField, MultiSelectFieldSchema, type MultiSelectValue, MultiSelectValueSchema, type NodeType, type NumberField, NumberFieldSchema, type NumberValue, NumberValueSchema, type Option, type OptionId, OptionIdSchema, OptionSchema, ParseError, type ParseScopeRefResult, type ParseTableResult, type ParsedForm, type ParsedRawTable, type ParsedScopeRef, type Patch, PatchSchema, type ProgressCounts, ProgressCountsSchema, type ProgressState, ProgressStateSchema, type ProgressSummary, ProgressSummarySchema, type QualifiedColumnRef, type QualifiedOptionRef, type QualifiedScopeRef, type RawFieldValue, type ResearchOptions, type ResearchResult, type ResearchStatus, type SerializeOptions, type SessionFinal, SessionFinalSchema, type SessionTranscript, SessionTranscriptSchema, type SessionTurn, SessionTurnSchema, type SessionTurnStats, type SetCheckboxesPatch, SetCheckboxesPatchSchema, type SetDatePatch, SetDatePatchSchema, type SetMultiSelectPatch, SetMultiSelectPatchSchema, type SetNumberPatch, SetNumberPatchSchema, type SetSingleSelectPatch, SetSingleSelectPatchSchema, type SetStringListPatch, SetStringListPatchSchema, type SetStringPatch, SetStringPatchSchema, type SetTablePatch, SetTablePatchSchema, type SetUrlListPatch, SetUrlListPatchSchema, type SetUrlPatch, SetUrlPatchSchema, type SetYearPatch, SetYearPatchSchema, type Severity, SeveritySchema, type SimpleCheckboxState, SimpleCheckboxStateSchema, type SingleSelectField, SingleSelectFieldSchema, type SingleSelectValue, SingleSelectValueSchema, type SourcePosition, SourcePositionSchema, type SourceRange, SourceRangeSchema, type StepResult, StepResultSchema, type StringField, StringFieldSchema, type StringListField, StringListFieldSchema, type StringListValue, StringListValueSchema, type StringValue, StringValueSchema, type StructureSummary, StructureSummarySchema, type TableColumn, TableColumnSchema, type TableField, TableFieldSchema, type TableRowPatch, TableRowPatchSchema, type TableRowResponse, TableRowResponseSchema, type TableValue, TableValueSchema, type TurnProgress, type TurnStats, type UrlField, UrlFieldSchema, type UrlListField, UrlListFieldSchema, type UrlListValue, UrlListValueSchema, type UrlValue, UrlValueSchema, VERSION, type ValidateOptions, type ValidateResult, type ValidationIssue, ValidationIssueSchema, type ValidatorContext, type ValidatorFn, type ValidatorRef, ValidatorRefSchema, type ValidatorRegistry, type YearField, YearFieldSchema, type YearValue, YearValueSchema, applyPatches, coerceInputContext, coerceToFieldPatch, computeAllSummaries, computeFormState, computeProgressSummary, computeStructureSummary, createHarness, createMockAgent, fillForm, findFieldById, getFieldId, inspect, isCellRef, isFieldRef, isFormComplete, isQualifiedRef, isResearchForm, parseCellValue, parseForm, parseMarkdownTable, parseRawTable, parseScopeRef, parseSession, resolveHarnessConfig, runResearch, serialize, serializeScopeRef, serializeSession, validate, validateResearchForm };
+export { type AgentResponse, type AnswerState, AnswerStateSchema, type ApplyResult, ApplyResultSchema, type CellResponse, CellResponseSchema, type CellScopeRef, type CheckboxMode, CheckboxModeSchema, type CheckboxProgressCounts, CheckboxProgressCountsSchema, type CheckboxValue, CheckboxValueSchema, type CheckboxesField, CheckboxesFieldSchema, type CheckboxesValue, CheckboxesValueSchema, type ClearFieldPatch, ClearFieldPatchSchema, type CoerceInputContextResult, type CoercionResult, type ColumnTypeName, ColumnTypeNameSchema, type ComputedSummaries, type DateField, DateFieldSchema, type DateValue, DateValueSchema, type DocumentationBlock, DocumentationBlockSchema, type DocumentationTag, DocumentationTagSchema, type ExplicitCheckboxValue, ExplicitCheckboxValueSchema, type Field, type FieldBase, type FieldGroup, FieldGroupSchema, type FieldKind, FieldKindSchema, type FieldProgress, FieldProgressSchema, type FieldResponse, FieldResponseSchema, FieldSchema, type FieldScopeRef, type FieldValue, FieldValueSchema, type FillCallbacks, type FillOptions, type FillResult, type FillStatus, FormHarness, type FormSchema, FormSchemaSchema, type FrontmatterHarnessConfig, type HarnessConfig, HarnessConfigSchema, type Id, type IdIndexEntry, IdSchema, type InputContext, type InspectIssue, InspectIssueSchema, type InspectOptions, type InspectResult, InspectResultSchema, type IssueReason, IssueReasonSchema, type IssueScope, IssueScopeSchema, type MarkformFrontmatter, MarkformFrontmatterSchema, MockAgent, type MultiCheckboxState, MultiCheckboxStateSchema, type MultiSelectField, MultiSelectFieldSchema, type MultiSelectValue, MultiSelectValueSchema, type NodeType, type NumberField, NumberFieldSchema, type NumberValue, NumberValueSchema, type Option, type OptionId, OptionIdSchema, OptionSchema, ParseError, type ParseScopeRefResult, type ParseTableResult, type ParsedForm, type ParsedRawTable, type ParsedScopeRef, type Patch, PatchSchema, type ProgressCounts, ProgressCountsSchema, type ProgressState, ProgressStateSchema, type ProgressSummary, ProgressSummarySchema, type QualifiedColumnRef, type QualifiedOptionRef, type QualifiedScopeRef, type RawFieldValue, type ResearchOptions, type ResearchResult, type ResearchStatus, type SerializeOptions, type SessionFinal, SessionFinalSchema, type SessionTranscript, SessionTranscriptSchema, type SessionTurn, SessionTurnSchema, type SessionTurnStats, type SetCheckboxesPatch, SetCheckboxesPatchSchema, type SetDatePatch, SetDatePatchSchema, type SetMultiSelectPatch, SetMultiSelectPatchSchema, type SetNumberPatch, SetNumberPatchSchema, type SetSingleSelectPatch, SetSingleSelectPatchSchema, type SetStringListPatch, SetStringListPatchSchema, type SetStringPatch, SetStringPatchSchema, type SetTablePatch, SetTablePatchSchema, type SetUrlListPatch, SetUrlListPatchSchema, type SetUrlPatch, SetUrlPatchSchema, type SetYearPatch, SetYearPatchSchema, type Severity, SeveritySchema, type SimpleCheckboxState, SimpleCheckboxStateSchema, type SingleSelectField, SingleSelectFieldSchema, type SingleSelectValue, SingleSelectValueSchema, type SourcePosition, SourcePositionSchema, type SourceRange, SourceRangeSchema, type StepResult, StepResultSchema, type StringField, StringFieldSchema, type StringListField, StringListFieldSchema, type StringListValue, StringListValueSchema, type StringValue, StringValueSchema, type StructureSummary, StructureSummarySchema, type TableColumn, TableColumnSchema, type TableField, TableFieldSchema, type TableRowPatch, TableRowPatchSchema, type TableRowResponse, TableRowResponseSchema, type TableValue, TableValueSchema, type TurnProgress, type TurnStats, type UrlField, UrlFieldSchema, type UrlListField, UrlListFieldSchema, type UrlListValue, UrlListValueSchema, type UrlValue, UrlValueSchema, VERSION, type ValidateOptions, type ValidateResult, type ValidationIssue, ValidationIssueSchema, type ValidatorContext, type ValidatorFn, type ValidatorRef, ValidatorRefSchema, type ValidatorRegistry, type YearField, YearFieldSchema, type YearValue, YearValueSchema, applyPatches, coerceInputContext, coerceToFieldPatch, computeAllSummaries, computeFormState, computeProgressSummary, computeStructureSummary, createHarness, createMockAgent, fillForm, findFieldById, getFieldId, inspect, isCellRef, isFieldRef, isFormComplete, isQualifiedRef, isResearchForm, parseCellValue, parseForm, parseMarkdownTable, parseRawTable, parseScopeRef, parseSession, resolveHarnessConfig, runResearch, serialize, serializeScopeRef, serializeSession, validate, validateResearchForm };

package/dist/index.mjs

@@ -1,6 +1,6 @@
 import { $ as SetUrlPatchSchema, A as MultiCheckboxStateSchema, B as ProgressSummarySchema, C as HarnessConfigSchema, Ct as ValidatorRefSchema, D as IssueReasonSchema, E as InspectResultSchema, F as OptionIdSchema, G as SetDatePatchSchema, H as SessionTranscriptSchema, I as OptionSchema, J as SetSingleSelectPatchSchema, K as SetMultiSelectPatchSchema, L as PatchSchema, M as MultiSelectValueSchema, N as NumberFieldSchema, O as IssueScopeSchema, P as NumberValueSchema, Q as SetUrlListPatchSchema, R as ProgressCountsSchema, S as FormSchemaSchema, St as ValidationIssueSchema, T as InspectIssueSchema, Tt as YearValueSchema, U as SessionTurnSchema, V as SessionFinalSchema, W as SetCheckboxesPatchSchema, X as SetStringPatchSchema, Y as SetStringListPatchSchema, Z as SetTablePatchSchema, _ as FieldKindSchema, _t as TableValueSchema, a as CheckboxProgressCountsSchema, at as SourcePositionSchema, b as FieldSchema, bt as UrlListValueSchema, c as CheckboxesValueSchema, ct as StringFieldSchema, d as DateFieldSchema, dt as StringValueSchema, et as SetYearPatchSchema, f as DateValueSchema, ft as StructureSummarySchema, g as FieldGroupSchema, gt as TableRowResponseSchema, h as ExplicitCheckboxValueSchema, ht as TableRowPatchSchema, i as CheckboxModeSchema, it as SingleSelectValueSchema, j as MultiSelectFieldSchema, k as MarkformFrontmatterSchema, l as ClearFieldPatchSchema, lt as StringListFieldSchema, m as DocumentationTagSchema, mt as TableFieldSchema, n as ApplyResultSchema, nt as SimpleCheckboxStateSchema, o as CheckboxValueSchema, ot as SourceRangeSchema, p as DocumentationBlockSchema, pt as TableColumnSchema, q as SetNumberPatchSchema, r as CellResponseSchema, rt as SingleSelectFieldSchema, s as CheckboxesFieldSchema, st as StepResultSchema, t as AnswerStateSchema, tt as SeveritySchema, u as ColumnTypeNameSchema, ut as StringListValueSchema, v as FieldProgressSchema, vt as UrlFieldSchema, w as IdSchema, wt as YearFieldSchema, x as FieldValueSchema, xt as UrlValueSchema, y as FieldResponseSchema, yt as UrlListFieldSchema, z as ProgressStateSchema } from "./coreTypes-pyctKRgc.mjs";
-import { a as computeAllSummaries, c as computeStructureSummary, i as validate, l as isFormComplete, o as computeFormState, r as inspect, s as computeProgressSummary, t as applyPatches, u as serialize } from "./apply-C54EMAJ1.mjs";
-import { C as serializeScopeRef, D as parseRawTable, E as parseMarkdownTable, O as ParseError, S as parseScopeRef, T as parseCellValue, _ as findFieldById, a as resolveHarnessConfig, b as isFieldRef, d as MockAgent, f as createMockAgent, g as coerceToFieldPatch, h as coerceInputContext, i as runResearch, m as createHarness, n as isResearchForm, o as fillForm, p as FormHarness, r as validateResearchForm, t as VERSION, v as getFieldId, w as parseForm, x as isQualifiedRef, y as isCellRef } from "./src-BNh7Cx9P.mjs";
+import { a as computeAllSummaries, c as computeStructureSummary, i as validate, l as isFormComplete, o as computeFormState, r as inspect, s as computeProgressSummary, t as applyPatches, u as serialize } from "./apply-DMQl-VVd.mjs";
+import { C as serializeScopeRef, D as parseRawTable, E as parseMarkdownTable, O as ParseError, S as parseScopeRef, T as parseCellValue, _ as findFieldById, a as resolveHarnessConfig, b as isFieldRef, d as MockAgent, f as createMockAgent, g as coerceToFieldPatch, h as coerceInputContext, i as runResearch, m as createHarness, n as isResearchForm, o as fillForm, p as FormHarness, r as validateResearchForm, t as VERSION, v as getFieldId, w as parseForm, x as isQualifiedRef, y as isCellRef } from "./src-o_5TSoHQ.mjs";
 import { n as serializeSession, t as parseSession } from "./session-uF0e6m6k.mjs";
 
 export { AnswerStateSchema, ApplyResultSchema, CellResponseSchema, CheckboxModeSchema, CheckboxProgressCountsSchema, CheckboxValueSchema, CheckboxesFieldSchema, CheckboxesValueSchema, ClearFieldPatchSchema, ColumnTypeNameSchema, DateFieldSchema, DateValueSchema, DocumentationBlockSchema, DocumentationTagSchema, ExplicitCheckboxValueSchema, FieldGroupSchema, FieldKindSchema, FieldProgressSchema, FieldResponseSchema, FieldSchema, FieldValueSchema, FormHarness, FormSchemaSchema, HarnessConfigSchema, IdSchema, InspectIssueSchema, InspectResultSchema, IssueReasonSchema, IssueScopeSchema, MarkformFrontmatterSchema, MockAgent, MultiCheckboxStateSchema, MultiSelectFieldSchema, MultiSelectValueSchema, NumberFieldSchema, NumberValueSchema, OptionIdSchema, OptionSchema, ParseError, PatchSchema, ProgressCountsSchema, ProgressStateSchema, ProgressSummarySchema, SessionFinalSchema, SessionTranscriptSchema, SessionTurnSchema, SetCheckboxesPatchSchema, SetDatePatchSchema, SetMultiSelectPatchSchema, SetNumberPatchSchema, SetSingleSelectPatchSchema, SetStringListPatchSchema, SetStringPatchSchema, SetTablePatchSchema, SetUrlListPatchSchema, SetUrlPatchSchema, SetYearPatchSchema, SeveritySchema, SimpleCheckboxStateSchema, SingleSelectFieldSchema, SingleSelectValueSchema, SourcePositionSchema, SourceRangeSchema, StepResultSchema, StringFieldSchema, StringListFieldSchema, StringListValueSchema, StringValueSchema, StructureSummarySchema, TableColumnSchema, TableFieldSchema, TableRowPatchSchema, TableRowResponseSchema, TableValueSchema, UrlFieldSchema, UrlListFieldSchema, UrlListValueSchema, UrlValueSchema, VERSION, ValidationIssueSchema, ValidatorRefSchema, YearFieldSchema, YearValueSchema, applyPatches, coerceInputContext, coerceToFieldPatch, computeAllSummaries, computeFormState, computeProgressSummary, computeStructureSummary, createHarness, createMockAgent, fillForm, findFieldById, getFieldId, inspect, isCellRef, isFieldRef, isFormComplete, isQualifiedRef, isResearchForm, parseCellValue, parseForm, parseMarkdownTable, parseRawTable, parseScopeRef, parseSession, resolveHarnessConfig, runResearch, serialize, serializeScopeRef, serializeSession, validate, validateResearchForm };

package/dist/{shared-BqPnYXrn.mjs → shared-DRlgu2ZJ.mjs}

@@ -1,6 +1,6 @@
 import YAML from "yaml";
-import { relative } from "node:path";
 import pc from "picocolors";
+import { relative } from "node:path";
 import { mkdir } from "node:fs/promises";
 import * as p from "@clack/prompts";
 

package/dist/{shared-CZsyShck.mjs → shared-u22MtBRo.mjs}

@@ -1,3 +1,3 @@
-import { a as formatPath, c as logError, d as logTiming, f as logVerbose, g as writeFile, h as shouldUseColors, i as formatOutput, l as logInfo, m as readFile, 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, h as shouldUseColors, i as formatOutput, l as logInfo, m as readFile, 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";
 
 export { writeFile };

package/dist/{src-BNh7Cx9P.mjs → src-o_5TSoHQ.mjs}

@@ -1,6 +1,5 @@
 import { L as PatchSchema } from "./coreTypes-pyctKRgc.mjs";
-import { C as DEFAULT_ROLE_INSTRUCTIONS, P as getWebSearchConfig, S as DEFAULT_ROLES, _ as DEFAULT_MAX_TURNS, b as DEFAULT_RESEARCH_MAX_ISSUES_PER_TURN, g as DEFAULT_MAX_PATCHES_PER_TURN, h as DEFAULT_MAX_ISSUES_PER_TURN, n as getFieldsForRoles, p as AGENT_ROLE, r as inspect, t as applyPatches, u as serialize, x as DEFAULT_RESEARCH_MAX_PATCHES_PER_TURN, y as DEFAULT_PRIORITY } from "./apply-C54EMAJ1.mjs";
-import { createRequire } from "node:module";
+import { C as DEFAULT_ROLE_INSTRUCTIONS, N as getWebSearchConfig, S as DEFAULT_ROLES, _ as DEFAULT_MAX_TURNS, b as DEFAULT_RESEARCH_MAX_ISSUES_PER_TURN, g as DEFAULT_MAX_PATCHES_PER_TURN, h as DEFAULT_MAX_ISSUES_PER_TURN, n as getFieldsForRoles, p as AGENT_ROLE, r as inspect, t as applyPatches, u as serialize, x as DEFAULT_RESEARCH_MAX_PATCHES_PER_TURN, y as DEFAULT_PRIORITY } from "./apply-DMQl-VVd.mjs";
 import { z } from "zod";
 import Markdoc from "@markdoc/markdoc";
 import YAML from "yaml";
@@ -1169,6 +1168,18 @@ function parseField(node) {
 *
 * Parses Markdoc documents and extracts form schema, values, and documentation blocks.
 */
+/**
+* Valid tag names inside a form.
+* Any other tag will produce a ParseError.
+*/
+const VALID_FORM_TAGS = new Set([
+	"group",
+	"field",
+	"note",
+	"description",
+	"instructions",
+	"documentation"
+]);
 const FRONTMATTER_REGEX = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?/;
 /**
 * Parse harness configuration from frontmatter.
@@ -1227,14 +1238,14 @@ function extractFrontmatter(content) {
 	}
 }
 /**
-* Parse a field-group tag.
+* Parse a group tag.
 */
 function parseFieldGroup(node, responsesByFieldId, orderIndex, idIndex, parentId) {
 	const id = getStringAttr(node, "id");
 	const title = getStringAttr(node, "title");
-	if (!id) throw new ParseError("field-group missing required 'id' attribute");
+	if (!id) throw new ParseError("group missing required 'id' attribute");
 	if (idIndex.has(id)) throw new ParseError(`Duplicate ID '${id}'`);
-	if (getStringAttr(node, "state") !== void 0) throw new ParseError(`Field-group '${id}' has state attribute. state attribute is not allowed on field-groups.`);
+	if (getStringAttr(node, "state") !== void 0) throw new ParseError(`Field-group '${id}' has state attribute. state attribute is not allowed on groups.`);
 	idIndex.set(id, {
 		nodeType: "group",
 		parentId
@@ -1275,7 +1286,7 @@ function parseFieldGroup(node, responsesByFieldId, orderIndex, idIndex, parentId
 }
 /**
 * Parse a form tag.
-* Handles both explicit field-groups and fields placed directly under the form.
+* Handles both explicit groups and fields placed directly under the form.
 */
 function parseFormTag(node, responsesByFieldId, orderIndex, idIndex) {
 	const id = getStringAttr(node, "id");
@@ -1287,7 +1298,8 @@ function parseFormTag(node, responsesByFieldId, orderIndex, idIndex) {
 	const ungroupedFields = [];
 	function processContent(child) {
 		if (!child || typeof child !== "object") return;
-		if (isTagNode(child, "field-group")) {
+		if (isTagNode(child) && !VALID_FORM_TAGS.has(child.tag)) throw new ParseError(`Unknown tag '${child.tag}' inside form`);
+		if (isTagNode(child, "group")) {
 			const group = parseFieldGroup(child, responsesByFieldId, orderIndex, idIndex, id);
 			groups.push(group);
 			return;
@@ -7600,6 +7612,7 @@ var LiveAgent = class {
 	enableWebSearch;
 	webSearchTools = null;
 	additionalTools;
+	callbacks;
 	constructor(config) {
 		this.model = config.model;
 		this.maxStepsPerTurn = config.maxStepsPerTurn ?? 3;
@@ -7608,6 +7621,7 @@ var LiveAgent = class {
 		this.provider = config.provider;
 		this.enableWebSearch = config.enableWebSearch;
 		this.additionalTools = config.additionalTools ?? {};
+		this.callbacks = config.callbacks;
 		if (this.enableWebSearch && this.provider) this.webSearchTools = loadWebSearchTools(this.provider);
 	}
 	/**
@@ -7633,14 +7647,18 @@ var LiveAgent = class {
 		if (this.systemPromptAddition) systemPrompt += "\n\n# Additional Context\n" + this.systemPromptAddition;
 		if (this.enableWebSearch && this.provider && !this.webSearchTools) this.webSearchTools = loadWebSearchTools(this.provider);
 		if (this.webSearchTools && Object.keys(this.webSearchTools).length > 0) systemPrompt += "\n\n" + WEB_SEARCH_INSTRUCTIONS;
-		const tools = {
+		const tools = wrapToolsWithCallbacks({
 			generatePatches: {
 				description: GENERATE_PATCHES_TOOL_DESCRIPTION,
 				inputSchema: zodSchema(z.object({ patches: z.array(PatchSchema).max(maxPatches).describe("Array of patches. Each patch sets a value for one field.") }))
 			},
 			...this.webSearchTools,
 			...this.additionalTools
-		};
+		}, this.callbacks);
+		const modelId = this.model.modelId ?? "unknown";
+		if (this.callbacks?.onLlmCallStart) try {
+			this.callbacks.onLlmCallStart({ model: modelId });
+		} catch {}
 		const result = await generateText({
 			model: this.model,
 			system: systemPrompt,
@@ -7648,6 +7666,13 @@ var LiveAgent = class {
 			tools,
 			stopWhen: stepCountIs(this.maxStepsPerTurn)
 		});
+		if (this.callbacks?.onLlmCallEnd) try {
+			this.callbacks.onLlmCallEnd({
+				model: modelId,
+				inputTokens: result.usage?.inputTokens ?? 0,
+				outputTokens: result.usage?.outputTokens ?? 0
+			});
+		} catch {}
 		const patches = [];
 		const toolCallCounts = /* @__PURE__ */ new Map();
 		for (const step of result.steps) for (const toolCall of step.toolCalls) {
@@ -7784,6 +7809,60 @@ function findField(form, fieldId) {
 	return null;
 }
 /**
+* Wrap tools with callbacks for observability.
+*
+* Only wraps tools that have an execute function.
+* Declarative tools (schema only) are passed through unchanged.
+*/
+function wrapToolsWithCallbacks(tools, callbacks) {
+	if (!callbacks?.onToolStart && !callbacks?.onToolEnd) return tools;
+	const wrapped = {};
+	for (const [name$2, tool$1] of Object.entries(tools)) {
+		const execute = tool$1.execute;
+		if (typeof execute === "function") wrapped[name$2] = wrapTool(name$2, tool$1, execute, callbacks);
+		else wrapped[name$2] = tool$1;
+	}
+	return wrapped;
+}
+/**
+* Wrap a single tool with callbacks.
+*/
+function wrapTool(name$2, tool$1, originalExecute, callbacks) {
+	return {
+		...tool$1,
+		execute: async (input) => {
+			const startTime = Date.now();
+			if (callbacks.onToolStart) try {
+				callbacks.onToolStart({
+					name: name$2,
+					input
+				});
+			} catch {}
+			try {
+				const output = await originalExecute(input);
+				if (callbacks.onToolEnd) try {
+					callbacks.onToolEnd({
+						name: name$2,
+						output,
+						durationMs: Date.now() - startTime
+					});
+				} catch {}
+				return output;
+			} catch (error) {
+				if (callbacks.onToolEnd) try {
+					callbacks.onToolEnd({
+						name: name$2,
+						output: null,
+						durationMs: Date.now() - startTime,
+						error: error instanceof Error ? error.message : String(error)
+					});
+				} catch {}
+				throw error;
+			}
+		}
+	};
+}
+/**
 * Load web search tools for a provider.
 * Uses centralized config from llms.ts.
 */
@@ -7981,6 +8060,7 @@ function buildResult(form, turns, totalPatches, status, inputContextWarnings, re
 * const result = await fillForm({
 *   form: formMarkdown,
 *   model: 'anthropic/claude-sonnet-4-5',
+*   enableWebSearch: true,
 *   inputContext: {
 *     company_name: 'Apple Inc.',
 *   },
@@ -7988,8 +8068,10 @@ function buildResult(form, turns, totalPatches, status, inputContextWarnings, re
 *     ## Additional Context
 *     ${backgroundInfo}
 *   `,
-*   onTurnComplete: (progress) => {
-*     console.log(`Turn ${progress.turnNumber}: ${progress.requiredIssuesRemaining} remaining`);
+*   callbacks: {
+*     onTurnComplete: (progress) => {
+*       console.log(`Turn ${progress.turnNumber}: ${progress.requiredIssuesRemaining} remaining`);
+*     },
 *   },
 * });
 *
@@ -8066,7 +8148,8 @@ async function fillForm(options) {
 		targetRole: targetRoles[0] ?? AGENT_ROLE,
 		provider,
 		enableWebSearch: options.enableWebSearch,
-		additionalTools: options.additionalTools
+		additionalTools: options.additionalTools,
+		callbacks: options.callbacks
 	});
 	let turnCount = 0;
 	let stepResult = harness.step();
@@ -8075,6 +8158,12 @@ async function fillForm(options) {
 			ok: false,
 			reason: "cancelled"
 		}, inputContextWarnings, stepResult.issues);
+		if (options.callbacks?.onTurnStart) try {
+			options.callbacks.onTurnStart({
+				turnNumber: turnCount + 1,
+				issuesCount: stepResult.issues.length
+			});
+		} catch {}
 		const { patches, stats } = await agent.generatePatches(stepResult.issues, form, maxPatchesPerTurn);
 		if (options.signal?.aborted) return buildResult(form, turnCount, totalPatches, {
 			ok: false,
@@ -8089,9 +8178,9 @@ async function fillForm(options) {
 		stepResult = harness.apply(patches, stepResult.issues, llmStats);
 		totalPatches += patches.length;
 		turnCount++;
-		if (options.onTurnComplete) try {
+		if (options.callbacks?.onTurnComplete) try {
 			const requiredIssues = stepResult.issues.filter((i) => i.severity === "required");
-			options.onTurnComplete({
+			options.callbacks.onTurnComplete({
 				turnNumber: turnCount,
 				issuesShown: stepResult.issues.length,
 				patchesApplied: patches.length,
@@ -8253,15 +8342,8 @@ function validateResearchForm(form) {
 
 //#endregion
 //#region src/index.ts
-/**
-* Markform - Agent-friendly, human-readable, editable forms.
-*
-* This is the main library entry point that exports the core engine,
-* types, and utilities for working with .form.md files.
-*/
-const pkg = createRequire(import.meta.url)("../package.json");
-/** Markform version (read from package.json). */
-const VERSION = pkg.version;
+/** Markform version (injected at build time). */
+const VERSION = "0.1.6";
 
 //#endregion
 export { serializeScopeRef as C, parseRawTable as D, parseMarkdownTable as E, ParseError as O, parseScopeRef as S, parseCellValue as T, findFieldById as _, resolveHarnessConfig as a, isFieldRef as b, getProviderNames as c, MockAgent as d, createMockAgent as f, coerceToFieldPatch as g, coerceInputContext as h, runResearch as i, resolveModel as l, createHarness as m, isResearchForm as n, fillForm as o, FormHarness as p, validateResearchForm as r, getProviderInfo as s, VERSION as t, createLiveAgent as u, getFieldId as v, parseForm as w, isQualifiedRef as x, isCellRef as y };

package/docs/markform-apis.md

@@ -152,10 +152,57 @@ High-level API for filling a form with an AI model.
 const result = await fillForm({
   form: parsedForm,
   model: 'anthropic/claude-sonnet-4-5',
-  roles: ['agent'],
+  enableWebSearch: true,
+  targetRoles: ['agent'],
 });
 ```
 
+### FillCallbacks
+
+Optional callbacks for observing form-filling execution in real-time.
+All callbacks are optional and errors in callbacks don't abort filling.
+
+```typescript
+import type { FillCallbacks } from 'markform';
+
+const callbacks: FillCallbacks = {
+  onTurnStart: ({ turnNumber, issuesCount }) => {
+    console.log(`Turn ${turnNumber}: ${issuesCount} issues`);
+  },
+  onTurnComplete: (progress) => {
+    console.log(`Completed: ${progress.patchesApplied} patches applied`);
+  },
+  onToolStart: ({ name }) => {
+    spinner.message(`🔧 ${name}...`);
+  },
+  onToolEnd: ({ name, durationMs }) => {
+    console.log(`${name} completed in ${durationMs}ms`);
+  },
+  onLlmCallStart: ({ model }) => {
+    console.log(`Calling ${model}...`);
+  },
+  onLlmCallEnd: ({ inputTokens, outputTokens }) => {
+    console.log(`Tokens: ${inputTokens} in, ${outputTokens} out`);
+  },
+};
+
+await fillForm({
+  form: parsedForm,
+  model: 'anthropic/claude-sonnet-4-5',
+  enableWebSearch: true,
+  callbacks,
+});
+```
+
+| Callback | Parameters | Description |
+| --- | --- | --- |
+| `onTurnStart` | `{ turnNumber, issuesCount }` | Called when a turn begins |
+| `onTurnComplete` | `TurnProgress` | Called when a turn completes |
+| `onToolStart` | `{ name, input }` | Called before a tool executes |
+| `onToolEnd` | `{ name, output, durationMs, error? }` | Called after a tool completes |
+| `onLlmCallStart` | `{ model }` | Called before an LLM request |
+| `onLlmCallEnd` | `{ model, inputTokens, outputTokens }` | Called after an LLM response |
+
 ### createHarness(form, config?): FormHarness
 
 Create a harness for manual control over the fill loop.
@@ -187,6 +234,10 @@ import type {
   FieldValue,
   Patch,
   InspectResult,
+  FillCallbacks,
+  FillOptions,
+  FillResult,
+  TurnProgress,
   // ... many more
 } from 'markform';
 ```

package/docs/markform-reference.md

@@ -39,11 +39,11 @@ markform:
 
 {% form id="form_id" title="Form Title" %}
 
-{% field-group id="group_id" title="Group Title" %}
+{% group id="group_id" title="Group Title" %}
 
 <!-- fields go here -->
 
-{% /field-group %}
+{% /group %}
 
 {% /form %}
 ```
@@ -399,7 +399,7 @@ A focused research form for gathering ratings and key statistics for any film.
 Pulls from IMDB, Rotten Tomatoes, and Metacritic.
 {% /description %}
 
-{% field-group id="movie_input" title="Movie Identification" %}
+{% group id="movie_input" title="Movie Identification" %}
 
 {% field kind="string" id="movie" label="Movie" role="user" required=true minLength=1 maxLength=300 %}{% /field %}
 
@@ -407,9 +407,9 @@ Pulls from IMDB, Rotten Tomatoes, and Metacritic.
 Enter the movie title (add any details to help identify, like "Barbie 2023" or "the Batman movie with Robert Pattinson")
 {% /instructions %}
 
-{% /field-group %}
+{% /group %}
 
-{% field-group id="title_identification" title="Title Identification" %}
+{% group id="title_identification" title="Title Identification" %}
 
 {% field kind="string" id="full_title" label="Full Title" role="agent" required=true %}{% /field %}
 
@@ -417,9 +417,9 @@ Enter the movie title (add any details to help identify, like "Barbie 2023" or "
 Look up what film the user had in mind and fill in the official title including subtitle if any (e.g., "The Lord of the Rings: The Fellowship of the Ring").
 {% /instructions %}
 
-{% /field-group %}
+{% /group %}
 
-{% field-group id="sources" title="Sources" %}
+{% group id="sources" title="Sources" %}
 
 {% field kind="url" id="imdb_url" label="IMDB URL" role="agent" required=true %}{% /field %}
 
@@ -439,9 +439,9 @@ Direct link to the movie's Rotten Tomatoes page.
 Direct link to the movie's Metacritic page.
 {% /instructions %}
 
-{% /field-group %}
+{% /group %}
 
-{% field-group id="basic_details" title="Basic Details" %}
+{% group id="basic_details" title="Basic Details" %}
 
 {% field kind="number" id="year" label="Release Year" role="agent" required=true min=1888 max=2030 %}{% /field %}
 
@@ -462,9 +462,9 @@ One director per line. Most films have one; some have two or more co-directors.
 - [ ] NR/Unrated {% #nr %}
 {% /field %}
 
-{% /field-group %}
+{% /group %}
 
-{% field-group id="imdb_ratings" title="IMDB Ratings" %}
+{% group id="imdb_ratings" title="IMDB Ratings" %}
 
 {% field kind="number" id="imdb_rating" label="IMDB Rating" role="agent" min=1.0 max=10.0 %}{% /field %}
 
@@ -478,9 +478,9 @@ IMDB user rating (1.0-10.0 scale).
 Number of IMDB user votes (e.g., 2800000 for a popular film).
 {% /instructions %}
 
-{% /field-group %}
+{% /group %}
 
-{% field-group id="rotten_tomatoes_ratings" title="Rotten Tomatoes Ratings" %}
+{% group id="rotten_tomatoes_ratings" title="Rotten Tomatoes Ratings" %}
 
 {% field kind="number" id="rt_critics_score" label="Tomatometer (Critics)" role="agent" min=0 max=100 %}{% /field %}
 
@@ -496,9 +496,9 @@ Tomatometer percentage (0-100).
 Audience Score percentage (0-100).
 {% /instructions %}
 
-{% /field-group %}
+{% /group %}
 
-{% field-group id="metacritic_ratings" title="Metacritic Ratings" %}
+{% group id="metacritic_ratings" title="Metacritic Ratings" %}
 
 {% field kind="number" id="metacritic_score" label="Metacritic Score" role="agent" min=0 max=100 %}{% /field %}
 
@@ -506,9 +506,9 @@ Audience Score percentage (0-100).
 Metascore (0-100 scale). Leave empty if not available.
 {% /instructions %}
 
-{% /field-group %}
+{% /group %}
 
-{% field-group id="summary" title="Summary" %}
+{% group id="summary" title="Summary" %}
 
 {% field kind="string" id="logline" label="One-Line Summary" role="agent" maxLength=300 %}{% /field %}
 
@@ -524,7 +524,7 @@ Format: Award | Category | Year
 Example: "Oscar | Best Picture | 1995"
 {% /instructions %}
 
-{% /field-group %}
+{% /group %}
 
 {% /form %}
 ```
@@ -595,7 +595,7 @@ markform fill template.form.md --mock --mock-source filled.form.md
 
 3. **Set constraints**: Use `min`, `max`, `minLength`, `pattern` to validate
 
-4. **Group logically**: Related fields in the same `field-group`
+4. **Group logically**: Related fields in the same `group`
 
 5. **Assign roles**: Separate user input from agent research