red/.planning/phases/13-ai-field-placement-and-pre-fill/13-04-PLAN.md

---
phase: 13-ai-field-placement-and-pre-fill
plan: 04
type: execute
wave: 4
depends_on:
  - 13-01
  - 13-02
  - 13-03
files_modified: []
autonomous: false
requirements:
  - AI-01
  - AI-02

must_haves:
  truths:
    - "Agent can click 'AI Auto-place Fields' on a real document and fields appear on the PDF canvas"
    - "AI-placed text fields are pre-filled with client name and/or property address where available"
    - "AI-placed fields are editable — agent can move, resize, and delete them after AI placement"
    - "Coordinate conversion is correct — fields appear at the expected vertical positions (not inverted)"
    - "Unit test passes: aiCoordsToPagePdfSpace produces correct Y-axis flip for US Letter dimensions"
  artifacts:
    - path: "teressa-copeland-homes/src/lib/pdf/__tests__/ai-coords.test.ts"
      provides: "Passing unit tests for coordinate conversion"
      contains: "aiCoordsToPagePdfSpace"
  key_links:
    - from: "AI Auto-place button"
      to: "/api/documents/[id]/ai-prepare"
      via: "PreparePanel onAiAutoPlace → DocumentPageClient handleAiAutoPlace → fetch POST"
      pattern: "ai-prepare"
    - from: "FieldPlacer"
      to: "DB (signatureFields)"
      via: "loadFields useEffect re-runs when aiPlacementKey increments"
      pattern: "aiPlacementKey"
---

<objective>
Verify the complete AI field placement feature end-to-end: unit tests, integration test with a real document, coordinate accuracy check, and final human UAT sign-off.

Purpose: AI coordinate accuracy on real Utah forms is listed as an explicit concern in STATE.md Blockers/Concerns. This plan is the mandatory verification gate before Phase 13 ships.

Output: Human-verified AI field placement on a real document. Phase 13 complete.
</objective>

<execution_context>
@/Users/ccopeland/.claude/get-shit-done/workflows/execute-plan.md
@/Users/ccopeland/.claude/get-shit-done/templates/summary.md
</execution_context>

<context>
@.planning/PROJECT.md
@.planning/ROADMAP.md
@.planning/STATE.md
@.planning/phases/13-ai-field-placement-and-pre-fill/13-RESEARCH.md
@.planning/phases/13-ai-field-placement-and-pre-fill/13-01-SUMMARY.md
@.planning/phases/13-ai-field-placement-and-pre-fill/13-02-SUMMARY.md
@.planning/phases/13-ai-field-placement-and-pre-fill/13-03-SUMMARY.md
</context>

<tasks>

<task type="auto">
  <name>Task 1: Run unit tests and TypeScript build check</name>
  <files></files>
  <action>
Run the full test suite for the AI coordinate conversion and confirm TypeScript compiles clean:

```bash
cd /Users/ccopeland/temp/red/teressa-copeland-homes
npx jest src/lib/pdf/__tests__/ai-coords.test.ts --no-coverage --verbose
npx tsc --noEmit
```

If any test fails:
- Re-read the formula in `aiCoordsToPagePdfSpace` against FieldPlacer.tsx lines 289-290
- The expected values in the test file are authoritative — fix the implementation, not the tests
- Re-run until GREEN

If TypeScript errors:
- Fix them (likely missing prop types or import errors)
- Re-run `npx tsc --noEmit` until clean

Do NOT proceed to the checkpoint task until both commands pass cleanly.
  </action>
  <verify>
    <automated>cd /Users/ccopeland/temp/red/teressa-copeland-homes && npx jest src/lib/pdf/__tests__/ai-coords.test.ts --no-coverage --verbose && npx tsc --noEmit</automated>
  </verify>
  <done>All aiCoordsToPagePdfSpace test cases PASS. TypeScript compiles with no errors. Ready for human verification.</done>
</task>

<task type="checkpoint:human-verify" gate="blocking">
  <name>Task 2: Human E2E verification of AI field placement</name>
  <action>Human verifies the complete AI auto-place feature end-to-end on a real document at localhost:3000.</action>
  <what-built>
Complete AI field placement feature:
- "AI Auto-place Fields" button (violet) in PreparePanel for all Draft documents
- POST /api/documents/[id]/ai-prepare route that extracts PDF text, calls GPT-4o-mini, converts coordinates, writes fields to DB
- FieldPlacer re-fetches from DB after AI placement (aiPlacementKey increment)
- Text fields pre-filled from client profile (name, property address) where available
- Unit test: aiCoordsToPagePdfSpace Y-axis flip verified for US Letter 612×792 pts
  </what-built>
  <how-to-verify>
Before running this test, ensure:
- `.env.local` in the teressa-copeland-homes directory has `OPENAI_API_KEY=sk-...` set
- `npm run dev` is running at localhost:3000

