docs(11-02): complete agent signature bake-in prepare pipeline plan

- 11-02-SUMMARY.md: preparePdf() embeds agent PNG + prepare route 422 guard
- STATE.md: advance to plan 2 of 3, add phase 11-02 decisions, update metrics
- ROADMAP.md: phase 11 progress updated (2/3 plans complete)
- REQUIREMENTS.md: AGENT-04 marked complete

.planning/REQUIREMENTS.md

@@ -81,7 +81,7 @@
 - [x] **AGENT-01**: Agent can draw and save a signature to their account profile (drawn once, reused)
 - [x] **AGENT-02**: Agent can update their saved signature at any time
 - [x] **AGENT-03**: Agent can place agent signature field markers on a PDF
-- [ ] **AGENT-04**: Agent applies their saved signature to agent signature fields during document preparation (before sending to client)
+- [x] **AGENT-04**: Agent applies their saved signature to agent signature fields during document preparation (before sending to client)
 
 ### Document Preview
 
@@ -176,7 +176,7 @@ Which phases cover which requirements. Updated during roadmap creation.
 | AGENT-01 | Phase 11 | Complete |
 | AGENT-02 | Phase 11 | Complete |
 | AGENT-03 | Phase 11 | Complete |
-| AGENT-04 | Phase 11 | Pending |
+| AGENT-04 | Phase 11 | Complete |
 | PREV-01 | Phase 12 | Pending |
 | AI-01 | Phase 13 | Pending |
 | AI-02 | Phase 13 | Pending |

.planning/ROADMAP.md

@@ -276,6 +276,6 @@ Phases execute in numeric order: 1 → 2 → 3 → 4 → 5 → 6 → 7 → 8 →
 | 8. Schema Foundation and Signing Page Safety | 2/2 | Complete   | 2026-03-21 | - |
 | 9. Client Property Address | 1/1 | Complete    | 2026-03-21 | - |
 | 10. Expanded Field Types End-to-End | v1.1 | 3/3 | Complete | 2026-03-21 |
-| 11. Agent Saved Signature and Signing Workflow | 1/3 | In Progress|  | - |
+| 11. Agent Saved Signature and Signing Workflow | 2/3 | In Progress|  | - |
 | 12. Filled Document Preview | v1.1 | 0/2 | Not started | - |
 | 13. AI Field Placement and Pre-fill | v1.1 | 0/4 | Not started | - |

.planning/STATE.md

@@ -3,12 +3,12 @@ gsd_state_version: 1.0
 milestone: v1.1
 milestone_name: Smart Document Preparation
 status: in_progress
-last_updated: "2026-03-21T20:13:00.000Z"
+last_updated: "2026-03-21T20:07:05Z"
 progress:
   total_phases: 13
   completed_phases: 10
   total_plans: 37
-  completed_plans: 35
+  completed_plans: 36
 ---
 
 # Project State
@@ -23,9 +23,9 @@ See: .planning/PROJECT.md (updated 2026-03-21)
 ## Current Position
 
 Phase: 11 of 13 (Agent Saved Signature and Signing Workflow) — IN PROGRESS
-Plan: 1 of 3 in phase 11
+Plan: 2 of 3 in phase 11
 Status: In progress
-Last activity: 2026-03-21 — Phase 11 Plan 01 complete: agentSignatureData column + GET/PUT API routes + AgentSignaturePanel + /portal/profile page + PortalNav Profile link + FieldPlacer red Agent Signature token.
+Last activity: 2026-03-21 — Phase 11 Plan 02 complete: preparePdf() embeds agent signature PNG at agent-sig field coordinates; prepare route fetches agentSignatureData from DB with 422 guard when signature missing.
 
 Progress: [██████████░░░] 77% (10/13 phases complete)
 
@@ -49,6 +49,7 @@ Progress: [██████████░░░] 77% (10/13 phases complete)
 | Phase 09-client-property-address P01 | 25 | 3 tasks | 7 files |
 | Phase 10-expanded-field-types-end-to-end P02 | 2 | 2 tasks | 2 files |
 | Phase 11-agent-saved-signature P01 | 8 | 2 tasks | 7 files |
