markform 0.1.2 → 0.1.4

package/{SPEC.md → docs/markform-spec.md}

@@ -190,7 +190,7 @@ Markform defines its own scoping rules where option IDs are field-scoped.
 
 - IDs use `snake_case` (e.g., `company_info`, `ten_k`)
 
-- Tag names use `kebab-case` (Markdoc convention, e.g., `string-field`)
+- The `field` tag uses a `kind` attribute to specify the field kind
 
 #### Structural Tags
 
@@ -203,27 +203,31 @@ Markform defines its own scoping rules where option IDs are field-scoped.
 Custom tags are defined following [Markdoc tag conventions][markdoc-tags]. See
 [Markdoc Config][markdoc-config] for how to register custom tags.
 
-Each field tag maps to a **kind** value that identifies the field type.
-The `kind` property is reserved exclusively for field types—it identifies what type of
-field a `Field` or `FieldValue` represents.
+All fields use the unified `{% field kind="..." %}` syntax. The `kind` attribute
+identifies what type of field a `Field` or `FieldValue` represents.
 (In TypeScript, the type is `FieldKind`.)
 
-| Tag | Kind | Description |
-| --- | --- | --- |
-| `string-field` | `'string'` | String value; optional `required`, `pattern`, `minLength`, `maxLength` |
-| `number-field` | `'number'` | Numeric value; optional `min`, `max`, `integer` |
-| `string-list` | `'string_list'` | Array of strings (open-ended list); supports `minItems`, `maxItems`, `itemMinLength`, `itemMaxLength`, `uniqueItems` |
-| `single-select` | `'single_select'` | Select one option from enumerated list |
-| `multi-select` | `'multi_select'` | Select multiple options; supports `minSelections`, `maxSelections` constraints |
-| `checkboxes` | `'checkboxes'` | Stateful checklist; supports `checkboxMode` with values `multi` (5 states), `simple` (2 states), or `explicit` (yes/no); optional `minDone` for completion threshold |
-| `url-field` | `'url'` | Single URL value with built-in format validation |
-| `url-list` | `'url_list'` | Array of URLs (for citations, sources, references); supports `minItems`, `maxItems`, `uniqueItems` |
+| Kind | Description |
+| --- | --- |
+| `string` | String value; optional `required`, `pattern`, `minLength`, `maxLength` |
+| `number` | Numeric value; optional `min`, `max`, `integer` |
+| `date` | ISO 8601 date (YYYY-MM-DD); optional `min`, `max` date constraints |
+| `year` | Integer year; optional `min`, `max` year constraints |
+| `string_list` | Array of strings (open-ended list); supports `minItems`, `maxItems`, `itemMinLength`, `itemMaxLength`, `uniqueItems` |
+| `single_select` | Select one option from enumerated list |
+| `multi_select` | Select multiple options; supports `minSelections`, `maxSelections` constraints |
+| `checkboxes` | Stateful checklist; supports `checkboxMode` with values `multi` (5 states), `simple` (2 states), or `explicit` (yes/no); optional `minDone` for completion threshold |
+| `url` | Single URL value with built-in format validation |
+| `url_list` | Array of URLs (for citations, sources, references); supports `minItems`, `maxItems`, `uniqueItems` |
+| `table` | Structured tabular data with typed columns; supports `columnIds`, `columnLabels`, `columnTypes`, `minRows`, `maxRows` |
+
+**Syntax:** `{% field kind="<kind>" id="..." label="..." %}...{% /field %}`
 
 **Note on `pattern`:** The `pattern` attribute accepts a JavaScript-compatible regular
 expression string (without delimiters).
 Example: `pattern="^[A-Z]{1,5}$"` for a ticker symbol.
 
-**Common attributes (all field types):**
+**Common attributes (all field kinds):**
 
 | Attribute | Type | Description |
 | --- | --- | --- |
@@ -234,6 +238,32 @@ Example: `pattern="^[A-Z]{1,5}$"` for a ticker symbol.
 
 The `role` attribute enables multi-actor workflows where different fields are assigned
 to different actors.
+
+**Text-entry field attributes (string, number, string-list, url, url-list only):**
+
+| Attribute | Type | Description |
+| --- | --- | --- |
+| `placeholder` | string | Hint text shown in empty fields (displayed in UI) |
+| `examples` | string[] | Example values for the field (helps LLMs, shown in prompts) |
+
+These attributes are only valid on text-entry field kinds. Using them on chooser fields
+(single-select, multi-select, checkboxes) will result in a parse error.
+
+**Example with placeholder and examples:**
+```md
+{% field kind="string" id="company_name" label="Company name" placeholder="Enter company name" examples=["ACME Corp", "Globex Inc"] %}{% /field %}
+```
+
+For number fields, examples must be valid numbers:
+```md
+{% field kind="number" id="revenue" label="Revenue (USD)" placeholder="1000000" examples=["500000", "1000000", "5000000"] %}{% /field %}
+```
+
+For URL fields, examples must be valid URLs:
+```md
+{% field kind="url" id="website" label="Website" placeholder="https://example.com" examples=["https://example.com", "https://github.com"] %}{% /field %}
+```
+
 When running the fill harness with `targetRoles`, only fields matching those roles are
 considered for completion.
 See **Role-filtered completion** in the ProgressState Definitions section.
