From 44cfd88bddc1c62d497301cf7645b6fb8cfe226f Mon Sep 17 00:00:00 2001
From: Blake Bertuccelli-Booth <46652+bbertucc@users.noreply.github.com>
Date: Thu, 21 May 2026 14:47:26 -0700
Subject: [PATCH 1/7] feat(pipeline): form reconstruction subagent emitting
 composable form blocks
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Realigns form handling to the table/list/image pattern instead of a
standalone step. The structure pass now detects forms (new has_forms page
attribute), which gates a reconstruct_form tool on the page-correction
agent — so the orchestrator only pays for form work on pages that actually
have a form, and forms compose with the other per-page corrections.

The form subagent reads the form from the page image and returns a
structured FormReconstructionResult (legend + typed fields). A deterministic
renderer turns that into a self-contained ```form block (a small composable
DSL inspired by Obsidian custom code-block processors / Meta Bind), which the
page agent splices in via str_replace. Rendering the block to accessible
controls is the viewer's / downstream renderer's job; the block contract is
documented in docs/reference/form-block.md.

- has_forms on PageAttributes + structure-analysis prompt detection
- src/agents/prompts/form_reconstruction.py (subagent prompt)
- procedures/page_correction/content/has_forms.md (gated page guidance)
- FormFieldType / FormFieldSpec / FormReconstructionResult models
- _render_form_block / _form_dsl_escape / _run_form_reconstructor + tool
  wiring and token accounting in pipeline_viewer
- docs/reference/form-block.md spec + pipeline-phases updates
- 18 unit tests (renderer, escaping, has_forms composition, subagent wrapper)

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 docs/reference/form-block.md                  | 100 ++++++++
 docs/reference/pipeline-phases.md             |   5 +-
 src/agents/prompts/form_reconstruction.py     |  99 +++++++
 .../page_correction/content/has_forms.md      |  54 ++++
 src/agents/prompts/structure_analysis.py      |   7 +
 src/services/pipeline_viewer.py               | 208 +++++++++++++++
 src/services/pipeline_viewer_models.py        |  62 +++++
 .../unit/services/test_form_reconstruction.py | 241 ++++++++++++++++++
 8 files changed, 774 insertions(+), 2 deletions(-)
 create mode 100644 docs/reference/form-block.md
 create mode 100644 src/agents/prompts/form_reconstruction.py
 create mode 100644 src/agents/prompts/procedures/page_correction/content/has_forms.md
 create mode 100644 tests/unit/services/test_form_reconstruction.py

diff --git a/docs/reference/form-block.md b/docs/reference/form-block.md
new file mode 100644
index 0000000..01943db
--- /dev/null
+++ b/docs/reference/form-block.md
@@ -0,0 +1,100 @@
+# The `form` block
+
+When the pipeline finds a fillable form on a page, it does not emit raw inline
+HTML. Instead the `page_content` form subagent (see
+[pipeline-phases.md](pipeline-phases.md)) replaces the flattened form text with
+a single self-contained fenced **`form` block** — a small, composable DSL that
+describes the whole form. A downstream renderer (the viewer, a WordPress
+plugin, an Obsidian-style code-block processor) compiles the block into
+accessible form controls.
+
+This keeps the converted markdown clean and round-trippable: one block per form,
+trivially diffable, and validated by a deterministic renderer rather than
+trusting an LLM to emit correct HTML. The pattern is modelled on Obsidian custom
+code-block processors (e.g. Meta Bind input fields).
+
+> **Accessibility note:** the `form` block is an *intermediate representation*.
+> It is only accessible once a renderer turns it into labelled controls. Any
+> surface that ships the converted document to end users must run a `form`-block
+> renderer; raw, unrendered blocks are not accessible on their own.
+
+## Grammar
+
+````
+```form
+legend: <form title>            # optional, at most one, must be first
+- <type>[*] | <label>           # one field per line, in document order
+- <type>[*] | <label> | <opt>; <opt>; <opt>
+```
+````
+
+- **`legend:`** — optional form title, used as the rendered `<fieldset>`
+  `<legend>` / form heading. Omitted if the form has no overall title.
+- **Field lines** start with `- ` and have up to three `|`-separated columns:
+  1. `<type>` with an optional trailing `*` marking a **required** field.
+  2. `<label>` — the field's accessible label (the group prompt for grouped
+     types).
+  3. `<options>` — for `radio` / `multiselect` / `select` only:
+     semicolon-separated choice labels, in display order.
+- Fields appear in top-to-bottom page order.
+
+### Field types
+
+| Token | Control | Notes |
+|---|---|---|
+| `text` | single-line text input | name, email, short answer |
+| `textarea` | multi-line text input | comments, long answers |
+| `checkbox` | single checkbox | one yes/no statement; no options column |
+| `multiselect` | checkbox group | "select all that apply"; uses options |
+| `radio` | radio-button group | exactly one choice; uses options |
+| `select` | dropdown | uses options |
+| `date` | date input | |
+| `signature` | signature line | rendered as a labelled text field |
+
+### Escaping
+
+Labels and option text are sanitised by the renderer before they enter a block:
+newlines collapse to spaces, a literal `|` becomes `/`, and a literal `;`
+becomes `,`. Blocks therefore never contain a raw delimiter inside a value, and
+parsers can split on `|` and `;` without quoting.
+
+## Example
+
+A registration form flattened by Docling as:
+
+```
+Course Registration
+Full name: ____________________
+Date of birth: __/__/____
+Standing: ☐ Undergraduate ☐ Graduate
+Topics (choose any): ☐ AI ☐ Systems ☐ Theory
+☐ I confirm the information is accurate *
+```
+
+is rebuilt as:
+
+````
+```form
+legend: Course Registration
+- text* | Full name
+- date | Date of birth
+- radio* | Standing | Undergraduate; Graduate
+- multiselect | Topics (choose any) | AI; Systems; Theory
+- checkbox* | I confirm the information is accurate
+```
+````
+
+## Reference renderer
+
+A compliant renderer should produce, per field, a programmatically associated
+label and control:
+
+- `text` / `textarea` / `date` / `signature`: a `<label for>` bound to the
+  control by `id`.
+- `checkbox`: the control followed by its `<label for>`.
+- `radio` / `multiselect` / `select`: a `<fieldset>` with the label as
+  `<legend>`, one control per option (radios share a `name`).
+- Required fields carry `aria-required="true"` and a visible required marker.
+
+The pipeline guarantees a well-formed block; renderers should still skip
+unknown type tokens gracefully (render as `text`) so the format can grow.
diff --git a/docs/reference/pipeline-phases.md b/docs/reference/pipeline-phases.md
index 2db405f..3b808b3 100644
--- a/docs/reference/pipeline-phases.md
+++ b/docs/reference/pipeline-phases.md
@@ -10,9 +10,9 @@ The pipeline has **5 versioned conversion phases** plus a **PII Review** gate th
 |---|---|---|---|
 | **PII Review** (gate) | `pii_scan` | No | Runs Presidio against a text-only docling pass before full extraction. If findings exist, the streaming pipeline blocks on `session.pii_decision_event` until the user approves or denies via `POST /api/v1/pipeline/sessions/{sid}/pii-decision`. Denial aborts the pipeline. Can be opted out with `skip_pii_scan=true`. |
 | 1. **Extraction** | `docling`, `docling_ocr` (conditional) | No | PDF → markdown + page images via IBM Docling. `docling_ocr` only fires when the classifier flags a scanned document. |
-| 2. **Analysis** | `classification`, `structure` | Yes | `classification` tags the document as digital / scanned / malformed. `structure` identifies headings, footnotes, code blocks, per-page layout attributes. |
+| 2. **Analysis** | `classification`, `structure` | Yes | `classification` tags the document as digital / scanned / malformed. `structure` identifies headings, footnotes, code blocks, per-page layout attributes, and per-page content flags (`has_tables`, `has_lists`, `has_forms`, …) that gate the Translation subagents. |
 | 3. **Headings** | `heading_reconciliation`, `heading_levels` | Yes | `heading_reconciliation` reconciles per-page heading candidates against the global outline. `heading_levels` normalises the hierarchy (H1 → H2 → H3, no skips). |
-| 4. **Translation** | `page_content`, `code_blocks` | Yes | `page_content` does per-page accessibility corrections (invokes image / table / list subagents). `code_blocks` tags fenced blocks with detected programming language. |
+| 4. **Translation** | `page_content`, `code_blocks` | Yes | `page_content` does per-page accessibility corrections (invokes image / table / list / form subagents). `code_blocks` tags fenced blocks with detected programming language. |
 | 5. **Assembly** | `boundaries`, `cleanup` | Mixed | `boundaries` rejoins cross-page split content and relocates footnotes (AI). `cleanup` normalises whitespace and lints the markdown (deterministic). |
 
 The viewer also shows a dynamic **Review** stage that catches any orphan steps (`revision_*`, `feedback_*`, custom steps) not listed above.
@@ -46,6 +46,7 @@ Some main-agent tool calls delegate to specialist subagents:
 | `page_content` | Image describer | `ImageDescriptionResult` |
 | `page_content` | Table reconstructor | `TableReconstructionResult` |
 | `page_content` | List reconstructor | `ListReconstructionResult` |
+| `page_content` | Form reconstructor | `FormReconstructionResult` (rendered to a `form` block — see [form-block.md](form-block.md)) |
 | `boundaries` | Footnote relocator | (inline, no dedicated output model) |
 
 ## Versioning
diff --git a/src/agents/prompts/form_reconstruction.py b/src/agents/prompts/form_reconstruction.py
new file mode 100644
index 0000000..35e0a73
--- /dev/null
+++ b/src/agents/prompts/form_reconstruction.py
@@ -0,0 +1,99 @@
+"""System prompt and user message template for the form reconstruction subagent.
+
+Invoked as the ``reconstruct_form`` tool by the page-correction agent when the
+structure pass flagged the page with ``has_forms``. The subagent re-reads the
+form from the page image and returns a structured ``FormReconstructionResult``
+(legend + fields); a deterministic renderer turns that into a ``form`` block.
+"""
+
+FORM_RECONSTRUCTOR_SYSTEM_PROMPT = """\
+You are a form accessibility specialist. The page agent has found a form on \
+the page and handed you the page image (visual ground truth) plus the markdown \
+fragment Docling extracted for it. Your job is to read the form precisely and \
+return a clean, structured description of its fields so it can be rebuilt as an \
+accessible, navigable form.
+
+You report structure only. You do not write HTML and you do not edit markdown.
+
+## Identify the form
+
+- **legend**: the form's overall title or prompt, read from the image (e.g. \
+"Course Registration", "Consent"). If there is no clear overall title, leave \
+it empty.
+
+## Identify each field, top to bottom
+
+For every field a person is expected to fill in, report:
+
+- **field_type** — choose the most specific match:
+  - `text` — a single-line blank for a short answer (name, email, ID number).
+  - `textarea` — a large multi-line blank for long answers or comments.
+  - `checkbox` — ONE standalone box next to a single statement \
+("☐ I agree to the terms").
+  - `multiselect` — a group of checkboxes under one prompt where MORE THAN ONE \
+may be ticked ("Select all that apply").
+  - `radio` — a group of options under one prompt where EXACTLY ONE is chosen \
+("Gender: ☐ Female ☐ Male ☐ Other").
+  - `select` — a dropdown / choice list (often a box with a chevron).
+  - `date` — a blank specifically for a date ("__/__/____", "Date of birth").
+  - `signature` — a ruled signature line.
+- **label** — the field's accessible label, read from the IMAGE (the markdown \
+may carry OCR errors). For `radio`, `multiselect`, and `select`, this is the \
+GROUP prompt (e.g. "Marital status"), not an individual option. If a field has \
+no visible label, write a short, accurate one.
+- **options** — for `radio`, `multiselect`, and `select` only: the choice \
+labels, in the order shown. Empty for every other type.
+- **required** — true only if the field is visibly marked required (an \
+asterisk, the word "required", "must").
+
+## Rules
+
+- Distinguish `radio` (pick one) from `multiselect` (pick many) and `checkbox` \
+(a single yes/no) carefully — this is the most common mistake.
+- Read every label and option from the image. Never invent fields or options \
+that are not visible.
+- Report fields in the order they appear on the page, top to bottom.
+- If, on closer inspection, the region is not actually a fillable form (e.g. it \
+is a data table or a decorative rule), return an empty ``fields`` list and say \
+so in ``reasoning``.
+"""
+
+
+def build_form_user_message(
+    form_text: str,
+    surrounding_text: str,
+    page_number: int,
+) -> str:
+    """Build the text portion of the form reconstructor user message.
+
+    The page image is passed separately as a binary content part.
+
+    Args:
+        form_text: The markdown fragment the page agent identified as the form.
+        surrounding_text: A little markdown context around the form region.
+        page_number: 1-indexed page number, for logging/grounding.
+
+    Returns:
+        Text portion of the user message.
+    """
+    parts: list[str] = []
+    parts.append(f"## Form on page {page_number}")
+    parts.append("")
+    parts.append("### Extracted markdown for the form region")
+    parts.append("")
+    parts.append("```markdown")
+    parts.append(form_text)
+    parts.append("```")
+    parts.append("")
+    if surrounding_text.strip():
+        parts.append("### Surrounding context")
+        parts.append("")
+        parts.append("```markdown")
+        parts.append(surrounding_text)
+        parts.append("```")
+        parts.append("")
+    parts.append(
+        "The page image is attached. Read the form from the image (ground "
+        "truth) and return its legend and fields in top-to-bottom order."
+    )
+    return "\n".join(parts)
diff --git a/src/agents/prompts/procedures/page_correction/content/has_forms.md b/src/agents/prompts/procedures/page_correction/content/has_forms.md
new file mode 100644
index 0000000..0cc6b5d
--- /dev/null
+++ b/src/agents/prompts/procedures/page_correction/content/has_forms.md
@@ -0,0 +1,54 @@
+# Pages with Forms
+
+This page contains a form — fields a person is expected to fill in (labelled
+blanks, checkboxes, option groups, dropdowns, date blanks, signature lines).
+
+Docling renders forms as lossy plain text: a label followed by underscores, a
+stray `☐` or `[ ]`, option words run together, the field grouping lost
+entirely. That text is not accessible — a screen-reader user cannot tell it is
+a form, what the fields are, or which options belong together.
+
+## What to do
+
+Identify each contiguous form region in the page markdown, then call
+`reconstruct_form` with that text. The tool re-reads the form from the page
+image and returns a structured `form` block. Use `str_replace` to replace the
+original lossy form text with the returned block.
+
+Replace the whole region in one edit — do not leave half the form as raw
+underscores and half as a `form` block.
+
+## Verification checklist
+
+- **Field boundaries**: Each label + its blank is one field; don't merge two.
+- **Control type**: A single box is a `checkbox`; a "pick one" group is `radio`;
+  a "select all" group is `multiselect`; a chevroned box is `select`.
+- **Options**: Every option label in a group is captured, in order.
+- **Required**: Asterisks / "required" markers are preserved.
+
+## Tool
+
+- **`reconstruct_form(form_text, reasoning)`**: Pass the exact markdown text of
+  the form region and why it needs rebuilding. Returns a `form` block to apply
+  with `str_replace`.
+
+## Tool call example
+
+<example>
+<description>Rebuilding a registration form Docling flattened</description>
+<tool_call>
+reconstruct_form(
+  form_text="Name: ____________\nStatus: ☐ Single ☐ Married\n☐ I agree to the terms",
+  reasoning="Flattened form: a text field, a single-choice group, and a consent checkbox"
+)
+</tool_call>
+<follow_up>
+After receiving the form block, use str_replace:
+str_replace(
+  old_text="Name: ____________\nStatus: ☐ Single ☐ Married\n☐ I agree to the terms",
+  new_text="[form block from tool output]",
+  reasoning="Replaced flattened form text with structured accessible form block",
+  category="form_fix"
+)
+</follow_up>
+</example>
diff --git a/src/agents/prompts/structure_analysis.py b/src/agents/prompts/structure_analysis.py
index 078ae94..62a9f97 100644
--- a/src/agents/prompts/structure_analysis.py
+++ b/src/agents/prompts/structure_analysis.py
@@ -78,6 +78,13 @@
 - **has_lists** — True if the page contains bulleted lists, numbered lists, \
 or definition-style term/description pairs. Not single items that happen to \
 start with a dash.
+- **has_forms** — True if the page contains form fields a person is meant to \
+fill in: a label followed by a blank line/box to write in ("Name: \
+______"), checkboxes (☐, [ ]) next to statements, mutually-exclusive option \
+sets, dropdowns, date blanks ("__/__/____"), or signature lines. Do NOT set \
+this for ordinary tables, rules used for emphasis, or table borders — only \
+genuine fillable fields. When in doubt, a cluster of labelled blanks the \
+reader would complete is a form.
 - **has_equations** — True if the page contains mathematical equations, \
 either display (centered) or complex inline equations.
 - **is_scanned** — True if the page appears to be a scan of a physical \
diff --git a/src/services/pipeline_viewer.py b/src/services/pipeline_viewer.py
index 10188ee..0b75a1e 100644
--- a/src/services/pipeline_viewer.py
+++ b/src/services/pipeline_viewer.py
@@ -26,6 +26,7 @@
     DocumentChange,
     FigureData,
     FootnoteInfo,
+    FormReconstructionResult,
     HeadingReconciliationOutput,
     ImageDescriptionResult,
     LayoutType,
@@ -111,6 +112,11 @@ def _compose_page_prompt(attrs: PageAttributes) -> str:
         if lst:
             fragments.append(lst)
 
+    if attrs.has_forms:
+        frm = _load_fragment("content/has_forms")
+        if frm:
+            fragments.append(frm)
+
     if attrs.has_equations:
         eq = _load_fragment("content/has_equations")
         if eq:
@@ -273,6 +279,56 @@ def _apply_code_block_fence(
     )
 
 
