# Format Workflows

How to fill each of the four form formats. Read the section that matches the file in hand.

The PDF Tools connector (labeled "PDF Tools - Fill, Sign, Merge, Split, Extract") is the workhorse for PDFs. **Its tools require absolute paths on the user's local machine, not container paths** — pass the real file path the user gave you.

---

## A. Fillable PDF (AcroForm)

Best case — the PDF has named form fields you can set directly.

1. **Read the fields:** call `read_pdf_fields` on the PDF. This returns every field name, type, and current value. This tells you the exact field names to target (they're rarely pretty — e.g., `topmostSubform[0].Page1[0].LegalName[0]`).
2. **Ensure the `mpm` profile exists:** call `list_profiles`. If there's no `mpm` profile, seed one: read `assets/mpm-profile.json`, build a flat `{field_name: value}` map from the non-null values, and call `save_profile` with `profile_name: "mpm"`. (Saving once makes every future fill a one-liner.)
3. **Map profile → form fields:** the saved profile keys won't match the PDF's field names. Build the mapping by matching each PDF field name/label against the `aliases` in `mpm-profile.json`. Values you can't map, or whose profile value is null, stay out.
4. **Fill:** call `fill_with_profile` with `pdf_path`, `output_path` (outputs folder), `profile_name: "mpm"`, and an `additional_data` object carrying the specific field-name→value pairs you mapped in step 3 (this overrides/supplements the profile). If it's simpler, skip the saved profile and pass everything through `additional_data`.
5. **Leave human/blank fields alone:** do not fill signature, date, or certification-selection fields.
6. **Verify:** re-read fields or render the page to confirm values landed in the right boxes.

---

## B. Flat / scanned PDF (no form fields)

The PDF looks like a form but `read_pdf_fields` returns nothing fillable. You overlay text.

1. **Understand the layout:** call `get_page_analysis` (and/or `render_pdf_page`) to see where labels and blank lines sit. `search_pdf_text` can locate a label's coordinates so you can place the value just after/below it.
2. **Overlay text:** use the connector's `apply_text` to place each value at the right (x, y) on the right page. For many fields, the bundled `scripts/fill_flat_pdf.py` is faster — it takes the PDF plus a JSON list of `{page, x, y, text}` placements and writes a filled copy in one pass.
3. **Coordinate system:** PDF origin is bottom-left, y increases upward, points (72 = 1 inch). If `get_page_analysis` gives top-left coordinates, convert: `y_pdf = page_height - y_top`. Always render the result and eyeball it — flat-PDF placement is the most error-prone format.
4. **Signature/cert fields:** leave blank.
5. **Verify:** render each filled page and confirm text sits on the blanks, not over labels.

If placement proves too fiddly or the scan is low quality, fall back: reproduce the form as a clean .docx (Format C) and note to the user that you rebuilt it rather than annotating the scan.

---

## C. Word (.docx) form

Use the `docx` skill (read its SKILL.md for the mechanics of editing Word files).

1. Open the document and inspect its structure — agency Word forms are usually tables where the left cell is a label and the right cell is the answer, or inline "Name: ____" runs.
2. For each labeled cell/blank, match the label to a profile field (via aliases) and insert the value into the answer cell/run, preserving the surrounding formatting.
3. Leave signature lines, date lines, and certification checkboxes for the human.
4. Save the filled .docx to outputs. Verify by re-reading the document text.

---

## D. Table embedded in the RFP body

A certification block or info table living inside the solicitation document itself (not a separate form).

1. Locate and extract the exact table/block (with the `docx` or `pdf` skill depending on the source).
2. Decide the return format with the user's intent in mind: usually cleanest to reproduce the table in a standalone .docx labeled with the solicitation/agency, fill MPM's values, and hand that back. If the user wants the whole document returned with the block filled in place, do that instead.
3. Fill via alias matching; leave human-affirm items marked.
4. Save to outputs and verify.

---

## After any format
Keep the three running lists the SKILL.md asks for: (1) fields filled, (2) fields left blank for lack of data, (3) certification/signature items for the human. Report them back — the "left blank" list is the user's actionable to-do.