markform 0.1.22 → 0.1.24

package/docs/markform-apis.md

@@ -138,6 +138,12 @@ Each patch has an `op` and `fieldId`.
 | `set_date` | date | `{ "op": "set_date", "fieldId": "deadline", "value": "2024-06-15" }` |
 | `set_year` | year | `{ "op": "set_year", "fieldId": "founded", "value": 2015 }` |
 | `set_table` | table | `{ "op": "set_table", "fieldId": "data", "value": [{"col1": "v1"}] }` |
+| `append_table` | table | `{ "op": "append_table", "fieldId": "data", "value": [{"col1": "v2"}] }` |
+| `delete_table` | table | `{ "op": "delete_table", "fieldId": "data", "value": [0, 2] }` |
+| `append_string_list` | string_list | `{ "op": "append_string_list", "fieldId": "tags", "value": ["c"] }` |
+| `delete_string_list` | string_list | `{ "op": "delete_string_list", "fieldId": "tags", "value": ["a"] }` |
+| `append_url_list` | url_list | `{ "op": "append_url_list", "fieldId": "sources", "value": ["https://new"] }` |
+| `delete_url_list` | url_list | `{ "op": "delete_url_list", "fieldId": "sources", "value": ["https://old"] }` |
 | `clear_field` | any | `{ "op": "clear_field", "fieldId": "name" }` |
 | `skip_field` | optional | `{ "op": "skip_field", "fieldId": "notes", "reason": "Not applicable" }` |
 | `abort_field` | any | `{ "op": "abort_field", "fieldId": "data", "reason": "Unable to find" }` |

package/docs/markform-reference.md

@@ -716,7 +716,22 @@ markform inspect form.md --format=json
 # Validate form (check for errors)
 markform validate form.md
 
-# Fill forms
+# Set field values (agent-friendly, auto-coerced)
+markform set form.md fieldId "value"              # Set a single field
+markform set form.md --values '{"name": "Alice", "age": 30}'  # Batch set
+markform set form.md fieldId --clear              # Clear a field
+markform set form.md fieldId --skip               # Skip a field
+markform set form.md fieldId --abort              # Abort a field
+markform set form.md tableId --append '[{"col": "val"}]'      # Append rows
+markform set form.md tableId --delete '[0, 2]'                # Delete rows by index
+
+# Get next field recommendation
+markform next form.md                             # What field to fill next
+
+# Apply raw typed patches (low-level)
+markform patch form.md '[{"op": "set_string", "fieldId": "name", "value": "Alice"}]'
+
+# Fill forms (harness-driven sessions)
 markform fill form.md --interactive              # Interactive prompts for user fields
 markform fill form.md --roles=user --interactive # Only fill user-role fields
 markform fill form.md --model anthropic/claude-sonnet-4-5  # AI fills agent fields
@@ -783,6 +798,16 @@ markform fill template.form.md --mock --mock-source filled.form.md
 
 6. **Document thoroughly**: Use `{% instructions %}` for complex fields
 
+## Claude Code Skill Setup
+
+Install markform as a Claude Code skill so agents know how to use it:
+
+```bash
+markform setup --auto         # Non-interactive (for agents)
+markform setup --interactive  # Guided setup (for humans)
+markform skill                # View the skill content
+```
+
 ## Programmatic API
 
 For TypeScript and AI SDK integration, run `markform apis` or see

package/docs/markform-spec.md

@@ -2868,9 +2868,11 @@ This formula ensures:
 | Operation | CLI | AI SDK | MCP (MF/0.2) |
 | --- | --- | --- | --- |
 | inspect | `markform inspect` (prints YAML report) | `markform_inspect` | `markform.inspect` |
-| apply | `markform apply` | `markform_apply` | `markform.apply` |
+| patch | `markform patch` (raw typed patches) | `markform_apply` | `markform.apply` |
+| set | `markform set` (auto-coerced value setting) | — | — |
+| next | `markform next` (next-field advisor) | — | — |
 | export | `markform export --format=json` | `markform_export` | `markform.export` |
