red/.planning/phases/19-template-editor-ui/19-03-PLAN.md

---
phase: 19-template-editor-ui
plan: "03"
type: execute
wave: 3
depends_on: ["19-02"]
files_modified: []
autonomous: false
requirements: [TMPL-05, TMPL-06, TMPL-07, TMPL-08, TMPL-09]

must_haves:
  truths:
    - "Agent can open a template editor and drag fields onto the PDF"
    - "Agent can use AI auto-place to populate fields"
    - "Agent can assign signer roles instead of emails"
    - "Agent can set text hints on text fields"
    - "Agent can save and fields persist across refresh"
  artifacts: []
  key_links: []
---

<objective>
Human verification of all Phase 19 TMPL-05 through TMPL-09 requirements via live browser testing.

Purpose: Confirm the template editor UI works end-to-end before marking Phase 19 complete.

Output: Human sign-off on all 5 requirements.
</objective>

<execution_context>
@$HOME/.claude/get-shit-done/workflows/execute-plan.md
</execution_context>

<context>
@.planning/phases/19-template-editor-ui/19-CONTEXT.md
@.planning/phases/19-template-editor-ui/19-01-SUMMARY.md
@.planning/phases/19-template-editor-ui/19-02-SUMMARY.md
</context>

<tasks>

<task type="checkpoint:human-verify" gate="blocking">
  <name>Task 1: Full Phase 19 human verification — template editor E2E</name>
  <action>
    Human verifies all TMPL-05 through TMPL-09 requirements in a single 9-step browser test.

    What was built:
    - Templates list page at /portal/templates with create-template modal
    - Template editor page at /portal/templates/[id] with FieldPlacer + TemplatePanel
    - AI auto-place for templates via POST /api/templates/[id]/ai-prepare
    - Signer role label system (Buyer/Seller instead of emails)
    - Text hint support on client-text fields
    - Save via PATCH /api/templates/[id]
    - Three supporting API routes (file, fields, ai-prepare)
    - "Templates" link in portal nav
  </action>
  <verify>
    Ensure the dev server is running: `cd teressa-copeland-homes && npm run dev`

    **Step 1 — Nav link (TMPL-05 prereq):**
    Visit http://localhost:3000/portal/dashboard. Confirm "Templates" appears in the top nav between "Clients" and "Profile". Click it.

    **Step 2 — Templates list page:**
    Confirm the list page loads at /portal/templates. If empty, verify the empty state message "No templates yet" is shown.

    **Step 3 — Create a template:**
    Click "+ New Template". In the modal, enter a name (e.g. "Test Listing Agreement") and select a form from the dropdown. Click "Create Template". Verify redirect to the editor page.

    **Step 4 — TMPL-05: Drag-drop fields:**
    On the editor page, verify the PDF is displayed on the left and TemplatePanel is on the right. Drag a "Signature" token from the palette onto the PDF. Verify it appears at the drop location. Drag a "Text" token. Verify it also appears.

    **Step 5 — TMPL-07: Signer role labels:**
    Verify "Signers / Roles" section shows "Buyer" and "Seller" by default. Place a field while "Buyer" is the active role. Verify the field appears with the Buyer color. Add a custom role (e.g. "Lender") using the Add Role input. Verify no email validation error occurs.

    **Step 6 — TMPL-06: AI Auto-place:**
    Click "AI Auto-place Fields". Wait for the spinner. Verify fields appear on the PDF after completion. (Requires OPENAI_API_KEY in .env.local — skip if not configured and note in feedback.)

    **Step 7 — TMPL-08: Text hints:**
    Click on a placed text field. Type a hint value (e.g. "Enter property address"). Click "Save Template". Refresh the page (Ctrl+R). Verify the hint value is still displayed in the text field.

    **Step 8 — TMPL-09: Save persists:**
    After placing several fields and saving, refresh the page. Verify all field positions, types, and role assignments are preserved. Verify the template name is preserved.

    **Step 9 — Templates list page verification:**
    Navigate back to /portal/templates. Verify the template you created appears in the list with the correct name, form name, field count, and a recent "last updated" date.
  </verify>
  <done>Human confirms all 9 verification steps pass. All TMPL-05 through TMPL-09 requirements satisfied. Phase 19 is complete.</done>
</task>

</tasks>

<verification>
All 5 requirements (TMPL-05 through TMPL-09) verified by human in a single 9-step live browser test.
</verification>

<success_criteria>
Human confirms all 9 verification steps pass. Phase 19 is complete.
</success_criteria>

<output>
After completion, create `.planning/phases/19-template-editor-ui/19-03-SUMMARY.md`
</output>