markform 0.1.20 → 0.1.22

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

@@ -119,7 +119,7 @@ turns:
             test: na
     after:
       required_issue_count: 2
-      markdown_sha256: 6150f47670d0e52b3ee790d41e3e4f69b67bcf2a2855e917510dd3af059094f7
+      markdown_sha256: 49988e793b98572daf567414d125e9ab2cc0889b6c19fcca1b5f6362f2e8d82d
       answered_field_count: 10
       skipped_field_count: 0
     context:
@@ -172,7 +172,7 @@ turns:
         `{ op: "skip_field", fieldId: "...", reason: "Could not find verified data" }`
 
 
-        # Instructions for agent role
+        # Role guidance
         Complete the remaining fields based on the provided context.
 
         # Field-specific instructions
@@ -193,177 +193,183 @@ turns:
         ```markdown
         ---
         markform:
-          spec: "MF/0.1"
-          run_mode: "interactive"
-        role_instructions:
-          user: "Fill in the fields you have direct knowledge of."
-          agent: "Complete the remaining fields based on the provided context."
+          spec: MF/0.1
+          title: Simple Test Form
+          description: Fully interactive demo - no LLM required. Demonstrates all Markform field types.
+          run_mode: interactive
+          roles:
+            - user
+          role_instructions:
+            user: Fill in all fields in this form.
         ---
 
-        {% form id="simple_test" title="Simple Test Form" %}
+        <!-- form id="simple_test" title="Simple Test Form" -->
 
-        {% description ref="simple_test" %}
+        <!-- description ref="simple_test" -->
         A fully interactive form demonstrating all Markform v0.1 field types.
         Fill all fields using interactive prompts - no LLM API key needed.
-        {% /description %}
+        <!-- /description -->
 
-        {% group id="basic_fields" title="Basic Fields" %}
+        <!-- group id="basic_fields" title="Basic Fields" -->
 
-        {% field kind="string" id="name" role="user" examples=["John Smith", "Jane Doe"] label="Name" maxLength=50 minLength=2 placeholder="Enter your name" required=true %}{% /field %}
+        <!-- field kind="string" id="name" role="user" examples=["John Smith", "Jane Doe"] label="Name" maxLength=50 minLength=2 placeholder="Enter your name" required=true --><!-- /field -->
 
-        {% instructions ref="name" %}
+        <!-- instructions ref="name" -->
         Enter your full name (2-50 characters).
-        {% /instructions %}
+        <!-- /instructions -->
 
-        {% field kind="string" id="email" role="user" examples=["alice@company.com", "bob@example.org"] label="Email" pattern="^[^@]+@[^@]+\\.[^@]+$" placeholder="email@example.com" required=true %}{% /field %}
+        <!-- field kind="string" id="email" role="user" examples=["alice@company.com", "bob@example.org"] label="Email" pattern="^[^@]+@[^@]+\\.[^@]+$" placeholder="email@example.com" required=true --><!-- /field -->
 
-        {% field kind="number" id="age" role="user" examples=["18", "30", "45"] integer=true label="Age" max=150 min=0 placeholder="25" required=true %}{% /field %}
+        <!-- field kind="number" id="age" role="user" examples=["18", "30", "45"] integer=true label="Age" max=150 min=0 placeholder="25" required=true --><!-- /field -->
 
-        {% field kind="number" id="score" role="user" examples=["75.0", "90.5", "100.0"] label="Score" max=100 min=0 placeholder="85.5" %}{% /field %}
+        <!-- field kind="number" id="score" role="user" examples=["75.0", "90.5", "100.0"] label="Score" max=100 min=0 placeholder="85.5" --><!-- /field -->
 
-        {% instructions ref="score" %}
+        <!-- instructions ref="score" -->
         Enter a score between 0 and 100 (optional).
-        {% /instructions %}
+        <!-- /instructions -->
 
-        {% /group %}
+        <!-- /group -->
 
-        {% group id="list_fields" title="List Fields" %}
+        <!-- group id="list_fields" title="List Fields" -->
 
-        {% field kind="string_list" id="tags" role="user" itemMinLength=2 label="Tags" maxItems=5 minItems=1 required=true uniqueItems=true %}{% /field %}
+        <!-- field kind="string_list" id="tags" role="user" itemMinLength=2 label="Tags" maxItems=5 minItems=1 required=true uniqueItems=true --><!-- /field -->
 
-        {% instructions ref="tags" %}
+        <!-- instructions ref="tags" -->
         Add 1-5 unique tags (each at least 2 characters).
-        {% /instructions %}
+        <!-- /instructions -->
 
-        {% /group %}
+        <!-- /group -->
 
-        {% group id="selection_fields" title="Selection Fields" %}
+        <!-- group id="selection_fields" title="Selection Fields" -->
 
-        {% field kind="single_select" id="priority" role="user" label="Priority" required=true %}
-        - [ ] Low {% #low %}
-        - [ ] Medium {% #medium %}
-        - [ ] High {% #high %}
-        {% /field %}
+        <!-- field kind="single_select" id="priority" role="user" label="Priority" required=true -->
+        - [ ] Low <!-- #low -->
+        - [ ] Medium <!-- #medium -->
+        - [ ] High <!-- #high -->
+        <!-- /field -->
 
-        {% field kind="multi_select" id="categories" role="user" label="Categories" maxSelections=3 minSelections=1 required=true %}
-        - [ ] Frontend {% #frontend %}
-        - [ ] Backend {% #backend %}
-        - [ ] Database {% #database %}
-        - [ ] DevOps {% #devops %}
-        {% /field %}
+        <!-- field kind="multi_select" id="categories" role="user" label="Categories" maxSelections=3 minSelections=1 required=true -->
+        - [ ] Frontend <!-- #frontend -->
+        - [ ] Backend <!-- #backend -->
+        - [ ] Database <!-- #database -->
+        - [ ] DevOps <!-- #devops -->
+        <!-- /field -->
 
-        {% /group %}
+        <!-- /group -->
 
-        {% group id="checkbox_fields" title="Checkbox Fields" %}
+        <!-- group id="checkbox_fields" title="Checkbox Fields" -->
 
-        {% field kind="checkboxes" id="tasks_multi" role="user" label="Tasks (Multi Mode)" required=true %}
-        - [ ] Research {% #research %}
-        - [ ] Design {% #design %}
-        - [ ] Implement {% #implement %}
-        - [ ] Test {% #test %}
-        {% /field %}
+        <!-- field kind="checkboxes" id="tasks_multi" role="user" label="Tasks (Multi Mode)" required=true -->
+        - [ ] Research <!-- #research -->
+        - [ ] Design <!-- #design -->
+        - [ ] Implement <!-- #implement -->
+        - [ ] Test <!-- #test -->
+        <!-- /field -->
 
-        {% instructions ref="tasks_multi" %}
+        <!-- instructions ref="tasks_multi" -->
         Track task progress.
         All must reach done or na state to complete.
-        {% /instructions %}
+        <!-- /instructions -->
 
-        {% field kind="checkboxes" id="tasks_simple" role="user" checkboxMode="simple" label="Agreements (Simple Mode)" required=true %}
-        - [ ] I have read the guidelines {% #read_guidelines %}
-        - [ ] I agree to the terms {% #agree_terms %}
-        {% /field %}
+        <!-- field kind="checkboxes" id="tasks_simple" role="user" checkboxMode="simple" label="Agreements (Simple Mode)" required=true -->
+        - [ ] I have read the guidelines <!-- #read_guidelines -->
+        - [ ] I agree to the terms <!-- #agree_terms -->
+        <!-- /field -->
 
-        {% field kind="checkboxes" id="confirmations" role="user" checkboxMode="explicit" label="Confirmations (Explicit Mode)" required=true %}
-        - [ ] Data has been backed up {% #backed_up %}
-        - [ ] Stakeholders notified {% #notified %}
-        {% /field %}
+        <!-- field kind="checkboxes" id="confirmations" role="user" checkboxMode="explicit" label="Confirmations (Explicit Mode)" required=true -->
+        - [ ] Data has been backed up <!-- #backed_up -->
+        - [ ] Stakeholders notified <!-- #notified -->
+        <!-- /field -->
 
-        {% instructions ref="confirmations" %}
+        <!-- instructions ref="confirmations" -->
         Answer yes or no for each confirmation.
         All must be explicitly answered.
-        {% /instructions %}
+        <!-- /instructions -->
 
-        {% /group %}
+        <!-- /group -->
 
-        {% group id="url_fields" title="URL Fields" %}
+        <!-- group id="url_fields" title="URL Fields" -->
 
-        {% field kind="url" id="website" role="user" examples=["https://github.com/user/repo", "https://company.com"] label="Website" placeholder="https://example.com" required=true %}{% /field %}
+        <!-- field kind="url" id="website" role="user" examples=["https://github.com/user/repo", "https://company.com"] label="Website" placeholder="https://example.com" required=true --><!-- /field -->
 
-        {% instructions ref="website" %}
+        <!-- instructions ref="website" -->
         Enter your website URL (must be http or https).
-        {% /instructions %}
+        <!-- /instructions -->
 
-        {% field kind="url_list" id="references" role="user" examples=["https://wikipedia.org/wiki/Example", "https://docs.github.com/en"] label="References" maxItems=5 minItems=1 placeholder="https://docs.example.com" uniqueItems=true %}{% /field %}
+        <!-- field kind="url_list" id="references" role="user" examples=["https://wikipedia.org/wiki/Example", "https://docs.github.com/en"] label="References" maxItems=5 minItems=1 placeholder="https://docs.example.com" uniqueItems=true --><!-- /field -->
 
-        {% instructions ref="references" %}
+        <!-- instructions ref="references" -->
         Add 1-5 unique reference URLs for sources or documentation.
-        {% /instructions %}
+        <!-- /instructions -->
 
-        {% /group %}
+        <!-- /group -->
 
-        {% group id="date_fields" title="Date and Year Fields" %}
+        <!-- group id="date_fields" title="Date and Year Fields" -->
 
-        {% field kind="date" id="event_date" role="user" label="Event Date" max="2030-12-31" min="2020-01-01" required=true %}{% /field %}
+        <!-- field kind="date" id="event_date" role="user" label="Event Date" max="2030-12-31" min="2020-01-01" required=true --><!-- /field -->
 
-        {% instructions ref="event_date" %}
+        <!-- instructions ref="event_date" -->
         Enter the event date (YYYY-MM-DD format, between 2020 and 2030).
-        {% /instructions %}
+        <!-- /instructions -->
 
-        {% field kind="year" id="founded_year" role="user" label="Founded Year" max=2030 min=1900 required=true %}{% /field %}
+        <!-- field kind="year" id="founded_year" role="user" label="Founded Year" max=2030 min=1900 required=true --><!-- /field -->
 
-        {% instructions ref="founded_year" %}
+        <!-- instructions ref="founded_year" -->
         Enter the year the company was founded (1900-2030).
-        {% /instructions %}
+        <!-- /instructions -->
 
-        {% /group %}
+        <!-- /group -->
 
-        {% group id="table_fields" title="Table Fields" %}
+        <!-- group id="table_fields" title="Table Fields" -->
 
-        {% field kind="table" id="team_members" role="user" columnIds=["name", "role", "start_date"] columnLabels=["Name", "Role", "Start Date"] columnTypes=[{type: "string", required: true}, "string", "date"] label="Team Members" maxRows=5 minRows=0 %}{% /field %}
+        <!-- field kind="table" id="team_members" role="user" columnIds=["name", "role", "start_date"] columnLabels=["Name", "Role", "Start Date"] columnTypes=[{type: "string", required: true}, "string", "date"] label="Team Members" maxRows=5 minRows=0 --><!-- /field -->
 
-        {% instructions ref="team_members" %}
+        <!-- instructions ref="team_members" -->
         Add team members with their name (required), role, and start date.
-        {% /instructions %}
+        <!-- /instructions -->
 
-        {% field kind="table" id="project_tasks" role="user" columnIds=["task", "estimate_hrs", "link"] columnLabels=["Task", "Estimate (hrs)", "Link"] columnTypes=[{type: "string", required: true}, "number", "url"] label="Project Tasks" maxRows=10 minRows=0 %}{% /field %}
+        <!-- field kind="table" id="project_tasks" role="user" columnIds=["task", "estimate_hrs", "link"] columnLabels=["Task", "Estimate (hrs)", "Link"] columnTypes=[{type: "string", required: true}, "number", "url"] label="Project Tasks" maxRows=10 minRows=0 --><!-- /field -->
 
-        {% instructions ref="project_tasks" %}
+        <!-- instructions ref="project_tasks" -->
         Optionally add project tasks with estimated hours and reference links.
-        {% /instructions %}
+        <!-- /instructions -->
 
-        {% /group %}
+        <!-- /group -->
 
-        {% group id="optional_fields" title="Optional Fields" %}
+        <!-- group id="optional_fields" title="Optional Fields" -->
 
-        {% field kind="string" id="notes" role="user" label="Notes" %}{% /field %}
+        <!-- field kind="string" id="notes" role="user" label="Notes" --><!-- /field -->
 
-        {% instructions ref="notes" %}
+        <!-- instructions ref="notes" -->
         Add any relevant notes or observations (optional).
-        {% /instructions %}
+        <!-- /instructions -->
 
-        {% field kind="number" id="optional_number" role="user" label="Optional Number" %}{% /field %}
+        <!-- field kind="number" id="optional_number" role="user" label="Optional Number" --><!-- /field -->
 
-        {% field kind="url" id="related_url" role="user" label="Related URL" %}{% /field %}
+        <!-- field kind="url" id="related_url" role="user" label="Related URL" --><!-- /field -->
 
-        {% instructions ref="related_url" %}
+        <!-- instructions ref="related_url" -->
         Optionally add a URL to related documentation or resources.
-        {% /instructions %}
+        <!-- /instructions -->
 
-        {% field kind="date" id="optional_date" role="user" label="Optional Date" %}{% /field %}
+        <!-- field kind="date" id="optional_date" role="user" label="Optional Date" --><!-- /field -->
 
-        {% instructions ref="optional_date" %}
+        <!-- instructions ref="optional_date" -->
         Optionally add a date (YYYY-MM-DD format).
-        {% /instructions %}
+        <!-- /instructions -->
 
-        {% field kind="year" id="optional_year" role="user" label="Optional Year" %}{% /field %}
+        <!-- field kind="year" id="optional_year" role="user" label="Optional Year" --><!-- /field -->
 
-        {% instructions ref="optional_year" %}
+        <!-- instructions ref="optional_year" -->
         Optionally add a year.
-        {% /instructions %}
+        <!-- /instructions -->
+
+        <!-- /group -->
+
+        <!-- /form -->
+
 
-        {% /group %}
 
-        {% /form %}
 
         ```
 