**Step 1: Verify the "AI Auto-place Fields" button appears**
- Open any Draft document in the portal: http://localhost:3000/portal/documents/[any-draft-docId]
- Confirm the violet "AI Auto-place Fields" button is visible in the PreparePanel (above the gray "Preview" button)
- Confirm it is NOT visible for non-Draft documents (Sent/Signed)

**Step 2: Test AI auto-place on a simple document**
- Choose a Draft document with a PDF that has visible form fields (any uploaded PDF)
- Click "AI Auto-place Fields"
- Expected: Button shows "AI placing fields..." during the request
- Expected: After completion, field overlays appear on the PDF canvas representing AI-placed fields
- Confirm field overlays appear — even if placement is imperfect, at least some fields should appear

**Step 3: Verify field editability (AI-01 success criterion)**
- Click on one of the AI-placed text field overlays — confirm it selects (blue ring appears)
- Try moving a field to a different position — confirm drag-and-drop works
- Try deleting a field (click x) — confirm it deletes
- Confirm the remaining fields still show after delete

**Step 4: Verify text pre-fill (AI-02)**
- If the document has an assigned client with a name and property address, open that document
- Click "AI Auto-place Fields"
- After completion, check the PreparePanel quick-fill area — click a text field
- Expected: The field value is already populated with client name or property address (if AI detected a matching field)
- Note: AI may not always pre-fill — this is best-effort. As long as the mechanism works when AI returns a prefillValue, it passes.

**Step 5: Verify Y-axis coordinate accuracy (AI-01 success criterion)**
- Place a known field manually at 10% from top on a real PDF, note its visual position
- Use AI auto-place on the same PDF
- Expected: AI-placed fields should appear at roughly correct vertical positions (not inverted/flipped to bottom)
- If fields appear at bottom when they should be at top, flag as a coordinate bug (do not approve)

**Step 6: Verify preview and prepare still work after AI placement**
- After AI auto-place, click "Preview" — confirm preview generates successfully
- Confirm the preview PDF shows the AI-placed fields
- Note: You do NOT need to click "Prepare and Send" for this verification

**Step 7: Verify error state**
- Temporarily set an invalid OPENAI_API_KEY in .env.local (e.g., OPENAI_API_KEY=invalid)
- Restart dev server, click "AI Auto-place Fields"
- Expected: An error message appears in PreparePanel (red text) — it should NOT crash the page
- Restore the correct API key afterward
  </how-to-verify>
  <verify>
    <automated>MISSING — this is a human-verify checkpoint; automated verification is Step 7 above (error state test)</automated>
  </verify>
  <done>Human approves all 7 verification steps. AI-01 and AI-02 verified. Phase 13 complete.</done>
  <resume-signal>
Type "approved" if all 7 steps pass. Describe any issues (especially Y-axis inversion in Step 5 or field editability failures in Step 3) and I will diagnose and fix.

Known acceptable limitations:
- AI may not place fields on every form perfectly — imprecise positions are acceptable as long as they are in the correct vertical region
- AI may not pre-fill text fields if it does not detect matching labels — that is acceptable
- Very long PDFs (20+ pages) may take 10-20 seconds — that is acceptable

Blocking failures (do NOT approve):
- Fields appear at inverted Y positions (Step 5) — this means aiCoordsToPagePdfSpace has a bug
- Fields cannot be moved or deleted after AI placement (Step 3)
- Page crashes or 500 error without user-visible error message
- "AI Auto-place Fields" button does not appear for Draft documents (Step 1)
  </resume-signal>
</task>

</tasks>

<verification>
- All aiCoordsToPagePdfSpace unit tests pass
- TypeScript compiles clean: npx tsc --noEmit
- AI Auto-place button visible in PreparePanel for Draft documents
- AI placement populates FieldPlacer with field overlays from DB
- Fields are movable/resizable/deletable after AI placement
- Text pre-fill from client profile works when AI detects matching fields
- Error state visible (not a crash) when API key is missing/invalid
- Human approved all 7 verification steps
</verification>

<success_criteria>
- Unit tests green (aiCoordsToPagePdfSpace)
- TypeScript clean build
- Human approves Steps 1-7:
  - AI Auto-place button appears for Draft docs
  - Fields appear on canvas after AI placement
  - Fields are editable (move, resize, delete)
  - Y-axis coordinates are correct (not inverted)
  - Preview and prepare-and-send still work after AI placement
  - Error state shown (not crash) when API key invalid
- AI-01 satisfied: one-click button places field types from PDF analysis
- AI-02 satisfied: text fields pre-filled with client data where AI detects match
- Phase 13 complete — v1.1 Smart Document Preparation milestone fully shipped
</success_criteria>

<output>
After completion, create `.planning/phases/13-ai-field-placement-and-pre-fill/13-04-SUMMARY.md`
</output>