+def _form_dsl_escape(text: str) -> str:
+    """Make a label/option safe to embed in a ``form`` block line.
+
+    The DSL is line- and delimiter-oriented: ``|`` separates a field's
+    columns and ``;`` separates options, so those characters (and newlines)
+    are replaced with safe equivalents rather than allowed to break parsing.
+    """
+    return (
+        " ".join(text.split())  # collapse newlines/runs of whitespace
+        .replace("|", "/")
+        .replace(";", ",")
+        .strip()
+    )
+
+
+def _render_form_block(result: FormReconstructionResult) -> str:
+    """Render a reconstructed form as a composable ``form`` code block.
+
+    Grammar (one self-contained fenced block per form)::
+
+        ```form
+        legend: <form title>
+        - <type>[*] | <label>[ | opt1; opt2; ...]
+        ```
+
+    ``<type>`` is the field-type DSL token, ``*`` marks a required field, and
+    options (semicolon-separated) appear only for radio/multiselect/select.
+    A downstream renderer compiles this to accessible controls; see
+    ``docs/reference/form-block.md``.
+    """
+    lines = ["```form"]
+    legend = _form_dsl_escape(result.legend)
+    if legend:
+        lines.append(f"legend: {legend}")
+
+    for field in result.fields:
+        token = field.field_type.value
+        required = "*" if field.required else ""
+        label = _form_dsl_escape(field.label) or "Field"
+        line = f"- {token}{required} | {label}"
+        if field.options:
+            opts = "; ".join(_form_dsl_escape(o) for o in field.options if o.strip())
+            if opts:
+                line += f" | {opts}"
+        lines.append(line)
+
+    lines.append("```")
+    return "\n".join(lines)
+
+
 def _replace_image_placeholders(
     markdown: str,
     figures: list[FigureData],
@@ -2023,6 +2079,86 @@ async def _run_list_reconstructor(
             f"corrected version:\n\n{result.reconstructed_content}"
         )
 
+    # ------------------------------------------------------------------
+    # Form reconstruction subagent
+    # ------------------------------------------------------------------
+
+    async def _run_form_reconstructor(
+        self,
+        form_text: str,
+        surrounding_text: str,
+        page_image_b64: str | None,
+        page_number: int,
+        update_tokens: Any,
+    ) -> str:
+        """Run the form reconstruction vision subagent.
+
+        Mirrors _run_list_reconstructor: a one-shot PydanticAI agent with
+        structured output reads the form from the page image, then a
+        deterministic renderer turns the result into a ``form`` block that the
+        page agent applies with str_replace.
+        """
+        from pydantic_ai import Agent
+        from pydantic_ai.messages import BinaryContent
+
+        from ..agents.model_factory import get_model_for_tier
+        from ..agents.model_tiers import ModelTier
+        from ..agents.prompts.form_reconstruction import (
+            FORM_RECONSTRUCTOR_SYSTEM_PROMPT,
+            build_form_user_message,
+        )
+
+        user_parts: list[Any] = []
+        if page_image_b64:
+            user_parts.append(
+                BinaryContent(
+                    data=base64.b64decode(page_image_b64),
+                    media_type="image/png",
+                )
+            )
+        user_parts.append(
+            build_form_user_message(
+                form_text=form_text,
+                surrounding_text=surrounding_text,
+                page_number=page_number,
+            )
+        )
+
+        model = get_model_for_tier(ModelTier.EFFICIENT)
+        reconstructor_agent: Agent[None, FormReconstructionResult] = Agent(
+            model=model,
+            output_type=FormReconstructionResult,
+            system_prompt=FORM_RECONSTRUCTOR_SYSTEM_PROMPT,
+        )
+
+        try:
+            agent_result = await reconstructor_agent.run(user_parts)
+            usage = agent_result.usage()
+            update_tokens(usage.request_tokens or 0, usage.response_tokens or 0)
+        except Exception as e:
+            logger.warning(f"Form reconstructor failed on page {page_number}: {e}")
+            return (
+                f"Form reconstruction failed: {e}. "
+                f"Use str_replace to fix the form manually if needed."
+            )
+
+        result = agent_result.output
+
+        if not result.fields:
+            return (
+                "No fillable fields were found in that region — it may be a "
+                f"table or decorative rule. Reason: {result.reasoning}. "
+                "Leave it as-is or fix it with str_replace if needed."
+            )
+
+        form_block = _render_form_block(result)
+        return (
+            f"Reconstructed the form as a `form` block "
+            f"({len(result.fields)} field(s)).\n"
+            f"Use str_replace to replace the original form text with this "
+            f"block exactly:\n\n{form_block}"
+        )
+
     # ------------------------------------------------------------------
     # Phase 2 — Page Content Corrections (parallel, semaphore-limited)
     # ------------------------------------------------------------------
@@ -2106,6 +2242,8 @@ async def _process_page(page_num: int) -> PageCorrectionResult:
         total_table_reconstructor_output = 0
         total_list_reconstructor_input = 0
         total_list_reconstructor_output = 0
+        total_form_reconstructor_input = 0
+        total_form_reconstructor_output = 0
         for i, pr in enumerate(page_results):
             page_num = pages_to_process[i]
             page_key = str(page_num)
@@ -2127,6 +2265,8 @@ async def _process_page(page_num: int) -> PageCorrectionResult:
             total_table_reconstructor_output += pr.table_reconstructor_output_tokens
             total_list_reconstructor_input += pr.list_reconstructor_input_tokens
             total_list_reconstructor_output += pr.list_reconstructor_output_tokens
+            total_form_reconstructor_input += pr.form_reconstructor_input_tokens
+            total_form_reconstructor_output += pr.form_reconstructor_output_tokens
 
         # Write v1
         result.page_markdowns["v1"] = corrected_mds
@@ -2143,12 +2283,14 @@ async def _process_page(page_num: int) -> PageCorrectionResult:
             + total_describer_input
             + total_table_reconstructor_input
             + total_list_reconstructor_input
+            + total_form_reconstructor_input
         )
         combined_output = (
             total_output_tokens
             + total_describer_output
             + total_table_reconstructor_output
             + total_list_reconstructor_output
+            + total_form_reconstructor_output
         )
         cost_cents = calculate_estimated_cost(combined_input, combined_output)
 
@@ -2172,6 +2314,8 @@ async def _process_page(page_num: int) -> PageCorrectionResult:
                     "table_reconstructor_output_tokens": total_table_reconstructor_output,
                     "list_reconstructor_input_tokens": total_list_reconstructor_input,
                     "list_reconstructor_output_tokens": total_list_reconstructor_output,
+                    "form_reconstructor_input_tokens": total_form_reconstructor_input,
+                    "form_reconstructor_output_tokens": total_form_reconstructor_output,
                 },
                 input_tokens=combined_input,
                 output_tokens=combined_output,
@@ -2283,6 +2427,16 @@ async def _run_page_agent(
             page_attrs and page_attrs.has_lists
         )
 
+        # ------------------------------------------------------------------
+        # reconstruct_form tool: closure state
+        # ------------------------------------------------------------------
+        max_form_reconstruct_calls = 5
+        form_reconstructor_input_tokens = 0
+        form_reconstructor_output_tokens = 0
+        form_reconstruct_call_count = 0
+
+        enable_form_reconstruct = bool(page_attrs and page_attrs.has_forms)
+
         # Create agent with tools
         model = get_model_for_tier(ModelTier.EFFICIENT)
         agent: Agent[None, None] = Agent(
@@ -2494,6 +2648,58 @@ def _update_list_tokens(inp: int, out: int) -> None:
                 list_reconstructor_input_tokens += inp
                 list_reconstructor_output_tokens += out
 
+        # ------------------------------------------------------------------
+        # Conditionally register reconstruct_form tool
+        # ------------------------------------------------------------------
+        if enable_form_reconstruct:
+            @agent.tool_plain
+            async def reconstruct_form(form_text: str, reasoning: str) -> str:
+                """Rebuild a form region as an accessible ``form`` block.
+
+                Args:
+                    form_text: The exact markdown text of the form region to
+                        rebuild. Include enough text to uniquely identify it
+                        in the page markdown.
+                    reasoning: Why reconstruction is needed (e.g. "labels and
+                        checkboxes flattened into plain text").
+                """
+                nonlocal form_reconstruct_call_count
+
+                if form_reconstruct_call_count >= max_form_reconstruct_calls:
+                    return (
+                        f"ERROR: Maximum reconstruct_form calls "
+                        f"({max_form_reconstruct_calls}) reached. "
+                        f"Fix remaining forms with str_replace."
+                    )
+
+                form_reconstruct_call_count += 1
+
+                if form_text not in current_markdown:
+                    return (
+                        f"ERROR: form_text not found in page markdown. "
+                        f"Pass the exact text from the current markdown. "
+                        f"Current markdown:\n---\n{current_markdown}\n---"
+                    )
+
+                idx = current_markdown.find(form_text)
+                start = max(0, idx - 200)
+                end = min(len(current_markdown), idx + len(form_text) + 200)
+                surrounding = current_markdown[start:end]
+
+                return await self._run_form_reconstructor(
+                    form_text=form_text,
+                    surrounding_text=surrounding,
+                    page_image_b64=page_image_b64,
+                    page_number=page_num,
+                    update_tokens=lambda inp, out: _update_form_tokens(inp, out),
+                )
+
+            def _update_form_tokens(inp: int, out: int) -> None:
+                nonlocal form_reconstructor_input_tokens
+                nonlocal form_reconstructor_output_tokens
+                form_reconstructor_input_tokens += inp
+                form_reconstructor_output_tokens += out
+
         # ------------------------------------------------------------------
         # Conditionally register rewrite_page tool (create mode only)
         # ------------------------------------------------------------------
@@ -2590,6 +2796,8 @@ def rewrite_page(new_markdown: str, reasoning: str) -> str:
             table_reconstructor_output_tokens=table_reconstructor_output_tokens,
             list_reconstructor_input_tokens=list_reconstructor_input_tokens,
             list_reconstructor_output_tokens=list_reconstructor_output_tokens,
+            form_reconstructor_input_tokens=form_reconstructor_input_tokens,
+            form_reconstructor_output_tokens=form_reconstructor_output_tokens,
         )
 
     # ------------------------------------------------------------------
diff --git a/src/services/pipeline_viewer_models.py b/src/services/pipeline_viewer_models.py
index 558f73c..fbc5d62 100644
--- a/src/services/pipeline_viewer_models.py
+++ b/src/services/pipeline_viewer_models.py
@@ -34,6 +34,7 @@ class PageAttributes(BaseModel):
     has_tables: bool = False
     has_lists: bool = False
     has_equations: bool = False
+    has_forms: bool = False
     is_scanned: bool = False
 
 
@@ -251,6 +252,61 @@ class ListReconstructionResult(BaseModel):
     """Why this reconstruction was chosen."""
 
 
+class FormFieldType(str, Enum):
+    """Type of form control, mapped to a ``form`` block DSL token.
+
+    The DSL token (the value here) is what appears in the rendered
+    ``form`` code block; a downstream renderer turns each into the
+    appropriate accessible control.
+    """
+
+    TEXT = "text"
+    TEXTAREA = "textarea"
+    CHECKBOX = "checkbox"  # single standalone checkbox
+    MULTISELECT = "multiselect"  # group of checkboxes (more than one allowed)
+    RADIO = "radio"  # mutually-exclusive option group
+    SELECT = "select"  # dropdown / choice list
+    DATE = "date"
+    SIGNATURE = "signature"
+
+
+class FormFieldSpec(BaseModel):
+    """One field in a detected form, read from the page image."""
+
+    field_type: FormFieldType
+    """The kind of control this field represents."""
+
+    label: str
+    """Accessible label, read from the IMAGE. For grouped fields
+    (radio / multiselect / select) this is the group prompt."""
+
+    options: list[str] = Field(default_factory=list)
+    """Choice labels for radio / multiselect / select. Empty otherwise."""
+
+    required: bool = False
+    """True if the field is visibly marked required (asterisk, "required")."""
+
+
+class FormReconstructionResult(BaseModel):
+    """Result from the form reconstruction subagent.
+
+    The deterministic renderer turns this into a ``form`` code block; the
+    page agent then splices that block in via ``str_replace``.
+    """
+
+    legend: str = ""
+    """The form's overall title/prompt, used as the block legend. May be empty."""
+
+    fields: list[FormFieldSpec] = Field(default_factory=list)
+    """The fields that make up the form, in top-to-bottom order."""
+
+    confidence: str = "high"
+    """Confidence level: high, medium, or low."""
+
+    reasoning: str = ""
+    """How the fields and types were identified from the image."""
+
+
 class SectionCorrectionResult(BaseModel):
     """What a section correction agent returns."""
 
@@ -310,6 +366,12 @@ class PageCorrectionResult(BaseModel):
     list_reconstructor_output_tokens: int = 0
     """Output tokens from list reconstructor subagent calls."""
 
+    form_reconstructor_input_tokens: int = 0
+    """Input tokens consumed by form reconstructor subagent calls."""
+
+    form_reconstructor_output_tokens: int = 0
+    """Output tokens from form reconstructor subagent calls."""
+
 
 # ---------------------------------------------------------------------------
 # Phase 3 — Cross-page models
diff --git a/tests/unit/services/test_form_reconstruction.py b/tests/unit/services/test_form_reconstruction.py
new file mode 100644
index 0000000..d267638
--- /dev/null
+++ b/tests/unit/services/test_form_reconstruction.py
@@ -0,0 +1,241 @@
+"""Unit tests for form reconstruction.
+
+Covers the deterministic ``form`` block renderer (`_render_form_block` /
+`_form_dsl_escape`), the `_run_form_reconstructor` subagent wrapper (model
+mocked), and that the `has_forms` page flag composes the form procedure into
+the page prompt.
+"""
+
+from __future__ import annotations
+
+from unittest.mock import AsyncMock, MagicMock, patch
+
+import pytest
+from src.services.pipeline_viewer import (
+    PipelineViewerService,
+    _compose_page_prompt,
+    _form_dsl_escape,
+    _render_form_block,
+)
+from src.services.pipeline_viewer_models import (
+    FormFieldSpec,
+    FormFieldType,
+    FormReconstructionResult,
+    LayoutType,
+    PageAttributes,
+)
+
+pytestmark = pytest.mark.unit
+
+
+# ---------------------------------------------------------------------------
+# _render_form_block — DSL rendering
+# ---------------------------------------------------------------------------
+
+
+class TestRenderFormBlock:
+    def test_fenced_with_form_language(self):
+        block = _render_form_block(FormReconstructionResult(legend="", fields=[]))
+        assert block.startswith("```form\n")
+        assert block.endswith("\n```")
+
+    def test_legend_emitted_when_present(self):
+        result = FormReconstructionResult(legend="Course Registration", fields=[])
+        block = _render_form_block(result)
+        assert "legend: Course Registration" in block
+
+    def test_legend_omitted_when_empty(self):
+        block = _render_form_block(FormReconstructionResult(legend="", fields=[]))
+        assert "legend:" not in block
+
+    def test_text_field_line(self):
+        result = FormReconstructionResult(fields=[FormFieldSpec(field_type=FormFieldType.TEXT, label="Full name")])
+        assert "- text | Full name" in _render_form_block(result)
+
+    def test_required_marker(self):
+        result = FormReconstructionResult(
+            fields=[FormFieldSpec(field_type=FormFieldType.TEXT, label="Email", required=True)]
+        )
+        assert "- text* | Email" in _render_form_block(result)
+
+    def test_radio_with_options(self):
+        result = FormReconstructionResult(
+            fields=[
+                FormFieldSpec(
+                    field_type=FormFieldType.RADIO,
+                    label="Standing",
+                    options=["Undergraduate", "Graduate"],
+                    required=True,
+                )
+            ]
+        )
+        assert "- radio* | Standing | Undergraduate; Graduate" in _render_form_block(result)
+
+    def test_multiselect_and_select_tokens(self):
+        result = FormReconstructionResult(
+            fields=[
+                FormFieldSpec(
+                    field_type=FormFieldType.MULTISELECT,
+                    label="Topics",
+                    options=["AI", "Systems"],
+                ),
+                FormFieldSpec(
+                    field_type=FormFieldType.SELECT,
+                    label="State",
+                    options=["IL", "IA"],
+                ),
+            ]
+        )
+        block = _render_form_block(result)
+        assert "- multiselect | Topics | AI; Systems" in block
+        assert "- select | State | IL; IA" in block
+
+    def test_checkbox_has_no_options_column(self):
+        result = FormReconstructionResult(
+            fields=[FormFieldSpec(field_type=FormFieldType.CHECKBOX, label="I agree", required=True)]
+        )
+        line = [line_ for line_ in _render_form_block(result).splitlines() if "I agree" in line_][0]
+        assert line == "- checkbox* | I agree"
+
+    def test_empty_label_falls_back(self):
+        result = FormReconstructionResult(fields=[FormFieldSpec(field_type=FormFieldType.TEXT, label="")])
+        assert "- text | Field" in _render_form_block(result)
+
+
+# ---------------------------------------------------------------------------
+# _form_dsl_escape — delimiter safety
+# ---------------------------------------------------------------------------
+
+
+class TestFormDslEscape:
+    def test_pipe_replaced(self):
+        assert _form_dsl_escape("a | b") == "a / b"
+
+    def test_semicolon_replaced(self):
+        assert _form_dsl_escape("a; b") == "a, b"
+
+    def test_newlines_collapsed(self):
+        assert _form_dsl_escape("line one\nline two") == "line one line two"
+
+    def test_escaping_applied_in_block(self):
+        result = FormReconstructionResult(
+            fields=[
+                FormFieldSpec(
+                    field_type=FormFieldType.RADIO,
+                    label="Pick | one",
+                    options=["a; b", "c"],
+                )
+            ]
+        )
+        block = _render_form_block(result)
+        assert "Pick / one" in block
+        assert "a, b; c" in block
+        # the only delimiters left are the structural ones
+        field_line = [line for line in block.splitlines() if line.startswith("- ")][0]
+        assert field_line.count(" | ") == 2
+
+
+# ---------------------------------------------------------------------------
+# has_forms composes the form procedure into the page prompt
+# ---------------------------------------------------------------------------
+
+
+class TestHasFormsProcedure:
+    def test_form_fragment_loaded_when_has_forms(self):
+        attrs = PageAttributes(layout=LayoutType.SINGLE_COLUMN, has_forms=True)
+        prompt = _compose_page_prompt(attrs)
+        assert "reconstruct_form" in prompt
+
+    def test_form_fragment_absent_without_flag(self):
+        attrs = PageAttributes(layout=LayoutType.SINGLE_COLUMN, has_forms=False)
+        prompt = _compose_page_prompt(attrs)
+        assert "reconstruct_form" not in prompt
+
+
+# ---------------------------------------------------------------------------
+# _run_form_reconstructor — subagent wrapper
+# ---------------------------------------------------------------------------
+
+
+@pytest.fixture
+def service():
+    return PipelineViewerService()
+
+
+def _patched_run(output: FormReconstructionResult):
+    """Context managers patching the deferred pydantic_ai imports + model."""
+    mock_agent = MagicMock()
+    mock_run_result = MagicMock()
+    mock_run_result.output = output
+    mock_run_result.usage.return_value = MagicMock(request_tokens=12, response_tokens=7)
+    mock_agent.run = AsyncMock(return_value=mock_run_result)
+    return mock_agent
+
+
+class TestRunFormReconstructor:
+    @pytest.mark.asyncio
+    async def test_returns_str_replace_instruction_with_block(self, service):
+        output = FormReconstructionResult(
+            legend="Consent",
+            fields=[FormFieldSpec(field_type=FormFieldType.CHECKBOX, label="I agree", required=True)],
+        )
+        tokens = []
+        with (
+            patch("pydantic_ai.Agent", return_value=_patched_run(output)),
+            patch("pydantic_ai.models.bedrock.BedrockConverseModel"),
+            patch("pydantic_ai.messages.BinaryContent"),
+            patch("src.agents.model_factory.get_model_for_tier", return_value=MagicMock()),
+        ):
+            msg = await service._run_form_reconstructor(
+                form_text="☐ I agree",
+                surrounding_text="",
+                page_image_b64=None,
+                page_number=1,
+                update_tokens=lambda i, o: tokens.append((i, o)),
+            )
+
+        assert "```form" in msg
+        assert "legend: Consent" in msg
+        assert "- checkbox* | I agree" in msg
+        assert "str_replace" in msg
+        assert tokens == [(12, 7)]
+
+    @pytest.mark.asyncio
+    async def test_empty_fields_reports_not_a_form(self, service):
+        output = FormReconstructionResult(fields=[], reasoning="This region is a data table, not a form.")
+        with (
+            patch("pydantic_ai.Agent", return_value=_patched_run(output)),
+            patch("pydantic_ai.models.bedrock.BedrockConverseModel"),
+            patch("pydantic_ai.messages.BinaryContent"),
+            patch("src.agents.model_factory.get_model_for_tier", return_value=MagicMock()),
+        ):
+            msg = await service._run_form_reconstructor(
+                form_text="| a | b |",
+                surrounding_text="",
+                page_image_b64=None,
+                page_number=2,
+                update_tokens=lambda i, o: None,
+            )
+
+        assert "```form" not in msg
+        assert "No fillable fields" in msg
+
+    @pytest.mark.asyncio
+    async def test_subagent_failure_returns_graceful_message(self, service):
+        mock_agent = MagicMock()
+        mock_agent.run = AsyncMock(side_effect=RuntimeError("LLM error"))
+        with (
+            patch("pydantic_ai.Agent", return_value=mock_agent),
+            patch("pydantic_ai.models.bedrock.BedrockConverseModel"),
+            patch("pydantic_ai.messages.BinaryContent"),
+            patch("src.agents.model_factory.get_model_for_tier", return_value=MagicMock()),
+        ):
+            msg = await service._run_form_reconstructor(
+                form_text="Name: ____",
+                surrounding_text="",
+                page_image_b64=None,
+                page_number=3,
+                update_tokens=lambda i, o: None,
+            )
+
+        assert "Form reconstruction failed" in msg