@@ -492,7 +498,7 @@ turns:
           `{ op: "skip_field", fieldId: "...", reason: "Could not find verified data" }`
 
 
-          # Instructions for agent role
+          # Role guidance
           Complete the remaining fields based on the provided context.
 
           # Field-specific instructions
@@ -513,177 +519,183 @@ turns:
           ```markdown
           ---
           markform:
-            spec: "MF/0.1"
-            run_mode: "interactive"
-          role_instructions:
-            user: "Fill in the fields you have direct knowledge of."
-            agent: "Complete the remaining fields based on the provided context."
+            spec: MF/0.1
+            title: Simple Test Form
+            description: Fully interactive demo - no LLM required. Demonstrates all Markform field types.
+            run_mode: interactive
+            roles:
+              - user
+            role_instructions:
+              user: Fill in all fields in this form.
           ---
 
-          {% form id="simple_test" title="Simple Test Form" %}
+          <!-- form id="simple_test" title="Simple Test Form" -->
 
-          {% description ref="simple_test" %}
+          <!-- description ref="simple_test" -->
           A fully interactive form demonstrating all Markform v0.1 field types.
           Fill all fields using interactive prompts - no LLM API key needed.
-          {% /description %}
+          <!-- /description -->
 
-          {% group id="basic_fields" title="Basic Fields" %}
+          <!-- group id="basic_fields" title="Basic Fields" -->
 
-          {% field kind="string" id="name" role="user" examples=["John Smith", "Jane Doe"] label="Name" maxLength=50 minLength=2 placeholder="Enter your name" required=true %}{% /field %}
+          <!-- field kind="string" id="name" role="user" examples=["John Smith", "Jane Doe"] label="Name" maxLength=50 minLength=2 placeholder="Enter your name" required=true --><!-- /field -->
 
-          {% instructions ref="name" %}
+          <!-- instructions ref="name" -->
           Enter your full name (2-50 characters).
-          {% /instructions %}
+          <!-- /instructions -->
 
-          {% field kind="string" id="email" role="user" examples=["alice@company.com", "bob@example.org"] label="Email" pattern="^[^@]+@[^@]+\\.[^@]+$" placeholder="email@example.com" required=true %}{% /field %}
+          <!-- field kind="string" id="email" role="user" examples=["alice@company.com", "bob@example.org"] label="Email" pattern="^[^@]+@[^@]+\\.[^@]+$" placeholder="email@example.com" required=true --><!-- /field -->
 
-          {% field kind="number" id="age" role="user" examples=["18", "30", "45"] integer=true label="Age" max=150 min=0 placeholder="25" required=true %}{% /field %}
+          <!-- field kind="number" id="age" role="user" examples=["18", "30", "45"] integer=true label="Age" max=150 min=0 placeholder="25" required=true --><!-- /field -->
 
-          {% field kind="number" id="score" role="user" examples=["75.0", "90.5", "100.0"] label="Score" max=100 min=0 placeholder="85.5" %}{% /field %}
+          <!-- field kind="number" id="score" role="user" examples=["75.0", "90.5", "100.0"] label="Score" max=100 min=0 placeholder="85.5" --><!-- /field -->
 
-          {% instructions ref="score" %}
+          <!-- instructions ref="score" -->
           Enter a score between 0 and 100 (optional).
-          {% /instructions %}
+          <!-- /instructions -->
 
-          {% /group %}
+          <!-- /group -->
 
-          {% group id="list_fields" title="List Fields" %}
+          <!-- group id="list_fields" title="List Fields" -->
 
-          {% field kind="string_list" id="tags" role="user" itemMinLength=2 label="Tags" maxItems=5 minItems=1 required=true uniqueItems=true %}{% /field %}
+          <!-- field kind="string_list" id="tags" role="user" itemMinLength=2 label="Tags" maxItems=5 minItems=1 required=true uniqueItems=true --><!-- /field -->
 
-          {% instructions ref="tags" %}
+          <!-- instructions ref="tags" -->
           Add 1-5 unique tags (each at least 2 characters).
-          {% /instructions %}
+          <!-- /instructions -->
 
-          {% /group %}
+          <!-- /group -->
 
-          {% group id="selection_fields" title="Selection Fields" %}
+          <!-- group id="selection_fields" title="Selection Fields" -->
 
-          {% field kind="single_select" id="priority" role="user" label="Priority" required=true %}
-          - [ ] Low {% #low %}
-          - [ ] Medium {% #medium %}
-          - [ ] High {% #high %}
-          {% /field %}
+          <!-- field kind="single_select" id="priority" role="user" label="Priority" required=true -->
+          - [ ] Low <!-- #low -->
+          - [ ] Medium <!-- #medium -->
+          - [ ] High <!-- #high -->
+          <!-- /field -->
 
-          {% field kind="multi_select" id="categories" role="user" label="Categories" maxSelections=3 minSelections=1 required=true %}
-          - [ ] Frontend {% #frontend %}
-          - [ ] Backend {% #backend %}
-          - [ ] Database {% #database %}
-          - [ ] DevOps {% #devops %}
-          {% /field %}
+          <!-- field kind="multi_select" id="categories" role="user" label="Categories" maxSelections=3 minSelections=1 required=true -->
+          - [ ] Frontend <!-- #frontend -->
+          - [ ] Backend <!-- #backend -->
+          - [ ] Database <!-- #database -->
+          - [ ] DevOps <!-- #devops -->
+          <!-- /field -->
 
-          {% /group %}
+          <!-- /group -->
 
-          {% group id="checkbox_fields" title="Checkbox Fields" %}
+          <!-- group id="checkbox_fields" title="Checkbox Fields" -->
 
-          {% field kind="checkboxes" id="tasks_multi" role="user" label="Tasks (Multi Mode)" required=true %}
-          - [ ] Research {% #research %}
-          - [ ] Design {% #design %}
-          - [ ] Implement {% #implement %}
-          - [ ] Test {% #test %}
-          {% /field %}
+          <!-- field kind="checkboxes" id="tasks_multi" role="user" label="Tasks (Multi Mode)" required=true -->
+          - [ ] Research <!-- #research -->
+          - [ ] Design <!-- #design -->
+          - [ ] Implement <!-- #implement -->
+          - [ ] Test <!-- #test -->
+          <!-- /field -->
 
-          {% instructions ref="tasks_multi" %}
+          <!-- instructions ref="tasks_multi" -->
           Track task progress.
           All must reach done or na state to complete.
-          {% /instructions %}
+          <!-- /instructions -->
 
-          {% field kind="checkboxes" id="tasks_simple" role="user" checkboxMode="simple" label="Agreements (Simple Mode)" required=true %}
-          - [ ] I have read the guidelines {% #read_guidelines %}
-          - [ ] I agree to the terms {% #agree_terms %}
-          {% /field %}
+          <!-- field kind="checkboxes" id="tasks_simple" role="user" checkboxMode="simple" label="Agreements (Simple Mode)" required=true -->
+          - [ ] I have read the guidelines <!-- #read_guidelines -->
+          - [ ] I agree to the terms <!-- #agree_terms -->
+          <!-- /field -->
 
-          {% field kind="checkboxes" id="confirmations" role="user" checkboxMode="explicit" label="Confirmations (Explicit Mode)" required=true %}
-          - [ ] Data has been backed up {% #backed_up %}
-          - [ ] Stakeholders notified {% #notified %}
-          {% /field %}
+          <!-- field kind="checkboxes" id="confirmations" role="user" checkboxMode="explicit" label="Confirmations (Explicit Mode)" required=true -->
+          - [ ] Data has been backed up <!-- #backed_up -->
+          - [ ] Stakeholders notified <!-- #notified -->
+          <!-- /field -->
 
-          {% instructions ref="confirmations" %}
+          <!-- instructions ref="confirmations" -->
           Answer yes or no for each confirmation.
           All must be explicitly answered.
-          {% /instructions %}
+          <!-- /instructions -->
 
-          {% /group %}
+          <!-- /group -->
 
-          {% group id="url_fields" title="URL Fields" %}
+          <!-- group id="url_fields" title="URL Fields" -->
 
-          {% field kind="url" id="website" role="user" examples=["https://github.com/user/repo", "https://company.com"] label="Website" placeholder="https://example.com" required=true %}{% /field %}
+          <!-- field kind="url" id="website" role="user" examples=["https://github.com/user/repo", "https://company.com"] label="Website" placeholder="https://example.com" required=true --><!-- /field -->
 
-          {% instructions ref="website" %}
+          <!-- instructions ref="website" -->
           Enter your website URL (must be http or https).
-          {% /instructions %}
+          <!-- /instructions -->
 
-          {% field kind="url_list" id="references" role="user" examples=["https://wikipedia.org/wiki/Example", "https://docs.github.com/en"] label="References" maxItems=5 minItems=1 placeholder="https://docs.example.com" uniqueItems=true %}{% /field %}
+          <!-- field kind="url_list" id="references" role="user" examples=["https://wikipedia.org/wiki/Example", "https://docs.github.com/en"] label="References" maxItems=5 minItems=1 placeholder="https://docs.example.com" uniqueItems=true --><!-- /field -->
 
-          {% instructions ref="references" %}
+          <!-- instructions ref="references" -->
           Add 1-5 unique reference URLs for sources or documentation.
-          {% /instructions %}
+          <!-- /instructions -->
 
-          {% /group %}
+          <!-- /group -->
 
-          {% group id="date_fields" title="Date and Year Fields" %}
+          <!-- group id="date_fields" title="Date and Year Fields" -->
 
-          {% field kind="date" id="event_date" role="user" label="Event Date" max="2030-12-31" min="2020-01-01" required=true %}{% /field %}
+          <!-- field kind="date" id="event_date" role="user" label="Event Date" max="2030-12-31" min="2020-01-01" required=true --><!-- /field -->
 
-          {% instructions ref="event_date" %}
+          <!-- instructions ref="event_date" -->
           Enter the event date (YYYY-MM-DD format, between 2020 and 2030).
-          {% /instructions %}
+          <!-- /instructions -->
 
-          {% field kind="year" id="founded_year" role="user" label="Founded Year" max=2030 min=1900 required=true %}{% /field %}
+          <!-- field kind="year" id="founded_year" role="user" label="Founded Year" max=2030 min=1900 required=true --><!-- /field -->
 
-          {% instructions ref="founded_year" %}
+          <!-- instructions ref="founded_year" -->
           Enter the year the company was founded (1900-2030).
-          {% /instructions %}
+          <!-- /instructions -->
 
-          {% /group %}
+          <!-- /group -->
 
-          {% group id="table_fields" title="Table Fields" %}
+          <!-- group id="table_fields" title="Table Fields" -->
 
-          {% field kind="table" id="team_members" role="user" columnIds=["name", "role", "start_date"] columnLabels=["Name", "Role", "Start Date"] columnTypes=[{type: "string", required: true}, "string", "date"] label="Team Members" maxRows=5 minRows=0 %}{% /field %}
+          <!-- field kind="table" id="team_members" role="user" columnIds=["name", "role", "start_date"] columnLabels=["Name", "Role", "Start Date"] columnTypes=[{type: "string", required: true}, "string", "date"] label="Team Members" maxRows=5 minRows=0 --><!-- /field -->
 
-          {% instructions ref="team_members" %}
+          <!-- instructions ref="team_members" -->
           Add team members with their name (required), role, and start date.
-          {% /instructions %}
+          <!-- /instructions -->
 
-          {% field kind="table" id="project_tasks" role="user" columnIds=["task", "estimate_hrs", "link"] columnLabels=["Task", "Estimate (hrs)", "Link"] columnTypes=[{type: "string", required: true}, "number", "url"] label="Project Tasks" maxRows=10 minRows=0 %}{% /field %}
+          <!-- field kind="table" id="project_tasks" role="user" columnIds=["task", "estimate_hrs", "link"] columnLabels=["Task", "Estimate (hrs)", "Link"] columnTypes=[{type: "string", required: true}, "number", "url"] label="Project Tasks" maxRows=10 minRows=0 --><!-- /field -->
 
-          {% instructions ref="project_tasks" %}
+          <!-- instructions ref="project_tasks" -->
           Optionally add project tasks with estimated hours and reference links.
-          {% /instructions %}
+          <!-- /instructions -->
 
-          {% /group %}
+          <!-- /group -->
 
-          {% group id="optional_fields" title="Optional Fields" %}
+          <!-- group id="optional_fields" title="Optional Fields" -->
 
-          {% field kind="string" id="notes" role="user" label="Notes" %}{% /field %}
+          <!-- field kind="string" id="notes" role="user" label="Notes" --><!-- /field -->
 
-          {% instructions ref="notes" %}
+          <!-- instructions ref="notes" -->
           Add any relevant notes or observations (optional).
-          {% /instructions %}
+          <!-- /instructions -->
 
-          {% field kind="number" id="optional_number" role="user" label="Optional Number" %}{% /field %}
+          <!-- field kind="number" id="optional_number" role="user" label="Optional Number" --><!-- /field -->
 
-          {% field kind="url" id="related_url" role="user" label="Related URL" %}{% /field %}
+          <!-- field kind="url" id="related_url" role="user" label="Related URL" --><!-- /field -->
 
-          {% instructions ref="related_url" %}
+          <!-- instructions ref="related_url" -->
           Optionally add a URL to related documentation or resources.
-          {% /instructions %}
+          <!-- /instructions -->
 
-          {% field kind="date" id="optional_date" role="user" label="Optional Date" %}{% /field %}
+          <!-- field kind="date" id="optional_date" role="user" label="Optional Date" --><!-- /field -->
 
-          {% instructions ref="optional_date" %}
+          <!-- instructions ref="optional_date" -->
           Optionally add a date (YYYY-MM-DD format).
-          {% /instructions %}
+          <!-- /instructions -->
 
-          {% field kind="year" id="optional_year" role="user" label="Optional Year" %}{% /field %}
+          <!-- field kind="year" id="optional_year" role="user" label="Optional Year" --><!-- /field -->
 
-          {% instructions ref="optional_year" %}
+          <!-- instructions ref="optional_year" -->
           Optionally add a year.
-          {% /instructions %}
+          <!-- /instructions -->
+
+          <!-- /group -->
+
+          <!-- /form -->
+
 
-          {% /group %}
 
-          {% /form %}
 
           ```
 