-| getMarkdown | `markform apply` (writes file) | `markform_get_markdown` | `markform.get_markdown` |
+| getMarkdown | `markform patch` (writes file) | `markform_get_markdown` | `markform.get_markdown` |
 | render | `markform render` (static HTML output) | — | — |
 | serve | `markform serve` (interactive web UI) | — | — |
 
@@ -2889,6 +2891,12 @@ type Patch =
   | { op: 'set_table'; fieldId: Id; value: PatchTableRow[] }
   | { op: 'set_date'; fieldId: Id; value: string | null }
   | { op: 'set_year'; fieldId: Id; value: number | null }
+  | { op: 'append_table'; fieldId: Id; value: PatchTableRow[] }
+  | { op: 'delete_table'; fieldId: Id; value: number[] }
+  | { op: 'append_string_list'; fieldId: Id; value: string[] }
+  | { op: 'delete_string_list'; fieldId: Id; value: string[] }
+  | { op: 'append_url_list'; fieldId: Id; value: string[] }
+  | { op: 'delete_url_list'; fieldId: Id; value: string[] }
   | { op: 'clear_field'; fieldId: Id }
   | { op: 'skip_field'; fieldId: Id; role: string; reason?: string }
   | { op: 'abort_field'; fieldId: Id; role: string; reason?: string }
@@ -3059,7 +3067,7 @@ This is the normal inspect/apply/fix workflow.
 
 **Patch conflict handling:**
 
-- Patches are applied in array order within a single `apply` call
+- Patches are applied in array order within a single `patch`/`applyPatches()` call
 
 - Later patches to the same field overwrite earlier ones (last-write-wins)
 

package/docs/skill/SKILL.md