@@ -243,10 +273,10 @@ See **Role-filtered completion** in the ProgressState Definitions section.
 Markdoc does **not** natively support GFM-style task list checkbox syntax.
 The `[ ]` and `[x]` markers are **Markform-specific syntax** parsed within tag content.
 
-All selection field types use checkbox-style markers for broad markdown renderer
+All selection field kinds use checkbox-style markers for broad markdown renderer
 compatibility:
 
-| Field Type | Marker | Meaning | Example |
+| Field Kind | Marker | Meaning | Example |
 | --- | --- | --- | --- |
 | `checkboxes` | `[ ]` | Unchecked / todo / unfilled | `- [ ] Item {% #item_id %}` |
 | `checkboxes` | `[x]` | Checked / done | `- [x] Item {% #item_id %}` |
@@ -255,13 +285,13 @@ compatibility:
 | `checkboxes` | `[-]` | Not applicable (multi only) | `- [-] Item {% #item_id %}` |
 | `checkboxes` | `[y]` | Yes (explicit only) | `- [y] Item {% #item_id %}` |
 | `checkboxes` | `[n]` | No (explicit only) | `- [n] Item {% #item_id %}` |
-| `single-select` | `[ ]` | Unselected | `- [ ] Option {% #opt_id %}` |
-| `single-select` | `[x]` | Selected (exactly one) | `- [x] Option {% #opt_id %}` |
-| `multi-select` | `[ ]` | Unselected | `- [ ] Option {% #opt_id %}` |
-| `multi-select` | `[x]` | Selected | `- [x] Option {% #opt_id %}` |
+| `single_select` | `[ ]` | Unselected | `- [ ] Option {% #opt_id %}` |
+| `single_select` | `[x]` | Selected (exactly one) | `- [x] Option {% #opt_id %}` |
+| `multi_select` | `[ ]` | Unselected | `- [ ] Option {% #opt_id %}` |
+| `multi_select` | `[x]` | Selected | `- [x] Option {% #opt_id %}` |
 
-**Note:** `single-select` enforces that exactly one option has `[x]`. The distinction
-between `single-select` and `multi-select` is in the tag name, not the marker syntax.
+**Note:** `single_select` enforces that exactly one option has `[x]`. The distinction
+between `single_select` and `multi_select` is in the `kind` attribute, not the marker syntax.
 
 The `{% #id %}` annotation **is** native Markdoc syntax (see
 [Attributes][markdoc-attributes]).
@@ -325,11 +355,11 @@ Type: `integer`, default: `-1` (require all).
 
 Example with partial completion allowed:
 ```md
-{% checkboxes id="optional_tasks" label="Optional tasks" required=true minDone=1 %}
+{% field kind="checkboxes" id="optional_tasks" label="Optional tasks" required=true minDone=1 %}
 - [ ] Task A {% #task_a %}
 - [ ] Task B {% #task_b %}
 - [ ] Task C {% #task_c %}
-{% /checkboxes %}
+{% /field %}
 ```
 
 **Note:** `minDone` only applies to `simple` mode.
@@ -361,6 +391,79 @@ The parser enforces this:
 - `active` (`[*]`): This item is the current focus right now (useful for showing where
   an agent is in a multi-step workflow)
 