From 0ba77f6e66412eb0b7b9aafc45f6072b727fa2bc Mon Sep 17 00:00:00 2001
From: Blake Bertuccelli-Booth <46652+bbertucc@users.noreply.github.com>
Date: Thu, 21 May 2026 16:44:50 -0700
Subject: [PATCH 2/7] =?UTF-8?q?feat(pipeline):=20form=5Ffields=20step=20?=
 =?UTF-8?q?=E2=86=92=20guaranteed=20accessible=20HTML=20on=20form=20pages?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Reworks form handling from the agent-optional `reconstruct_form` tool (which
the page agent skipped) + `form` DSL block into a dedicated, guaranteed step
that emits accessible HTML — the visible, standalone output users actually
need.

Why the old approach failed in practice: calling `reconstruct_form` was the
page agent's discretion, and on a real form it just made plain str_replace
edits and never invoked the tool; even if it had, the `form` block only
renders as HTML through a viewer plugin that doesn't exist yet.

What changed:
- `_step_form_fields`: a dedicated Translation step (after code_blocks) that
  always runs on form pages — no agent discretion. For each form page a vision
  agent reads the image + markdown and returns fields; a deterministic renderer
  injects accessible HTML (<label for>/<input>, <fieldset>/<legend> for option
  groups, aria-required) by replacing each field's anchor text.
- Robust detection: a page is processed when the doc is a form
  (classifier AcroForm widget count > 0, any has_forms page, or any form
  signal) OR the page itself is flagged/shows signals. This is the multi-page
  fix — Docling drops field text on later pages, so document-level detection
  scans every page (vision agent returns nothing for non-form pages).
- `_page_has_form_signals`: deterministic scan for long underline runs and
  checkbox glyphs.
- structure prompt: has_forms keys explicitly on long underlines/checkboxes
  and multi-page forms.
- has_forms page fragment now tells the page agent to leave form fields
  untouched (a dedicated step handles them).
- pdf_classifier: AcroForm PDFs are a WARNING, not a hard error, so forms
  reach the pipeline (XFA still blocked).
- Removed the `form` DSL block, its renderer/subagent/tool, and form-block.md.
- Viewer + pipeline-phases updated for the form_fields step.

Verified on the DOT Service Animal form (4 pp, 24 AcroForm fields): all pages
scanned, page 1 → 21 accessible label+input controls; instruction pages
correctly yield none. 22 unit tests.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 .../components/pipeline-viewer/StageTabs.tsx  |   2 +-
 clients/viewer/src/types/pipeline-viewer.ts   |   2 +-
 docs/reference/form-block.md                  | 100 ----
 docs/reference/pipeline-phases.md             |  10 +-
 src/agents/prompts/form_fields.py             | 101 ++++
 src/agents/prompts/form_reconstruction.py     |  99 ----
 .../page_correction/content/has_forms.md      |  59 +--
 src/agents/prompts/structure_analysis.py      |  14 +-
 src/services/pdf_classifier.py                |  13 +-
 src/services/pipeline_viewer.py               | 430 +++++++++++-------
 src/services/pipeline_viewer_models.py        |  93 ++--
 tests/unit/services/test_form_fields.py       | 334 ++++++++++++++
 .../unit/services/test_form_reconstruction.py | 241 ----------
 tests/unit/services/test_pdf_classifier.py    |  12 +-
 14 files changed, 796 insertions(+), 714 deletions(-)
 delete mode 100644 docs/reference/form-block.md
 create mode 100644 src/agents/prompts/form_fields.py
 delete mode 100644 src/agents/prompts/form_reconstruction.py
 create mode 100644 tests/unit/services/test_form_fields.py
 delete mode 100644 tests/unit/services/test_form_reconstruction.py

diff --git a/clients/viewer/src/components/pipeline-viewer/StageTabs.tsx b/clients/viewer/src/components/pipeline-viewer/StageTabs.tsx
index d2bf4dc..baf50e5 100644
--- a/clients/viewer/src/components/pipeline-viewer/StageTabs.tsx
+++ b/clients/viewer/src/components/pipeline-viewer/StageTabs.tsx
@@ -141,7 +141,7 @@ function isProcessingInStage(
     extraction: ['Docling Extraction', 'OCR Re-extraction', 'Extraction'],
     analysis: ['PDF Classification', 'Structure Analysis'],
     headings: ['Heading Levels', 'Heading Reconciliation'],
-    translation: ['Page Content Corrections', 'Code Block Languages'],
+    translation: ['Page Content Corrections', 'Code Block Languages', 'Form Fields'],
     assembly: ['Cross-Page Fixes', 'Final Cleanup'],
   };
   const names = nameMap[stage.name];
diff --git a/clients/viewer/src/types/pipeline-viewer.ts b/clients/viewer/src/types/pipeline-viewer.ts
index e539880..eda1baf 100644
--- a/clients/viewer/src/types/pipeline-viewer.ts
+++ b/clients/viewer/src/types/pipeline-viewer.ts
@@ -45,7 +45,7 @@ export const PIPELINE_STAGES: StageDefinition[] = [
   { name: 'extraction',  label: 'Extraction',   steps: ['docling', 'docling_ocr'] },
   { name: 'analysis',    label: 'Analysis',      steps: ['classification', 'structure'] },
   { name: 'headings',    label: 'Headings',      steps: ['heading_levels', 'heading_reconciliation'] },
-  { name: 'translation', label: 'Translation',   steps: ['page_content', 'code_blocks'] },
+  { name: 'translation', label: 'Translation',   steps: ['page_content', 'code_blocks', 'form_fields'] },
   { name: 'assembly',    label: 'Assembly',       steps: ['boundaries', 'cleanup'] },
 ];
 
diff --git a/docs/reference/form-block.md b/docs/reference/form-block.md
deleted file mode 100644
index 01943db..0000000
--- a/docs/reference/form-block.md
+++ /dev/null
@@ -1,100 +0,0 @@
-# The `form` block
-
-When the pipeline finds a fillable form on a page, it does not emit raw inline
-HTML. Instead the `page_content` form subagent (see
-[pipeline-phases.md](pipeline-phases.md)) replaces the flattened form text with
-a single self-contained fenced **`form` block** — a small, composable DSL that
-describes the whole form. A downstream renderer (the viewer, a WordPress
-plugin, an Obsidian-style code-block processor) compiles the block into
-accessible form controls.
-
-This keeps the converted markdown clean and round-trippable: one block per form,
-trivially diffable, and validated by a deterministic renderer rather than
-trusting an LLM to emit correct HTML. The pattern is modelled on Obsidian custom
-code-block processors (e.g. Meta Bind input fields).
-
-> **Accessibility note:** the `form` block is an *intermediate representation*.
-> It is only accessible once a renderer turns it into labelled controls. Any
-> surface that ships the converted document to end users must run a `form`-block
-> renderer; raw, unrendered blocks are not accessible on their own.
-
-## Grammar
-
-````
-```form
-legend: <form title>            # optional, at most one, must be first
-- <type>[*] | <label>           # one field per line, in document order
-- <type>[*] | <label> | <opt>; <opt>; <opt>
-```
-````
-
-- **`legend:`** — optional form title, used as the rendered `<fieldset>`
-  `<legend>` / form heading. Omitted if the form has no overall title.
-- **Field lines** start with `- ` and have up to three `|`-separated columns:
-  1. `<type>` with an optional trailing `*` marking a **required** field.
-  2. `<label>` — the field's accessible label (the group prompt for grouped
-     types).
-  3. `<options>` — for `radio` / `multiselect` / `select` only:
-     semicolon-separated choice labels, in display order.
-- Fields appear in top-to-bottom page order.
-
-### Field types
-
-| Token | Control | Notes |
-|---|---|---|
-| `text` | single-line text input | name, email, short answer |
-| `textarea` | multi-line text input | comments, long answers |
-| `checkbox` | single checkbox | one yes/no statement; no options column |
-| `multiselect` | checkbox group | "select all that apply"; uses options |
-| `radio` | radio-button group | exactly one choice; uses options |
-| `select` | dropdown | uses options |
-| `date` | date input | |
-| `signature` | signature line | rendered as a labelled text field |
-
-### Escaping
-
-Labels and option text are sanitised by the renderer before they enter a block:
-newlines collapse to spaces, a literal `|` becomes `/`, and a literal `;`
-becomes `,`. Blocks therefore never contain a raw delimiter inside a value, and
-parsers can split on `|` and `;` without quoting.
-
-## Example
-
-A registration form flattened by Docling as:
-
-```
-Course Registration
-Full name: ____________________
-Date of birth: __/__/____
-Standing: ☐ Undergraduate ☐ Graduate
-Topics (choose any): ☐ AI ☐ Systems ☐ Theory
-☐ I confirm the information is accurate *
-```
-
-is rebuilt as:
-
-````
-```form
-legend: Course Registration
-- text* | Full name
-- date | Date of birth
-- radio* | Standing | Undergraduate; Graduate
-- multiselect | Topics (choose any) | AI; Systems; Theory
-- checkbox* | I confirm the information is accurate
-```
-````
-
-## Reference renderer
-
-A compliant renderer should produce, per field, a programmatically associated
-label and control:
-
-- `text` / `textarea` / `date` / `signature`: a `<label for>` bound to the
-  control by `id`.
-- `checkbox`: the control followed by its `<label for>`.
-- `radio` / `multiselect` / `select`: a `<fieldset>` with the label as
-  `<legend>`, one control per option (radios share a `name`).
-- Required fields carry `aria-required="true"` and a visible required marker.
-
-The pipeline guarantees a well-formed block; renderers should still skip
-unknown type tokens gracefully (render as `text`) so the format can grow.
diff --git a/docs/reference/pipeline-phases.md b/docs/reference/pipeline-phases.md
index 3b808b3..cc03d22 100644
--- a/docs/reference/pipeline-phases.md
+++ b/docs/reference/pipeline-phases.md
@@ -10,16 +10,16 @@ The pipeline has **5 versioned conversion phases** plus a **PII Review** gate th
 |---|---|---|---|
 | **PII Review** (gate) | `pii_scan` | No | Runs Presidio against a text-only docling pass before full extraction. If findings exist, the streaming pipeline blocks on `session.pii_decision_event` until the user approves or denies via `POST /api/v1/pipeline/sessions/{sid}/pii-decision`. Denial aborts the pipeline. Can be opted out with `skip_pii_scan=true`. |
 | 1. **Extraction** | `docling`, `docling_ocr` (conditional) | No | PDF → markdown + page images via IBM Docling. `docling_ocr` only fires when the classifier flags a scanned document. |
-| 2. **Analysis** | `classification`, `structure` | Yes | `classification` tags the document as digital / scanned / malformed. `structure` identifies headings, footnotes, code blocks, per-page layout attributes, and per-page content flags (`has_tables`, `has_lists`, `has_forms`, …) that gate the Translation subagents. |
+| 2. **Analysis** | `classification`, `structure` | Yes | `classification` tags the document as digital / scanned / malformed. `structure` identifies headings, footnotes, code blocks, per-page layout attributes, and per-page content flags (`has_tables`, `has_lists`, `has_forms`, …) that gate Translation work. |
 | 3. **Headings** | `heading_reconciliation`, `heading_levels` | Yes | `heading_reconciliation` reconciles per-page heading candidates against the global outline. `heading_levels` normalises the hierarchy (H1 → H2 → H3, no skips). |
-| 4. **Translation** | `page_content`, `code_blocks` | Yes | `page_content` does per-page accessibility corrections (invokes image / table / list / form subagents). `code_blocks` tags fenced blocks with detected programming language. |
+| 4. **Translation** | `page_content`, `code_blocks`, `form_fields` | Yes | `page_content` does per-page accessibility corrections (invokes image / table / list subagents). `code_blocks` tags fenced blocks with detected programming language. `form_fields` runs on every form page (structure `has_forms` or a deterministic underline/checkbox scan) and converts detected fields into accessible HTML (`<fieldset>`/`<label>`/`<input>`). |
 | 5. **Assembly** | `boundaries`, `cleanup` | Mixed | `boundaries` rejoins cross-page split content and relocates footnotes (AI). `cleanup` normalises whitespace and lints the markdown (deterministic). |
 
 The viewer also shows a dynamic **Review** stage that catches any orphan steps (`revision_*`, `feedback_*`, custom steps) not listed above.
 
 ## Internal step → `_step_*` method map
 
