red/.planning/phases/11.1-agent-and-client-initials/11.1-03-PLAN.md

---
phase: 11.1-agent-and-client-initials
plan: "03"
type: execute
wave: 3
depends_on:
  - "11.1-01"
  - "11.1-02"
files_modified: []
autonomous: false
requirements:
  - INIT-01
  - INIT-02
  - INIT-03
  - INIT-04

must_haves:
  truths:
    - "All four INIT requirements (INIT-01 through INIT-04) verified by human in a single live test"
    - "Agent initials draw, save, place, prepare, and PDF embedding round-trip confirmed working"
    - "Client-initials (existing 'initials' type) confirmed unchanged — client can still initial fields during signing"
    - "Agent-initials field never surfaces to the client signing page"
  artifacts:
    - path: "teressa-copeland-homes/src/app/portal/(protected)/profile/page.tsx"
      provides: "Profile page with both Agent Signature and Agent Initials sections visible"
    - path: "teressa-copeland-homes/src/lib/pdf/prepare-document.ts"
      provides: "preparePdf() embeds agent initials at agent-initials field coordinates"
  key_links:
    - from: "Agent saves initials at /portal/profile"
      to: "Prepared PDF"
      via: "PUT /api/agent/initials → users.agentInitialsData → preparePdf() → pdfDoc.embedPng + drawImage"
      pattern: "full pipeline"
---

<objective>
Human end-to-end verification of all Phase 11.1 requirements: draw and save initials on the profile page, place an agent-initials field, prepare the document, confirm the initials are embedded in the prepared PDF and absent from the client signing session, and confirm the existing client-initials flow is unaffected.

Purpose: All four INIT requirements are verified end-to-end by a human using the portal. No code changes in this plan — all deliverables were completed in Plans 01 and 02.
Output: Phase 11.1 marked complete; INIT-01 through INIT-04 confirmed working.
</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/STATE.md
@.planning/phases/11.1-agent-and-client-initials/11.1-01-SUMMARY.md
@.planning/phases/11.1-agent-and-client-initials/11.1-02-SUMMARY.md
</context>

<tasks>

<task type="checkpoint:human-verify" gate="blocking">
  <name>Task 1: Human verification — full Phase 11.1 agent and client initials end-to-end</name>
  <action>Run the dev server and execute the verification steps below. There are no code changes in this plan — all code was delivered in Plans 01 and 02.</action>
  <what-built>
Complete Phase 11.1 agent and client initials implementation:
- DB migration: agentInitialsData TEXT column on users table
- GET/PUT /api/agent/initials API routes
- AgentInitialsPanel component on /portal/profile (below Agent Signature section)
- Orange "Agent Initials" token in FieldPlacer palette (7th token)
- isClientVisibleField() updated to exclude agent-initials from client signing session
- preparePdf() embeds agentInitialsData PNG at agent-initials field coordinates
- prepare route 422 guard for missing initials + combined single-query fetch
- Existing 'initials' (client-initials) pipeline confirmed untouched throughout
  </what-built>
  <how-to-verify>
Start the dev server: `cd /Users/ccopeland/temp/red/teressa-copeland-homes && npm run dev`

**Step 1 — Save agent initials (INIT-01):**
- Visit http://localhost:3000/portal/profile
- Confirm the page shows BOTH the "Agent Signature" section (existing, unchanged) AND a new "Agent Initials" section below it
- Draw your initials on the Agent Initials canvas
- Click "Save Initials"
- Expected: Canvas is replaced by a thumbnail of your initials with an "Update Initials" button

**Step 2 — Update agent initials (INIT-02):**
- Click "Update Initials" on the profile page
- Draw different initials
- Click "Save Updated Initials"
- Expected: New thumbnail replaces the old one

**Step 3 — Place agent-initials field and prepare (INIT-03):**
- Open any document in the portal and go to the prepare tab
- Confirm the FieldPlacer palette shows an orange "Agent Initials" token (7th token, distinct from the purple "Initials" client token)
- Drag the orange "Agent Initials" token and drop it onto the document (any page, any position)
- Expected: An orange field box appears on the PDF where you dropped it
- Assign the document to a client and click Prepare
- Expected: Prepare succeeds (no 422 error)
- Download the prepared PDF
- Open the prepared PDF — confirm your initials PNG is embedded at the position where you placed the field

**Step 4 — Confirm agent-initials absent from client signing page (INIT-03):**
- Send the prepared document to a client (or use the signing link directly)
- Open the signing link in the browser
- Expected: NO interactive overlay appears at the agent-initials field position
- Expected: Client-signature and initials overlays (if placed) still appear normally for the client

**Step 5 — Confirm client-initials unchanged (INIT-04):**
- Open a document and place the purple "Initials" token on it
- Prepare the document — confirm the prepared PDF shows a purple "Initials" placeholder at that position
- Open the signing link — confirm the purple initials overlay appears with animation
- Click the overlay — confirm the modal opens with "Add Initials" as the title
- Submit initials — confirm they are embedded in the signed PDF
  </how-to-verify>
  <resume-signal>Type "approved" if all 5 steps pass. Describe any issues found if not (include step number and observed vs expected behavior).</resume-signal>
  <verify>All 5 steps pass and human types "approved"</verify>
  <done>Full end-to-end round-trip confirmed: agent draws/saves initials, places agent-initials field, prepares document with embedded initials PNG, client signing session shows no agent-initials overlay; existing client-initials ('initials' type) flow is unaffected</done>
</task>

</tasks>

<verification>
Human verification approved — all four INIT requirements confirmed by live testing:
- INIT-01: Agent drew and saved initials; thumbnail visible at /portal/profile
- INIT-02: "Update Initials" replaced saved initials with a new one
- INIT-03: Orange "Agent Initials" token visible and usable in FieldPlacer palette; initials PNG embedded in prepared PDF at correct position; absent from client signing session
- INIT-04: Existing purple "Initials" client token unchanged; client still prompted to initial during signing; modal shows "Add Initials"
</verification>

<success_criteria>
Human approves all 5 verification steps. Phase 11.1 is complete and all INIT requirements are satisfied.
</success_criteria>

<output>
After completion, create `.planning/phases/11.1-agent-and-client-initials/11.1-03-SUMMARY.md`
</output>