markform 0.1.20 → 0.1.22

package/examples/simple/simple.session.yaml

@@ -120,7 +120,7 @@ turns:
             test: na
     after:
       required_issue_count: 2
-      markdown_sha256: 18f7c0fed3947e24df66bd4f8cafa4a5d916d77b6a0cd8f76327f9e14f04a74f
+      markdown_sha256: 5dc18a81508d9ae2487c8c7628d5afccd603df4e6461c840d40dd5ee8905b7bb
       answered_field_count: 10
       skipped_field_count: 0
     context:
@@ -173,7 +173,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
@@ -194,177 +194,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 %}
 
         ```
 
@@ -493,7 +499,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
@@ -514,177 +520,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 %}
 
           ```
 
@@ -936,7 +948,7 @@ turns:
           value: 87.5
     after:
       required_issue_count: 0
-      markdown_sha256: b3e42a2b1c09183968a8ff280c27381a71f05724987fd01b7fefe2d9a25ee765
+      markdown_sha256: 53aa6ec5a9c403633cb91d29d6e7f8c197f207695e2a66da460c1aa837ce22af
       answered_field_count: 16
       skipped_field_count: 4
     context:
@@ -989,7 +1001,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
@@ -1010,203 +1022,209 @@ 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
         Alice Johnson
         ```
-        {% /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
         alice@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
         32
         ```
-        {% /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
         forms
         ```
-        {% /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 %}
-        - [x] Medium {% #medium %}
-        - [ ] High {% #high %}
-        {% /field %}
+        <!-- field kind="single_select" id="priority" role="user" label="Priority" required=true -->
+        - [ ] Low <!-- #low -->
+        - [x] Medium <!-- #medium -->
+        - [ ] 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-06-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
         2020
         ```
-        {% /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 %}
 
         ```
 
@@ -1333,7 +1351,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
@@ -1354,203 +1372,209 @@ 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
           Alice Johnson
           ```
-          {% /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
           alice@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
           32
           ```
-          {% /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
           forms
           ```
-          {% /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 %}
-          - [x] Medium {% #medium %}
-          - [ ] High {% #high %}
-          {% /field %}
+          <!-- field kind="single_select" id="priority" role="user" label="Priority" required=true -->
+          - [ ] Low <!-- #low -->
+          - [x] Medium <!-- #medium -->
+          - [ ] 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-06-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
           2020
           ```
-          {% /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 %}
 
           ```
 
@@ -1714,7 +1738,7 @@ turns:
               start_date: 2023-06-01
     after:
       required_issue_count: 0
-      markdown_sha256: 72665385974b33d91df16c5e2323be5e13b514dd0f34220417bc6f021c09f690
+      markdown_sha256: 4f95050f83002c993880cf5ac7ff3ed6a8e261a660ab5956d9274d24c9fe192c
       answered_field_count: 17
       skipped_field_count: 4
     context:
@@ -1767,7 +1791,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
@@ -1781,241 +1805,247 @@ 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
         Alice Johnson
         ```
-        {% /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
         alice@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
         32
         ```
-        {% /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 kind="number" id="score" role="user" examples=["75.0", "90.5", "100.0"] label="Score" max=100 min=0 placeholder="85.5" -->
         ```value
         87.5
         ```
-        {% /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
         forms
         ```
-        {% /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 %}
-        - [x] Medium {% #medium %}
-        - [ ] High {% #high %}
-        {% /field %}
+        <!-- field kind="single_select" id="priority" role="user" label="Priority" required=true -->
+        - [ ] Low <!-- #low -->
+        - [x] Medium <!-- #medium -->
+        - [ ] 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://alice.dev
         ```
-        {% /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/guide
         https://github.com/example/project
         https://medium.com/article-about-forms
         ```
-        {% /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-06-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
         2020
         ```
-        {% /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" %}
+        <!-- field kind="string" id="notes" role="user" label="Notes" -->
         ```value
         This is a test note.
         ```
-        {% /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" %}
+        <!-- field kind="url" id="related_url" role="user" label="Related URL" -->
         ```value
         https://markform.dev/docs
         ```
-        {% /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 %}
 
         ```
 
@@ -2086,7 +2116,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
@@ -2100,241 +2130,247 @@ 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
           Alice Johnson
           ```
-          {% /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
           alice@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
           32
           ```
-          {% /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 kind="number" id="score" role="user" examples=["75.0", "90.5", "100.0"] label="Score" max=100 min=0 placeholder="85.5" -->
           ```value
           87.5
           ```
-          {% /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
           forms
           ```
-          {% /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 %}
-          - [x] Medium {% #medium %}
-          - [ ] High {% #high %}
-          {% /field %}
+          <!-- field kind="single_select" id="priority" role="user" label="Priority" required=true -->
+          - [ ] Low <!-- #low -->
+          - [x] Medium <!-- #medium -->
+          - [ ] 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://alice.dev
           ```
-          {% /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/guide
           https://github.com/example/project
           https://medium.com/article-about-forms
           ```
-          {% /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-06-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
           2020
           ```
-          {% /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" %}
+          <!-- field kind="string" id="notes" role="user" label="Notes" -->
           ```value
           This is a test note.
           ```
-          {% /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" %}
+          <!-- field kind="url" id="related_url" role="user" label="Related URL" -->
           ```value
           https://markform.dev/docs
           ```
-          {% /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 %}
 
           ```