@@ -0,0 +1,119 @@
+---
+name: markform
+description: >-
+  Markdown-based form system for structured data collection by AI agents and humans.
+  Inspect, fill, validate, and export .form.md files with typed fields and role-based workflows.
+  Use when working with .form.md files, filling forms, validating fields, exporting data,
+  or when the user mentions markform, forms, form filling, structured data, or field validation.
+allowed-tools: Bash(markform:*)
+---
+
+# Markform — Agent Skill
+
+Markform is structured Markdown for forms. Files combine YAML frontmatter with HTML
+comment tags to define typed, validated fields. Forms render cleanly on GitHub since
+structure is hidden in comments.
+
+## What Markform Does
+
+1. **Structured Forms**: Define typed fields (string, number, select, table, etc.) in
+   Markdown with validation constraints
+2. **Role-Based Filling**: Separate fields for humans (`role="user"`) and AI agents
+   (`role="agent"`)
+3. **Incremental Filling**: Fill fields one at a time with immediate validation
+4. **Agent-Driven Workflows**: AI agents fill forms via CLI or programmatic API
+5. **Multi-Format Export**: Export filled data as JSON, YAML, or Markdown
+
+## Core CLI Commands
+
+| Command | Purpose |
+| --- | --- |
+| `markform inspect <form>` | Show form structure, progress, and issues |
+| `markform validate <form>` | Check for constraint violations and errors |
+| `markform set <form> <field> "value"` | Set a field value (auto-coerced) |
+| `markform set <form> --values '{"k":"v"}'` | Batch set multiple fields |
+| `markform next <form>` | Recommend the next field to fill |
+| `markform fill <form> --interactive` | Interactive prompts for user fields |
+| `markform fill <form> --model <model>` | AI agent fills form fields |
+| `markform export <form> --format=json` | Export values as JSON |
+| `markform export <form> --format=yaml` | Export values as YAML |
+| `markform schema <form>` | Export JSON Schema for form structure |
+| `markform dump <form>` | Quick dump of current field values |
+| `markform status <form>` | Show fill progress per role |
+| `markform docs` | Show Markform syntax reference |
+| `markform examples` | Copy built-in example forms |
+| `markform serve <form>` | Web UI for browsing and editing |
+
+## Agent Workflow
+
+When working with markform files:
+
+1. **Inspect first**: `markform inspect form.md` to understand the form structure,
+   see which fields exist, their types, constraints, and current fill progress
+2. **Check what's next**: `markform next form.md` to see which field should be
+   filled next (respects priority, order, and role)
+3. **Set values**: `markform set form.md field_id "value"` to fill fields one at
+   a time, or use `--values` for batch updates
+4. **Validate**: `markform validate form.md` to check all constraints are met
+5. **Export**: `markform export form.md --format=json` to extract filled data
+
+## Setting Field Values
+
+The `set` command is the primary way to fill fields. It auto-coerces values to
+the correct type:
+
+```bash
+# String fields
+markform set form.md name "Alice Smith"
+
+# Number fields (auto-coerced from string)
+markform set form.md age 30
+
+# Single select (by option ID)
+markform set form.md rating high
+
+# Multi select (JSON array of option IDs)
+markform set form.md categories '["frontend","backend"]'
+
+# Checkboxes (JSON object of {itemId: value})
+markform set form.md tasks '{"research":"done","testing":"done"}'
+
+# Table (append rows as JSON)
+markform set form.md team --append '[{"name": "Alice", "title": "Engineer"}]'
+
+# Batch set multiple fields
+markform set form.md --values '{"name": "Alice", "age": 30, "rating": "high"}'
+
+# Special operations
+markform set form.md field_id --clear    # Clear a field value
+markform set form.md field_id --skip     # Skip (mark as skipped)
+markform set form.md field_id --abort    # Abort (mark as aborted)
+```
+
+## Global Options
+
+All commands support:
+
+| Option | Description |
+| --- | --- |
+| `--format <fmt>` | Output format: console, json, yaml, plaintext, markform, markdown |
+| `--verbose` | Enable verbose/debug output |
+| `--quiet` | Suppress non-essential output |
+| `--dry-run` | Show what would be done without changes |
+| `--overwrite` | Overwrite existing field values |
+
+## File Conventions
+
+| Extension | Purpose |
+| --- | --- |
+| `.form.md` | Markform source and filled forms |
+| `.fill.json` | Execution metadata (sidecar, auto-generated) |
+| `.report.md` | Filtered human-readable output |
+| `.schema.json` | JSON Schema export |
+
+## More Information
+
+- Syntax reference: `markform docs`
+- Full specification: `markform spec`
+- API documentation: `markform apis`
+- Example forms: `markform examples`

package/examples/rejection-test/rejection-test.session.yaml

@@ -78,6 +78,19 @@ turns:
         | checkboxes | `{ op: "set_checkboxes", fieldId: "tasks", value: { "task1": "done", "task2": "todo" } }` |
         | table | `{ op: "set_table", fieldId: "team", value: [{ "name": "Alice", "role": "Engineer" }] }` |
 
+        ## Incremental Operations (for collections)
+
+        Use these to add/remove items without replacing the entire collection:
+
+        | Type | Example |
+        |------|---------|
+        | append_table | `{ op: "append_table", fieldId: "team", value: [{ "name": "Bob", "role": "PM" }] }` |
+        | append_string_list | `{ op: "append_string_list", fieldId: "tags", value: ["new_tag"] }` |
+        | append_url_list | `{ op: "append_url_list", fieldId: "sources", value: ["https://new.com"] }` |
+        | delete_table | `{ op: "delete_table", fieldId: "team", value: 0 }` (0-based row index) |
+        | delete_string_list | `{ op: "delete_string_list", fieldId: "tags", value: 0 }` (0-based item index) |
+        | delete_url_list | `{ op: "delete_url_list", fieldId: "sources", value: 0 }` (0-based item index) |
+
         ## Important: checkboxes vs multi_select
 
         These two types look similar but have DIFFERENT value formats:
@@ -201,6 +214,19 @@ turns:
           | checkboxes | `{ op: "set_checkboxes", fieldId: "tasks", value: { "task1": "done", "task2": "todo" } }` |
           | table | `{ op: "set_table", fieldId: "team", value: [{ "name": "Alice", "role": "Engineer" }] }` |
 