+#### Table Fields
+
+Table fields enable structured tabular data collection with typed columns.
+They use standard markdown table syntax for values and support validation per column
+type.
+
+**Table field attributes:**
+
+| Attribute | Type | Required | Description |
+| --- | --- | --- | --- |
+| `columnIds` | string[] | Yes | Array of snake_case column identifiers |
+| `columnLabels` | string[] | No | Array of display labels (backfilled from table header row if omitted) |
+| `columnTypes` | string[] | No | Array of column types (defaults to all `'string'`) |
+| `minRows` | number | No | Minimum row count (default: 0) |
+| `maxRows` | number | No | Maximum row count (default: unlimited) |
+
+**Column types and validation:**
+
+| Type | Description | Validation |
+| --- | --- | --- |
+| `string` | Any text value | None |
+| `number` | Numeric value | Integer or float |
+| `url` | URL value | Valid URL format |
+| `date` | Date value | ISO 8601 format (YYYY-MM-DD) |
+| `year` | Year value | Integer (1000-9999) |
+
+**Per-column required setting:** Column types can optionally specify a `required` flag:
+```md
+columnTypes=[{type: "string", required: true}, "number", "url"]
+```
+
+**Basic table-field (columnLabels backfilled from header row):**
+```md
+{% field kind="table" id="team" label="Team Members"
+   columnIds=["name", "title", "department"] %}
+| Name | Title | Department |
+|------|-------|------------|
+{% /field %}
+```
+
+**Explicit column labels (when different from header row):**
+```md
+{% field kind="table" id="team" label="Team Members"
+   columnIds=["name", "title", "department"]
+   columnLabels=["Full Name", "Job Title", "Department"]
+   columnTypes=["string", "string", "string"] %}
+| Full Name | Job Title | Department |
+|-----------|-----------|------------|
+{% /field %}
+```
+
+**Complete example with types and data:**
+```md
+{% field kind="table" id="films" label="Notable Films" required=true
+   columnIds=["release_year", "title", "rt_score", "box_office_m"]
+   columnLabels=["Year", "Title", "RT Score", "Box Office ($M)"]
+   columnTypes=["year", "string", "number", "number"]
+   minRows=1 maxRows=10 %}
+| Year | Title | RT Score | Box Office ($M) |
+|------|-------|----------|-----------------|
+| 2023 | Barbie | 88 | 1441.8 |
+| 2019 | Once Upon a Time in Hollywood | 85 | 374.3 |
+{% /field %}
+```
+
+**Sentinel values in table cells:**
+Cells can use `%SKIP%` and `%ABORT%` sentinels with optional reasons:
+```md
+| 2017 | I, Tonya | 90 | %SKIP% (Box office not tracked) |
+```
+
+**Cell escaping:** Use `\|` for literal pipe characters in cell values.
+
 #### Documentation Blocks
 
 Documentation blocks provide contextual help attached to form elements and each has its
@@ -416,7 +519,7 @@ without filtering out nested doc blocks.
 
 #### Field Values
 
-Values are encoded differently based on field type.
+Values are encoded differently based on field kind.
 The `fence` node with `language="value"` is used for scalar values (see
 [Markdoc Nodes][markdoc-nodes] for fence handling).
 