-Nine methods in `src/services/pipeline_viewer.py`, plus `pii_scan` which runs inline in `src/api/pipeline_viewer.py` (no `_step_*` method — it's pre-extraction gate logic, not a PipelineViewerService method):
+Ten methods in `src/services/pipeline_viewer.py`, plus `pii_scan` which runs inline in `src/api/pipeline_viewer.py` (no `_step_*` method — it's pre-extraction gate logic, not a PipelineViewerService method):
 
 | Step name | Method | Phase | Deterministic / AI |
 |---|---|---|---|
@@ -32,10 +32,11 @@ Nine methods in `src/services/pipeline_viewer.py`, plus `pii_scan` which runs in
 | `heading_levels` | `_step_heading_levels` | Headings | AI |
 | `page_content` | `_step_page_content` | Translation | AI + subagents |
 | `code_blocks` | `_step_code_blocks` | Translation | AI |
+| `form_fields` | `_step_form_fields` | Translation | AI (vision, per form page) + deterministic HTML injection |
 | `boundaries` | `_step_boundaries` | Assembly | AI + subagent |
 | `cleanup` | `_step_cleanup` | Assembly | Deterministic |
 
-`classification` is not its own `_step_*` method — it's a `StepResult` emitted from within `_step_docling` when the classifier runs. Up to 10 named step results can appear in one run.
+`classification` is not its own `_step_*` method — it's a `StepResult` emitted from within `_step_docling` when the classifier runs. Up to 11 named step results can appear in one run.
 
 ## Subagents
 
@@ -46,7 +47,6 @@ Some main-agent tool calls delegate to specialist subagents:
 | `page_content` | Image describer | `ImageDescriptionResult` |
 | `page_content` | Table reconstructor | `TableReconstructionResult` |
 | `page_content` | List reconstructor | `ListReconstructionResult` |
-| `page_content` | Form reconstructor | `FormReconstructionResult` (rendered to a `form` block — see [form-block.md](form-block.md)) |
 | `boundaries` | Footnote relocator | (inline, no dedicated output model) |
 
 ## Versioning
diff --git a/src/agents/prompts/form_fields.py b/src/agents/prompts/form_fields.py
new file mode 100644
index 0000000..ead1a99
--- /dev/null
+++ b/src/agents/prompts/form_fields.py
@@ -0,0 +1,101 @@
+"""System prompt and user message template for the Form Fields agent.
+
+This agent examines one page of a PDF at a time, comparing the page image
+(visual ground truth) against its extracted markdown, and reports any form
+fields it finds. It does NOT modify the markdown — a deterministic injector
+turns each reported field into accessible HTML and splices it in afterwards.
+"""
+
+FORM_FIELDS_SYSTEM_PROMPT = """\
+You are a form accessibility analyst. You examine one page of a PDF at a \
+time, comparing the page image (visual ground truth) against its extracted \
+markdown, and you identify form fields a person would be expected to fill in.
+
+Your job is strictly detection — you do NOT modify the markdown. You report \
+what you find so that a later deterministic step can replace each field with \
+accessible HTML.
+
+## What counts as a form field
+
+Look at the page image for anything a person fills in by hand or on screen:
+
+- **Text fields** — a label followed by a blank line or box to write in, e.g. \
+"Name: ____________", "Email", an empty ruled box.
+- **Textareas** — large multi-line blank areas for long answers, comments, \
+or essays.
+- **Checkboxes** — a single square/box to tick (☐, [ ], a small empty box) \
+next to a statement, e.g. "☐ I agree to the terms".
+- **Checkbox groups** — several checkboxes under one prompt where more than \
+one may be ticked, e.g. "Select all that apply".
+- **Radio groups** — several mutually-exclusive options under one prompt \
+where exactly one is chosen, e.g. "Marital status: ☐ Single ☐ Married".
+- **Select / dropdowns** — a labelled choice list (often a box with a chevron).
+- **Date fields** — a labelled blank for a date (e.g. "Date of birth: __/__/____").
+- **Signature lines** — a ruled line labelled "Signature".
+
+Decorative rules, table borders, and underlines used purely for emphasis are \
+NOT form fields. Only report something a person is meant to complete.
+
+## What to report for each field
+
+- **field_type**: one of text, textarea, checkbox, checkbox_group, \
+radio_group, select, date, signature.
+- **label**: the accessible label, read from the IMAGE (not the markdown, \
+which may have OCR errors). For a single field this is the prompt next to \
+the blank (e.g. "Full name"). For a grouped field (radio_group, \
+checkbox_group, select) this is the group prompt/legend (e.g. "Marital \
+status"). If a field has no visible label, write a short descriptive one.
+- **anchor_text**: copy, VERBATIM, the exact text in the extracted markdown \
+that represents this field — for example the line "Name: ____________" or \
+"☐ I agree". This is used to locate and replace the field, so it must match \
+the markdown character-for-character. If the field is visible in the image \
+but absent from the markdown, set anchor_text to the nearest preceding \
+markdown line (e.g. the section heading) so the field can be inserted after it.
+- **options**: for radio_group, checkbox_group, and select only — the list of \
+choices, each with its visible label and whether it appears pre-ticked. \
+Empty for all other types.
+- **required**: true if the field is visibly marked required (an asterisk, \
+the word "required", bold "must").
+- **reasoning**: one sentence on how you determined the type and label.
+
+## Rules
+
+- Report fields in the order they appear top-to-bottom on the page.
+- A page with no form fields is a valid result — return an empty list.
+- Never invent options or labels that are not visible in the image.
+- Do not report the same field twice.
+"""
+
+
+def build_form_fields_user_message(
+    page_markdown: str,
+    page_number: int,
+    total_pages: int,
+) -> str:
+    """Build the text portion of the user message for one page.
+
+    The page image is passed separately as a binary content part.
+
+    Args:
+        page_markdown: Extracted markdown for this page (newest version).
+        page_number: Current page number (1-indexed).
+        total_pages: Total number of pages in the document.
+
+    Returns:
+        Text portion of the user message.
+    """
+    parts: list[str] = []
+    parts.append(f"## Page {page_number} of {total_pages}")
+    parts.append("")
+    parts.append("### Extracted markdown for this page")
+    parts.append("")
+    parts.append("```markdown")
+    parts.append(page_markdown)
+    parts.append("```")
+    parts.append("")
+    parts.append(
+        "The page image is attached. Compare the image (ground truth) against "
+        "the markdown above and report every form field you find. Copy each "
+        "field's anchor_text verbatim from the markdown."
+    )
+    return "\n".join(parts)
diff --git a/src/agents/prompts/form_reconstruction.py b/src/agents/prompts/form_reconstruction.py
deleted file mode 100644
index 35e0a73..0000000
--- a/src/agents/prompts/form_reconstruction.py
+++ /dev/null
@@ -1,99 +0,0 @@
-"""System prompt and user message template for the form reconstruction subagent.
-
-Invoked as the ``reconstruct_form`` tool by the page-correction agent when the
-structure pass flagged the page with ``has_forms``. The subagent re-reads the
-form from the page image and returns a structured ``FormReconstructionResult``
-(legend + fields); a deterministic renderer turns that into a ``form`` block.
-"""
-
-FORM_RECONSTRUCTOR_SYSTEM_PROMPT = """\
-You are a form accessibility specialist. The page agent has found a form on \
-the page and handed you the page image (visual ground truth) plus the markdown \
-fragment Docling extracted for it. Your job is to read the form precisely and \
-return a clean, structured description of its fields so it can be rebuilt as an \
-accessible, navigable form.
-
-You report structure only. You do not write HTML and you do not edit markdown.
-
-## Identify the form
-
-- **legend**: the form's overall title or prompt, read from the image (e.g. \
-"Course Registration", "Consent"). If there is no clear overall title, leave \
-it empty.
-
-## Identify each field, top to bottom
-
-For every field a person is expected to fill in, report:
-
-- **field_type** — choose the most specific match:
-  - `text` — a single-line blank for a short answer (name, email, ID number).
-  - `textarea` — a large multi-line blank for long answers or comments.
-  - `checkbox` — ONE standalone box next to a single statement \
-("☐ I agree to the terms").
-  - `multiselect` — a group of checkboxes under one prompt where MORE THAN ONE \
-may be ticked ("Select all that apply").
-  - `radio` — a group of options under one prompt where EXACTLY ONE is chosen \
-("Gender: ☐ Female ☐ Male ☐ Other").
-  - `select` — a dropdown / choice list (often a box with a chevron).
-  - `date` — a blank specifically for a date ("__/__/____", "Date of birth").
-  - `signature` — a ruled signature line.
-- **label** — the field's accessible label, read from the IMAGE (the markdown \
-may carry OCR errors). For `radio`, `multiselect`, and `select`, this is the \
-GROUP prompt (e.g. "Marital status"), not an individual option. If a field has \
-no visible label, write a short, accurate one.
-- **options** — for `radio`, `multiselect`, and `select` only: the choice \
-labels, in the order shown. Empty for every other type.
-- **required** — true only if the field is visibly marked required (an \
-asterisk, the word "required", "must").
-
-## Rules
-
-- Distinguish `radio` (pick one) from `multiselect` (pick many) and `checkbox` \
-(a single yes/no) carefully — this is the most common mistake.
-- Read every label and option from the image. Never invent fields or options \
-that are not visible.
-- Report fields in the order they appear on the page, top to bottom.
-- If, on closer inspection, the region is not actually a fillable form (e.g. it \
-is a data table or a decorative rule), return an empty ``fields`` list and say \
-so in ``reasoning``.
-"""
-
-
-def build_form_user_message(
-    form_text: str,
-    surrounding_text: str,
-    page_number: int,
-) -> str:
-    """Build the text portion of the form reconstructor user message.
-
-    The page image is passed separately as a binary content part.
-
-    Args:
-        form_text: The markdown fragment the page agent identified as the form.
-        surrounding_text: A little markdown context around the form region.
-        page_number: 1-indexed page number, for logging/grounding.
-
-    Returns:
-        Text portion of the user message.
-    """
-    parts: list[str] = []
-    parts.append(f"## Form on page {page_number}")
-    parts.append("")
-    parts.append("### Extracted markdown for the form region")
-    parts.append("")
-    parts.append("```markdown")
-    parts.append(form_text)
-    parts.append("```")
-    parts.append("")
-    if surrounding_text.strip():
-        parts.append("### Surrounding context")
-        parts.append("")
-        parts.append("```markdown")
-        parts.append(surrounding_text)
-        parts.append("```")
-        parts.append("")
-    parts.append(
-        "The page image is attached. Read the form from the image (ground "
-        "truth) and return its legend and fields in top-to-bottom order."
-    )
-    return "\n".join(parts)
diff --git a/src/agents/prompts/procedures/page_correction/content/has_forms.md b/src/agents/prompts/procedures/page_correction/content/has_forms.md
index 0cc6b5d..4bacfb1 100644
--- a/src/agents/prompts/procedures/page_correction/content/has_forms.md
+++ b/src/agents/prompts/procedures/page_correction/content/has_forms.md
@@ -2,53 +2,20 @@
 
 This page contains a form — fields a person is expected to fill in (labelled
 blanks, checkboxes, option groups, dropdowns, date blanks, signature lines).
+Docling renders these as lossy plain text: a label followed by underscores, a
+stray `☐` or `[ ]`, options run together.
 
-Docling renders forms as lossy plain text: a label followed by underscores, a
-stray `☐` or `[ ]`, option words run together, the field grouping lost
-entirely. That text is not accessible — a screen-reader user cannot tell it is
-a form, what the fields are, or which options belong together.
+## Leave the form fields alone
 
-## What to do
+A dedicated later step converts form fields into accessible HTML by reading the
+page image. Do **not** try to fix the form yourself:
 
-Identify each contiguous form region in the page markdown, then call
-`reconstruct_form` with that text. The tool re-reads the form from the page
-image and returns a structured `form` block. Use `str_replace` to replace the
-original lossy form text with the returned block.
+- Do not delete, shorten, or "tidy" runs of underscores (`____`) — they mark
+  where a field goes and are used to locate it.
+- Do not remove or rewrite checkbox glyphs (`☐`, `[ ]`) or the option text
+  next to them.
+- Do not merge a field's label into the blank or restructure the layout.
 
-Replace the whole region in one edit — do not leave half the form as raw
-underscores and half as a `form` block.
-
-## Verification checklist
-
-- **Field boundaries**: Each label + its blank is one field; don't merge two.
-- **Control type**: A single box is a `checkbox`; a "pick one" group is `radio`;
-  a "select all" group is `multiselect`; a chevroned box is `select`.
-- **Options**: Every option label in a group is captured, in order.
-- **Required**: Asterisks / "required" markers are preserved.
-
-## Tool
-
-- **`reconstruct_form(form_text, reasoning)`**: Pass the exact markdown text of
-  the form region and why it needs rebuilding. Returns a `form` block to apply
-  with `str_replace`.
-
-## Tool call example
-
-<example>
-<description>Rebuilding a registration form Docling flattened</description>
-<tool_call>
-reconstruct_form(
-  form_text="Name: ____________\nStatus: ☐ Single ☐ Married\n☐ I agree to the terms",
-  reasoning="Flattened form: a text field, a single-choice group, and a consent checkbox"
-)
-</tool_call>
-<follow_up>
-After receiving the form block, use str_replace:
-str_replace(
-  old_text="Name: ____________\nStatus: ☐ Single ☐ Married\n☐ I agree to the terms",
-  new_text="[form block from tool output]",
-  reasoning="Replaced flattened form text with structured accessible form block",
-  category="form_fix"
-)
-</follow_up>
-</example>
+Apply your normal corrections to the surrounding prose (OCR fixes, headings,
+lists), but treat the form fields themselves as read-only. Touching them can
+prevent the form step from locating and converting them.
diff --git a/src/agents/prompts/structure_analysis.py b/src/agents/prompts/structure_analysis.py
index 62a9f97..a87c895 100644
--- a/src/agents/prompts/structure_analysis.py
+++ b/src/agents/prompts/structure_analysis.py
@@ -79,12 +79,14 @@
 or definition-style term/description pairs. Not single items that happen to \
 start with a dash.
 - **has_forms** — True if the page contains form fields a person is meant to \
-fill in: a label followed by a blank line/box to write in ("Name: \
-______"), checkboxes (☐, [ ]) next to statements, mutually-exclusive option \
-sets, dropdowns, date blanks ("__/__/____"), or signature lines. Do NOT set \
-this for ordinary tables, rules used for emphasis, or table borders — only \
-genuine fillable fields. When in doubt, a cluster of labelled blanks the \
-reader would complete is a form.
+fill in. The strongest signals are **long horizontal underline runs** that a \
+person writes on (e.g. "Name: ______________________") and **checkboxes** \
+(☐, [ ]) next to statements. Also: mutually-exclusive option sets, dropdowns, \
+date blanks ("__/__/____"), and signature lines. A page with several labelled \
+blanks or checkboxes is a form even if it has no overall "Form" title, and a \
+multi-page form means later pages are still forms. Do NOT set this for ordinary \
+tables, rules used for emphasis, or table borders — only genuine fillable \
+fields.
 - **has_equations** — True if the page contains mathematical equations, \
 either display (centered) or complex inline equations.
 - **is_scanned** — True if the page appears to be a scan of a physical \
diff --git a/src/services/pdf_classifier.py b/src/services/pdf_classifier.py
index f8eeb00..2d1a350 100644
--- a/src/services/pdf_classifier.py
+++ b/src/services/pdf_classifier.py
@@ -326,14 +326,19 @@ def _check_hard_blockers(classification: PdfClassification) -> None:
                 details={"form_type": meta.form_type, "form_field_count": meta.form_field_count},
             ))
         else:
-            # AcroForm (1) or unknown form type with real widgets
+            # AcroForm (1) or unknown form type with real widgets.
+            # Not a blocker: AcroForm field *content* isn't extracted directly,
+            # but the form-reconstruction subagent rebuilds the form visually
+            # from the page image into an accessible `form` block. Surface a
+            # warning so the user knows the form was detected and handled.
             classification.findings.append(ClassificationFinding(
                 code=FINDING_FORM_ACROFORM,
-                severity=ClassificationSeverity.ERROR,
+                severity=ClassificationSeverity.WARNING,
                 message=(
                     f"PDF contains {meta.form_field_count} interactive form "
-                    f"field(s) (AcroForm). Form content cannot be reliably "
-                    "extracted. Please flatten the form or export as a standard PDF."
+                    f"field(s) (AcroForm). Interactive fields are not extracted "
+                    "directly; the form is reconstructed from the page image into "
+                    "an accessible form block."
                 ),
                 details={"form_type": meta.form_type, "form_field_count": meta.form_field_count},
             ))
diff --git a/src/services/pipeline_viewer.py b/src/services/pipeline_viewer.py
index 0b75a1e..5058690 100644
--- a/src/services/pipeline_viewer.py
+++ b/src/services/pipeline_viewer.py
@@ -13,6 +13,7 @@
 import asyncio
 import base64
 import difflib
+import html
 import logging
 import re
 import time
@@ -26,7 +27,9 @@
     DocumentChange,
     FigureData,
     FootnoteInfo,
-    FormReconstructionResult,
+    FormFieldInfo,
+    FormFieldsPageOutput,
+    FormFieldType,
     HeadingReconciliationOutput,
     ImageDescriptionResult,
     LayoutType,
@@ -279,54 +282,135 @@ def _apply_code_block_fence(
     )
 
 
-def _form_dsl_escape(text: str) -> str:
-    """Make a label/option safe to embed in a ``form`` block line.
+# Markers Docling leaves behind when it flattens a form: runs of underscores
+# (fill-in blanks), checkbox glyphs, and bracket checkboxes. Used to detect
+# form pages deterministically, independent of the structure agent.
+_FORM_UNDERLINE_RE = re.compile(r"_{4,}")
+_FORM_CHECKBOX_RE = re.compile(r"[☐☑☒□◻❐❏]|\[\s?\]")
 
-    The DSL is line- and delimiter-oriented: ``|`` separates a field's
-    columns and ``;`` separates options, so those characters (and newlines)
-    are replaced with safe equivalents rather than allowed to break parsing.
+
+def _page_has_form_signals(page_md: str) -> bool:
+    """Heuristically decide whether a page contains a fillable form.
+
+    Keys on the typical artifacts Docling produces for forms — long underline
+    runs (``____``) and checkbox glyphs (``☐``, ``[ ]``) — so form pages are
+    caught even when the structure agent's ``has_forms`` flag misses them.
     """
-    return (
-        " ".join(text.split())  # collapse newlines/runs of whitespace
-        .replace("|", "/")
-        .replace(";", ",")
-        .strip()
+    return bool(
+        _FORM_UNDERLINE_RE.search(page_md) or _FORM_CHECKBOX_RE.search(page_md)
     )
 
 
-def _render_form_block(result: FormReconstructionResult) -> str:
-    """Render a reconstructed form as a composable ``form`` code block.
+def _render_form_field_html(field: FormFieldInfo, field_id: str) -> str:
+    """Render a detected form field as an accessible, static HTML control.
+
+    The output is a *representation* of the form for accessibility, not a
+    working form: there is no surrounding ``<form>`` and inputs are marked
+    ``readonly`` / ``disabled`` so they advertise their role and label to a
+    screen reader without implying the document is fillable.
+
+    Every control is paired with a programmatic label:
+      - text / textarea / date / select use ``<label for=...>``,
+      - checkbox / single fields put the label after the control,
+      - radio_group / checkbox_group / multi-option select wrap options in a
+        ``<fieldset>`` with the prompt as the ``<legend>``.
+    """
+    label = html.escape(field.label or "Field")
+    required_attr = ' aria-required="true"' if field.required else ""
+    req_marker = ' <abbr title="required">*</abbr>' if field.required else ""
+
+    if field.field_type in (FormFieldType.TEXT, FormFieldType.DATE):
+        input_type = "date" if field.field_type == FormFieldType.DATE else "text"
+        return (
+            f'<label for="{field_id}">{label}{req_marker}</label>\n'
+            f'<input type="{input_type}" id="{field_id}" '
+            f'name="{field_id}"{required_attr} readonly>'
+        )
+
+    if field.field_type == FormFieldType.TEXTAREA:
+        return (
+            f'<label for="{field_id}">{label}{req_marker}</label>\n'
+            f'<textarea id="{field_id}" name="{field_id}"{required_attr} '
+            f"readonly></textarea>"
+        )
+
+    if field.field_type == FormFieldType.SIGNATURE:
+        return (
+            f'<label for="{field_id}">{label}{req_marker}</label>\n'
+            f'<input type="text" id="{field_id}" name="{field_id}" '
+            f'aria-label="{label} (signature)"{required_attr} readonly>'
+        )
+
+    if field.field_type == FormFieldType.CHECKBOX:
+        checked = " checked" if (field.options and field.options[0].checked) else ""
+        return (
+            f'<input type="checkbox" id="{field_id}" name="{field_id}"'
+            f"{checked}{required_attr} disabled> "
+            f'<label for="{field_id}">{label}{req_marker}</label>'
+        )
+
+    if field.field_type == FormFieldType.SELECT:
+        opts = "\n".join(
+            f'  <option{" selected" if o.checked else ""}>'
+            f"{html.escape(o.label)}</option>"
+            for o in field.options
+        )
+        return (
+            f'<label for="{field_id}">{label}{req_marker}</label>\n'
+            f'<select id="{field_id}" name="{field_id}"{required_attr} disabled>\n'
+            f"{opts}\n"
+            f"</select>"
+        )
+
+    # radio_group / checkbox_group — fieldset + legend, one control per option
+    input_type = (
+        "checkbox" if field.field_type == FormFieldType.CHECKBOX_GROUP else "radio"
+    )
+    parts = ["<fieldset>", f"  <legend>{label}{req_marker}</legend>"]
+    for i, opt in enumerate(field.options):
+        opt_id = f"{field_id}-{i}"
+        checked = " checked" if opt.checked else ""
+        # All radios in a group share a name; checkboxes get distinct names.
+        name = field_id if input_type == "radio" else opt_id
+        parts.append(
+            f'  <input type="{input_type}" id="{opt_id}" name="{name}"'
+            f"{checked} disabled> "
+            f'<label for="{opt_id}">{html.escape(opt.label)}</label>'
+        )
+    parts.append("</fieldset>")
+    return "\n".join(parts)
 