+          ## Incremental Operations (for collections)
+
+          Use these to add/remove items without replacing the entire collection:
+
+          | Type | Example |
+          |------|---------|
+          | append_table | `{ op: "append_table", fieldId: "team", value: [{ "name": "Bob", "role": "PM" }] }` |
+          | append_string_list | `{ op: "append_string_list", fieldId: "tags", value: ["new_tag"] }` |
+          | append_url_list | `{ op: "append_url_list", fieldId: "sources", value: ["https://new.com"] }` |
+          | delete_table | `{ op: "delete_table", fieldId: "team", value: 0 }` (0-based row index) |
+          | delete_string_list | `{ op: "delete_string_list", fieldId: "tags", value: 0 }` (0-based item index) |
+          | delete_url_list | `{ op: "delete_url_list", fieldId: "sources", value: 0 }` (0-based item index) |
+
           ## Important: checkboxes vs multi_select
 
           These two types look similar but have DIFFERENT value formats:
@@ -381,6 +407,19 @@ turns:
         | checkboxes | `{ op: "set_checkboxes", fieldId: "tasks", value: { "task1": "done", "task2": "todo" } }` |
         | table | `{ op: "set_table", fieldId: "team", value: [{ "name": "Alice", "role": "Engineer" }] }` |
 
+        ## Incremental Operations (for collections)
+
+        Use these to add/remove items without replacing the entire collection:
+
+        | Type | Example |
+        |------|---------|
+        | append_table | `{ op: "append_table", fieldId: "team", value: [{ "name": "Bob", "role": "PM" }] }` |
+        | append_string_list | `{ op: "append_string_list", fieldId: "tags", value: ["new_tag"] }` |
+        | append_url_list | `{ op: "append_url_list", fieldId: "sources", value: ["https://new.com"] }` |
+        | delete_table | `{ op: "delete_table", fieldId: "team", value: 0 }` (0-based row index) |
+        | delete_string_list | `{ op: "delete_string_list", fieldId: "tags", value: 0 }` (0-based item index) |
+        | delete_url_list | `{ op: "delete_url_list", fieldId: "sources", value: 0 }` (0-based item index) |
+
         ## Important: checkboxes vs multi_select
 
         These two types look similar but have DIFFERENT value formats:
@@ -510,6 +549,19 @@ turns:
           | checkboxes | `{ op: "set_checkboxes", fieldId: "tasks", value: { "task1": "done", "task2": "todo" } }` |
           | table | `{ op: "set_table", fieldId: "team", value: [{ "name": "Alice", "role": "Engineer" }] }` |
 
+          ## Incremental Operations (for collections)
+
+          Use these to add/remove items without replacing the entire collection:
+
+          | Type | Example |
+          |------|---------|
+          | append_table | `{ op: "append_table", fieldId: "team", value: [{ "name": "Bob", "role": "PM" }] }` |
+          | append_string_list | `{ op: "append_string_list", fieldId: "tags", value: ["new_tag"] }` |
+          | append_url_list | `{ op: "append_url_list", fieldId: "sources", value: ["https://new.com"] }` |
+          | delete_table | `{ op: "delete_table", fieldId: "team", value: 0 }` (0-based row index) |
+          | delete_string_list | `{ op: "delete_string_list", fieldId: "tags", value: 0 }` (0-based item index) |
+          | delete_url_list | `{ op: "delete_url_list", fieldId: "sources", value: 0 }` (0-based item index) |
+
           ## Important: checkboxes vs multi_select
 
           These two types look similar but have DIFFERENT value formats:

package/examples/simple/simple-with-skips.session.yaml

@@ -151,6 +151,19 @@ turns:
         | checkboxes | `{ op: "set_checkboxes", fieldId: "tasks", value: { "task1": "done", "task2": "todo" } }` |
         | table | `{ op: "set_table", fieldId: "team", value: [{ "name": "Alice", "role": "Engineer" }] }` |
 
