---
phase: 11-agent-saved-signature-and-signing-workflow
plan: "03"
type: execute
wave: 3
depends_on:
  - "11-01"
  - "11-02"
files_modified: []
autonomous: false
requirements:
  - AGENT-01
  - AGENT-02
  - AGENT-03
  - AGENT-04

must_haves:
  truths:
    - "Agent can draw, save, and see a thumbnail of their signature from /portal/profile"
    - "Agent can update (replace) their saved signature"
    - "Agent can place an Agent Signature token on a PDF document in the FieldPlacer"
    - "Preparing a document with agent-signature fields embeds the saved PNG in the correct position in the prepared PDF"
    - "Opening the client signing link for the prepared document does NOT show any agent-signature overlay"
  artifacts:
    - path: "teressa-copeland-homes/src/app/portal/(protected)/profile/page.tsx"
      provides: "Accessible profile page with draw/save/thumbnail signature flow"
    - path: "teressa-copeland-homes/src/lib/pdf/prepare-document.ts"
      provides: "preparePdf with agent PNG embedding at agent-sig field coordinates"
  key_links:
    - from: "Agent saves signature at /portal/profile"
      to: "Prepared PDF"
      via: "PUT /api/agent/signature → users.agentSignatureData → preparePdf() → pdfDoc.embedPng + drawImage"
      pattern: "full pipeline"
---

<objective>
Human verification of the complete Phase 11 agent signature workflow: draw once at profile, place fields on a document, prepare the document, verify the signature is embedded in the correct position in the PDF, and confirm the client signing session is unaffected.

Purpose: All four AGENT requirements are verified end-to-end by a human using the portal.
Output: Phase 11 marked complete; AGENT-01 through AGENT-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-agent-saved-signature-and-signing-workflow/11-01-SUMMARY.md
@.planning/phases/11-agent-saved-signature-and-signing-workflow/11-02-SUMMARY.md
</context>

<tasks>

<task type="checkpoint:human-verify" gate="blocking">
  <name>Task 1: Human verification — full Phase 11 agent signature end-to-end</name>
  <action>Run the dev server and execute the 5-step verification below. There are no code changes in this plan — all code was delivered in Plans 01 and 02.</action>
  <what-built>
    Complete Phase 11 agent signature workflow:
    - /portal/profile page with signature draw canvas and thumbnail
    - "Agent Signature" token in FieldPlacer palette (red, draggable)
    - preparePdf() embeds saved PNG at agent-signature field coordinates
    - Prepare route fetches agentSignatureData and passes 422 guard
    - Client signing session filters out agent-signature fields (unchanged from Phase 8)
  </what-built>
  <how-to-verify>
    Start the dev server: `cd /Users/ccopeland/temp/red/teressa-copeland-homes && npm run dev`

    **Step 1 — Save your signature (AGENT-01):**
    - Visit http://localhost:3000/portal/profile
    - Confirm "Profile" appears in the portal nav
    - Draw a distinctive signature on the canvas
    - Click "Save Signature"
    - Expected: Canvas is replaced by a thumbnail image of your signature

    **Step 2 — Update signature (AGENT-02):**
    - Click "Update Signature" on the profile page
    - Draw a slightly different signature
    - Click "Save Updated Signature"
    - Expected: New thumbnail replaces the old one

    **Step 3 — Place agent-signature field (AGENT-03):**
    - Open any document in the portal and go to the prepare tab
    - Confirm the FieldPlacer palette shows a red "Agent Signature" token
    - Drag the "Agent Signature" token and drop it onto the document (any page, any position)
    - Expected: A red field box appears on the PDF where you dropped it

    **Step 4 — Prepare with embedded signature (AGENT-04):**
    - Assign the document to a client, fill any required text fields
    - Click Prepare
    - Expected: Prepare succeeds (no error, document status changes)
    - Download the prepared PDF from the portal
    - Open the downloaded PDF and navigate to the page where you placed the agent-signature field
    - Expected: Your saved signature image appears at that position in the PDF

    **Step 5 — Client signing session is unaffected:**
    - Send the prepared document to a client (or use a test signing link)
    - Open the signing link in the browser
    - Expected: The client signing page does NOT show any overlay or prompt for the agent-signature position
    - Expected: Client-signature and initials overlays (if placed) still appear normally for the client
  </how-to-verify>
  <resume-signal>Type "approved" if all 5 steps pass. Describe any issues found if not.</resume-signal>
  <verify>All 5 steps pass and human types "approved"</verify>
  <done>Full end-to-end round-trip confirmed: agent draws, saves, places field, prepares, and embedded signature appears in prepared PDF; client signing session is unaffected</done>
</task>

</tasks>

<verification>
Human verification approved — all four AGENT requirements confirmed by live testing:
- AGENT-01: Agent drew and saved signature; thumbnail visible at /portal/profile
- AGENT-02: "Update Signature" replaced saved signature with a new one
- AGENT-03: Red "Agent Signature" token visible and usable in FieldPlacer palette
- AGENT-04: Prepared PDF contains agent signature PNG at the placed field coordinates; client signing session shows no agent-signature overlay
</verification>

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

<output>
After completion, create `.planning/phases/11-agent-saved-signature-and-signing-workflow/11-03-SUMMARY.md`
</output>