@@ -935,7 +947,7 @@ turns:
           reason: No value in mock form
     after:
       required_issue_count: 0
-      markdown_sha256: 21c8527d7c79ecc116a3c7513ce537bf1837428accd69525f199270bffb5b415
+      markdown_sha256: 977039176fe8f9cba5a40f8726db43653bf4bc101c2add9cfaee4d4f6ed5e164
       answered_field_count: 13
       skipped_field_count: 7
     context:
@@ -988,7 +1000,7 @@ turns:
         `{ op: "skip_field", fieldId: "...", reason: "Could not find verified data" }`
 
 
-        # Instructions for agent role
+        # Role guidance
         Complete the remaining fields based on the provided context.
 
         # Field-specific instructions
@@ -1009,202 +1021,208 @@ turns:
         ```markdown
         ---
         markform:
-          spec: "MF/0.1"
-          run_mode: "interactive"
-        role_instructions:
-          user: "Fill in the fields you have direct knowledge of."
-          agent: "Complete the remaining fields based on the provided context."
+          spec: MF/0.1
+          title: Simple Test Form
+          description: Fully interactive demo - no LLM required. Demonstrates all Markform field types.
+          run_mode: interactive
+          roles:
+            - user
+          role_instructions:
+            user: Fill in all fields in this form.
         ---
 
-        {% form id="simple_test" title="Simple Test Form" %}
+        <!-- form id="simple_test" title="Simple Test Form" -->
 
-        {% description ref="simple_test" %}
+        <!-- description ref="simple_test" -->
         A fully interactive form demonstrating all Markform v0.1 field types.
         Fill all fields using interactive prompts - no LLM API key needed.
-        {% /description %}
+        <!-- /description -->
 
-        {% group id="basic_fields" title="Basic Fields" %}
+        <!-- group id="basic_fields" title="Basic Fields" -->
 
-        {% field kind="string" id="name" role="user" examples=["John Smith", "Jane Doe"] label="Name" maxLength=50 minLength=2 placeholder="Enter your name" required=true %}
+        <!-- field kind="string" id="name" role="user" examples=["John Smith", "Jane Doe"] label="Name" maxLength=50 minLength=2 placeholder="Enter your name" required=true -->
         ```value
         Test User
         ```
-        {% /field %}
+        <!-- /field -->
 
-        {% instructions ref="name" %}
+        <!-- instructions ref="name" -->
         Enter your full name (2-50 characters).
-        {% /instructions %}
+        <!-- /instructions -->
 
-        {% field kind="string" id="email" role="user" examples=["alice@company.com", "bob@example.org"] label="Email" pattern="^[^@]+@[^@]+\\.[^@]+$" placeholder="email@example.com" required=true %}
+        <!-- field kind="string" id="email" role="user" examples=["alice@company.com", "bob@example.org"] label="Email" pattern="^[^@]+@[^@]+\\.[^@]+$" placeholder="email@example.com" required=true -->
         ```value
         test@example.com
         ```
-        {% /field %}
+        <!-- /field -->
 
-        {% field kind="number" id="age" role="user" examples=["18", "30", "45"] integer=true label="Age" max=150 min=0 placeholder="25" required=true %}
+        <!-- field kind="number" id="age" role="user" examples=["18", "30", "45"] integer=true label="Age" max=150 min=0 placeholder="25" required=true -->
         ```value
         25
         ```
-        {% /field %}
+        <!-- /field -->
 
-        {% field kind="number" id="score" role="user" examples=["75.0", "90.5", "100.0"] label="Score" max=100 min=0 placeholder="85.5" %}{% /field %}
+        <!-- field kind="number" id="score" role="user" examples=["75.0", "90.5", "100.0"] label="Score" max=100 min=0 placeholder="85.5" --><!-- /field -->
 
-        {% instructions ref="score" %}
+        <!-- instructions ref="score" -->
         Enter a score between 0 and 100 (optional).
-        {% /instructions %}
+        <!-- /instructions -->
 
-        {% /group %}
+        <!-- /group -->
 
-        {% group id="list_fields" title="List Fields" %}
+        <!-- group id="list_fields" title="List Fields" -->
 
-        {% field kind="string_list" id="tags" role="user" itemMinLength=2 label="Tags" maxItems=5 minItems=1 required=true uniqueItems=true %}
+        <!-- field kind="string_list" id="tags" role="user" itemMinLength=2 label="Tags" maxItems=5 minItems=1 required=true uniqueItems=true -->
         ```value
         typescript
         testing
         ```
-        {% /field %}
+        <!-- /field -->
 
-        {% instructions ref="tags" %}
+        <!-- instructions ref="tags" -->
         Add 1-5 unique tags (each at least 2 characters).
-        {% /instructions %}
+        <!-- /instructions -->
 
-        {% /group %}
+        <!-- /group -->
 
-        {% group id="selection_fields" title="Selection Fields" %}
+        <!-- group id="selection_fields" title="Selection Fields" -->
 
-        {% field kind="single_select" id="priority" role="user" label="Priority" required=true %}
-        - [ ] Low {% #low %}
-        - [ ] Medium {% #medium %}
-        - [x] High {% #high %}
-        {% /field %}
+        <!-- field kind="single_select" id="priority" role="user" label="Priority" required=true -->
+        - [ ] Low <!-- #low -->
+        - [ ] Medium <!-- #medium -->
+        - [x] High <!-- #high -->
+        <!-- /field -->
 
-        {% field kind="multi_select" id="categories" role="user" label="Categories" maxSelections=3 minSelections=1 required=true %}
-        - [x] Frontend {% #frontend %}
-        - [x] Backend {% #backend %}
-        - [ ] Database {% #database %}
-        - [ ] DevOps {% #devops %}
-        {% /field %}
+        <!-- field kind="multi_select" id="categories" role="user" label="Categories" maxSelections=3 minSelections=1 required=true -->
+        - [x] Frontend <!-- #frontend -->
+        - [x] Backend <!-- #backend -->
+        - [ ] Database <!-- #database -->
+        - [ ] DevOps <!-- #devops -->
+        <!-- /field -->
 
-        {% /group %}
+        <!-- /group -->
 
-        {% group id="checkbox_fields" title="Checkbox Fields" %}
+        <!-- group id="checkbox_fields" title="Checkbox Fields" -->
 
-        {% field kind="checkboxes" id="tasks_multi" role="user" label="Tasks (Multi Mode)" required=true %}
-        - [x] Research {% #research %}
-        - [x] Design {% #design %}
-        - [x] Implement {% #implement %}
-        - [-] Test {% #test %}
-        {% /field %}
+        <!-- field kind="checkboxes" id="tasks_multi" role="user" label="Tasks (Multi Mode)" required=true -->
+        - [x] Research <!-- #research -->
+        - [x] Design <!-- #design -->
+        - [x] Implement <!-- #implement -->
+        - [-] Test <!-- #test -->
+        <!-- /field -->
 
-        {% instructions ref="tasks_multi" %}
+        <!-- instructions ref="tasks_multi" -->
         Track task progress.
         All must reach done or na state to complete.
-        {% /instructions %}
+        <!-- /instructions -->
 
-        {% field kind="checkboxes" id="tasks_simple" role="user" checkboxMode="simple" label="Agreements (Simple Mode)" required=true %}
-        - [ ] I have read the guidelines {% #read_guidelines %}
-        - [ ] I agree to the terms {% #agree_terms %}
-        {% /field %}
+        <!-- field kind="checkboxes" id="tasks_simple" role="user" checkboxMode="simple" label="Agreements (Simple Mode)" required=true -->
+        - [ ] I have read the guidelines <!-- #read_guidelines -->
+        - [ ] I agree to the terms <!-- #agree_terms -->
+        <!-- /field -->
 
-        {% field kind="checkboxes" id="confirmations" role="user" checkboxMode="explicit" label="Confirmations (Explicit Mode)" required=true %}
-        - [y] Data has been backed up {% #backed_up %}
-        - [n] Stakeholders notified {% #notified %}
-        {% /field %}
+        <!-- field kind="checkboxes" id="confirmations" role="user" checkboxMode="explicit" label="Confirmations (Explicit Mode)" required=true -->
+        - [y] Data has been backed up <!-- #backed_up -->
+        - [n] Stakeholders notified <!-- #notified -->
+        <!-- /field -->
 
-        {% instructions ref="confirmations" %}
+        <!-- instructions ref="confirmations" -->
         Answer yes or no for each confirmation.
         All must be explicitly answered.
-        {% /instructions %}
+        <!-- /instructions -->
 
-        {% /group %}
+        <!-- /group -->
 
-        {% group id="url_fields" title="URL Fields" %}
+        <!-- group id="url_fields" title="URL Fields" -->
 
-        {% field kind="url" id="website" role="user" examples=["https://github.com/user/repo", "https://company.com"] label="Website" placeholder="https://example.com" required=true %}{% /field %}
+        <!-- field kind="url" id="website" role="user" examples=["https://github.com/user/repo", "https://company.com"] label="Website" placeholder="https://example.com" required=true --><!-- /field -->
 
-        {% instructions ref="website" %}
+        <!-- instructions ref="website" -->
         Enter your website URL (must be http or https).
-        {% /instructions %}
+        <!-- /instructions -->
 
-        {% field kind="url_list" id="references" role="user" examples=["https://wikipedia.org/wiki/Example", "https://docs.github.com/en"] label="References" maxItems=5 minItems=1 placeholder="https://docs.example.com" uniqueItems=true %}{% /field %}
+        <!-- field kind="url_list" id="references" role="user" examples=["https://wikipedia.org/wiki/Example", "https://docs.github.com/en"] label="References" maxItems=5 minItems=1 placeholder="https://docs.example.com" uniqueItems=true --><!-- /field -->
 
-        {% instructions ref="references" %}
+        <!-- instructions ref="references" -->
         Add 1-5 unique reference URLs for sources or documentation.
-        {% /instructions %}
+        <!-- /instructions -->
 
-        {% /group %}
+        <!-- /group -->
 
-        {% group id="date_fields" title="Date and Year Fields" %}
+        <!-- group id="date_fields" title="Date and Year Fields" -->
 
-        {% field kind="date" id="event_date" role="user" label="Event Date" max="2030-12-31" min="2020-01-01" required=true %}
+        <!-- field kind="date" id="event_date" role="user" label="Event Date" max="2030-12-31" min="2020-01-01" required=true -->
         ```value
         2025-03-15
         ```
-        {% /field %}
+        <!-- /field -->
 
-        {% instructions ref="event_date" %}
+        <!-- instructions ref="event_date" -->
         Enter the event date (YYYY-MM-DD format, between 2020 and 2030).
-        {% /instructions %}
+        <!-- /instructions -->
 
-        {% field kind="year" id="founded_year" role="user" label="Founded Year" max=2030 min=1900 required=true %}
+        <!-- field kind="year" id="founded_year" role="user" label="Founded Year" max=2030 min=1900 required=true -->
         ```value
         2021
         ```
-        {% /field %}
+        <!-- /field -->
 
-        {% instructions ref="founded_year" %}
+        <!-- instructions ref="founded_year" -->
         Enter the year the company was founded (1900-2030).
-        {% /instructions %}
+        <!-- /instructions -->
 
-        {% /group %}
+        <!-- /group -->
 
-        {% group id="table_fields" title="Table Fields" %}
+        <!-- group id="table_fields" title="Table Fields" -->
 
-        {% field kind="table" id="team_members" role="user" columnIds=["name", "role", "start_date"] columnLabels=["Name", "Role", "Start Date"] columnTypes=[{type: "string", required: true}, "string", "date"] label="Team Members" maxRows=5 minRows=0 %}{% /field %}
+        <!-- field kind="table" id="team_members" role="user" columnIds=["name", "role", "start_date"] columnLabels=["Name", "Role", "Start Date"] columnTypes=[{type: "string", required: true}, "string", "date"] label="Team Members" maxRows=5 minRows=0 --><!-- /field -->
 
-        {% instructions ref="team_members" %}
+        <!-- instructions ref="team_members" -->
         Add team members with their name (required), role, and start date.
-        {% /instructions %}
+        <!-- /instructions -->
 
-        {% field kind="table" id="project_tasks" role="user" columnIds=["task", "estimate_hrs", "link"] columnLabels=["Task", "Estimate (hrs)", "Link"] columnTypes=[{type: "string", required: true}, "number", "url"] label="Project Tasks" maxRows=10 minRows=0 %}{% /field %}
+        <!-- field kind="table" id="project_tasks" role="user" columnIds=["task", "estimate_hrs", "link"] columnLabels=["Task", "Estimate (hrs)", "Link"] columnTypes=[{type: "string", required: true}, "number", "url"] label="Project Tasks" maxRows=10 minRows=0 --><!-- /field -->
 
-        {% instructions ref="project_tasks" %}
+        <!-- instructions ref="project_tasks" -->
         Optionally add project tasks with estimated hours and reference links.
-        {% /instructions %}
+        <!-- /instructions -->
 
-        {% /group %}
+        <!-- /group -->
 
-        {% group id="optional_fields" title="Optional Fields" %}
+        <!-- group id="optional_fields" title="Optional Fields" -->
 
-        {% field kind="string" id="notes" role="user" label="Notes" %}{% /field %}
+        <!-- field kind="string" id="notes" role="user" label="Notes" --><!-- /field -->
 
-        {% instructions ref="notes" %}
+        <!-- instructions ref="notes" -->
         Add any relevant notes or observations (optional).
-        {% /instructions %}
+        <!-- /instructions -->
 
-        {% field kind="number" id="optional_number" role="user" label="Optional Number" %}{% /field %}
+        <!-- field kind="number" id="optional_number" role="user" label="Optional Number" --><!-- /field -->
 
-        {% field kind="url" id="related_url" role="user" label="Related URL" %}{% /field %}
+        <!-- field kind="url" id="related_url" role="user" label="Related URL" --><!-- /field -->
 
-        {% instructions ref="related_url" %}
+        <!-- instructions ref="related_url" -->
         Optionally add a URL to related documentation or resources.
-        {% /instructions %}
+        <!-- /instructions -->
 
-        {% field kind="date" id="optional_date" role="user" label="Optional Date" %}{% /field %}
+        <!-- field kind="date" id="optional_date" role="user" label="Optional Date" --><!-- /field -->
 
-        {% instructions ref="optional_date" %}
+        <!-- instructions ref="optional_date" -->
         Optionally add a date (YYYY-MM-DD format).
-        {% /instructions %}
+        <!-- /instructions -->
 
-        {% field kind="year" id="optional_year" role="user" label="Optional Year" %}{% /field %}
+        <!-- field kind="year" id="optional_year" role="user" label="Optional Year" --><!-- /field -->
 
-        {% instructions ref="optional_year" %}
+        <!-- instructions ref="optional_year" -->
         Optionally add a year.
-        {% /instructions %}
+        <!-- /instructions -->
+
+        <!-- /group -->
+
+        <!-- /form -->
+
 
-        {% /group %}
 
-        {% /form %}
 
         ```
 