+        ## Incremental Operations (for collections)
+
+        Use these to add/remove items without replacing the entire collection:
+
+        | Type | Example |
+        |------|---------|
+        | append_table | `{ op: "append_table", fieldId: "team", value: [{ "name": "Bob", "role": "PM" }] }` |
+        | append_string_list | `{ op: "append_string_list", fieldId: "tags", value: ["new_tag"] }` |
+        | append_url_list | `{ op: "append_url_list", fieldId: "sources", value: ["https://new.com"] }` |
+        | delete_table | `{ op: "delete_table", fieldId: "team", value: 0 }` (0-based row index) |
+        | delete_string_list | `{ op: "delete_string_list", fieldId: "tags", value: 0 }` (0-based item index) |
+        | delete_url_list | `{ op: "delete_url_list", fieldId: "sources", value: 0 }` (0-based item index) |
+
         ## Important: checkboxes vs multi_select
 
         These two types look similar but have DIFFERENT value formats:
@@ -477,6 +490,19 @@ turns:
           | checkboxes | `{ op: "set_checkboxes", fieldId: "tasks", value: { "task1": "done", "task2": "todo" } }` |
           | table | `{ op: "set_table", fieldId: "team", value: [{ "name": "Alice", "role": "Engineer" }] }` |
 
+          ## Incremental Operations (for collections)
+
+          Use these to add/remove items without replacing the entire collection:
+
+          | Type | Example |
+          |------|---------|
+          | append_table | `{ op: "append_table", fieldId: "team", value: [{ "name": "Bob", "role": "PM" }] }` |
+          | append_string_list | `{ op: "append_string_list", fieldId: "tags", value: ["new_tag"] }` |
+          | append_url_list | `{ op: "append_url_list", fieldId: "sources", value: ["https://new.com"] }` |
+          | delete_table | `{ op: "delete_table", fieldId: "team", value: 0 }` (0-based row index) |
+          | delete_string_list | `{ op: "delete_string_list", fieldId: "tags", value: 0 }` (0-based item index) |
+          | delete_url_list | `{ op: "delete_url_list", fieldId: "sources", value: 0 }` (0-based item index) |
+
           ## Important: checkboxes vs multi_select
 
           These two types look similar but have DIFFERENT value formats:
@@ -979,6 +1005,19 @@ turns:
         | checkboxes | `{ op: "set_checkboxes", fieldId: "tasks", value: { "task1": "done", "task2": "todo" } }` |
         | table | `{ op: "set_table", fieldId: "team", value: [{ "name": "Alice", "role": "Engineer" }] }` |
 
+        ## Incremental Operations (for collections)
+
+        Use these to add/remove items without replacing the entire collection:
+
+        | Type | Example |
+        |------|---------|
+        | append_table | `{ op: "append_table", fieldId: "team", value: [{ "name": "Bob", "role": "PM" }] }` |
+        | append_string_list | `{ op: "append_string_list", fieldId: "tags", value: ["new_tag"] }` |
+        | append_url_list | `{ op: "append_url_list", fieldId: "sources", value: ["https://new.com"] }` |
+        | delete_table | `{ op: "delete_table", fieldId: "team", value: 0 }` (0-based row index) |
+        | delete_string_list | `{ op: "delete_string_list", fieldId: "tags", value: 0 }` (0-based item index) |
+        | delete_url_list | `{ op: "delete_url_list", fieldId: "sources", value: 0 }` (0-based item index) |
+
         ## Important: checkboxes vs multi_select
 
         These two types look similar but have DIFFERENT value formats:
@@ -1328,6 +1367,19 @@ turns:
           | checkboxes | `{ op: "set_checkboxes", fieldId: "tasks", value: { "task1": "done", "task2": "todo" } }` |
           | table | `{ op: "set_table", fieldId: "team", value: [{ "name": "Alice", "role": "Engineer" }] }` |
 