-    Grammar (one self-contained fenced block per form)::
 
-        ```form
-        legend: <form title>
-        - <type>[*] | <label>[ | opt1; opt2; ...]
-        ```
+def _apply_form_field(
+    page_md: str,
+    field: FormFieldInfo,
+    field_id: str,
+) -> tuple[str, DocumentChange | None]:
+    """Replace a detected field's ``anchor_text`` with accessible HTML.
 
-    ``<type>`` is the field-type DSL token, ``*`` marks a required field, and
-    options (semicolon-separated) appear only for radio/multiselect/select.
-    A downstream renderer compiles this to accessible controls; see
-    ``docs/reference/form-block.md``.
+    Fuzzy-finds the anchor line in *page_md* and swaps it for the rendered
+    control. Returns ``(new_markdown, change)`` or ``(original, None)`` if the
+    anchor could not be located.
     """
-    lines = ["```form"]
-    legend = _form_dsl_escape(result.legend)
-    if legend:
-        lines.append(f"legend: {legend}")
-
-    for field in result.fields:
-        token = field.field_type.value
-        required = "*" if field.required else ""
-        label = _form_dsl_escape(field.label) or "Field"
-        line = f"- {token}{required} | {label}"
-        if field.options:
-            opts = "; ".join(_form_dsl_escape(o) for o in field.options if o.strip())
-            if opts:
-                line += f" | {opts}"
-        lines.append(line)
-
-    lines.append("```")
-    return "\n".join(lines)
+    lines = page_md.split("\n")
+    idx = _fuzzy_find_line(lines, field.anchor_text)
+    if idx < 0:
+        return page_md, None
+
+    new_html = _render_form_field_html(field, field_id)
+    old_text = lines[idx]
+    new_lines = lines[:idx] + [new_html] + lines[idx + 1 :]
+
+    return "\n".join(new_lines), DocumentChange(
+        page=field.page,
+        old_text=old_text[:200] + ("..." if len(old_text) > 200 else ""),
+        new_text=new_html[:200] + ("..." if len(new_html) > 200 else ""),
+        reasoning=(
+            f"Replaced {field.field_type.value} field "
+            f"'{field.label}' with accessible HTML ({field.reasoning})"
+        ),
+        stage="form_field",
+    )
 
 
 def _replace_image_placeholders(
@@ -554,6 +638,11 @@ def _emit_phase(name: str, display_name: str) -> None:
             "findings_count": len(classification.findings),
             "elapsed_ms": classification.elapsed_ms,
         }
+        # Document-level form signal: count of interactive AcroForm widgets.
+        # Docling often drops form-field content from the extracted markdown
+        # (especially on later pages), so the form step uses this to decide
+        # whether to scan every page with the vision agent.
+        result.stats["form_field_count"] = classification.metadata.form_field_count
 
         # ── Tesseract OCR re-run for scanned documents ──────────
         # If the classifier flagged a scanned document (< 50 chars/page),
@@ -693,6 +782,8 @@ def _emit_phase(name: str, display_name: str) -> None:
             await self._step_page_content(result, structure, page_hints=page_hints)
             _emit_phase("code_blocks", "Code Block Languages")
             await self._step_code_blocks(result, structure)
+            _emit_phase("form_fields", "Form Fields")
+            await self._step_form_fields(result, structure)
 
         if enable_boundaries and structure is not None:
             if section_map is None and structure is not None:
@@ -2080,83 +2171,158 @@ async def _run_list_reconstructor(
         )
 
     # ------------------------------------------------------------------
-    # Form reconstruction subagent
+    # Phase 2c — Form fields → accessible HTML (guaranteed on form pages)
     # ------------------------------------------------------------------
 