@@ -424,32 +527,32 @@ The `fence` node with `language="value"` is used for scalar values (see
 
 **Empty:** Omit the body entirely:
 ```md
-{% string-field id="company_name" label="Company name" required=true %}{% /string-field %}
+{% field kind="string" id="company_name" label="Company name" required=true %}{% /field %}
 ```
 
 **Filled:** Value in a fenced code block with language `value`:
 ````md
-{% string-field id="company_name" label="Company name" required=true %}
+{% field kind="string" id="company_name" label="Company name" required=true %}
 ```value
 ACME Corp
 ````
-{% /string-field %}
+{% /field %}
 ````
 
 ##### Number Fields
 
 **Empty:**
 ```md
-{% number-field id="revenue_m" label="Revenue (millions)" %}{% /number-field %}
+{% field kind="number" id="revenue_m" label="Revenue (millions)" %}{% /field %}
 ````
 
 **Filled:** Numeric value as string in fence (parsed to number):
 ````md
-{% number-field id="revenue_m" label="Revenue (millions)" %}
+{% field kind="number" id="revenue_m" label="Revenue (millions)" %}
 ```value
 1234.56
 ````
-{% /number-field %}
+{% /field %}
 ````
 
 ##### Single-Select Fields
@@ -457,11 +560,11 @@ ACME Corp
 Values are encoded **inline** via `[x]` marker—at most one option may be selected (if
 `required=true`, exactly one must be selected):
 ```md
-{% single-select id="rating" label="Rating" %}
+{% field kind="single_select" id="rating" label="Rating" %}
 - [ ] Bullish {% #bullish %}
 - [x] Neutral {% #neutral %}
 - [ ] Bearish {% #bearish %}
-{% /single-select %}
+{% /field %}
 ````
 
 Option IDs are scoped to the field—reference as `rating.bullish`, `rating.neutral`, etc.
@@ -470,41 +573,41 @@ Option IDs are scoped to the field—reference as `rating.bullish`, `rating.neut
 
 Values are encoded **inline** via `[x]` markers—no separate value fence:
 ```md
-{% multi-select id="categories" label="Categories" %}
+{% field kind="multi_select" id="categories" label="Categories" %}
 - [x] Technology {% #tech %}
 - [ ] Healthcare {% #health %}
 - [x] Finance {% #finance %}
-{% /multi-select %}
+{% /field %}
 ```
 
 ##### Checkboxes Fields
 
 Values are encoded **inline** via state markers—no separate value fence:
 ```md
-{% checkboxes id="tasks" label="Tasks" %}
+{% field kind="checkboxes" id="tasks" label="Tasks" %}
 - [x] Review docs {% #review %}
 - [/] Write tests {% #tests %}
 - [*] Run CI {% #ci %}
 - [ ] Deploy {% #deploy %}
 - [-] Manual QA {% #manual_qa %}
-{% /checkboxes %}
+{% /field %}
 ```
 
 For simple two-state checkboxes:
 ```md
-{% checkboxes id="agreements" label="Agreements" checkboxMode="simple" %}
+{% field kind="checkboxes" id="agreements" label="Agreements" checkboxMode="simple" %}
 - [x] I agree to terms {% #terms %}
 - [ ] Subscribe to newsletter {% #newsletter %}
-{% /checkboxes %}
+{% /field %}
 ```
 
 For explicit yes/no checkboxes (requires answer for each):
 ```md
-{% checkboxes id="risk_factors" label="Risk Assessment" checkboxMode="explicit" required=true %}
+{% field kind="checkboxes" id="risk_factors" label="Risk Assessment" checkboxMode="explicit" required=true %}
 - [y] Market volatility risk assessed {% #market %}
 - [n] Regulatory risk assessed {% #regulatory %}
 - [ ] Currency risk assessed {% #currency %}
-{% /checkboxes %}
+{% /field %}
 ```
 
 In this example, `risk_factors.currency` is unfilled (`[ ]`) and will fail validation
@@ -518,18 +621,18 @@ Items do not have individual IDs—the field has an ID and items are positional
 
 **Empty:**
 ```md
-{% string-list id="key_commitments" label="Key commitments" minItems=1 %}{% /string-list %}
+{% field kind="string_list" id="key_commitments" label="Key commitments" minItems=1 %}{% /field %}
 ```
 
 **Filled:** One item per non-empty line in the value fence:
 ````md
-{% string-list id="key_commitments" label="Key commitments" minItems=1 %}
+{% field kind="string_list" id="key_commitments" label="Key commitments" minItems=1 %}
 ```value
 Ship v1.0 by end of Q1
 Complete security audit
 Migrate legacy users to new platform
 ````
-{% /string-list %}
+{% /field %}
 ````
 
 **Parsing rules:**
@@ -558,7 +661,7 @@ Regulatory changes in EU market
 Competitor launching similar feature in Q2
 Customer concentration risk (top 3 = 60% revenue)
 ````
-{% /string-list %}
+{% /field %}
 
 {% instructions ref="top_risks" %} One risk per line.
 Be specific (company- or product-specific), not generic.
@@ -575,12 +678,12 @@ serialized on the opening tag:
 
 **Skipped field (no reason):**
 ```md
-{% string-field id="optional_notes" label="Optional notes" state="skipped" %}{% /string-field %}
+{% field kind="string" id="optional_notes" label="Optional notes" state="skipped" %}{% /field %}
 ````
 
 **Aborted field (no reason):**
 ```md
-{% string-field id="company_name" label="Company name" required=true state="aborted" %}{% /string-field %}
+{% field kind="string" id="company_name" label="Company name" required=true state="aborted" %}{% /field %}
 ```
 
 **State attribute values:**
@@ -595,19 +698,19 @@ When a field has a skip or abort state AND a reason was provided via the patch,
 reason is embedded in the sentinel value using parentheses:
 
 ````md
-{% string-field id="competitor_analysis" label="Competitor analysis" state="skipped" %}
+{% field kind="string" id="competitor_analysis" label="Competitor analysis" state="skipped" %}
 ```value
 %SKIP% (Information not publicly available)
 ````
-{% /string-field %}
+{% /field %}
 ````
 
 ```md
-{% number-field id="projected_revenue" label="Projected revenue" state="aborted" %}
+{% field kind="number" id="projected_revenue" label="Projected revenue" state="aborted" %}
 ```value
 %ABORT% (Financial projections cannot be determined from available data)
 ````
-{% /number-field %}
+{% /field %}
 ````
 
 **Parsing rules:**
@@ -668,11 +771,11 @@ Analysis completed with partial data due to API limitations.
 {% form id="quarterly_earnings" title="Quarterly Earnings Analysis" %}
 
 {% field-group id="company_info" title="Company Info" %}
-{% string-field id="company_name" label="Company name" state="skipped" %}
+{% field kind="string" id="company_name" label="Company name" state="skipped" %}
 ```value
 %SKIP% (Not applicable for this analysis type)
 ````
-{% /string-field %} {% /field-group %}
+{% /field %} {% /field-group %}
 
 {% note id="n1" ref="quarterly_earnings" role="agent" %} Analysis completed with partial
 data due to API limitations.
@@ -709,20 +812,20 @@ function containsMarkdocSyntax(value: string): boolean {
 
 **Example (process=false required):**
 ````md
-{% string-field id="notes" label="Notes" %}
+{% field kind="string" id="notes" label="Notes" %}
 ```value {% process=false %}
 Use {% tag %} for special formatting.
 ````
-{% /string-field %}
+{% /field %}
 ````
 
 **Example (process=false not needed):**
 ```md
-{% string-field id="name" label="Name" %}
+{% field kind="string" id="name" label="Name" %}
 ```value
 Alice Johnson
 ````
-{% /string-field %}
+{% /field %}
 ````
 
 See [GitHub Discussion #261][markdoc-process-false] for background on the attribute.
@@ -744,33 +847,33 @@ Prepare an earnings-call brief by extracting key financials and writing a thesis
 {% /description %}
 
 {% field-group id="company_info" title="Company Info" %}
-{% string-field id="company_name" label="Company name" required=true %}{% /string-field %}
-{% string-field id="ticker" label="Ticker" required=true %}{% /string-field %}
-{% string-field id="fiscal_period" label="Fiscal period" required=true %}{% /string-field %}
+{% field kind="string" id="company_name" label="Company name" required=true %}{% /field %}
+{% field kind="string" id="ticker" label="Ticker" required=true %}{% /field %}
+{% field kind="string" id="fiscal_period" label="Fiscal period" required=true %}{% /field %}
 {% /field-group %}
 
 {% field-group id="source_docs" title="Source Documents" %}
-{% checkboxes id="docs_reviewed" label="Documents reviewed" required=true %}
+{% field kind="checkboxes" id="docs_reviewed" label="Documents reviewed" required=true %}
 - [ ] 10-K {% #ten_k %}
 - [ ] 10-Q {% #ten_q %}
 - [ ] Earnings release {% #earnings_release %}
 - [ ] Earnings call transcript {% #call_transcript %}
-{% /checkboxes %}
+{% /field %}
 {% /field-group %}
 
 {% field-group id="financials" title="Key Financials" %}
-{% number-field id="revenue_m" label="Revenue (USD millions)" required=true %}{% /number-field %}
-{% number-field id="gross_margin_pct" label="Gross margin (%)" %}{% /number-field %}
-{% number-field id="eps_diluted" label="Diluted EPS" required=true %}{% /number-field %}
+{% field kind="number" id="revenue_m" label="Revenue (USD millions)" required=true %}{% /field %}
+{% field kind="number" id="gross_margin_pct" label="Gross margin (%)" %}{% /field %}
+{% field kind="number" id="eps_diluted" label="Diluted EPS" required=true %}{% /field %}
 {% /field-group %}
 
 {% field-group id="analysis" title="Analysis" %}
-{% single-select id="rating" label="Overall rating" required=true %}
+{% field kind="single_select" id="rating" label="Overall rating" required=true %}
 - [ ] Bullish {% #bullish %}
 - [ ] Neutral {% #neutral %}
 - [ ] Bearish {% #bearish %}
-{% /single-select %}
-{% string-field id="thesis" label="Investment thesis" required=true %}{% /string-field %}
+{% /field %}
+{% field kind="string" id="thesis" label="Investment thesis" required=true %}{% /field %}
 {% /field-group %}
 
 {% /form %}
@@ -784,16 +887,16 @@ Hand-authored forms only need the `spec` field.
 
 ````md
 {% field-group id="company_info" title="Company Info" %}
-{% string-field id="company_name" label="Company name" required=true %}
+{% field kind="string" id="company_name" label="Company name" required=true %}
 ```value
 ACME Corp
 ````
-{% /string-field %} {% string-field id="ticker" label="Ticker" required=true %}
+{% /field %} {% field kind="string" id="ticker" label="Ticker" required=true %}
 ```value
 ACME
 ```
-{% /string-field %} {% string-field id="fiscal_period" label="Fiscal period"
-required=true %}{% /string-field %} {% /field-group %}
+{% /field %} {% field kind="string" id="fiscal_period" label="Fiscal period"
+required=true %}{% /field %} {% /field-group %}
 
 {% field-group id="source_docs" title="Source Documents" %} {% checkboxes
 id="docs_reviewed" label="Documents reviewed" required=true %}
@@ -804,7 +907,7 @@ id="docs_reviewed" label="Documents reviewed" required=true %}
 
 - [/] Earnings release {% #earnings_release %}
 
-- [ ] Earnings call transcript {% #call_transcript %} {% /checkboxes %} {% /field-group
+- [ ] Earnings call transcript {% #call_transcript %} {% /field %} {% /field-group
   %}
 ````
 
@@ -912,7 +1015,7 @@ would create ambiguous or malformed output.
 **Example—Markdown documentation inside a value:**
 
 ```md
-{% string-field id="setup_guide" label="Setup Guide" %}
+{% field kind="string" id="setup_guide" label="Setup Guide" %}
 ~~~value
 ## Installation
 
@@ -930,7 +1033,7 @@ Then configure:
 }
 ```
 ~~~
-{% /string-field %}
+{% /field %}
 ```
 
 Here the serializer chose tildes (`~~~`) because the content contains backticks. The
@@ -953,6 +1056,107 @@ language (e.g., Pydantic for Python, JSON Schema for language-agnostic interchan
 The schemas below are normative—conforming implementations must support equivalent
 data structures.
 
+#### Type System
+
+This section formalizes the distinction between **field kinds** (Markform's field
+classification) and **data types** (the underlying value representation).
+
+##### Terminology
+
+| Term | Definition | Examples |
+| --- | --- | --- |
+| **Field Kind** | Markform field classification. Determines syntax, validation, and behavior. | `string`, `single_select`, `table` |
+| **Data Type** | TypeScript/JSON type of the value. | `string`, `number`, `string[]` |
+| **Value Type** | Complete type expression including nullability. | `string \| null`, `OptionId[]` |
+| **Scalar Type** | Single atomic value (optionally format-constrained). | `string`, `url`, `date` |
+| **Column Type** | Type of a cell in a table field (subset of scalar types). | `string`, `number`, `url` |
+
+##### Data Type Taxonomy
+
+**Primitive Types** — Base JSON types:
+
+| Primitive | Description |
+| --- | --- |
+| `string` | UTF-8 text |
+| `number` | IEEE 754 float (includes integers) |
+| `boolean` | true/false |
+| `null` | Absence of value |
+
+**Scalar Types** — Primitives with optional format constraints:
+
+| Scalar Type | Base Primitive | Format Constraint |
+| --- | --- | --- |
+| `string` | `string` | — |
+| `number` | `number` | — |
+| `url` | `string` | Valid URL |
+| `date` | `string` | ISO 8601 (YYYY-MM-DD) |
+| `year` | `number` | Integer in valid year range |
+
+**Enum Types** — Values constrained to a defined set:
+
+| Enum Type | Base Primitive | Values |
+| --- | --- | --- |
+| `OptionId` | `string` | One of the field's defined option IDs |
+| `CheckboxValue` | `string` | State tokens based on `checkboxMode` |
+
+**Collection Types** — Compound types:
+
+| Collection Type | Structure |
+| --- | --- |
+| `Array<T>` | Ordered list of `T` |
+| `Record<K, V>` | Key-value map |
+
+**Structured Types** — Complex domain objects:
+
+| Structured Type | Definition |
+| --- | --- |
+| `TableRow` | `Record<ColumnId, CellValue>` |
+| `CellValue` | Scalar type determined by column's type |
+
+##### Field Kind Taxonomy
+
+Field kinds are organized into four categories:
+
+```
+Field Kinds
+├── Simple Kinds ──────── Single scalar value (nullable)
+│   ├── string           Also usable as column types
+│   ├── number           in table fields
+│   ├── url
+│   ├── date
+│   └── year
+│
+├── List Kinds ────────── Ordered array of scalars
+│   ├── string_list      Open-ended (user provides items)
+│   └── url_list
+│
+├── Chooser Kinds ─────── Selection from predefined options
+│   ├── single_select    Pick one
+│   ├── multi_select     Pick many
+│   └── checkboxes       State per option
+│
+└── Structured Kinds ──── Complex nested data
+    └── table            Rows × typed columns
+```
+
+**Simple Kinds** can also be used as column types in table fields.
+
+##### Kind → Type Mapping
+
+| Field Kind | Category | Value Type | Base Type | Notes |
+| --- | --- | --- | --- | --- |
+| `string` | Simple | `string \| null` | `string` | Plain text |
+| `number` | Simple | `number \| null` | `number` | Integer or float |
+| `url` | Simple | `string \| null` | `string` | URL format validated |
+| `date` | Simple | `string \| null` | `string` | ISO 8601 format |
+| `year` | Simple | `number \| null` | `number` | Integer year |
+| `string_list` | List | `string[]` | `Array<string>` | Empty = `[]` |
+| `url_list` | List | `string[]` | `Array<string>` | URL format validated |
+| `single_select` | Chooser | `OptionId \| null` | `string` (enum) | One of defined options |
+| `multi_select` | Chooser | `OptionId[]` | `Array<string>` (enum) | Subset of options |
+| `checkboxes` | Chooser | `Record<OptionId, CheckboxValue>` | `Record<string, string>` | State per option |
+| `table` | Structured | `TableRow[]` | `Array<Record<string, CellValue>>` | Typed columns |
+
 #### Canonical TypeScript Types
 
 ```ts
@@ -961,7 +1165,7 @@ type Id = string; // validated snake_case, e.g., /^[a-z][a-z0-9_]*$/
 // Validator reference: simple string ID or parameterized object
 type ValidatorRef = string | { id: string; [key: string]: unknown };
 
-// Answer state for a field - orthogonal to field type
+// Answer state for a field - orthogonal to field kind
 // Any field can be in any answer state
 type AnswerState = 'unanswered' | 'answered' | 'skipped' | 'aborted';
 
@@ -1196,10 +1400,10 @@ type FieldKind = 'string' | 'number' | 'string_list' | 'checkboxes' | 'single_se
 
 interface StructureSummary {
   groupCount: number;           // total field-groups
-  fieldCount: number;           // total fields (all types)
+  fieldCount: number;           // total fields (all kinds)
   optionCount: number;          // total options across all select/checkbox fields
 
-  fieldCountByKind: Record<FieldKind, number>;  // breakdown by field type
+  fieldCountByKind: Record<FieldKind, number>;  // breakdown by field kind
 
   /** Map of group ID -> 'field_group' (for completeness; groups have one kind) */
   groupsById: Record<Id, 'field_group'>;
@@ -1237,7 +1441,7 @@ Tracks filling progress per field without exposing actual values:
 type ProgressState = 'empty' | 'incomplete' | 'invalid' | 'complete';
 
 interface FieldProgress {
-  kind: FieldKind;             // field type
+  kind: FieldKind;             // field kind
   required: boolean;           // whether field has required=true
 
   answerState: AnswerState;    // unified answer state (unanswered/answered/skipped/aborted)
@@ -1390,7 +1594,7 @@ else:
 For form completion purposes, fields with constraints are treated as implicitly
 required:
 
-| Field Type | Implicit Required When |
+| Field Kind | Implicit Required When |
 | --- | --- |
 | `string-list` | `minItems > 0` |
 | `multi-select` | `minSelections > 0` |
@@ -1577,10 +1781,10 @@ const MarkformFrontmatterSchema = z.object({
 Use a `toSnakeCaseDeep()` helper for deterministic conversion at the frontmatter
 boundary.
 
-#### Comprehensive Field Type Reference
+#### Comprehensive Field Kind Reference
 
 This section provides a complete mapping between Markdoc syntax, TypeScript types, and
-schema representations for all field types.
+schema representations for all field kinds.
 
 ##### Naming Conventions
 
@@ -1593,7 +1797,7 @@ schema representations for all field types.
 | JSON Schema keywords | camelCase | `minItems`, `maxLength`, `uniqueItems` |
 | IDs (values) | snake_case | `company_name`, `ten_k`, `quarterly_earnings` |
 | YAML keys (frontmatter, session transcripts) | snake_case | `spec`, `form_summary`, `field_count_by_kind` |
-| Kind values (field types) | snake_case | `'string'`, `'single_select'` |
+| Kind values (field kinds) | snake_case | `'string'`, `'single_select'` |
 | Patch operations | snake_case | `set_string`, `set_single_select` |
 
 **Rationale:** Using camelCase for Markdoc attributes aligns with JSON Schema keywords
@@ -1605,11 +1809,11 @@ YAML keys use snake_case for readability and consistency with common YAML conven
 
 | Property | Used on | Values | Notes |
 | --- | --- | --- | --- |
-| `kind` | `Field`, `FieldValue` | `FieldKind` values | Reserved for field type discrimination only |
+| `kind` | `Field`, `FieldValue` | `FieldKind` values | Reserved for field kind discrimination only |
 | `tag` | `DocumentationBlock` | `DocumentationTag` values | Identifies doc block type |
 | `nodeType` | `IdIndexEntry` | `'form' \| 'group' \| 'field'` | Identifies structural element type |
 
-##### Field Type Mappings
+##### Field Kind Mappings
 
 **`string-field`** — Single string value
 
@@ -1715,6 +1919,45 @@ YAML keys use snake_case for readability and consistency with common YAML conven
 | Zod | `z.array(z.string().url()).min(n).max(m)` |
 | JSON Schema | `{ type: "array", items: { type: "string", format: "uri" }, minItems, maxItems, uniqueItems }` |
 
+**`date-field`** — ISO 8601 date value (YYYY-MM-DD)
+
+| Aspect | Value |
+| --- | --- |
+| Markdoc tag | `date-field` |
+| TypeScript interface | `DateField` |
+| TypeScript kind | `'date'` |
+| Attributes | `id`, `label`, `required`, `min`, `max` |
+| FieldValue | `{ kind: 'date'; value: string \| null }` |
+| Patch operation | `{ op: 'set_date'; fieldId: Id; value: string \| null }` |
+| Zod | `z.string().regex(/^\d{4}-\d{2}-\d{2}$/)` |
+| JSON Schema | `{ type: "string", format: "date" }` |
+
+**`year-field`** — Integer year value
+
+| Aspect | Value |
+| --- | --- |
+| Markdoc tag | `year-field` |
+| TypeScript interface | `YearField` |
+| TypeScript kind | `'year'` |
+| Attributes | `id`, `label`, `required`, `min`, `max` |
+| FieldValue | `{ kind: 'year'; value: number \| null }` |
+| Patch operation | `{ op: 'set_year'; fieldId: Id; value: number \| null }` |
+| Zod | `z.number().int().min(min).max(max)` |
+| JSON Schema | `{ type: "integer", minimum: min, maximum: max }` |
+
+**`table-field`** — Structured tabular data with typed columns
+
+| Aspect | Value |
+| --- | --- |
+| Markdoc tag | `table-field` |
+| TypeScript interface | `TableField` |
+| TypeScript kind | `'table'` |
+| Attributes | `id`, `label`, `required`, `columnIds`, `columnLabels`, `columnTypes`, `minRows`, `maxRows` |
+| FieldValue | `{ kind: 'table'; rows: TableRowResponse[] }` |
+| Patch operation | `{ op: 'set_table'; fieldId: Id; rows: PatchTableRow[] }` |
+| Zod | `z.object({ kind: z.literal('table'), rows: z.array(TableRowResponseSchema) })` |
+| JSON Schema | `{ type: "object", properties: { kind: { const: "table" }, rows: { type: "array" } } }` |
+
 **Note:** `OptionId` values are local to the field (e.g., `"ten_k"`, `"bullish"`). They
 are NOT qualified with the field ID in patches or FieldValue—the field context is
 implicit.
@@ -1742,12 +1985,16 @@ Validation happens at two levels: Markdoc syntax validation (see
 
 Schema checks (always available, deterministic):
 
-| Check | Field Type | Constraint Source |
+| Check | Field Kind | Constraint Source |
 | --- | --- | --- |
 | Required fields present | All | `required=true` attribute |
 | Number parsing success | `number-field` | Built-in |
 | Min/max value range | `number-field` | `min`, `max` attributes |
 | Integer constraint | `number-field` | `integer=true` attribute |
+| Date format validation | `date-field` | Built-in (ISO 8601 YYYY-MM-DD) |
+| Min/max date range | `date-field` | `min`, `max` attributes |
+| Year integer validation | `year-field` | Built-in (integer) |
+| Min/max year range | `year-field` | `min`, `max` attributes |
 | Pattern match | `string-field` | `pattern` attribute (JS regex) |
 | Min/max length | `string-field` | `minLength`, `maxLength` attributes |
 | Min/max item count | `string-list` | `minItems`, `maxItems` attributes |
@@ -1762,13 +2009,17 @@ Output: `ValidationIssue[]`
 
 #### Required Field Semantics
 
-The `required` attribute has specific semantics for each field type.
+The `required` attribute has specific semantics for each field kind.
 This section provides normative definitions:
 
-| Field Type | `required=true` means | `required=false` (or omitted) means |
+| Field Kind | `required=true` means | `required=false` (or omitted) means |
 | --- | --- | --- |
 | `string-field` | `value !== null && value.trim() !== ""` | Value may be null or empty |
 | `number-field` | `value !== null` (and parseable as number) | Value may be null |
+| `date-field` | `value !== null && isValidDate(value)` | Value may be null |
+| `year-field` | `value !== null` (and valid integer) | Value may be null |
+| `url-field` | `value !== null && isValidUrl(value)` | Value may be null |
+| `url-list` | `items.length >= max(1, minItems)` | Empty array is valid (unless `minItems` constraint) |
 | `string-list` | `items.length >= max(1, minItems)` | Empty array is valid (unless `minItems` constraint) |
 | `single-select` | Exactly one option must be selected | Zero or one option selected (never >1) |
 | `multi-select` | `selected.length >= max(1, minSelections)` | Empty selection valid (unless `minSelections` constraint) |
@@ -1906,11 +2157,11 @@ export const validators: Record<string, (ctx: ValidatorContext) => ValidationIss
 
 <!-- Parameterized: pass min word count as parameter -->
 
-{% string-field id="thesis" label="Investment thesis" validate=[{id: "min_words", min: 50}] %}{% /string-field %}
+{% field kind="string" id="thesis" label="Investment thesis" validate=[{id: "min_words", min: 50}] %}{% /field %}
 
 <!-- Multiple validators with different params -->
 
-{% string-field id="summary" label="Summary" validate=[{id: "min_words", min: 25}, {id: "max_words", max: 100}] %}{% /string-field %}
+{% field kind="string" id="summary" label="Summary" validate=[{id: "min_words", min: 25}, {id: "max_words", max: 100}] %}{% /field %}
 
 <!-- Sum-to validator with configurable target -->