# PDF form filling (agent workflows)

Follow these steps **in order**. Scripts live under `scripts/` relative to this skill; invoke them via the Skill tool with `cwd` set to this skill directory.

## Step 0: Detect fillable AcroForm fields

Run:

`python scripts/scan_fillable_pdf.py <file.pdf>`

- If the PDF **has** interactive fields, use **AcroForm path** below.
- If **not**, use **annotation overlay path** (flat PDF).

---

## AcroForm path (interactive fields)

1. **Export field metadata** to JSON:

   `python scripts/list_form_fields.py <input.pdf> <field_info.json>`

   Each entry includes `field_id`, `page` (1-based), `rect`, `type` (`text`, `checkbox`, `radio_group`, `choice`), and type-specific keys (`checked_value` / `unchecked_value`, `radio_options`, `choice_options`, etc.).

2. **Rasterize pages** for visual context (label semantics):

   `python scripts/pdf_page_png_export.py <file.pdf> <output_dir/>`

   Map PDF coordinates to image pixels when interpreting boxes.

3. **Author values** as `field_values.json` — array of objects with `field_id`, `page`, optional `description`, and `value` (for checkboxes use the widget’s `checked_value` string; for radios use one of the option values).

4. **Apply values**:

   `python scripts/write_acroform_fields.py <input.pdf> <field_values.json> <output.pdf>`

   Fix any validation errors printed by the script and retry.

---

## Annotation overlay path (non-interactive / flat PDF)

Use when there are **no** usable AcroForm fields.

### Phase 1 — Prefer structure extraction

`python scripts/form_schema_dump.py <input.pdf> form_structure.json`

Inspect JSON for `labels`, `lines`, `checkboxes`, `row_boundaries`. If labels are meaningful, build `fields.json` in **PDF space** using `pdf_width` / `pdf_height` on each page and rectangles for labels and entry areas.

### Phase 2 — Geometry checks

`python scripts/bbox_self_check.py fields.json`

Resolve overlaps and undersized entry boxes before filling.

### Phase 3 — Draw values

`python scripts/overlay_widget_values.py <input.pdf> fields.json <output.pdf>`

### Phase 4 — QA

Re-rasterize the output and visually confirm placement.

---

## Fallback: image-based coordinate picking

When structure extraction returns nothing useful (scanned PDFs, CID gibberish):

1. Export page images with `pdf_page_png_export.py`.
2. Estimate regions, then **crop/zoom** (e.g. ImageMagick) to refine pixel coordinates.
3. Build `fields.json` with `image_width` / `image_height` for those pages.
4. For a **hybrid** document, convert image coords to PDF space before mixing with structure-based fields:

   `pdf_x = image_x * (pdf_w / image_w)`  
   `pdf_y = image_y * (pdf_h / image_h)`

5. Run `bbox_self_check.py`, then `overlay_widget_values.py`.

---

## Coordinate conventions

- **PDF user space**: origin often bottom-left for some APIs; this skill’s JSON formats follow the scripts’ documented axes — always match the emitted `field_info.json` / `form_structure.json` conventions when converting.

---

## Debugging placement

- `python scripts/debug_highlight_render.py` — optional helper to paint boxes for verification (see script docstring).
- Re-run `pdf_page_png_export.py` on the filled PDF to compare.