-    async def _run_form_reconstructor(
+    async def _step_form_fields(
         self,
-        form_text: str,
-        surrounding_text: str,
-        page_image_b64: str | None,
-        page_number: int,
-        update_tokens: Any,
-    ) -> str:
-        """Run the form reconstruction vision subagent.
-
-        Mirrors _run_list_reconstructor: a one-shot PydanticAI agent with
-        structured output reads the form from the page image, then a
-        deterministic renderer turns the result into a ``form`` block that the
-        page agent applies with str_replace.
+        result: PipelineViewerResult,
+        structure: StructureResult,
+    ) -> None:
+        """Convert detected form fields to accessible HTML on every form page.
+
+        Runs unconditionally as a step (not an agent-optional tool, which the
+        page agent was skipping). A page is processed when the structure agent
+        flagged it ``has_forms`` OR a deterministic scan finds form signals
+        (underline runs, checkbox glyphs) — so multi-page forms are caught even
+        where ``has_forms`` missed a page.
+
+        For each form page, a vision agent reads the page image + markdown and
+        returns the fields it sees; a deterministic renderer then replaces each
+        field's ``anchor_text`` with accessible HTML (labelled controls,
+        ``<fieldset>``/``<legend>`` for option groups). Edits whichever per-page
+        version is newest (v1 if present, else v0) in-place.
         """
         from pydantic_ai import Agent
         from pydantic_ai.messages import BinaryContent
 
         from ..agents.model_factory import get_model_for_tier
         from ..agents.model_tiers import ModelTier
-        from ..agents.prompts.form_reconstruction import (
-            FORM_RECONSTRUCTOR_SYSTEM_PROMPT,
-            build_form_user_message,
+        from ..agents.prompts.form_fields import (
+            FORM_FIELDS_SYSTEM_PROMPT,
+            build_form_fields_user_message,
         )
+        from ..shared.llm_cost import calculate_estimated_cost
 
-        user_parts: list[Any] = []
-        if page_image_b64:
-            user_parts.append(
-                BinaryContent(
-                    data=base64.b64decode(page_image_b64),
-                    media_type="image/png",
-                )
-            )
-        user_parts.append(
-            build_form_user_message(
-                form_text=form_text,
-                surrounding_text=surrounding_text,
-                page_number=page_number,
-            )
-        )
+        step_start = time.time()
+        source_version = "v1" if "v1" in result.page_markdowns else "v0"
+        page_mds = result.page_markdowns.get(source_version, {})
 
         model = get_model_for_tier(ModelTier.EFFICIENT)
-        reconstructor_agent: Agent[None, FormReconstructionResult] = Agent(
+        agent: Agent[None, FormFieldsPageOutput] = Agent(
             model=model,
-            output_type=FormReconstructionResult,
-            system_prompt=FORM_RECONSTRUCTOR_SYSTEM_PROMPT,
+            output_type=FormFieldsPageOutput,
+            system_prompt=FORM_FIELDS_SYSTEM_PROMPT,
         )
 
-        try:
-            agent_result = await reconstructor_agent.run(user_parts)
-            usage = agent_result.usage()
-            update_tokens(usage.request_tokens or 0, usage.response_tokens or 0)
-        except Exception as e:
-            logger.warning(f"Form reconstructor failed on page {page_number}: {e}")
-            return (
-                f"Form reconstruction failed: {e}. "
-                f"Use str_replace to fix the form manually if needed."
+        changes: list[DocumentChange] = []
+        fields_found = 0
+        pages_processed = 0
+        total_input_tokens = 0
+        total_output_tokens = 0
+
+        # Document-level form signal. Docling frequently drops form-field text
+        # (underscores, checkboxes) from later pages, so per-page text signals
+        # alone miss multi-page forms. When the document is a form — it has
+        # AcroForm widgets, OR any page was flagged ``has_forms``, OR any page
+        # shows form signals — scan EVERY page with the vision agent (it returns
+        # no fields for non-form pages, so the cost is bounded and safe).
+        has_acroform = result.stats.get("form_field_count", 0) > 0
+        any_flagged = any(
+            a.has_forms for a in structure.page_attributes.values()
+        )
+        any_signal = any(_page_has_form_signals(md) for md in page_mds.values())
+        is_form_document = has_acroform or any_flagged or any_signal
+
+        for page_num in range(1, result.total_pages + 1):
+            page_key = str(page_num)
+            page_md = page_mds.get(page_key, "")
+            page_image_b64 = result.page_images.get(page_key)
+            if not page_md or not page_image_b64:
+                continue
+
+            attrs = structure.page_attributes.get(page_num)
+            is_form_page = (
+                is_form_document
+                or (attrs and attrs.has_forms)
+                or _page_has_form_signals(page_md)
             )
+            if not is_form_page:
+                continue
+            pages_processed += 1
 
-        result = agent_result.output
+            text_msg = build_form_fields_user_message(
+                page_markdown=page_md,
+                page_number=page_num,
+                total_pages=result.total_pages,
+            )
+            messages: list[Any] = [
+                BinaryContent(
+                    data=base64.b64decode(page_image_b64), media_type="image/png"
+                ),
+                text_msg,
+            ]
 
-        if not result.fields:
-            return (
-                "No fillable fields were found in that region — it may be a "
-                f"table or decorative rule. Reason: {result.reasoning}. "
-                "Leave it as-is or fix it with str_replace if needed."
+            try:
+                agent_result = await agent.run(messages)
+                page_output = agent_result.output
+                usage = agent_result.usage()
+                total_input_tokens += usage.request_tokens or 0
+                total_output_tokens += usage.response_tokens or 0
+            except Exception as e:
+                logger.error(f"Form field detection failed on page {page_num}: {e}")
+                continue
+
+            if not page_output.form_fields:
+                continue
+
+            fields_found += len(page_output.form_fields)
+            current_md = page_mds[page_key]
+            for i, field in enumerate(page_output.form_fields):
+                field.page = page_num
+                field_id = f"ff-p{page_num}-{i}"
+                new_md, change = _apply_form_field(current_md, field, field_id)
+                if change:
+                    current_md = new_md
+                    changes.append(change)
+                else:
+                    logger.info(
+                        f"Form field anchor not found on page {page_num}: "
+                        f"{field.anchor_text!r}"
+                    )
+            page_mds[page_key] = current_md
+
+            logger.info(
+                f"Form fields page {page_num}/{result.total_pages}: "
+                f"detected={len(page_output.form_fields)}"
             )
 
-        form_block = _render_form_block(result)
-        return (
-            f"Reconstructed the form as a `form` block "
-            f"({len(result.fields)} field(s)).\n"
-            f"Use str_replace to replace the original form text with this "
-            f"block exactly:\n\n{form_block}"
+        # Rebuild the full version from corrected pages
+        if changes:
+            result.versions[source_version] = "\n\n".join(
+                page_mds.get(str(p), "") for p in range(1, result.total_pages + 1)
+            )
+
+        elapsed_ms = int((time.time() - step_start) * 1000)
+        cost_cents = calculate_estimated_cost(total_input_tokens, total_output_tokens)
+
+        result.steps.append(
+            StepResult(
+                name="form_fields",
+                display_name="Form Fields",
+                version_before=source_version,
+                version_after=source_version,
+                elapsed_ms=elapsed_ms,
+                changes=changes,
+                metadata={
+                    "pages_processed": pages_processed,
+                    "fields_detected": fields_found,
+                    "fields_injected": len(changes),
+                },
+                input_tokens=total_input_tokens,
+                output_tokens=total_output_tokens,
+                cost_cents=cost_cents,
+            )
         )
 
     # ------------------------------------------------------------------
@@ -2242,8 +2408,6 @@ async def _process_page(page_num: int) -> PageCorrectionResult:
         total_table_reconstructor_output = 0
         total_list_reconstructor_input = 0
         total_list_reconstructor_output = 0
-        total_form_reconstructor_input = 0
-        total_form_reconstructor_output = 0
         for i, pr in enumerate(page_results):
             page_num = pages_to_process[i]
             page_key = str(page_num)
@@ -2265,8 +2429,6 @@ async def _process_page(page_num: int) -> PageCorrectionResult:
             total_table_reconstructor_output += pr.table_reconstructor_output_tokens
             total_list_reconstructor_input += pr.list_reconstructor_input_tokens
             total_list_reconstructor_output += pr.list_reconstructor_output_tokens
-            total_form_reconstructor_input += pr.form_reconstructor_input_tokens
-            total_form_reconstructor_output += pr.form_reconstructor_output_tokens
 
         # Write v1
         result.page_markdowns["v1"] = corrected_mds
@@ -2283,14 +2445,12 @@ async def _process_page(page_num: int) -> PageCorrectionResult:
             + total_describer_input
             + total_table_reconstructor_input
             + total_list_reconstructor_input
-            + total_form_reconstructor_input
         )
         combined_output = (
             total_output_tokens
             + total_describer_output
             + total_table_reconstructor_output
             + total_list_reconstructor_output
-            + total_form_reconstructor_output
         )
         cost_cents = calculate_estimated_cost(combined_input, combined_output)
 
@@ -2314,8 +2474,6 @@ async def _process_page(page_num: int) -> PageCorrectionResult:
                     "table_reconstructor_output_tokens": total_table_reconstructor_output,
                     "list_reconstructor_input_tokens": total_list_reconstructor_input,
                     "list_reconstructor_output_tokens": total_list_reconstructor_output,
-                    "form_reconstructor_input_tokens": total_form_reconstructor_input,
-                    "form_reconstructor_output_tokens": total_form_reconstructor_output,
                 },
                 input_tokens=combined_input,
                 output_tokens=combined_output,
@@ -2427,16 +2585,6 @@ async def _run_page_agent(
             page_attrs and page_attrs.has_lists
         )
 
-        # ------------------------------------------------------------------
-        # reconstruct_form tool: closure state
-        # ------------------------------------------------------------------
-        max_form_reconstruct_calls = 5
-        form_reconstructor_input_tokens = 0
-        form_reconstructor_output_tokens = 0
-        form_reconstruct_call_count = 0
-
-        enable_form_reconstruct = bool(page_attrs and page_attrs.has_forms)
-
         # Create agent with tools
         model = get_model_for_tier(ModelTier.EFFICIENT)
         agent: Agent[None, None] = Agent(
@@ -2648,58 +2796,6 @@ def _update_list_tokens(inp: int, out: int) -> None:
                 list_reconstructor_input_tokens += inp
                 list_reconstructor_output_tokens += out
 
-        # ------------------------------------------------------------------
-        # Conditionally register reconstruct_form tool
-        # ------------------------------------------------------------------
-        if enable_form_reconstruct:
-            @agent.tool_plain
-            async def reconstruct_form(form_text: str, reasoning: str) -> str:
-                """Rebuild a form region as an accessible ``form`` block.
-
-                Args:
-                    form_text: The exact markdown text of the form region to
-                        rebuild. Include enough text to uniquely identify it
-                        in the page markdown.
-                    reasoning: Why reconstruction is needed (e.g. "labels and
-                        checkboxes flattened into plain text").
-                """
-                nonlocal form_reconstruct_call_count
-
-                if form_reconstruct_call_count >= max_form_reconstruct_calls:
-                    return (
-                        f"ERROR: Maximum reconstruct_form calls "
-                        f"({max_form_reconstruct_calls}) reached. "
-                        f"Fix remaining forms with str_replace."
-                    )
-
-                form_reconstruct_call_count += 1
-
-                if form_text not in current_markdown:
-                    return (
-                        f"ERROR: form_text not found in page markdown. "
-                        f"Pass the exact text from the current markdown. "
-                        f"Current markdown:\n---\n{current_markdown}\n---"
-                    )
-
-                idx = current_markdown.find(form_text)
-                start = max(0, idx - 200)
-                end = min(len(current_markdown), idx + len(form_text) + 200)
-                surrounding = current_markdown[start:end]
-
-                return await self._run_form_reconstructor(
-                    form_text=form_text,
-                    surrounding_text=surrounding,
-                    page_image_b64=page_image_b64,
-                    page_number=page_num,
-                    update_tokens=lambda inp, out: _update_form_tokens(inp, out),
-                )
-
-            def _update_form_tokens(inp: int, out: int) -> None:
-                nonlocal form_reconstructor_input_tokens
-                nonlocal form_reconstructor_output_tokens
-                form_reconstructor_input_tokens += inp
-                form_reconstructor_output_tokens += out
-
         # ------------------------------------------------------------------
         # Conditionally register rewrite_page tool (create mode only)
         # ------------------------------------------------------------------
@@ -2796,8 +2892,6 @@ def rewrite_page(new_markdown: str, reasoning: str) -> str:
             table_reconstructor_output_tokens=table_reconstructor_output_tokens,
             list_reconstructor_input_tokens=list_reconstructor_input_tokens,
             list_reconstructor_output_tokens=list_reconstructor_output_tokens,
-            form_reconstructor_input_tokens=form_reconstructor_input_tokens,
-            form_reconstructor_output_tokens=form_reconstructor_output_tokens,
         )
 
     # ------------------------------------------------------------------
diff --git a/src/services/pipeline_viewer_models.py b/src/services/pipeline_viewer_models.py
index fbc5d62..3f3841c 100644
--- a/src/services/pipeline_viewer_models.py
+++ b/src/services/pipeline_viewer_models.py
@@ -253,58 +253,81 @@ class ListReconstructionResult(BaseModel):
 
 
 class FormFieldType(str, Enum):
-    """Type of form control, mapped to a ``form`` block DSL token.
-
-    The DSL token (the value here) is what appears in the rendered
-    ``form`` code block; a downstream renderer turns each into the
-    appropriate accessible control.
-    """
+    """Type of form control to render for a detected field."""
 
     TEXT = "text"
+    """Single-line free-text input (name, email, short answer)."""
+
     TEXTAREA = "textarea"
-    CHECKBOX = "checkbox"  # single standalone checkbox
-    MULTISELECT = "multiselect"  # group of checkboxes (more than one allowed)
-    RADIO = "radio"  # mutually-exclusive option group
-    SELECT = "select"  # dropdown / choice list
+    """Multi-line free-text input (comments, essay box)."""
+
+    CHECKBOX = "checkbox"
+    """A single standalone checkbox (e.g. "I attest …")."""
+
+    CHECKBOX_GROUP = "checkbox_group"
+    """A set of checkboxes where more than one may be ticked."""
+
+    RADIO_GROUP = "radio_group"
+    """A set of mutually-exclusive options (exactly one selected)."""
+
+    SELECT = "select"
+    """A dropdown / choice list."""
+
     DATE = "date"
+    """A date entry field."""
+
     SIGNATURE = "signature"
+    """A signature line."""
+
+
+class FormFieldOption(BaseModel):
+    """One selectable option within a radio, checkbox, or select group."""
+
+    label: str
+    """Visible option text as read from the page image."""
 
+    checked: bool = False
+    """True if the option appears pre-selected / ticked in the image."""
 
-class FormFieldSpec(BaseModel):
-    """One field in a detected form, read from the page image."""
+
+class FormFieldInfo(BaseModel):
+    """A form field detected on a page from the page image.
+
+    The agent reports what it sees; the deterministic injector turns this
+    into accessible HTML and splices it into the page markdown by replacing
+    ``anchor_text``.
+    """
 
     field_type: FormFieldType
     """The kind of control this field represents."""
 
     label: str
-    """Accessible label, read from the IMAGE. For grouped fields
-    (radio / multiselect / select) this is the group prompt."""
+    """Accessible label for the field, read from the IMAGE (e.g. "Full name").
+    For grouped fields this is the group prompt/legend (e.g. "Marital status")."""
 
-    options: list[str] = Field(default_factory=list)
-    """Choice labels for radio / multiselect / select. Empty otherwise."""
+    anchor_text: str
+    """The exact existing markdown text representing this field (e.g.
+    "Name: ____________" or "☐ I attest …"). The injector replaces this text
+    with the rendered accessible HTML. Copy it verbatim from the markdown."""
 
-    required: bool = False
-    """True if the field is visibly marked required (asterisk, "required")."""
+    options: list[FormFieldOption] = Field(default_factory=list)
+    """Options for radio_group / checkbox_group / select fields. Empty otherwise."""
 
+    required: bool = False
+    """True if the field is marked required (asterisk, "required", etc.)."""
 
-class FormReconstructionResult(BaseModel):
-    """Result from the form reconstruction subagent.
-
-    The deterministic renderer turns this into a ``form`` code block; the
-    page agent then splices that block in via ``str_replace``.
-    """
+    page: int = 0
+    """Page where this field appears (1-indexed). Set by the orchestrator."""
 
-    legend: str = ""
-    """The form's overall title/prompt, used as the block legend. May be empty."""
+    reasoning: str = ""
+    """How the field type and label were determined."""
 
-    fields: list[FormFieldSpec] = Field(default_factory=list)
-    """The fields that make up the form, in top-to-bottom order."""
 
-    confidence: str = "high"
-    """Confidence level: high, medium, or low."""
+class FormFieldsPageOutput(BaseModel):
+    """What the form-fields agent returns for a single page."""
 
-    reasoning: str = ""
-    """How the fields and types were identified from the image."""
+    form_fields: list[FormFieldInfo] = Field(default_factory=list)
+    """Form fields found on this page. Empty list if the page has no form."""
 
 
 class SectionCorrectionResult(BaseModel):
@@ -366,12 +389,6 @@ class PageCorrectionResult(BaseModel):
     list_reconstructor_output_tokens: int = 0
     """Output tokens from list reconstructor subagent calls."""
 
-    form_reconstructor_input_tokens: int = 0
-    """Input tokens consumed by form reconstructor subagent calls."""
-
-    form_reconstructor_output_tokens: int = 0
-    """Output tokens from form reconstructor subagent calls."""
-
 
 # ---------------------------------------------------------------------------
 # Phase 3 — Cross-page models
diff --git a/tests/unit/services/test_form_fields.py b/tests/unit/services/test_form_fields.py
new file mode 100644
index 0000000..b84da40
--- /dev/null
+++ b/tests/unit/services/test_form_fields.py
@@ -0,0 +1,334 @@
+"""Unit tests for the Form Fields step.
+
+Covers the accessible-HTML renderer (`_render_form_field_html`), the
+anchor-replacement injector (`_apply_form_field`), the deterministic form-signal
+heuristic (`_page_has_form_signals`), and the `_step_form_fields` orchestration
+(gating on has_forms OR heuristic, with the vision agent mocked).
+"""
+
+from __future__ import annotations
+
+from unittest.mock import AsyncMock, MagicMock, patch
+
+import pytest
+from src.services.pipeline_viewer import (
+    PipelineViewerService,
+    _apply_form_field,
+    _page_has_form_signals,
+    _render_form_field_html,
+)
+from src.services.pipeline_viewer_models import (
+    FormFieldInfo,
+    FormFieldOption,
+    FormFieldsPageOutput,
+    FormFieldType,
+    LayoutType,
+    PageAttributes,
+    PipelineViewerResult,
+    StructureResult,
+)
+
+pytestmark = pytest.mark.unit
+
+
+@pytest.fixture
+def service():
+    return PipelineViewerService()
+
+
+@pytest.fixture
+def base_result():
+    """A 1-page result whose newest per-page version is v0, with a form blank."""
+    md = "# Application\n\nName: ____________"
+    return PipelineViewerResult(
+        filename="form.pdf",
+        total_pages=1,
+        versions={"v0": md},
+        page_images={"1": "AAAA"},
+        page_markdowns={"v0": {"1": md}},
+        figures=[],
+        steps=[],
+        stats={},
+    )
+
+
+def _structure(has_forms: bool) -> StructureResult:
+    return StructureResult(page_attributes={1: PageAttributes(layout=LayoutType.SINGLE_COLUMN, has_forms=has_forms)})
+
+
+# ---------------------------------------------------------------------------
+# _render_form_field_html
+# ---------------------------------------------------------------------------
+
+
+class TestRenderFormFieldHtml:
+    def test_text_field_label_wired_to_input(self):
+        field = FormFieldInfo(field_type=FormFieldType.TEXT, label="Full name", anchor_text="Name:")
+        out = _render_form_field_html(field, "ff-p1-0")
+        assert '<label for="ff-p1-0">Full name</label>' in out
+        assert '<input type="text" id="ff-p1-0"' in out
+        assert "readonly" in out
+
+    def test_required_field_gets_aria_required(self):
+        field = FormFieldInfo(
+            field_type=FormFieldType.TEXT,
+            label="Email",
+            anchor_text="Email",
+            required=True,
+        )
+        out = _render_form_field_html(field, "ff-p1-1")
+        assert 'aria-required="true"' in out
+        assert '<abbr title="required">*</abbr>' in out
+
+    def test_date_field_uses_date_input(self):
+        field = FormFieldInfo(field_type=FormFieldType.DATE, label="DOB", anchor_text="Date of birth")
+        assert '<input type="date"' in _render_form_field_html(field, "ff-p1-0")
+
+    def test_textarea_field(self):
+        field = FormFieldInfo(field_type=FormFieldType.TEXTAREA, label="Comments", anchor_text="Comments")
+        out = _render_form_field_html(field, "ff-p1-0")
+        assert '<textarea id="ff-p1-0"' in out
+        assert "</textarea>" in out
+
+    def test_checkbox_label_after_control(self):
+        field = FormFieldInfo(
+            field_type=FormFieldType.CHECKBOX,
+            label="I attest",
+            anchor_text="I attest",
+            options=[FormFieldOption(label="I attest", checked=True)],
+        )
+        out = _render_form_field_html(field, "ff-p1-0")
+        assert '<input type="checkbox" id="ff-p1-0"' in out
+        assert "checked" in out
+        assert out.index("<input") < out.index("<label")
+
+    def test_radio_group_uses_fieldset_legend_and_shared_name(self):
+        field = FormFieldInfo(
+            field_type=FormFieldType.RADIO_GROUP,
+            label="Marital status",
+            anchor_text="Marital status",
+            options=[
+                FormFieldOption(label="Single"),
+                FormFieldOption(label="Married", checked=True),
+            ],
+        )
+        out = _render_form_field_html(field, "ff-p1-0")
+        assert "<fieldset>" in out
+        assert "<legend>Marital status</legend>" in out
+        assert out.count('name="ff-p1-0"') == 2
+        assert '<input type="radio" id="ff-p1-0-0"' in out
+        assert '<input type="radio" id="ff-p1-0-1"' in out
+
+    def test_checkbox_group_uses_distinct_names(self):
+        field = FormFieldInfo(
+            field_type=FormFieldType.CHECKBOX_GROUP,
+            label="Toppings",
+            anchor_text="Toppings",
+            options=[FormFieldOption(label="Cheese"), FormFieldOption(label="Olives")],
+        )
+        out = _render_form_field_html(field, "ff-p1-0")
+        assert "<fieldset>" in out
+        assert 'name="ff-p1-0-0"' in out
+        assert 'name="ff-p1-0-1"' in out
+
+    def test_select_renders_options(self):
+        field = FormFieldInfo(
+            field_type=FormFieldType.SELECT,
+            label="State",
+            anchor_text="State",
+            options=[
+                FormFieldOption(label="Illinois", checked=True),
+                FormFieldOption(label="Iowa"),
+            ],
+        )
+        out = _render_form_field_html(field, "ff-p1-0")
+        assert '<select id="ff-p1-0"' in out
+        assert "<option selected>Illinois</option>" in out
+        assert "<option>Iowa</option>" in out
+
+    def test_signature_field(self):
+        field = FormFieldInfo(field_type=FormFieldType.SIGNATURE, label="Signature", anchor_text="Sign")
+        assert "(signature)" in _render_form_field_html(field, "ff-p1-0")
+
+    def test_labels_html_escaped(self):
+        field = FormFieldInfo(
+            field_type=FormFieldType.SELECT,
+            label="Pick <one>",
+            anchor_text="Pick",
+            options=[FormFieldOption(label="A & B")],
+        )
+        out = _render_form_field_html(field, "ff-p1-0")
+        assert "Pick &lt;one&gt;" in out
+        assert "A &amp; B" in out
+
+
+# ---------------------------------------------------------------------------
+# _apply_form_field
+# ---------------------------------------------------------------------------
+
+
+class TestApplyFormField:
+    def test_replaces_matching_anchor_line(self):
+        md = "# Application\n\nName: ____________\n\nThanks"
+        field = FormFieldInfo(
+            field_type=FormFieldType.TEXT,
+            label="Full name",
+            anchor_text="Name: ____________",
+            page=1,
+        )
+        new_md, change = _apply_form_field(md, field, "ff-p1-0")
+        assert change is not None
+        assert "Name: ____________" not in new_md
+        assert '<input type="text" id="ff-p1-0"' in new_md
+        assert new_md.startswith("# Application")
+        assert new_md.endswith("Thanks")
+        assert change.stage == "form_field"
+
+    def test_missing_anchor_returns_original(self):
+        md = "# Application\n\nNothing to fill in here."
+        field = FormFieldInfo(
+            field_type=FormFieldType.TEXT,
+            label="Full name",
+            anchor_text="zzz totally absent anchor zzz",
+            page=1,
+        )
+        new_md, change = _apply_form_field(md, field, "ff-p1-0")
+        assert change is None
+        assert new_md == md
+
+
+# ---------------------------------------------------------------------------
+# _page_has_form_signals — deterministic detection
+# ---------------------------------------------------------------------------
+
+
+class TestPageHasFormSignals:
+    def test_long_underline_run_detected(self):
+        assert _page_has_form_signals("Name: ____________")
+
+    def test_checkbox_glyph_detected(self):
+        assert _page_has_form_signals("☐ I attest the animal is vaccinated")
+
+    def test_bracket_checkbox_detected(self):
+        assert _page_has_form_signals("[ ] Option A")
+
+    def test_short_underscores_not_a_signal(self):
+        # snake_case / a couple underscores shouldn't trip it
+        assert not _page_has_form_signals("see my_var and a__b in the code")
+
+    def test_plain_prose_has_no_signals(self):
+        assert not _page_has_form_signals("# Heading\n\nJust some ordinary text.")
+
+
+# ---------------------------------------------------------------------------
+# _step_form_fields — gating + orchestration
+# ---------------------------------------------------------------------------
+
+
+def _mock_agent_returning(output: FormFieldsPageOutput) -> MagicMock:
+    mock_agent = MagicMock()
+    run_result = MagicMock()
+    run_result.output = output
+    run_result.usage.return_value = MagicMock(request_tokens=10, response_tokens=5)
+    mock_agent.run = AsyncMock(return_value=run_result)
+    return mock_agent
+
+
+def _patches():
+    return (
+        patch("pydantic_ai.Agent"),
+        patch("pydantic_ai.models.bedrock.BedrockConverseModel"),
+        patch("pydantic_ai.messages.BinaryContent"),
+    )
+
+
+_FIELD_OUT = FormFieldsPageOutput(
+    form_fields=[
+        FormFieldInfo(
+            field_type=FormFieldType.TEXT,
+            label="Full name",
+            anchor_text="Name: ____________",
+        )
+    ]
+)
+
+
+class TestStepFormFields:
+    @pytest.mark.asyncio
+    async def test_fires_via_heuristic_even_when_has_forms_false(self, service, base_result):
+        """has_forms=False but underscores present → still processed (heuristic)."""
+        mock_agent = _mock_agent_returning(_FIELD_OUT)
+        p1, p2, p3 = _patches()
+        with p1 as agent_cls, p2, p3:
+            agent_cls.return_value = mock_agent
+            await service._step_form_fields(base_result, _structure(has_forms=False))
+
+        assert mock_agent.run.await_count == 1  # the page was processed
+        assert '<input type="text" id="ff-p1-0"' in base_result.versions["v0"]
+        step = next(s for s in base_result.steps if s.name == "form_fields")
+        assert step.metadata["pages_processed"] == 1
+        assert step.metadata["fields_injected"] == 1
+
+    @pytest.mark.asyncio
+    async def test_fires_via_has_forms_flag(self, service, base_result):
+        mock_agent = _mock_agent_returning(_FIELD_OUT)
+        p1, p2, p3 = _patches()
+        with p1 as agent_cls, p2, p3:
+            agent_cls.return_value = mock_agent
+            await service._step_form_fields(base_result, _structure(has_forms=True))
+        assert mock_agent.run.await_count == 1
+
+    @pytest.mark.asyncio
+    async def test_acroform_doc_scans_page_with_no_text_signals(self, service):
+        """Docling dropped the field text, but the doc has AcroForm widgets →
+        the page is still scanned (this is the multi-page-form fix)."""
+        md = "# Section B\n\nAnimal's Name"  # no underscores/checkboxes survived
+        result = PipelineViewerResult(
+            filename="form.pdf",
+            total_pages=1,
+            versions={"v0": md},
+            page_images={"1": "AAAA"},
+            page_markdowns={"v0": {"1": md}},
+            stats={"form_field_count": 24},
+        )
+        mock_agent = _mock_agent_returning(FormFieldsPageOutput(form_fields=[]))
+        p1, p2, p3 = _patches()
+        with p1 as agent_cls, p2, p3:
+            agent_cls.return_value = mock_agent
+            await service._step_form_fields(result, _structure(has_forms=False))
+
+        assert mock_agent.run.await_count == 1  # scanned despite no text signals
+        step = next(s for s in result.steps if s.name == "form_fields")
+        assert step.metadata["pages_processed"] == 1
+
+    @pytest.mark.asyncio
+    async def test_skips_page_in_non_form_document(self, service):
+        md = "# Notes\n\nJust prose, nothing to fill in."
+        result = PipelineViewerResult(
+            filename="x.pdf",
+            total_pages=1,
+            versions={"v0": md},
+            page_images={"1": "AAAA"},
+            page_markdowns={"v0": {"1": md}},
+        )
+        mock_agent = _mock_agent_returning(FormFieldsPageOutput(form_fields=[]))
+        p1, p2, p3 = _patches()
+        with p1 as agent_cls, p2, p3:
+            agent_cls.return_value = mock_agent
+            await service._step_form_fields(result, _structure(has_forms=False))
+
+        assert mock_agent.run.await_count == 0  # never invoked the model
+        step = next(s for s in result.steps if s.name == "form_fields")
+        assert step.metadata["pages_processed"] == 0
+        assert result.versions["v0"] == md
+
+    @pytest.mark.asyncio
+    async def test_agent_failure_does_not_raise(self, service, base_result):
+        mock_agent = MagicMock()
+        mock_agent.run = AsyncMock(side_effect=RuntimeError("LLM error"))
+        p1, p2, p3 = _patches()
+        with p1 as agent_cls, p2, p3:
+            agent_cls.return_value = mock_agent
+            await service._step_form_fields(base_result, _structure(has_forms=True))
+        step = next(s for s in base_result.steps if s.name == "form_fields")
+        assert step.metadata["fields_injected"] == 0
diff --git a/tests/unit/services/test_form_reconstruction.py b/tests/unit/services/test_form_reconstruction.py
deleted file mode 100644
index d267638..0000000
--- a/tests/unit/services/test_form_reconstruction.py
+++ /dev/null
@@ -1,241 +0,0 @@
-"""Unit tests for form reconstruction.
-
-Covers the deterministic ``form`` block renderer (`_render_form_block` /
-`_form_dsl_escape`), the `_run_form_reconstructor` subagent wrapper (model
-mocked), and that the `has_forms` page flag composes the form procedure into
-the page prompt.
-"""
-
-from __future__ import annotations
-
-from unittest.mock import AsyncMock, MagicMock, patch
-
-import pytest
-from src.services.pipeline_viewer import (
-    PipelineViewerService,
-    _compose_page_prompt,
-    _form_dsl_escape,
-    _render_form_block,
-)
-from src.services.pipeline_viewer_models import (
-    FormFieldSpec,
-    FormFieldType,
-    FormReconstructionResult,
-    LayoutType,
-    PageAttributes,
-)
-
-pytestmark = pytest.mark.unit
-
-
-# ---------------------------------------------------------------------------
-# _render_form_block — DSL rendering
-# ---------------------------------------------------------------------------
-
-
-class TestRenderFormBlock:
-    def test_fenced_with_form_language(self):
-        block = _render_form_block(FormReconstructionResult(legend="", fields=[]))
-        assert block.startswith("```form\n")
-        assert block.endswith("\n```")
-
-    def test_legend_emitted_when_present(self):
-        result = FormReconstructionResult(legend="Course Registration", fields=[])
-        block = _render_form_block(result)
-        assert "legend: Course Registration" in block
-
-    def test_legend_omitted_when_empty(self):
-        block = _render_form_block(FormReconstructionResult(legend="", fields=[]))
-        assert "legend:" not in block
-
-    def test_text_field_line(self):
-        result = FormReconstructionResult(fields=[FormFieldSpec(field_type=FormFieldType.TEXT, label="Full name")])
-        assert "- text | Full name" in _render_form_block(result)
-
-    def test_required_marker(self):
-        result = FormReconstructionResult(
-            fields=[FormFieldSpec(field_type=FormFieldType.TEXT, label="Email", required=True)]
-        )
-        assert "- text* | Email" in _render_form_block(result)
-
-    def test_radio_with_options(self):
-        result = FormReconstructionResult(
-            fields=[
-                FormFieldSpec(
-                    field_type=FormFieldType.RADIO,
-                    label="Standing",
-                    options=["Undergraduate", "Graduate"],
-                    required=True,
-                )
-            ]
-        )
-        assert "- radio* | Standing | Undergraduate; Graduate" in _render_form_block(result)
-
-    def test_multiselect_and_select_tokens(self):
-        result = FormReconstructionResult(
-            fields=[
-                FormFieldSpec(
-                    field_type=FormFieldType.MULTISELECT,
-                    label="Topics",
-                    options=["AI", "Systems"],
-                ),
-                FormFieldSpec(
-                    field_type=FormFieldType.SELECT,
-                    label="State",
-                    options=["IL", "IA"],
-                ),
-            ]
-        )
-        block = _render_form_block(result)
-        assert "- multiselect | Topics | AI; Systems" in block
-        assert "- select | State | IL; IA" in block
-
-    def test_checkbox_has_no_options_column(self):
-        result = FormReconstructionResult(
-            fields=[FormFieldSpec(field_type=FormFieldType.CHECKBOX, label="I agree", required=True)]
-        )
-        line = [line_ for line_ in _render_form_block(result).splitlines() if "I agree" in line_][0]
-        assert line == "- checkbox* | I agree"
-
-    def test_empty_label_falls_back(self):
-        result = FormReconstructionResult(fields=[FormFieldSpec(field_type=FormFieldType.TEXT, label="")])
-        assert "- text | Field" in _render_form_block(result)
-
-
-# ---------------------------------------------------------------------------
-# _form_dsl_escape — delimiter safety
-# ---------------------------------------------------------------------------
-
-
-class TestFormDslEscape:
-    def test_pipe_replaced(self):
-        assert _form_dsl_escape("a | b") == "a / b"
-
-    def test_semicolon_replaced(self):
-        assert _form_dsl_escape("a; b") == "a, b"
-
-    def test_newlines_collapsed(self):
-        assert _form_dsl_escape("line one\nline two") == "line one line two"
-
-    def test_escaping_applied_in_block(self):
-        result = FormReconstructionResult(
-            fields=[
-                FormFieldSpec(
-                    field_type=FormFieldType.RADIO,
-                    label="Pick | one",
-                    options=["a; b", "c"],
-                )
-            ]
-        )
-        block = _render_form_block(result)
-        assert "Pick / one" in block
-        assert "a, b; c" in block
-        # the only delimiters left are the structural ones
-        field_line = [line for line in block.splitlines() if line.startswith("- ")][0]
-        assert field_line.count(" | ") == 2
-
-
-# ---------------------------------------------------------------------------
-# has_forms composes the form procedure into the page prompt
-# ---------------------------------------------------------------------------
-
-
-class TestHasFormsProcedure:
-    def test_form_fragment_loaded_when_has_forms(self):
-        attrs = PageAttributes(layout=LayoutType.SINGLE_COLUMN, has_forms=True)
-        prompt = _compose_page_prompt(attrs)
-        assert "reconstruct_form" in prompt
-
-    def test_form_fragment_absent_without_flag(self):
-        attrs = PageAttributes(layout=LayoutType.SINGLE_COLUMN, has_forms=False)
-        prompt = _compose_page_prompt(attrs)
-        assert "reconstruct_form" not in prompt
-
-
-# ---------------------------------------------------------------------------
-# _run_form_reconstructor — subagent wrapper
-# ---------------------------------------------------------------------------
-
-
-@pytest.fixture
-def service():
-    return PipelineViewerService()
-
-
-def _patched_run(output: FormReconstructionResult):
-    """Context managers patching the deferred pydantic_ai imports + model."""
-    mock_agent = MagicMock()
-    mock_run_result = MagicMock()
-    mock_run_result.output = output
-    mock_run_result.usage.return_value = MagicMock(request_tokens=12, response_tokens=7)
-    mock_agent.run = AsyncMock(return_value=mock_run_result)
-    return mock_agent
-
-
-class TestRunFormReconstructor:
-    @pytest.mark.asyncio
-    async def test_returns_str_replace_instruction_with_block(self, service):
-        output = FormReconstructionResult(
-            legend="Consent",
-            fields=[FormFieldSpec(field_type=FormFieldType.CHECKBOX, label="I agree", required=True)],
-        )
-        tokens = []
-        with (
-            patch("pydantic_ai.Agent", return_value=_patched_run(output)),
-            patch("pydantic_ai.models.bedrock.BedrockConverseModel"),
-            patch("pydantic_ai.messages.BinaryContent"),
-            patch("src.agents.model_factory.get_model_for_tier", return_value=MagicMock()),
-        ):
-            msg = await service._run_form_reconstructor(
-                form_text="☐ I agree",
-                surrounding_text="",
-                page_image_b64=None,
-                page_number=1,
-                update_tokens=lambda i, o: tokens.append((i, o)),
-            )
-
-        assert "```form" in msg
-        assert "legend: Consent" in msg
-        assert "- checkbox* | I agree" in msg
-        assert "str_replace" in msg
-        assert tokens == [(12, 7)]
-
-    @pytest.mark.asyncio
-    async def test_empty_fields_reports_not_a_form(self, service):
-        output = FormReconstructionResult(fields=[], reasoning="This region is a data table, not a form.")
-        with (
-            patch("pydantic_ai.Agent", return_value=_patched_run(output)),
-            patch("pydantic_ai.models.bedrock.BedrockConverseModel"),
-            patch("pydantic_ai.messages.BinaryContent"),
-            patch("src.agents.model_factory.get_model_for_tier", return_value=MagicMock()),
-        ):
-            msg = await service._run_form_reconstructor(
-                form_text="| a | b |",
-                surrounding_text="",
-                page_image_b64=None,
-                page_number=2,
-                update_tokens=lambda i, o: None,
-            )
-
-        assert "```form" not in msg
-        assert "No fillable fields" in msg
-
-    @pytest.mark.asyncio
-    async def test_subagent_failure_returns_graceful_message(self, service):
-        mock_agent = MagicMock()
-        mock_agent.run = AsyncMock(side_effect=RuntimeError("LLM error"))
-        with (
-            patch("pydantic_ai.Agent", return_value=mock_agent),
-            patch("pydantic_ai.models.bedrock.BedrockConverseModel"),
-            patch("pydantic_ai.messages.BinaryContent"),
-            patch("src.agents.model_factory.get_model_for_tier", return_value=MagicMock()),
-        ):
-            msg = await service._run_form_reconstructor(
-                form_text="Name: ____",
-                surrounding_text="",
-                page_image_b64=None,
-                page_number=3,
-                update_tokens=lambda i, o: None,
-            )
-
-        assert "Form reconstruction failed" in msg
diff --git a/tests/unit/services/test_pdf_classifier.py b/tests/unit/services/test_pdf_classifier.py
index 991457a..c67a624 100644
--- a/tests/unit/services/test_pdf_classifier.py
+++ b/tests/unit/services/test_pdf_classifier.py
@@ -155,11 +155,12 @@ class TestHardBlockers:
     """Tests for _check_hard_blockers."""
 
     def test_acroform_with_fields_detected(self):
-        """AcroForm declared AND real widget fields present → block."""
+        """AcroForm with real widget fields → warn, not block (reconstructed visually)."""
         c = PdfClassification(metadata=PdfMetadata(page_count=5, form_type=1, form_field_count=10))
         _check_hard_blockers(c)
         assert FINDING_FORM_ACROFORM in _classification_codes(c)
-        assert c.findings[0].severity == ClassificationSeverity.ERROR
+        assert c.findings[0].severity == ClassificationSeverity.WARNING
+        assert not c.has_errors
         assert "10" in c.findings[0].message
 
     def test_acroform_without_fields_is_clean(self):
@@ -453,8 +454,8 @@ def test_encrypted_pdf(self, mock_pdf_cls):
 
     @patch("src.services.pdf_classifier._extract_metadata")
     @patch("pypdfium2.PdfDocument")
-    def test_form_pdf_with_fields_blocked(self, mock_pdf_cls, mock_extract):
-        """AcroForm with actual widget fields → blocked."""
+    def test_form_pdf_with_fields_warns_not_blocked(self, mock_pdf_cls, mock_extract):
+        """AcroForm with actual widget fields → warn (reconstructed visually), not blocked."""
         mock_pdf_cls.return_value = _make_mock_pdf(form_type=1)
 
         def populate_metadata(pdf, classification):
@@ -466,7 +467,8 @@ def populate_metadata(pdf, classification):
 
         result = classify_pdf(b"fake-pdf-bytes")
 
-        assert result.has_errors
+        assert not result.has_errors
+        assert result.has_warnings
         assert result.document_type == PdfDocumentType.FORM
         assert FINDING_FORM_ACROFORM in _classification_codes(result)
 

From 4b330886842c0219df2c6dde856b1ad2559ddd9a Mon Sep 17 00:00:00 2001
From: Blake Bertuccelli-Booth <46652+bbertucc@users.noreply.github.com>
Date: Thu, 21 May 2026 16:54:32 -0700
Subject: [PATCH 3/7] fix(pipeline): run form_fields step in the streaming
 pipeline too
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The viewer calls /process/stream, whose hand-rolled `_pipeline_steps`
sequence didn't include `_step_form_fields` — so forms were only converted
on the non-streaming /process path. Wire the step in after code_blocks,
mirroring the code_blocks emit, so the viewer actually produces form HTML.

Verified via /process/stream on the DOT form: form_fields runs
(pages_processed=4, fields_injected=21) and the streamed v1 contains the
accessible <label>/<input> controls.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 src/api/pipeline_viewer.py | 18 ++++++++++++++++++
 1 file changed, 18 insertions(+)

diff --git a/src/api/pipeline_viewer.py b/src/api/pipeline_viewer.py
index 084f65f..01a45fc 100644
--- a/src/api/pipeline_viewer.py
+++ b/src/api/pipeline_viewer.py
@@ -469,6 +469,24 @@ def _on_cold_start() -> None:
             logger.error(f"Code block language tagging failed: {e}")
             emit("error", {"step_name": "code_blocks", "message": str(e)})
 
+    # Step 3c: Form fields → accessible HTML (guaranteed on form pages)
+    if structure is not None:
+        emit("processing", {"step_name": "form_fields", "display_name": "Form Fields"})
+        try:
+            await service._step_form_fields(result, structure)
+            total_steps += 1
+            step = result.steps[-1]
+            # form_fields edits v1 (or v0) in-place — send the updated version
+            source_ver = "v1" if "v1" in result.page_markdowns else "v0"
+            emit("step", {
+                "step": step.model_dump(),
+                "new_versions": {source_ver: result.versions.get(source_ver, "")},
+                "new_page_markdowns": {source_ver: result.page_markdowns.get(source_ver, {})},
+            })
+        except Exception as e:
+            logger.error(f"Form fields step failed: {e}")
+            emit("error", {"step_name": "form_fields", "message": str(e)})
+
     # Step 4: Cross-page fixes (boundaries + footnotes)
     if structure is not None:
         emit("processing", {"step_name": "boundaries", "display_name": "Cross-Page Fixes"})

From c6b6f79e7a20ff68a5419182be80bb0220d0775a Mon Sep 17 00:00:00 2001
From: Blake Bertuccelli-Booth <46652+bbertucc@users.noreply.github.com>
Date: Thu, 21 May 2026 17:33:47 -0700
Subject: [PATCH 4/7] feat(forms): deterministic guarantee that no input is
 left as markdown
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Docling renders form checkboxes as GFM task-lists ("- [ ] ☐ I attest …"),
which remark-gfm renders as bare, unlabelled <input type=checkbox> — a
markdown-created, non-accessible input. The vision agent converts the ones it
detects, but to enforce the rule that NO input is ever expressed in markdown,
add a deterministic pass (`_convert_task_list_checkboxes`) that runs on every
form-step page after agent injection and rewrites any residual "- [ ]" /
"- [x]" task-list item into a labelled, accessible HTML checkbox (stripping the
redundant glyph). Reported via the new `markdown_checkboxes_converted` metric.

Verified on the DOT form via /process/stream: 0 markdown task-lists remain in
v1, 21 HTML inputs (7 checkboxes). 6 new unit tests.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 src/services/pipeline_viewer.py         | 68 +++++++++++++++++++++++--
 tests/unit/services/test_form_fields.py | 62 ++++++++++++++++++++++
 2 files changed, 126 insertions(+), 4 deletions(-)

diff --git a/src/services/pipeline_viewer.py b/src/services/pipeline_viewer.py
index 5058690..fb181da 100644
--- a/src/services/pipeline_viewer.py
+++ b/src/services/pipeline_viewer.py
@@ -381,6 +381,54 @@ def _render_form_field_html(field: FormFieldInfo, field_id: str) -> str:
     return "\n".join(parts)
 
 
+# A GFM task-list item (``- [ ]`` / ``* [x]``). remark-gfm renders these as
+# bare, unlabelled <input type=checkbox> — a markdown-created input. We convert
+# every one to a labelled, accessible HTML control so no input is left in
+# markdown form. An optional leading checkbox glyph (Docling emits both) is
+# stripped from the label.
+_TASK_LIST_CHECKBOX_RE = re.compile(r"^(\s*)[-*]\s+\[([ xX]?)\]\s*(.*)$")
+
+
+def _convert_task_list_checkboxes(
+    page_md: str, page_num: int
+) -> tuple[str, list[DocumentChange]]:
+    """Convert any GFM task-list checkboxes in *page_md* to accessible HTML.
+
+    Deterministic safeguard: guarantees no markdown-rendered checkbox inputs
+    survive, regardless of what the vision agent detected.
+    """
+    out: list[str] = []
+    changes: list[DocumentChange] = []
+    seq = 0
+    for line in page_md.split("\n"):
+        m = _TASK_LIST_CHECKBOX_RE.match(line)
+        if not m:
+            out.append(line)
+            continue
+        label = m.group(3).lstrip("☐☑☒□◻❐❏ \t").strip()
+        if not label:
+            out.append(line)
+            continue
+        checked = " checked" if m.group(2).lower() == "x" else ""
+        cid = f"cb-p{page_num}-{seq}"
+        seq += 1
+        html_line = (
+            f'<input type="checkbox" id="{cid}" name="{cid}"{checked} disabled> '
+            f'<label for="{cid}">{html.escape(label)}</label>'
+        )
+        out.append(html_line)
+        changes.append(
+            DocumentChange(
+                page=page_num,
+                old_text=line[:200],
+                new_text=html_line[:200],
+                reasoning="Converted markdown task-list checkbox to accessible HTML",
+                stage="form_field",
+            )
+        )
+    return "\n".join(out), changes
+
+
 def _apply_form_field(
     page_md: str,
     field: FormFieldInfo,
@@ -2217,6 +2265,7 @@ async def _step_form_fields(
 
         changes: list[DocumentChange] = []
         fields_found = 0
+        checkboxes_converted = 0
         pages_processed = 0
         total_input_tokens = 0
         total_output_tokens = 0
@@ -2273,11 +2322,10 @@ async def _step_form_fields(
                 logger.error(f"Form field detection failed on page {page_num}: {e}")
                 continue
 
-            if not page_output.form_fields:
-                continue
-
             fields_found += len(page_output.form_fields)
             current_md = page_mds[page_key]
+
+            # 1. Agent-detected fields → accessible HTML (text, checkbox, radio…)
             for i, field in enumerate(page_output.form_fields):
                 field.page = page_num
                 field_id = f"ff-p{page_num}-{i}"
@@ -2290,11 +2338,22 @@ async def _step_form_fields(
                         f"Form field anchor not found on page {page_num}: "
                         f"{field.anchor_text!r}"
                     )
+
+            # 2. Deterministic safeguard: convert any residual markdown
+            #    task-list checkboxes the agent didn't replace. Guarantees no
+            #    input is left as markdown.
+            current_md, cb_changes = _convert_task_list_checkboxes(
+                current_md, page_num
+            )
+            changes.extend(cb_changes)
+            checkboxes_converted += len(cb_changes)
+
             page_mds[page_key] = current_md
 
             logger.info(
                 f"Form fields page {page_num}/{result.total_pages}: "
-                f"detected={len(page_output.form_fields)}"
+                f"detected={len(page_output.form_fields)}, "
+                f"markdown_checkboxes_converted={len(cb_changes)}"
             )
 
         # Rebuild the full version from corrected pages
@@ -2318,6 +2377,7 @@ async def _step_form_fields(
                     "pages_processed": pages_processed,
                     "fields_detected": fields_found,
                     "fields_injected": len(changes),
+                    "markdown_checkboxes_converted": checkboxes_converted,
                 },
                 input_tokens=total_input_tokens,
                 output_tokens=total_output_tokens,
diff --git a/tests/unit/services/test_form_fields.py b/tests/unit/services/test_form_fields.py
index b84da40..7a0b29f 100644
--- a/tests/unit/services/test_form_fields.py
+++ b/tests/unit/services/test_form_fields.py
@@ -14,6 +14,7 @@
 from src.services.pipeline_viewer import (
     PipelineViewerService,
     _apply_form_field,
+    _convert_task_list_checkboxes,
     _page_has_form_signals,
     _render_form_field_html,
 )
@@ -197,6 +198,43 @@ def test_missing_anchor_returns_original(self):
         assert new_md == md
 
 
+# ---------------------------------------------------------------------------
+# _convert_task_list_checkboxes — no markdown inputs survive
+# ---------------------------------------------------------------------------
+
+
+class TestConvertTaskListCheckboxes:
+    def test_gfm_task_list_becomes_accessible_html(self):
+        md = "- [ ] I attest the animal is vaccinated"
+        out, changes = _convert_task_list_checkboxes(md, 1)
+        assert "- [ ]" not in out
+        assert '<input type="checkbox" id="cb-p1-0"' in out
+        assert "disabled>" in out
+        assert '<label for="cb-p1-0">I attest the animal is vaccinated</label>' in out
+        assert len(changes) == 1
+        assert changes[0].stage == "form_field"
+
+    def test_checked_task_item_is_checked(self):
+        out, _ = _convert_task_list_checkboxes("- [x] Done", 2)
+        assert " checked disabled>" in out
+
+    def test_leading_glyph_stripped_from_label(self):
+        # Docling emits both the task-list marker AND a glyph
+        out, _ = _convert_task_list_checkboxes("- [ ] ☐ I agree", 1)
+        assert '<label for="cb-p1-0">I agree</label>' in out
+        assert "☐" not in out
+
+    def test_label_html_escaped(self):
+        out, _ = _convert_task_list_checkboxes("- [ ] a < b & c", 1)
+        assert "a &lt; b &amp; c" in out
+
+    def test_non_task_lines_untouched(self):
+        md = "# Heading\n\n- a normal bullet\n\nprose"
+        out, changes = _convert_task_list_checkboxes(md, 1)
+        assert out == md
+        assert changes == []
+
+
 # ---------------------------------------------------------------------------
 # _page_has_form_signals — deterministic detection
 # ---------------------------------------------------------------------------
@@ -322,6 +360,30 @@ async def test_skips_page_in_non_form_document(self, service):
         assert step.metadata["pages_processed"] == 0
         assert result.versions["v0"] == md
 
+    @pytest.mark.asyncio
+    async def test_markdown_checkbox_converted_even_when_agent_finds_nothing(self, service):
+        """A GFM task-list checkbox must become HTML even if the vision agent
+        returns no fields — the deterministic safeguard."""
+        md = "# Form\n\n- [ ] I attest the animal is vaccinated"
+        result = PipelineViewerResult(
+            filename="form.pdf",
+            total_pages=1,
+            versions={"v0": md},
+            page_images={"1": "AAAA"},
+            page_markdowns={"v0": {"1": md}},
+        )
+        mock_agent = _mock_agent_returning(FormFieldsPageOutput(form_fields=[]))
+        p1, p2, p3 = _patches()
+        with p1 as agent_cls, p2, p3:
+            agent_cls.return_value = mock_agent
+            await service._step_form_fields(result, _structure(has_forms=False))
+
+        v0 = result.versions["v0"]
+        assert "- [ ]" not in v0
+        assert '<input type="checkbox"' in v0
+        step = next(s for s in result.steps if s.name == "form_fields")
+        assert step.metadata["markdown_checkboxes_converted"] == 1
+
     @pytest.mark.asyncio
     async def test_agent_failure_does_not_raise(self, service, base_result):
         mock_agent = MagicMock()

From 3df8e7cca8fea5148c0c104ee6e0dceedbdddd6d Mon Sep 17 00:00:00 2001
From: Blake Bertuccelli-Booth <46652+bbertucc@users.noreply.github.com>
Date: Thu, 21 May 2026 18:30:28 -0700
Subject: [PATCH 5/7] feat(forms): convert inline underscore blanks to
 accessible HTML inputs
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The vision agent + line-replacement couldn't handle lines packing several
fields into one (e.g. "Name____ Date of Birth____ Age___ Gender___"): the
per-field anchor fuzzy-match against the whole line fails, so the blanks were
left as raw underscores (which then render as plain text).

Add `_convert_underscore_fields`: a deterministic pass that walks each run of
underscores on a form page, turns the preceding words into the field's label,
and emits a labelled accessible <input> per blank — handling many per line and
running-together fields ("Zip____Telephone____"). Pure-underscore separator
rules are kept as-is. Input type is inferred from the label words
(Date/DOB/Birth → date, Email → email, Phone/Telephone → tel) per the
"understand underlines from context" guidance. Reported via the new
`underscore_fields_converted` metric.

Note: on scanned PDFs Docling drops the blanks until the OCR pass, so this runs
on the OCR'd v1 inside the form step. 9 new unit tests.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 src/services/pipeline_viewer.py         | 99 +++++++++++++++++++++++++
 tests/unit/services/test_form_fields.py | 59 +++++++++++++++
 2 files changed, 158 insertions(+)

diff --git a/src/services/pipeline_viewer.py b/src/services/pipeline_viewer.py
index fb181da..a4e15f5 100644
--- a/src/services/pipeline_viewer.py
+++ b/src/services/pipeline_viewer.py
@@ -429,6 +429,97 @@ def _convert_task_list_checkboxes(
     return "\n".join(out), changes
 
 
+# A run of 3+ underscores is a fill-in blank. Threshold 3 catches short blanks
+# like "Age___" while skipping snake_case / markdown emphasis (rarely 3+).
+_UNDERSCORE_RUN_RE = re.compile(r"_{3,}")
+# Trailing punctuation/whitespace to trim off a label before a blank.
+_LABEL_TRIM = " \t:.–—-"
+
+
+def _is_underscore_rule(line: str) -> bool:
+    """True if *line* is a horizontal rule / separator (underscores only).
+
+    Such lines are kept as-is — they are not fillable fields.
+    """
+    return len(re.sub(r"[_\s]", "", line)) < 2
+
+
+def _infer_input_type(label: str) -> str:
+    """Infer an HTML input type from a field label's words (context-driven).
+
+    Keeps the control semantic — a "Date of Birth" blank becomes a date input,
+    an "Email" blank an email input — which improves both accessibility and
+    on-screen affordances. Falls back to plain text.
+    """
+    low = label.lower()
+    if re.search(r"\b(date|dob|birth|expir\w*)\b", low):
+        return "date"
+    if "email" in low or "e-mail" in low:
+        return "email"
+    if re.search(r"\b(phone|telephone|tel|fax|mobile|cell)\b", low):
+        return "tel"
+    return "text"
+
+
+def _convert_underscore_fields(
+    page_md: str, page_num: int
+) -> tuple[str, list[DocumentChange]]:
+    """Convert ``label ____`` blanks (including several per line) to HTML.
+
+    Docling keeps form blanks as runs of underscores, often packing multiple
+    fields on one line (``Name____ Date of Birth____ Age___ Gender___``).
+    Line-granular replacement can't handle that, so this walks each underscore
+    run and turns the text preceding it into the field's label, emitting a
+    labelled, accessible ``<input>`` per blank. Pure-underscore separator rules
+    are left untouched.
+    """
+    out: list[str] = []
+    changes: list[DocumentChange] = []
+    seq = 0
+    for line in page_md.split("\n"):
+        runs = list(_UNDERSCORE_RUN_RE.finditer(line))
+        if not runs or _is_underscore_rule(line):
+            out.append(line)
+            continue
+
+        parts: list[str] = []
+        cursor = 0
+        for m in runs:
+            preceding = line[cursor : m.start()]
+            label = preceding.strip(_LABEL_TRIM)
+            # Keep labels short — use the trailing words if it ran long.
+            words = label.split()
+            if len(words) > 8:
+                label = " ".join(words[-8:])
+            if not label:
+                label = "Field"
+            fid = f"uf-p{page_num}-{seq}"
+            seq += 1
+            input_type = _infer_input_type(label)
+            parts.append(
+                f'<label for="{fid}">{html.escape(label)}</label> '
+                f'<input type="{input_type}" id="{fid}" name="{fid}" readonly>'
+            )
+            cursor = m.end()
+
+        trailing = line[cursor:].strip()
+        new_line = " ".join(parts)
+        if trailing:
+            new_line = f"{new_line} {trailing}"
+
+        out.append(new_line)
+        changes.append(
+            DocumentChange(
+                page=page_num,
+                old_text=line[:200],
+                new_text=new_line[:200],
+                reasoning=f"Converted {len(runs)} underscore blank(s) to accessible HTML input(s)",
+                stage="form_field",
+            )
+        )
+    return "\n".join(out), changes
+
+
 def _apply_form_field(
     page_md: str,
     field: FormFieldInfo,
@@ -2266,6 +2357,7 @@ async def _step_form_fields(
         changes: list[DocumentChange] = []
         fields_found = 0
         checkboxes_converted = 0
+        underscore_fields_converted = 0
         pages_processed = 0
         total_input_tokens = 0
         total_output_tokens = 0
@@ -2348,6 +2440,12 @@ async def _step_form_fields(
             changes.extend(cb_changes)
             checkboxes_converted += len(cb_changes)
 
+            # 3. Deterministic: convert residual "label ____" blanks (incl.
+            #    several per line) the agent's line-replacement couldn't handle.
+            current_md, uf_changes = _convert_underscore_fields(current_md, page_num)
+            changes.extend(uf_changes)
+            underscore_fields_converted += len(uf_changes)
+
             page_mds[page_key] = current_md
 
             logger.info(
@@ -2378,6 +2476,7 @@ async def _step_form_fields(
                     "fields_detected": fields_found,
                     "fields_injected": len(changes),
                     "markdown_checkboxes_converted": checkboxes_converted,
+                    "underscore_fields_converted": underscore_fields_converted,
                 },
                 input_tokens=total_input_tokens,
                 output_tokens=total_output_tokens,
diff --git a/tests/unit/services/test_form_fields.py b/tests/unit/services/test_form_fields.py
index 7a0b29f..dc69918 100644
--- a/tests/unit/services/test_form_fields.py
+++ b/tests/unit/services/test_form_fields.py
@@ -15,6 +15,8 @@
     PipelineViewerService,
     _apply_form_field,
     _convert_task_list_checkboxes,
+    _convert_underscore_fields,
+    _is_underscore_rule,
     _page_has_form_signals,
     _render_form_field_html,
 )
@@ -235,6 +237,63 @@ def test_non_task_lines_untouched(self):
         assert changes == []
 
 
+# ---------------------------------------------------------------------------
+# _convert_underscore_fields — inline "label ____" blanks
+# ---------------------------------------------------------------------------
+
+
+class TestConvertUnderscoreFields:
+    def test_multiple_fields_on_one_line(self):
+        line = "Name__________ Date of Birth________ Age___ Gender___"
+        out, changes = _convert_underscore_fields(line, 1)
+        assert "_" * 3 not in out  # no underscore runs survive
+        assert out.count("<input ") == 4
+        assert '<label for="uf-p1-0">Name</label>' in out
+        assert '<label for="uf-p1-1">Date of Birth</label>' in out
+        assert '<label for="uf-p1-2">Age</label>' in out
+        assert '<label for="uf-p1-3">Gender</label>' in out
+        assert len(changes) == 1
+
+    def test_run_together_fields(self):
+        out, _ = _convert_underscore_fields("Zip________Telephone__________", 1)
+        assert out.count("<input ") == 2
+        assert "Zip</label>" in out
+        assert "Telephone</label>" in out
+
+    def test_separator_rule_is_kept(self):
+        rule = "________________________________________"
+        out, changes = _convert_underscore_fields(rule, 1)
+        assert out == rule
+        assert changes == []
+
+    def test_label_trailing_punctuation_trimmed(self):
+        out, _ = _convert_underscore_fields("Email: ____________", 1)
+        assert '<label for="uf-p1-0">Email</label>' in out
+
+    def test_line_without_blanks_untouched(self):
+        line = "Just some prose with my_var and a__b."
+        out, changes = _convert_underscore_fields(line, 1)
+        assert out == line
+        assert changes == []
+
+    def test_trailing_text_preserved(self):
+        out, _ = _convert_underscore_fields("Date____ (mm/dd/yyyy)", 1)
+        assert "<input " in out
+        assert "(mm/dd/yyyy)" in out
+
+    def test_is_underscore_rule(self):
+        assert _is_underscore_rule("__________________")
+        assert _is_underscore_rule("   ____  ____  ")
+        assert not _is_underscore_rule("Name ____")
+
+    def test_input_type_inferred_from_label(self):
+        out, _ = _convert_underscore_fields("Date of Birth________ Email________ Telephone________ City________", 1)
+        assert '<input type="date"' in out
+        assert '<input type="email"' in out
+        assert '<input type="tel"' in out
+        assert '<input type="text"' in out  # City → plain text
+
+
 # ---------------------------------------------------------------------------
 # _page_has_form_signals — deterministic detection
 # ---------------------------------------------------------------------------

From 07406bd80ea26b7b9f19d683e2101eb41ba5dc7b Mon Sep 17 00:00:00 2001
From: Blake Bertuccelli-Booth <46652+bbertucc@users.noreply.github.com>
Date: Thu, 21 May 2026 18:46:10 -0700
Subject: [PATCH 6/7] fix(forms): defer multi-field lines from agent to
 deterministic converter
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The vision agent's whole-line replacement sometimes fuzzy-matched a line
packing several blanks (e.g. "Phone: ___ Email: ___") and replaced it with a
single input — dropping the other fields and leaving no underscores for the
deterministic pass to recover. Result: run-to-run variance (15 vs 21 fields).

Guard `_apply_form_field` so it declines to whole-line-replace a line that has
more than one underscore run, or one that already holds an injected control.
Those lines fall through to `_convert_underscore_fields`, which renders every
blank. The agent still handles single-field lines (better image-based labels
and types). Net: consistent, complete output — verified on the DOT form,
15 agent + 6 deterministic = 21 inputs every run.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 src/services/pipeline_viewer.py         |  9 +++++++++
 tests/unit/services/test_form_fields.py | 20 ++++++++++++++++++++
 2 files changed, 29 insertions(+)

diff --git a/src/services/pipeline_viewer.py b/src/services/pipeline_viewer.py
index a4e15f5..b82c9de 100644
--- a/src/services/pipeline_viewer.py
+++ b/src/services/pipeline_viewer.py
@@ -530,12 +530,21 @@ def _apply_form_field(
     Fuzzy-finds the anchor line in *page_md* and swaps it for the rendered
     control. Returns ``(new_markdown, change)`` or ``(original, None)`` if the
     anchor could not be located.
+
+    Defers two cases to the deterministic passes instead of whole-line
+    replacing: lines that already hold an injected control, and lines packing
+    multiple underscore blanks (``Phone: ___ Email: ___``) — replacing the
+    whole line there would drop every field but one.
     """
     lines = page_md.split("\n")
     idx = _fuzzy_find_line(lines, field.anchor_text)
     if idx < 0:
         return page_md, None
 
+    target = lines[idx]
+    if "<input" in target or len(_UNDERSCORE_RUN_RE.findall(target)) > 1:
+        return page_md, None
+
     new_html = _render_form_field_html(field, field_id)
     old_text = lines[idx]
     new_lines = lines[:idx] + [new_html] + lines[idx + 1 :]
diff --git a/tests/unit/services/test_form_fields.py b/tests/unit/services/test_form_fields.py
index dc69918..71c5f46 100644
--- a/tests/unit/services/test_form_fields.py
+++ b/tests/unit/services/test_form_fields.py
@@ -187,6 +187,26 @@ def test_replaces_matching_anchor_line(self):
         assert new_md.endswith("Thanks")
         assert change.stage == "form_field"
 
+    def test_defers_multi_field_line_to_deterministic(self):
+        """A line with several blanks must NOT be whole-line replaced (that
+        would drop all but one field); defer it to the underscore converter."""
+        md = "Phone: __________ Email: __________"
+        field = FormFieldInfo(
+            field_type=FormFieldType.TEXT,
+            label="Phone",
+            anchor_text="Phone: __________ Email: __________",
+            page=1,
+        )
+        new_md, change = _apply_form_field(md, field, "ff-p1-0")
+        assert change is None
+        assert new_md == md
+
+    def test_defers_line_already_holding_input(self):
+        md = '<input type="text" id="ff-p1-0"> Name'
+        field = FormFieldInfo(field_type=FormFieldType.TEXT, label="Name", anchor_text="Name", page=1)
+        new_md, change = _apply_form_field(md, field, "ff-p1-1")
+        assert change is None
+
     def test_missing_anchor_returns_original(self):
         md = "# Application\n\nNothing to fill in here."
         field = FormFieldInfo(

From feb881046f6f07adea6f60e42a8ab6ea4494e926 Mon Sep 17 00:00:00 2001
From: Blake Bertuccelli-Booth <46652+bbertucc@users.noreply.github.com>
Date: Fri, 22 May 2026 05:46:58 -0700
Subject: [PATCH 7/7] fix(dev): leave AWS_PROFILE unset for boto3 in
 api-gateway

boto3 treats a set-but-empty AWS_PROFILE as a missing named profile
(ProfileNotFound) and ignores the exported env credentials. Leaving it
unset makes boto3 use the AWS_ACCESS_KEY_ID/SECRET creds above.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 docker-compose.dev.yml | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/docker-compose.dev.yml b/docker-compose.dev.yml
index b01e80a..6f226f8 100644
--- a/docker-compose.dev.yml
+++ b/docker-compose.dev.yml
@@ -108,8 +108,9 @@ services:
       - AWS_ACCESS_KEY_ID=${AWS_ACCESS_KEY_ID:-test}
       - AWS_SECRET_ACCESS_KEY=${AWS_SECRET_ACCESS_KEY:-test}
       - AWS_SESSION_TOKEN=${AWS_SESSION_TOKEN:-}
-      # Clear AWS_PROFILE to prevent boto3 from looking for profile config in container
-      - AWS_PROFILE=
+      # AWS_PROFILE is intentionally NOT set here. boto3 treats a set-but-empty
+      # AWS_PROFILE as a missing named profile (ProfileNotFound) and ignores the
+      # exported env creds above. Leaving it unset makes boto3 use those creds.
       - AWS_DEFAULT_REGION=us-east-1
       # Disable AWS Instance Metadata Service (IMDS) to prevent boto3 hang in Docker
       - AWS_EC2_METADATA_DISABLED=true