+          ## Incremental Operations (for collections)
+
+          Use these to add/remove items without replacing the entire collection:
+
+          | Type | Example |
+          |------|---------|
+          | append_table | `{ op: "append_table", fieldId: "team", value: [{ "name": "Bob", "role": "PM" }] }` |
+          | append_string_list | `{ op: "append_string_list", fieldId: "tags", value: ["new_tag"] }` |
+          | append_url_list | `{ op: "append_url_list", fieldId: "sources", value: ["https://new.com"] }` |
+          | delete_table | `{ op: "delete_table", fieldId: "team", value: 0 }` (0-based row index) |
+          | delete_string_list | `{ op: "delete_string_list", fieldId: "tags", value: 0 }` (0-based item index) |
+          | delete_url_list | `{ op: "delete_url_list", fieldId: "sources", value: 0 }` (0-based item index) |
+
           ## Important: checkboxes vs multi_select
 
           These two types look similar but have DIFFERENT value formats:
@@ -1763,6 +1815,19 @@ turns:
         | checkboxes | `{ op: "set_checkboxes", fieldId: "tasks", value: { "task1": "done", "task2": "todo" } }` |
         | table | `{ op: "set_table", fieldId: "team", value: [{ "name": "Alice", "role": "Engineer" }] }` |
 
+        ## Incremental Operations (for collections)
+
+        Use these to add/remove items without replacing the entire collection:
+
+        | Type | Example |
+        |------|---------|
+        | append_table | `{ op: "append_table", fieldId: "team", value: [{ "name": "Bob", "role": "PM" }] }` |
+        | append_string_list | `{ op: "append_string_list", fieldId: "tags", value: ["new_tag"] }` |
+        | append_url_list | `{ op: "append_url_list", fieldId: "sources", value: ["https://new.com"] }` |
+        | delete_table | `{ op: "delete_table", fieldId: "team", value: 0 }` (0-based row index) |
+        | delete_string_list | `{ op: "delete_string_list", fieldId: "tags", value: 0 }` (0-based item index) |
+        | delete_url_list | `{ op: "delete_url_list", fieldId: "sources", value: 0 }` (0-based item index) |
+
         ## Important: checkboxes vs multi_select
 
         These two types look similar but have DIFFERENT value formats:
@@ -2085,6 +2150,19 @@ turns:
           | checkboxes | `{ op: "set_checkboxes", fieldId: "tasks", value: { "task1": "done", "task2": "todo" } }` |
           | table | `{ op: "set_table", fieldId: "team", value: [{ "name": "Alice", "role": "Engineer" }] }` |
 
+          ## Incremental Operations (for collections)
+
+          Use these to add/remove items without replacing the entire collection:
+
+          | Type | Example |
+          |------|---------|
+          | append_table | `{ op: "append_table", fieldId: "team", value: [{ "name": "Bob", "role": "PM" }] }` |
+          | append_string_list | `{ op: "append_string_list", fieldId: "tags", value: ["new_tag"] }` |
+          | append_url_list | `{ op: "append_url_list", fieldId: "sources", value: ["https://new.com"] }` |
+          | delete_table | `{ op: "delete_table", fieldId: "team", value: 0 }` (0-based row index) |
+          | delete_string_list | `{ op: "delete_string_list", fieldId: "tags", value: 0 }` (0-based item index) |
+          | delete_url_list | `{ op: "delete_url_list", fieldId: "sources", value: 0 }` (0-based item index) |
+
           ## Important: checkboxes vs multi_select
 
           These two types look similar but have DIFFERENT value formats:

package/examples/simple/simple.session.yaml

@@ -152,6 +152,19 @@ turns:
         | checkboxes | `{ op: "set_checkboxes", fieldId: "tasks", value: { "task1": "done", "task2": "todo" } }` |
         | table | `{ op: "set_table", fieldId: "team", value: [{ "name": "Alice", "role": "Engineer" }] }` |
 