@@ -1331,7 +1349,7 @@ turns:
           `{ op: "skip_field", fieldId: "...", reason: "Could not find verified data" }`
 
 
-          # Instructions for agent role
+          # Role guidance
           Complete the remaining fields based on the provided context.
 
           # Field-specific instructions
@@ -1352,202 +1370,208 @@ turns:
           ```markdown
           ---
           markform:
-            spec: "MF/0.1"
-            run_mode: "interactive"
-          role_instructions:
-            user: "Fill in the fields you have direct knowledge of."
-            agent: "Complete the remaining fields based on the provided context."
+            spec: MF/0.1
+            title: Simple Test Form
+            description: Fully interactive demo - no LLM required. Demonstrates all Markform field types.
+            run_mode: interactive
+            roles:
+              - user
+            role_instructions:
+              user: Fill in all fields in this form.
           ---
 
-          {% form id="simple_test" title="Simple Test Form" %}
+          <!-- form id="simple_test" title="Simple Test Form" -->
 
-          {% description ref="simple_test" %}
+          <!-- description ref="simple_test" -->
           A fully interactive form demonstrating all Markform v0.1 field types.
           Fill all fields using interactive prompts - no LLM API key needed.
-          {% /description %}
+          <!-- /description -->
 
-          {% group id="basic_fields" title="Basic Fields" %}
+          <!-- group id="basic_fields" title="Basic Fields" -->
 
-          {% field kind="string" id="name" role="user" examples=["John Smith", "Jane Doe"] label="Name" maxLength=50 minLength=2 placeholder="Enter your name" required=true %}
+          <!-- field kind="string" id="name" role="user" examples=["John Smith", "Jane Doe"] label="Name" maxLength=50 minLength=2 placeholder="Enter your name" required=true -->
           ```value
           Test User
           ```
-          {% /field %}
+          <!-- /field -->
 
-          {% instructions ref="name" %}
+          <!-- instructions ref="name" -->
           Enter your full name (2-50 characters).
-          {% /instructions %}
+          <!-- /instructions -->
 
-          {% field kind="string" id="email" role="user" examples=["alice@company.com", "bob@example.org"] label="Email" pattern="^[^@]+@[^@]+\\.[^@]+$" placeholder="email@example.com" required=true %}
+          <!-- field kind="string" id="email" role="user" examples=["alice@company.com", "bob@example.org"] label="Email" pattern="^[^@]+@[^@]+\\.[^@]+$" placeholder="email@example.com" required=true -->
           ```value
           test@example.com
           ```
-          {% /field %}
+          <!-- /field -->
 
-          {% field kind="number" id="age" role="user" examples=["18", "30", "45"] integer=true label="Age" max=150 min=0 placeholder="25" required=true %}
+          <!-- field kind="number" id="age" role="user" examples=["18", "30", "45"] integer=true label="Age" max=150 min=0 placeholder="25" required=true -->
           ```value
           25
           ```
-          {% /field %}
+          <!-- /field -->
 
-          {% field kind="number" id="score" role="user" examples=["75.0", "90.5", "100.0"] label="Score" max=100 min=0 placeholder="85.5" %}{% /field %}
+          <!-- field kind="number" id="score" role="user" examples=["75.0", "90.5", "100.0"] label="Score" max=100 min=0 placeholder="85.5" --><!-- /field -->
 
-          {% instructions ref="score" %}
+          <!-- instructions ref="score" -->
           Enter a score between 0 and 100 (optional).
-          {% /instructions %}
+          <!-- /instructions -->
 
-          {% /group %}
+          <!-- /group -->
 
-          {% group id="list_fields" title="List Fields" %}
+          <!-- group id="list_fields" title="List Fields" -->
 
-          {% field kind="string_list" id="tags" role="user" itemMinLength=2 label="Tags" maxItems=5 minItems=1 required=true uniqueItems=true %}
+          <!-- field kind="string_list" id="tags" role="user" itemMinLength=2 label="Tags" maxItems=5 minItems=1 required=true uniqueItems=true -->
           ```value
           typescript
           testing
           ```
-          {% /field %}
+          <!-- /field -->
 
-          {% instructions ref="tags" %}
+          <!-- instructions ref="tags" -->
           Add 1-5 unique tags (each at least 2 characters).
-          {% /instructions %}
+          <!-- /instructions -->
 
-          {% /group %}
+          <!-- /group -->
 
-          {% group id="selection_fields" title="Selection Fields" %}
+          <!-- group id="selection_fields" title="Selection Fields" -->
 
-          {% field kind="single_select" id="priority" role="user" label="Priority" required=true %}
-          - [ ] Low {% #low %}
-          - [ ] Medium {% #medium %}
-          - [x] High {% #high %}
-          {% /field %}
+          <!-- field kind="single_select" id="priority" role="user" label="Priority" required=true -->
+          - [ ] Low <!-- #low -->
+          - [ ] Medium <!-- #medium -->
+          - [x] High <!-- #high -->
+          <!-- /field -->
 
-          {% field kind="multi_select" id="categories" role="user" label="Categories" maxSelections=3 minSelections=1 required=true %}
-          - [x] Frontend {% #frontend %}
-          - [x] Backend {% #backend %}
-          - [ ] Database {% #database %}
-          - [ ] DevOps {% #devops %}
-          {% /field %}
+          <!-- field kind="multi_select" id="categories" role="user" label="Categories" maxSelections=3 minSelections=1 required=true -->
+          - [x] Frontend <!-- #frontend -->
+          - [x] Backend <!-- #backend -->
+          - [ ] Database <!-- #database -->
+          - [ ] DevOps <!-- #devops -->
+          <!-- /field -->
 
-          {% /group %}
+          <!-- /group -->
 
-          {% group id="checkbox_fields" title="Checkbox Fields" %}
+          <!-- group id="checkbox_fields" title="Checkbox Fields" -->
 
-          {% field kind="checkboxes" id="tasks_multi" role="user" label="Tasks (Multi Mode)" required=true %}
-          - [x] Research {% #research %}
-          - [x] Design {% #design %}
-          - [x] Implement {% #implement %}
-          - [-] Test {% #test %}
-          {% /field %}
+          <!-- field kind="checkboxes" id="tasks_multi" role="user" label="Tasks (Multi Mode)" required=true -->
+          - [x] Research <!-- #research -->
+          - [x] Design <!-- #design -->
+          - [x] Implement <!-- #implement -->
+          - [-] Test <!-- #test -->
+          <!-- /field -->
 
-          {% instructions ref="tasks_multi" %}
+          <!-- instructions ref="tasks_multi" -->
           Track task progress.
           All must reach done or na state to complete.
-          {% /instructions %}
+          <!-- /instructions -->
 
-          {% field kind="checkboxes" id="tasks_simple" role="user" checkboxMode="simple" label="Agreements (Simple Mode)" required=true %}
-          - [ ] I have read the guidelines {% #read_guidelines %}
-          - [ ] I agree to the terms {% #agree_terms %}
-          {% /field %}
+          <!-- field kind="checkboxes" id="tasks_simple" role="user" checkboxMode="simple" label="Agreements (Simple Mode)" required=true -->
+          - [ ] I have read the guidelines <!-- #read_guidelines -->
+          - [ ] I agree to the terms <!-- #agree_terms -->
+          <!-- /field -->
 
-          {% field kind="checkboxes" id="confirmations" role="user" checkboxMode="explicit" label="Confirmations (Explicit Mode)" required=true %}
-          - [y] Data has been backed up {% #backed_up %}
-          - [n] Stakeholders notified {% #notified %}
-          {% /field %}
+          <!-- field kind="checkboxes" id="confirmations" role="user" checkboxMode="explicit" label="Confirmations (Explicit Mode)" required=true -->
+          - [y] Data has been backed up <!-- #backed_up -->
+          - [n] Stakeholders notified <!-- #notified -->
+          <!-- /field -->
 
-          {% instructions ref="confirmations" %}
+          <!-- instructions ref="confirmations" -->
           Answer yes or no for each confirmation.
           All must be explicitly answered.
-          {% /instructions %}
+          <!-- /instructions -->
 
-          {% /group %}
+          <!-- /group -->
 
-          {% group id="url_fields" title="URL Fields" %}
+          <!-- group id="url_fields" title="URL Fields" -->
 
-          {% field kind="url" id="website" role="user" examples=["https://github.com/user/repo", "https://company.com"] label="Website" placeholder="https://example.com" required=true %}{% /field %}
+          <!-- field kind="url" id="website" role="user" examples=["https://github.com/user/repo", "https://company.com"] label="Website" placeholder="https://example.com" required=true --><!-- /field -->
 
-          {% instructions ref="website" %}
+          <!-- instructions ref="website" -->
           Enter your website URL (must be http or https).
-          {% /instructions %}
+          <!-- /instructions -->
 
-          {% field kind="url_list" id="references" role="user" examples=["https://wikipedia.org/wiki/Example", "https://docs.github.com/en"] label="References" maxItems=5 minItems=1 placeholder="https://docs.example.com" uniqueItems=true %}{% /field %}
+          <!-- field kind="url_list" id="references" role="user" examples=["https://wikipedia.org/wiki/Example", "https://docs.github.com/en"] label="References" maxItems=5 minItems=1 placeholder="https://docs.example.com" uniqueItems=true --><!-- /field -->
 
-          {% instructions ref="references" %}
+          <!-- instructions ref="references" -->
           Add 1-5 unique reference URLs for sources or documentation.
-          {% /instructions %}
+          <!-- /instructions -->
 
-          {% /group %}
+          <!-- /group -->
 
-          {% group id="date_fields" title="Date and Year Fields" %}
+          <!-- group id="date_fields" title="Date and Year Fields" -->
 
-          {% field kind="date" id="event_date" role="user" label="Event Date" max="2030-12-31" min="2020-01-01" required=true %}
+          <!-- field kind="date" id="event_date" role="user" label="Event Date" max="2030-12-31" min="2020-01-01" required=true -->
           ```value
           2025-03-15
           ```
-          {% /field %}
+          <!-- /field -->
 
-          {% instructions ref="event_date" %}
+          <!-- instructions ref="event_date" -->
           Enter the event date (YYYY-MM-DD format, between 2020 and 2030).
-          {% /instructions %}
+          <!-- /instructions -->
 
-          {% field kind="year" id="founded_year" role="user" label="Founded Year" max=2030 min=1900 required=true %}
+          <!-- field kind="year" id="founded_year" role="user" label="Founded Year" max=2030 min=1900 required=true -->
           ```value
           2021
           ```
-          {% /field %}
+          <!-- /field -->
 
-          {% instructions ref="founded_year" %}
+          <!-- instructions ref="founded_year" -->
           Enter the year the company was founded (1900-2030).
-          {% /instructions %}
+          <!-- /instructions -->
 
-          {% /group %}
+          <!-- /group -->
 
-          {% group id="table_fields" title="Table Fields" %}
+          <!-- group id="table_fields" title="Table Fields" -->
 
-          {% field kind="table" id="team_members" role="user" columnIds=["name", "role", "start_date"] columnLabels=["Name", "Role", "Start Date"] columnTypes=[{type: "string", required: true}, "string", "date"] label="Team Members" maxRows=5 minRows=0 %}{% /field %}
+          <!-- field kind="table" id="team_members" role="user" columnIds=["name", "role", "start_date"] columnLabels=["Name", "Role", "Start Date"] columnTypes=[{type: "string", required: true}, "string", "date"] label="Team Members" maxRows=5 minRows=0 --><!-- /field -->
 
-          {% instructions ref="team_members" %}
+          <!-- instructions ref="team_members" -->
           Add team members with their name (required), role, and start date.
-          {% /instructions %}
+          <!-- /instructions -->
 
-          {% field kind="table" id="project_tasks" role="user" columnIds=["task", "estimate_hrs", "link"] columnLabels=["Task", "Estimate (hrs)", "Link"] columnTypes=[{type: "string", required: true}, "number", "url"] label="Project Tasks" maxRows=10 minRows=0 %}{% /field %}
+          <!-- field kind="table" id="project_tasks" role="user" columnIds=["task", "estimate_hrs", "link"] columnLabels=["Task", "Estimate (hrs)", "Link"] columnTypes=[{type: "string", required: true}, "number", "url"] label="Project Tasks" maxRows=10 minRows=0 --><!-- /field -->
 
-          {% instructions ref="project_tasks" %}
+          <!-- instructions ref="project_tasks" -->
           Optionally add project tasks with estimated hours and reference links.
-          {% /instructions %}
+          <!-- /instructions -->
 
-          {% /group %}
+          <!-- /group -->
 
-          {% group id="optional_fields" title="Optional Fields" %}
+          <!-- group id="optional_fields" title="Optional Fields" -->
 
-          {% field kind="string" id="notes" role="user" label="Notes" %}{% /field %}
+          <!-- field kind="string" id="notes" role="user" label="Notes" --><!-- /field -->
 
-          {% instructions ref="notes" %}
+          <!-- instructions ref="notes" -->
           Add any relevant notes or observations (optional).
-          {% /instructions %}
+          <!-- /instructions -->
 
-          {% field kind="number" id="optional_number" role="user" label="Optional Number" %}{% /field %}
+          <!-- field kind="number" id="optional_number" role="user" label="Optional Number" --><!-- /field -->
 
-          {% field kind="url" id="related_url" role="user" label="Related URL" %}{% /field %}
+          <!-- field kind="url" id="related_url" role="user" label="Related URL" --><!-- /field -->
 
-          {% instructions ref="related_url" %}
+          <!-- instructions ref="related_url" -->
           Optionally add a URL to related documentation or resources.
-          {% /instructions %}
+          <!-- /instructions -->
 
-          {% field kind="date" id="optional_date" role="user" label="Optional Date" %}{% /field %}
+          <!-- field kind="date" id="optional_date" role="user" label="Optional Date" --><!-- /field -->
 
-          {% instructions ref="optional_date" %}
+          <!-- instructions ref="optional_date" -->
           Optionally add a date (YYYY-MM-DD format).
-          {% /instructions %}
+          <!-- /instructions -->
 
-          {% field kind="year" id="optional_year" role="user" label="Optional Year" %}{% /field %}
+          <!-- field kind="year" id="optional_year" role="user" label="Optional Year" --><!-- /field -->
 
-          {% instructions ref="optional_year" %}
+          <!-- instructions ref="optional_year" -->
           Optionally add a year.
-          {% /instructions %}
+          <!-- /instructions -->
+
+          <!-- /group -->
+
+          <!-- /form -->
+
 
-          {% /group %}
 
-          {% /form %}
 
           ```
 