+| Phase 11-agent-saved-signature P02 | 2 | 2 tasks | 2 files |
 
 ## Accumulated Context
 
@@ -76,6 +77,9 @@ Recent decisions affecting v1.1 work:
 - [Phase 11-01]: Migration auto-named 0008_windy_cloak.sql by drizzle-kit; content is correct ALTER TABLE users ADD COLUMN agent_signature_data text
 - [Phase 11-01]: AgentSignaturePanel fully self-contained — local state, fetch/save within component, no external context needed
 - [Phase 11-01]: Agent Signature palette token is red #dc2626 to visually distinguish from client-facing field types
+- [Phase 11-02]: PDFImage embedded once before field loop and reused via drawImage in loop — embed-once-draw-many pattern
+- [Phase 11-02]: Session guard strengthened to !session?.user?.id in prepare route — required for TypeScript narrowing of session.user.id to string
+- [Phase 11-02]: 422 guard fires only when hasAgentSigFields && !agentSignatureData — documents with no agent-sig fields prepare normally
 
 ### Pending Todos
 
@@ -89,5 +93,5 @@ None yet.
 ## Session Continuity
 
 Last session: 2026-03-21
-Stopped at: Completed 11-agent-saved-signature-and-signing-workflow/11-01-PLAN.md
+Stopped at: Completed 11-agent-saved-signature-and-signing-workflow/11-02-PLAN.md
 Resume file: None

.planning/phases/11-agent-saved-signature-and-signing-workflow/11-02-SUMMARY.md