+        ## Incremental Operations (for collections)
+
+        Use these to add/remove items without replacing the entire collection:
+
+        | Type | Example |
+        |------|---------|
+        | append_table | `{ op: "append_table", fieldId: "team", value: [{ "name": "Bob", "role": "PM" }] }` |
+        | append_string_list | `{ op: "append_string_list", fieldId: "tags", value: ["new_tag"] }` |
+        | append_url_list | `{ op: "append_url_list", fieldId: "sources", value: ["https://new.com"] }` |
+        | delete_table | `{ op: "delete_table", fieldId: "team", value: 0 }` (0-based row index) |
+        | delete_string_list | `{ op: "delete_string_list", fieldId: "tags", value: 0 }` (0-based item index) |
+        | delete_url_list | `{ op: "delete_url_list", fieldId: "sources", value: 0 }` (0-based item index) |
+
         ## Important: checkboxes vs multi_select
 
         These two types look similar but have DIFFERENT value formats:
@@ -478,6 +491,19 @@ turns:
           | checkboxes | `{ op: "set_checkboxes", fieldId: "tasks", value: { "task1": "done", "task2": "todo" } }` |
           | table | `{ op: "set_table", fieldId: "team", value: [{ "name": "Alice", "role": "Engineer" }] }` |
 
+          ## Incremental Operations (for collections)
+
+          Use these to add/remove items without replacing the entire collection:
+
+          | Type | Example |
+          |------|---------|
+          | append_table | `{ op: "append_table", fieldId: "team", value: [{ "name": "Bob", "role": "PM" }] }` |
+          | append_string_list | `{ op: "append_string_list", fieldId: "tags", value: ["new_tag"] }` |
+          | append_url_list | `{ op: "append_url_list", fieldId: "sources", value: ["https://new.com"] }` |
+          | delete_table | `{ op: "delete_table", fieldId: "team", value: 0 }` (0-based row index) |
+          | delete_string_list | `{ op: "delete_string_list", fieldId: "tags", value: 0 }` (0-based item index) |
+          | delete_url_list | `{ op: "delete_url_list", fieldId: "sources", value: 0 }` (0-based item index) |
+
           ## Important: checkboxes vs multi_select
 
           These two types look similar but have DIFFERENT value formats:
@@ -980,6 +1006,19 @@ turns:
         | checkboxes | `{ op: "set_checkboxes", fieldId: "tasks", value: { "task1": "done", "task2": "todo" } }` |
         | table | `{ op: "set_table", fieldId: "team", value: [{ "name": "Alice", "role": "Engineer" }] }` |
 
+        ## Incremental Operations (for collections)
+
+        Use these to add/remove items without replacing the entire collection:
+
+        | Type | Example |
+        |------|---------|
+        | append_table | `{ op: "append_table", fieldId: "team", value: [{ "name": "Bob", "role": "PM" }] }` |
+        | append_string_list | `{ op: "append_string_list", fieldId: "tags", value: ["new_tag"] }` |
+        | append_url_list | `{ op: "append_url_list", fieldId: "sources", value: ["https://new.com"] }` |
+        | delete_table | `{ op: "delete_table", fieldId: "team", value: 0 }` (0-based row index) |
+        | delete_string_list | `{ op: "delete_string_list", fieldId: "tags", value: 0 }` (0-based item index) |
+        | delete_url_list | `{ op: "delete_url_list", fieldId: "sources", value: 0 }` (0-based item index) |
+
         ## Important: checkboxes vs multi_select
 
         These two types look similar but have DIFFERENT value formats:
@@ -1330,6 +1369,19 @@ turns:
           | checkboxes | `{ op: "set_checkboxes", fieldId: "tasks", value: { "task1": "done", "task2": "todo" } }` |
           | table | `{ op: "set_table", fieldId: "team", value: [{ "name": "Alice", "role": "Engineer" }] }` |
 
+          ## Incremental Operations (for collections)
+
+          Use these to add/remove items without replacing the entire collection:
+
+          | Type | Example |
+          |------|---------|
+          | append_table | `{ op: "append_table", fieldId: "team", value: [{ "name": "Bob", "role": "PM" }] }` |
+          | append_string_list | `{ op: "append_string_list", fieldId: "tags", value: ["new_tag"] }` |
+          | append_url_list | `{ op: "append_url_list", fieldId: "sources", value: ["https://new.com"] }` |
+          | delete_table | `{ op: "delete_table", fieldId: "team", value: 0 }` (0-based row index) |
+          | delete_string_list | `{ op: "delete_string_list", fieldId: "tags", value: 0 }` (0-based item index) |
+          | delete_url_list | `{ op: "delete_url_list", fieldId: "sources", value: 0 }` (0-based item index) |
+
           ## Important: checkboxes vs multi_select
 
           These two types look similar but have DIFFERENT value formats:
@@ -1770,6 +1822,19 @@ turns:
         | checkboxes | `{ op: "set_checkboxes", fieldId: "tasks", value: { "task1": "done", "task2": "todo" } }` |
         | table | `{ op: "set_table", fieldId: "team", value: [{ "name": "Alice", "role": "Engineer" }] }` |
 
+        ## Incremental Operations (for collections)
+
+        Use these to add/remove items without replacing the entire collection:
+
+        | Type | Example |
+        |------|---------|
+        | append_table | `{ op: "append_table", fieldId: "team", value: [{ "name": "Bob", "role": "PM" }] }` |
+        | append_string_list | `{ op: "append_string_list", fieldId: "tags", value: ["new_tag"] }` |
+        | append_url_list | `{ op: "append_url_list", fieldId: "sources", value: ["https://new.com"] }` |
+        | delete_table | `{ op: "delete_table", fieldId: "team", value: 0 }` (0-based row index) |
+        | delete_string_list | `{ op: "delete_string_list", fieldId: "tags", value: 0 }` (0-based item index) |
+        | delete_url_list | `{ op: "delete_url_list", fieldId: "sources", value: 0 }` (0-based item index) |
+
         ## Important: checkboxes vs multi_select
 
         These two types look similar but have DIFFERENT value formats:
@@ -2095,6 +2160,19 @@ turns:
           | checkboxes | `{ op: "set_checkboxes", fieldId: "tasks", value: { "task1": "done", "task2": "todo" } }` |
           | table | `{ op: "set_table", fieldId: "team", value: [{ "name": "Alice", "role": "Engineer" }] }` |
 
+          ## Incremental Operations (for collections)
+
+          Use these to add/remove items without replacing the entire collection:
+
+          | Type | Example |
+          |------|---------|
+          | append_table | `{ op: "append_table", fieldId: "team", value: [{ "name": "Bob", "role": "PM" }] }` |
+          | append_string_list | `{ op: "append_string_list", fieldId: "tags", value: ["new_tag"] }` |
+          | append_url_list | `{ op: "append_url_list", fieldId: "sources", value: ["https://new.com"] }` |
+          | delete_table | `{ op: "delete_table", fieldId: "team", value: 0 }` (0-based row index) |
+          | delete_string_list | `{ op: "delete_string_list", fieldId: "tags", value: 0 }` (0-based item index) |
+          | delete_url_list | `{ op: "delete_url_list", fieldId: "sources", value: 0 }` (0-based item index) |
+
           ## Important: checkboxes vs multi_select
 
           These two types look similar but have DIFFERENT value formats:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "markform",
-  "version": "0.1.22",
+  "version": "0.1.24",
   "description": "Markdown forms for token-friendly workflows",
   "license": "AGPL-3.0-or-later",
   "author": "Joshua Levy",
@@ -92,7 +92,7 @@
     "vitest": "^4.0.18"
   },
   "scripts": {
-    "copy-docs": "cp ../../README.md . && mkdir -p docs && cp ../../docs/markform-spec.md docs/ && cp ../../docs/markform-reference.md docs/ && cp ../../docs/markform-apis.md docs/",
+    "copy-docs": "cp ../../README.md . && mkdir -p docs docs/skill && cp ../../docs/markform-spec.md docs/ && cp ../../docs/markform-reference.md docs/ && cp ../../docs/markform-apis.md docs/ && cp ../../docs/skill/SKILL.md docs/skill/",
     "build": "pnpm run copy-docs && tsdown",
     "dev": "tsdown --watch",
     "typecheck": "tsc -p tsconfig.json --noEmit",