@@ -1707,7 +1731,7 @@ turns:
           reason: No value in mock form
     after:
       required_issue_count: 0
-      markdown_sha256: 04cdbfc3f7880ee03c965da6c0bb2e27ffe933f75b3469c632ac589fdf3a617d
+      markdown_sha256: 6bff8d2d1e64c787c0a6e0661051b8ff6fd94bfc2cb3ed4054e74c93576a75d5
       answered_field_count: 13
       skipped_field_count: 8
     context:
@@ -1760,7 +1784,7 @@ turns:
         `{ op: "skip_field", fieldId: "...", reason: "Could not find verified data" }`
 
 
-        # Instructions for agent role
+        # Role guidance
         Complete the remaining fields based on the provided context.
 
         # Field-specific instructions
@@ -1774,238 +1798,244 @@ turns:
         ```markdown
         ---
         markform:
-          spec: "MF/0.1"
-          run_mode: "interactive"
-        role_instructions:
-          user: "Fill in the fields you have direct knowledge of."
-          agent: "Complete the remaining fields based on the provided context."
+          spec: MF/0.1
+          title: Simple Test Form
+          description: Fully interactive demo - no LLM required. Demonstrates all Markform field types.
+          run_mode: interactive
+          roles:
+            - user
+          role_instructions:
+            user: Fill in all fields in this form.
         ---
 
-        {% form id="simple_test" title="Simple Test Form" %}
+        <!-- form id="simple_test" title="Simple Test Form" -->
 
-        {% description ref="simple_test" %}
+        <!-- description ref="simple_test" -->
         A fully interactive form demonstrating all Markform v0.1 field types.
         Fill all fields using interactive prompts - no LLM API key needed.
-        {% /description %}
+        <!-- /description -->
 
-        {% group id="basic_fields" title="Basic Fields" %}
+        <!-- group id="basic_fields" title="Basic Fields" -->
 
-        {% field kind="string" id="name" role="user" examples=["John Smith", "Jane Doe"] label="Name" maxLength=50 minLength=2 placeholder="Enter your name" required=true %}
+        <!-- field kind="string" id="name" role="user" examples=["John Smith", "Jane Doe"] label="Name" maxLength=50 minLength=2 placeholder="Enter your name" required=true -->
         ```value
         Test User
         ```
-        {% /field %}
+        <!-- /field -->
 
-        {% instructions ref="name" %}
+        <!-- instructions ref="name" -->
         Enter your full name (2-50 characters).
-        {% /instructions %}
+        <!-- /instructions -->
 
-        {% field kind="string" id="email" role="user" examples=["alice@company.com", "bob@example.org"] label="Email" pattern="^[^@]+@[^@]+\\.[^@]+$" placeholder="email@example.com" required=true %}
+        <!-- field kind="string" id="email" role="user" examples=["alice@company.com", "bob@example.org"] label="Email" pattern="^[^@]+@[^@]+\\.[^@]+$" placeholder="email@example.com" required=true -->
         ```value
         test@example.com
         ```
-        {% /field %}
+        <!-- /field -->
 
-        {% field kind="number" id="age" role="user" examples=["18", "30", "45"] integer=true label="Age" max=150 min=0 placeholder="25" required=true %}
+        <!-- field kind="number" id="age" role="user" examples=["18", "30", "45"] integer=true label="Age" max=150 min=0 placeholder="25" required=true -->
         ```value
         25
         ```
-        {% /field %}
+        <!-- /field -->
 
-        {% field kind="number" id="score" role="user" examples=["75.0", "90.5", "100.0"] label="Score" max=100 min=0 placeholder="85.5" state="skipped" %}
+        <!-- field kind="number" id="score" role="user" examples=["75.0", "90.5", "100.0"] label="Score" max=100 min=0 placeholder="85.5" state="skipped" -->
         ```value
         %SKIP% (No value in mock form)
         ```
-        {% /field %}
+        <!-- /field -->
 
-        {% instructions ref="score" %}
+        <!-- instructions ref="score" -->
         Enter a score between 0 and 100 (optional).
-        {% /instructions %}
+        <!-- /instructions -->
 
-        {% /group %}
+        <!-- /group -->
 
-        {% group id="list_fields" title="List Fields" %}
+        <!-- group id="list_fields" title="List Fields" -->
 
-        {% field kind="string_list" id="tags" role="user" itemMinLength=2 label="Tags" maxItems=5 minItems=1 required=true uniqueItems=true %}
+        <!-- field kind="string_list" id="tags" role="user" itemMinLength=2 label="Tags" maxItems=5 minItems=1 required=true uniqueItems=true -->
         ```value
         typescript
         testing
         ```
-        {% /field %}
+        <!-- /field -->
 
-        {% instructions ref="tags" %}
+        <!-- instructions ref="tags" -->
         Add 1-5 unique tags (each at least 2 characters).
-        {% /instructions %}
+        <!-- /instructions -->
 
-        {% /group %}
+        <!-- /group -->
 
-        {% group id="selection_fields" title="Selection Fields" %}
+        <!-- group id="selection_fields" title="Selection Fields" -->
 
-        {% field kind="single_select" id="priority" role="user" label="Priority" required=true %}
-        - [ ] Low {% #low %}
-        - [ ] Medium {% #medium %}
-        - [x] High {% #high %}
-        {% /field %}
+        <!-- field kind="single_select" id="priority" role="user" label="Priority" required=true -->
+        - [ ] Low <!-- #low -->
+        - [ ] Medium <!-- #medium -->
+        - [x] High <!-- #high -->
+        <!-- /field -->
 
-        {% field kind="multi_select" id="categories" role="user" label="Categories" maxSelections=3 minSelections=1 required=true %}
-        - [x] Frontend {% #frontend %}
-        - [x] Backend {% #backend %}
-        - [ ] Database {% #database %}
-        - [ ] DevOps {% #devops %}
-        {% /field %}
+        <!-- field kind="multi_select" id="categories" role="user" label="Categories" maxSelections=3 minSelections=1 required=true -->
+        - [x] Frontend <!-- #frontend -->
+        - [x] Backend <!-- #backend -->
+        - [ ] Database <!-- #database -->
+        - [ ] DevOps <!-- #devops -->
+        <!-- /field -->
 
-        {% /group %}
+        <!-- /group -->
 
-        {% group id="checkbox_fields" title="Checkbox Fields" %}
+        <!-- group id="checkbox_fields" title="Checkbox Fields" -->
 
-        {% field kind="checkboxes" id="tasks_multi" role="user" label="Tasks (Multi Mode)" required=true %}
-        - [x] Research {% #research %}
-        - [x] Design {% #design %}
-        - [x] Implement {% #implement %}
-        - [-] Test {% #test %}
-        {% /field %}
+        <!-- field kind="checkboxes" id="tasks_multi" role="user" label="Tasks (Multi Mode)" required=true -->
+        - [x] Research <!-- #research -->
+        - [x] Design <!-- #design -->
+        - [x] Implement <!-- #implement -->
+        - [-] Test <!-- #test -->
+        <!-- /field -->
 
-        {% instructions ref="tasks_multi" %}
+        <!-- instructions ref="tasks_multi" -->
         Track task progress.
         All must reach done or na state to complete.
-        {% /instructions %}
+        <!-- /instructions -->
 
-        {% field kind="checkboxes" id="tasks_simple" role="user" checkboxMode="simple" label="Agreements (Simple Mode)" required=true %}
-        - [x] I have read the guidelines {% #read_guidelines %}
-        - [x] I agree to the terms {% #agree_terms %}
-        {% /field %}
+        <!-- field kind="checkboxes" id="tasks_simple" role="user" checkboxMode="simple" label="Agreements (Simple Mode)" required=true -->
+        - [x] I have read the guidelines <!-- #read_guidelines -->
+        - [x] I agree to the terms <!-- #agree_terms -->
+        <!-- /field -->
 
-        {% field kind="checkboxes" id="confirmations" role="user" checkboxMode="explicit" label="Confirmations (Explicit Mode)" required=true %}
-        - [y] Data has been backed up {% #backed_up %}
-        - [n] Stakeholders notified {% #notified %}
-        {% /field %}
+        <!-- field kind="checkboxes" id="confirmations" role="user" checkboxMode="explicit" label="Confirmations (Explicit Mode)" required=true -->
+        - [y] Data has been backed up <!-- #backed_up -->
+        - [n] Stakeholders notified <!-- #notified -->
+        <!-- /field -->
 
-        {% instructions ref="confirmations" %}
+        <!-- instructions ref="confirmations" -->
         Answer yes or no for each confirmation.
         All must be explicitly answered.
-        {% /instructions %}
+        <!-- /instructions -->
 
-        {% /group %}
+        <!-- /group -->
 
-        {% group id="url_fields" title="URL Fields" %}
+        <!-- group id="url_fields" title="URL Fields" -->
 
-        {% field kind="url" id="website" role="user" examples=["https://github.com/user/repo", "https://company.com"] label="Website" placeholder="https://example.com" required=true %}
+        <!-- field kind="url" id="website" role="user" examples=["https://github.com/user/repo", "https://company.com"] label="Website" placeholder="https://example.com" required=true -->
         ```value
         https://test.example.com
         ```
-        {% /field %}
+        <!-- /field -->
 
-        {% instructions ref="website" %}
+        <!-- instructions ref="website" -->
         Enter your website URL (must be http or https).
-        {% /instructions %}
+        <!-- /instructions -->
 
-        {% field kind="url_list" id="references" role="user" examples=["https://wikipedia.org/wiki/Example", "https://docs.github.com/en"] label="References" maxItems=5 minItems=1 placeholder="https://docs.example.com" uniqueItems=true %}
+        <!-- field kind="url_list" id="references" role="user" examples=["https://wikipedia.org/wiki/Example", "https://docs.github.com/en"] label="References" maxItems=5 minItems=1 placeholder="https://docs.example.com" uniqueItems=true -->
         ```value
         https://docs.example.com
         ```
-        {% /field %}
+        <!-- /field -->
 
-        {% instructions ref="references" %}
+        <!-- instructions ref="references" -->
         Add 1-5 unique reference URLs for sources or documentation.
-        {% /instructions %}
+        <!-- /instructions -->
 
-        {% /group %}
+        <!-- /group -->
 
-        {% group id="date_fields" title="Date and Year Fields" %}
+        <!-- group id="date_fields" title="Date and Year Fields" -->
 
-        {% field kind="date" id="event_date" role="user" label="Event Date" max="2030-12-31" min="2020-01-01" required=true %}
+        <!-- field kind="date" id="event_date" role="user" label="Event Date" max="2030-12-31" min="2020-01-01" required=true -->
         ```value
         2025-03-15
         ```
-        {% /field %}
+        <!-- /field -->
 
-        {% instructions ref="event_date" %}
+        <!-- instructions ref="event_date" -->
         Enter the event date (YYYY-MM-DD format, between 2020 and 2030).
-        {% /instructions %}
+        <!-- /instructions -->
 
-        {% field kind="year" id="founded_year" role="user" label="Founded Year" max=2030 min=1900 required=true %}
+        <!-- field kind="year" id="founded_year" role="user" label="Founded Year" max=2030 min=1900 required=true -->
         ```value
         2021
         ```
-        {% /field %}
+        <!-- /field -->
 
-        {% instructions ref="founded_year" %}
+        <!-- instructions ref="founded_year" -->
         Enter the year the company was founded (1900-2030).
-        {% /instructions %}
+        <!-- /instructions -->
 
-        {% /group %}
+        <!-- /group -->
 
-        {% group id="table_fields" title="Table Fields" %}
+        <!-- group id="table_fields" title="Table Fields" -->
 
-        {% field kind="table" id="team_members" role="user" columnIds=["name", "role", "start_date"] columnLabels=["Name", "Role", "Start Date"] columnTypes=[{type: "string", required: true}, "string", "date"] label="Team Members" maxRows=5 minRows=0 %}{% /field %}
+        <!-- field kind="table" id="team_members" role="user" columnIds=["name", "role", "start_date"] columnLabels=["Name", "Role", "Start Date"] columnTypes=[{type: "string", required: true}, "string", "date"] label="Team Members" maxRows=5 minRows=0 --><!-- /field -->
 
-        {% instructions ref="team_members" %}
+        <!-- instructions ref="team_members" -->
         Add team members with their name (required), role, and start date.
-        {% /instructions %}
+        <!-- /instructions -->
 
-        {% field kind="table" id="project_tasks" role="user" columnIds=["task", "estimate_hrs", "link"] columnLabels=["Task", "Estimate (hrs)", "Link"] columnTypes=[{type: "string", required: true}, "number", "url"] label="Project Tasks" maxRows=10 minRows=0 state="skipped" %}
+        <!-- field kind="table" id="project_tasks" role="user" columnIds=["task", "estimate_hrs", "link"] columnLabels=["Task", "Estimate (hrs)", "Link"] columnTypes=[{type: "string", required: true}, "number", "url"] label="Project Tasks" maxRows=10 minRows=0 state="skipped" -->
         ```value
         %SKIP% (No value in mock form)
         ```
-        {% /field %}
+        <!-- /field -->
 
-        {% instructions ref="project_tasks" %}
+        <!-- instructions ref="project_tasks" -->
         Optionally add project tasks with estimated hours and reference links.
-        {% /instructions %}
+        <!-- /instructions -->
 
-        {% /group %}
+        <!-- /group -->
 
-        {% group id="optional_fields" title="Optional Fields" %}
+        <!-- group id="optional_fields" title="Optional Fields" -->
 
-        {% field kind="string" id="notes" role="user" label="Notes" state="skipped" %}
+        <!-- field kind="string" id="notes" role="user" label="Notes" state="skipped" -->
         ```value
         %SKIP% (No value in mock form)
         ```
-        {% /field %}
+        <!-- /field -->
 
-        {% instructions ref="notes" %}
+        <!-- instructions ref="notes" -->
         Add any relevant notes or observations (optional).
-        {% /instructions %}
+        <!-- /instructions -->
 
-        {% field kind="number" id="optional_number" role="user" label="Optional Number" state="skipped" %}
+        <!-- field kind="number" id="optional_number" role="user" label="Optional Number" state="skipped" -->
         ```value
         %SKIP% (No value in mock form)
         ```
-        {% /field %}
+        <!-- /field -->
 
-        {% field kind="url" id="related_url" role="user" label="Related URL" state="skipped" %}
+        <!-- field kind="url" id="related_url" role="user" label="Related URL" state="skipped" -->
         ```value
         %SKIP% (No value in mock form)
         ```
-        {% /field %}
+        <!-- /field -->
 
-        {% instructions ref="related_url" %}
+        <!-- instructions ref="related_url" -->
         Optionally add a URL to related documentation or resources.
-        {% /instructions %}
+        <!-- /instructions -->
 
-        {% field kind="date" id="optional_date" role="user" label="Optional Date" state="skipped" %}
+        <!-- field kind="date" id="optional_date" role="user" label="Optional Date" state="skipped" -->
         ```value
         %SKIP% (No value in mock form)
         ```
-        {% /field %}
+        <!-- /field -->
 
-        {% instructions ref="optional_date" %}
+        <!-- instructions ref="optional_date" -->
         Optionally add a date (YYYY-MM-DD format).
-        {% /instructions %}
+        <!-- /instructions -->
 
-        {% field kind="year" id="optional_year" role="user" label="Optional Year" state="skipped" %}
+        <!-- field kind="year" id="optional_year" role="user" label="Optional Year" state="skipped" -->
         ```value
         %SKIP% (No value in mock form)
         ```
-        {% /field %}
+        <!-- /field -->
 
-        {% instructions ref="optional_year" %}
+        <!-- instructions ref="optional_year" -->
         Optionally add a year.
-        {% /instructions %}
+        <!-- /instructions -->
+
+        <!-- /group -->
+
+        <!-- /form -->
+
 
-        {% /group %}
 
-        {% /form %}
 
         ```
 