@@ -0,0 +1,109 @@
+---
+phase: 11-agent-saved-signature-and-signing-workflow
+plan: "02"
+subsystem: pdf
+tags: [pdf-lib, agent-signature, prepare-pipeline, drizzle-orm]
+
+# Dependency graph
+requires:
+  - phase: 11-01
+    provides: agentSignatureData column on users table; agent-signature field type in FieldPlacer
+provides:
+  - preparePdf() embeds agent PNG at agent-signature field coordinates via pdfDoc.embedPng + page.drawImage
+  - prepare route fetches agentSignatureData from DB and passes to preparePdf()
+  - 422 guard when agent-signature fields present but no signature saved
+affects: [phase-12-preview, phase-13-ai-field-placement]
+
+# Tech tracking
+tech-stack:
+  added: []
+  patterns: [embed-once-draw-many for PDFImage reuse across field loop; 422 guard before preparePdf for missing agent signature]
+
+key-files:
+  created: []
+  modified:
+    - teressa-copeland-homes/src/lib/pdf/prepare-document.ts
+    - teressa-copeland-homes/src/app/api/documents/[id]/prepare/route.ts
+
+key-decisions:
+  - "PDFImage embedded once before field loop and reused across all agent-sig fields — matches plan guidance, avoids repeated embed cost"
+  - "Session guard strengthened to !session?.user?.id in prepare route — matches established pattern from agent/signature route; fixes TypeScript narrowing"
+  - "422 guard fires only when agent-sig fields exist AND no signature is saved — documents with no agent-sig fields prepare normally"
+
+patterns-established:
+  - "embed-once-draw-many: call pdfDoc.embedPng() once before field loop, store PDFImage, reuse in drawImage calls inside loop"
+  - "422-before-prepare: validate preconditions (agent sig present) before calling preparePdf() to prevent silent no-ops"
+
+requirements-completed: [AGENT-04]
+
+# Metrics
+duration: 2min
+completed: 2026-03-21
+---
+
+# Phase 11 Plan 02: Agent Signature Bake-In Summary
+
+**preparePdf() embeds agent PNG at agent-signature field coordinates using pdfDoc.embedPng + page.drawImage; prepare route fetches agentSignatureData from DB with a 422 guard when fields exist but no signature is saved**
+
+## Performance
+
+- **Duration:** ~2 min
+- **Started:** 2026-03-21T20:05:41Z
+- **Completed:** 2026-03-21T20:07:05Z
+- **Tasks:** 2
+- **Files modified:** 2
+
+## Accomplishments
+- `preparePdf()` gains optional 5th parameter `agentSignatureData: string | null = null`; agent-signature stub replaced with real `page.drawImage()` call using field.x/y/width/height
+- `PDFImage` imported from `@cantoo/pdf-lib`; image embedded once before field loop and reused across all agent-sig fields
+- Prepare route fetches `agentSignatureData` from `users` table for the authenticated session; passes it as 5th arg to `preparePdf()`
+- 422 guard with `{ error: 'agent-signature-missing' }` fires when any `agent-signature` field exists but no signature has been saved
+
+## Task Commits
+
+Each task was committed atomically:
+
+1. **Task 1: preparePdf() — add agentSignatureData param and embed at agent-sig field coordinates** - `d9652e1` (feat)
+2. **Task 2: prepare route — fetch agentSignatureData, 422 guard, pass to preparePdf** - `b2e9810` (feat)
+
+## Files Created/Modified
+- `teressa-copeland-homes/src/lib/pdf/prepare-document.ts` - Added `agentSignatureData` param, `PDFImage` import, embed-once-draw-many block, replaced agent-signature stub with `drawImage`
+- `teressa-copeland-homes/src/app/api/documents/[id]/prepare/route.ts` - Added `users`/`getFieldType` imports, strengthened session guard, DB fetch, 422 guard, 5-arg `preparePdf()` call
+
+## Decisions Made
+- PDFImage embedded once before field loop and reused — avoids re-embedding cost per field and matches plan guidance
+- Session guard strengthened from `!session` to `!session?.user?.id` — required for TypeScript narrowing so `session.user.id` is a `string` (not `string | undefined`) when passed to `eq()`
+- 422 guard fires only when `hasAgentSigFields && !agentSignatureData` — documents with no agent-signature fields prepare normally, preserving backward compatibility
+
+## Deviations from Plan
+
+### Auto-fixed Issues
+
+**1. [Rule 1 - Bug] Strengthened session guard to enable TypeScript narrowing**
+- **Found during:** Task 2 (prepare route — fetch agentSignatureData, 422 guard, pass to preparePdf)
+- **Issue:** Original `if (!session)` guard left `session.user` and `session.user.id` as possibly-undefined; TypeScript TS2769 + TS18048 errors when passing `session.user.id` to `eq(users.id, ...)`
+- **Fix:** Changed `if (!session)` to `if (!session?.user?.id)` — matches established pattern from `src/app/api/agent/signature/route.ts` (11-01)
+- **Files modified:** `teressa-copeland-homes/src/app/api/documents/[id]/prepare/route.ts`
+- **Verification:** `npx tsc --noEmit` passed with zero errors after fix
+- **Committed in:** `b2e9810` (part of Task 2 commit)
+
+---
+
+**Total deviations:** 1 auto-fixed (Rule 1 - type-narrowing bug in session guard)
+**Impact on plan:** Minimal — single-line guard change consistent with established codebase pattern. No scope creep.
+
+## Issues Encountered
+- TypeScript TS2769/TS18048 errors on `session.user.id` due to weaker session guard than established pattern. Resolved immediately by adopting `!session?.user?.id` guard (same as agent/signature route added in 11-01).
+
+## User Setup Required
+None - no external service configuration required.
+
+## Next Phase Readiness
+- AGENT-04 complete: agent's saved PNG is baked into prepared PDFs before reaching the client
+- Client signing session unaffected — `isClientVisibleField()` already excludes `agent-signature` fields
+- Phase 12 (preview route) can proceed; Phase 13 (AI field placement) has no dependency on this plan
+- Functional verification (draw → save → prepare → download PDF and inspect embedded signature) is recommended before Phase 12
+
+---
+*Phase: 11-agent-saved-signature-and-signing-workflow*
+*Completed: 2026-03-21*