@@ -2076,7 +2106,7 @@ turns:
           `{ op: "skip_field", fieldId: "...", reason: "Could not find verified data" }`
 
 
-          # Instructions for agent role
+          # Role guidance
           Complete the remaining fields based on the provided context.
 
           # Field-specific instructions
@@ -2090,238 +2120,244 @@ turns:
           ```markdown
           ---
           markform:
-            spec: "MF/0.1"
-            run_mode: "interactive"
-          role_instructions:
-            user: "Fill in the fields you have direct knowledge of."
-            agent: "Complete the remaining fields based on the provided context."
+            spec: MF/0.1
+            title: Simple Test Form
+            description: Fully interactive demo - no LLM required. Demonstrates all Markform field types.
+            run_mode: interactive
+            roles:
+              - user
+            role_instructions:
+              user: Fill in all fields in this form.
           ---
 
-          {% form id="simple_test" title="Simple Test Form" %}
+          <!-- form id="simple_test" title="Simple Test Form" -->
 
-          {% description ref="simple_test" %}
+          <!-- description ref="simple_test" -->
           A fully interactive form demonstrating all Markform v0.1 field types.
           Fill all fields using interactive prompts - no LLM API key needed.
-          {% /description %}
+          <!-- /description -->
 
-          {% group id="basic_fields" title="Basic Fields" %}
+          <!-- group id="basic_fields" title="Basic Fields" -->
 
-          {% field kind="string" id="name" role="user" examples=["John Smith", "Jane Doe"] label="Name" maxLength=50 minLength=2 placeholder="Enter your name" required=true %}
+          <!-- field kind="string" id="name" role="user" examples=["John Smith", "Jane Doe"] label="Name" maxLength=50 minLength=2 placeholder="Enter your name" required=true -->
           ```value
           Test User
           ```
-          {% /field %}
+          <!-- /field -->
 
-          {% instructions ref="name" %}
+          <!-- instructions ref="name" -->
           Enter your full name (2-50 characters).
-          {% /instructions %}
+          <!-- /instructions -->
 
-          {% field kind="string" id="email" role="user" examples=["alice@company.com", "bob@example.org"] label="Email" pattern="^[^@]+@[^@]+\\.[^@]+$" placeholder="email@example.com" required=true %}
+          <!-- field kind="string" id="email" role="user" examples=["alice@company.com", "bob@example.org"] label="Email" pattern="^[^@]+@[^@]+\\.[^@]+$" placeholder="email@example.com" required=true -->
           ```value
           test@example.com
           ```
-          {% /field %}
+          <!-- /field -->
 
-          {% field kind="number" id="age" role="user" examples=["18", "30", "45"] integer=true label="Age" max=150 min=0 placeholder="25" required=true %}
+          <!-- field kind="number" id="age" role="user" examples=["18", "30", "45"] integer=true label="Age" max=150 min=0 placeholder="25" required=true -->
           ```value
           25
           ```
-          {% /field %}
+          <!-- /field -->
 
-          {% field kind="number" id="score" role="user" examples=["75.0", "90.5", "100.0"] label="Score" max=100 min=0 placeholder="85.5" state="skipped" %}
+          <!-- field kind="number" id="score" role="user" examples=["75.0", "90.5", "100.0"] label="Score" max=100 min=0 placeholder="85.5" state="skipped" -->
           ```value
           %SKIP% (No value in mock form)
           ```
-          {% /field %}
+          <!-- /field -->
 
-          {% instructions ref="score" %}
+          <!-- instructions ref="score" -->
           Enter a score between 0 and 100 (optional).
-          {% /instructions %}
+          <!-- /instructions -->
 
-          {% /group %}
+          <!-- /group -->
 
-          {% group id="list_fields" title="List Fields" %}
+          <!-- group id="list_fields" title="List Fields" -->
 
-          {% field kind="string_list" id="tags" role="user" itemMinLength=2 label="Tags" maxItems=5 minItems=1 required=true uniqueItems=true %}
+          <!-- field kind="string_list" id="tags" role="user" itemMinLength=2 label="Tags" maxItems=5 minItems=1 required=true uniqueItems=true -->
           ```value
           typescript
           testing
           ```
-          {% /field %}
+          <!-- /field -->
 
-          {% instructions ref="tags" %}
+          <!-- instructions ref="tags" -->
           Add 1-5 unique tags (each at least 2 characters).
-          {% /instructions %}
+          <!-- /instructions -->
 
-          {% /group %}
+          <!-- /group -->
 
-          {% group id="selection_fields" title="Selection Fields" %}
+          <!-- group id="selection_fields" title="Selection Fields" -->
 
-          {% field kind="single_select" id="priority" role="user" label="Priority" required=true %}
-          - [ ] Low {% #low %}
-          - [ ] Medium {% #medium %}
-          - [x] High {% #high %}
-          {% /field %}
+          <!-- field kind="single_select" id="priority" role="user" label="Priority" required=true -->
+          - [ ] Low <!-- #low -->
+          - [ ] Medium <!-- #medium -->
+          - [x] High <!-- #high -->
+          <!-- /field -->
 
-          {% field kind="multi_select" id="categories" role="user" label="Categories" maxSelections=3 minSelections=1 required=true %}
-          - [x] Frontend {% #frontend %}
-          - [x] Backend {% #backend %}
-          - [ ] Database {% #database %}
-          - [ ] DevOps {% #devops %}
-          {% /field %}
+          <!-- field kind="multi_select" id="categories" role="user" label="Categories" maxSelections=3 minSelections=1 required=true -->
+          - [x] Frontend <!-- #frontend -->
+          - [x] Backend <!-- #backend -->
+          - [ ] Database <!-- #database -->
+          - [ ] DevOps <!-- #devops -->
+          <!-- /field -->
 
-          {% /group %}
+          <!-- /group -->
 
-          {% group id="checkbox_fields" title="Checkbox Fields" %}
+          <!-- group id="checkbox_fields" title="Checkbox Fields" -->
 
-          {% field kind="checkboxes" id="tasks_multi" role="user" label="Tasks (Multi Mode)" required=true %}
-          - [x] Research {% #research %}
-          - [x] Design {% #design %}
-          - [x] Implement {% #implement %}
-          - [-] Test {% #test %}
-          {% /field %}
+          <!-- field kind="checkboxes" id="tasks_multi" role="user" label="Tasks (Multi Mode)" required=true -->
+          - [x] Research <!-- #research -->
+          - [x] Design <!-- #design -->
+          - [x] Implement <!-- #implement -->
+          - [-] Test <!-- #test -->
+          <!-- /field -->
 
-          {% instructions ref="tasks_multi" %}
+          <!-- instructions ref="tasks_multi" -->
           Track task progress.
           All must reach done or na state to complete.
-          {% /instructions %}
+          <!-- /instructions -->
 
-          {% field kind="checkboxes" id="tasks_simple" role="user" checkboxMode="simple" label="Agreements (Simple Mode)" required=true %}
-          - [x] I have read the guidelines {% #read_guidelines %}
-          - [x] I agree to the terms {% #agree_terms %}
-          {% /field %}
+          <!-- field kind="checkboxes" id="tasks_simple" role="user" checkboxMode="simple" label="Agreements (Simple Mode)" required=true -->
+          - [x] I have read the guidelines <!-- #read_guidelines -->
+          - [x] I agree to the terms <!-- #agree_terms -->
+          <!-- /field -->
 
-          {% field kind="checkboxes" id="confirmations" role="user" checkboxMode="explicit" label="Confirmations (Explicit Mode)" required=true %}
-          - [y] Data has been backed up {% #backed_up %}
-          - [n] Stakeholders notified {% #notified %}
-          {% /field %}
+          <!-- field kind="checkboxes" id="confirmations" role="user" checkboxMode="explicit" label="Confirmations (Explicit Mode)" required=true -->
+          - [y] Data has been backed up <!-- #backed_up -->
+          - [n] Stakeholders notified <!-- #notified -->
+          <!-- /field -->
 
-          {% instructions ref="confirmations" %}
+          <!-- instructions ref="confirmations" -->
           Answer yes or no for each confirmation.
           All must be explicitly answered.
-          {% /instructions %}
+          <!-- /instructions -->
 
-          {% /group %}
+          <!-- /group -->
 
-          {% group id="url_fields" title="URL Fields" %}
+          <!-- group id="url_fields" title="URL Fields" -->
 
-          {% field kind="url" id="website" role="user" examples=["https://github.com/user/repo", "https://company.com"] label="Website" placeholder="https://example.com" required=true %}
+          <!-- field kind="url" id="website" role="user" examples=["https://github.com/user/repo", "https://company.com"] label="Website" placeholder="https://example.com" required=true -->
           ```value
           https://test.example.com
           ```
-          {% /field %}
+          <!-- /field -->
 
-          {% instructions ref="website" %}
+          <!-- instructions ref="website" -->
           Enter your website URL (must be http or https).
-          {% /instructions %}
+          <!-- /instructions -->
 
-          {% field kind="url_list" id="references" role="user" examples=["https://wikipedia.org/wiki/Example", "https://docs.github.com/en"] label="References" maxItems=5 minItems=1 placeholder="https://docs.example.com" uniqueItems=true %}
+          <!-- field kind="url_list" id="references" role="user" examples=["https://wikipedia.org/wiki/Example", "https://docs.github.com/en"] label="References" maxItems=5 minItems=1 placeholder="https://docs.example.com" uniqueItems=true -->
           ```value
           https://docs.example.com
           ```
-          {% /field %}
+          <!-- /field -->
 
-          {% instructions ref="references" %}
+          <!-- instructions ref="references" -->
           Add 1-5 unique reference URLs for sources or documentation.
-          {% /instructions %}
+          <!-- /instructions -->
 
-          {% /group %}
+          <!-- /group -->
 
-          {% group id="date_fields" title="Date and Year Fields" %}
+          <!-- group id="date_fields" title="Date and Year Fields" -->
 
-          {% field kind="date" id="event_date" role="user" label="Event Date" max="2030-12-31" min="2020-01-01" required=true %}
+          <!-- field kind="date" id="event_date" role="user" label="Event Date" max="2030-12-31" min="2020-01-01" required=true -->
           ```value
           2025-03-15
           ```
-          {% /field %}
+          <!-- /field -->
 
-          {% instructions ref="event_date" %}
+          <!-- instructions ref="event_date" -->
           Enter the event date (YYYY-MM-DD format, between 2020 and 2030).
-          {% /instructions %}
+          <!-- /instructions -->
 
-          {% field kind="year" id="founded_year" role="user" label="Founded Year" max=2030 min=1900 required=true %}
+          <!-- field kind="year" id="founded_year" role="user" label="Founded Year" max=2030 min=1900 required=true -->
           ```value
           2021
           ```
-          {% /field %}
+          <!-- /field -->
 
-          {% instructions ref="founded_year" %}
+          <!-- instructions ref="founded_year" -->
           Enter the year the company was founded (1900-2030).
-          {% /instructions %}
+          <!-- /instructions -->
 
-          {% /group %}
+          <!-- /group -->
 
-          {% group id="table_fields" title="Table Fields" %}
+          <!-- group id="table_fields" title="Table Fields" -->
 
-          {% field kind="table" id="team_members" role="user" columnIds=["name", "role", "start_date"] columnLabels=["Name", "Role", "Start Date"] columnTypes=[{type: "string", required: true}, "string", "date"] label="Team Members" maxRows=5 minRows=0 %}{% /field %}
+          <!-- field kind="table" id="team_members" role="user" columnIds=["name", "role", "start_date"] columnLabels=["Name", "Role", "Start Date"] columnTypes=[{type: "string", required: true}, "string", "date"] label="Team Members" maxRows=5 minRows=0 --><!-- /field -->
 
-          {% instructions ref="team_members" %}
+          <!-- instructions ref="team_members" -->
           Add team members with their name (required), role, and start date.
-          {% /instructions %}
+          <!-- /instructions -->
 
-          {% field kind="table" id="project_tasks" role="user" columnIds=["task", "estimate_hrs", "link"] columnLabels=["Task", "Estimate (hrs)", "Link"] columnTypes=[{type: "string", required: true}, "number", "url"] label="Project Tasks" maxRows=10 minRows=0 state="skipped" %}
+          <!-- field kind="table" id="project_tasks" role="user" columnIds=["task", "estimate_hrs", "link"] columnLabels=["Task", "Estimate (hrs)", "Link"] columnTypes=[{type: "string", required: true}, "number", "url"] label="Project Tasks" maxRows=10 minRows=0 state="skipped" -->
           ```value
           %SKIP% (No value in mock form)
           ```
-          {% /field %}
+          <!-- /field -->
 
-          {% instructions ref="project_tasks" %}
+          <!-- instructions ref="project_tasks" -->
           Optionally add project tasks with estimated hours and reference links.
-          {% /instructions %}
+          <!-- /instructions -->
 
-          {% /group %}
+          <!-- /group -->
 
-          {% group id="optional_fields" title="Optional Fields" %}
+          <!-- group id="optional_fields" title="Optional Fields" -->
 
-          {% field kind="string" id="notes" role="user" label="Notes" state="skipped" %}
+          <!-- field kind="string" id="notes" role="user" label="Notes" state="skipped" -->
           ```value
           %SKIP% (No value in mock form)
           ```
-          {% /field %}
+          <!-- /field -->
 
-          {% instructions ref="notes" %}
+          <!-- instructions ref="notes" -->
           Add any relevant notes or observations (optional).
-          {% /instructions %}
+          <!-- /instructions -->
 
-          {% field kind="number" id="optional_number" role="user" label="Optional Number" state="skipped" %}
+          <!-- field kind="number" id="optional_number" role="user" label="Optional Number" state="skipped" -->
           ```value
           %SKIP% (No value in mock form)
           ```
-          {% /field %}
+          <!-- /field -->
 
-          {% field kind="url" id="related_url" role="user" label="Related URL" state="skipped" %}
+          <!-- field kind="url" id="related_url" role="user" label="Related URL" state="skipped" -->
           ```value
           %SKIP% (No value in mock form)
           ```
-          {% /field %}
+          <!-- /field -->
 
-          {% instructions ref="related_url" %}
+          <!-- instructions ref="related_url" -->
           Optionally add a URL to related documentation or resources.
-          {% /instructions %}
+          <!-- /instructions -->
 
-          {% field kind="date" id="optional_date" role="user" label="Optional Date" state="skipped" %}
+          <!-- field kind="date" id="optional_date" role="user" label="Optional Date" state="skipped" -->
           ```value
           %SKIP% (No value in mock form)
           ```
-          {% /field %}
+          <!-- /field -->
 
-          {% instructions ref="optional_date" %}
+          <!-- instructions ref="optional_date" -->
           Optionally add a date (YYYY-MM-DD format).
-          {% /instructions %}
+          <!-- /instructions -->
 
-          {% field kind="year" id="optional_year" role="user" label="Optional Year" state="skipped" %}
+          <!-- field kind="year" id="optional_year" role="user" label="Optional Year" state="skipped" -->
           ```value
           %SKIP% (No value in mock form)
           ```
-          {% /field %}
+          <!-- /field -->
 
-          {% instructions ref="optional_year" %}
+          <!-- instructions ref="optional_year" -->
           Optionally add a year.
-          {% /instructions %}
+          <!-- /instructions -->
+
+          <!-- /group -->
+
+          <!-- /form -->
+
 
-          {% /group %}
 
-          {% /form %}
 
           ```