docs(07-02): complete download UI wiring plan — SUMMARY, STATE, ROADMAP updated

- 07-02-SUMMARY.md: documents PreparePanel Signed panel, agentDownloadUrl server-side generation, Date Signed column, and auto-fix of ClientProfileClient type mismatch
- STATE.md: advanced to Phase 7 plan 2 of 3, added 3 key decisions, logged metrics row
- ROADMAP.md: updated phase 7 progress (2/3 plans complete)

.planning/phases/07-audit-trail-and-download/07-02-SUMMARY.md

@@ -0,0 +1,127 @@
+---
+phase: 07-audit-trail-and-download
+plan: "02"
+subsystem: ui
+tags: [next.js, jwt, pdf, download, react, typescript]
+
+# Dependency graph
+requires:
+  - phase: 07-audit-trail-and-download
+    plan: "01"
+    provides: createAgentDownloadToken (5-min TTL, purpose:'agent-download') and GET /api/documents/[id]/download route
+  - phase: 06-signing-flow
+    provides: documents.signedAt and documents.signedFilePath columns written on signing completion
+provides:
+  - agentDownloadUrl generated server-side in document detail page and passed to PreparePanel
+  - PreparePanel Signed status: green panel with signed timestamp and Download Signed PDF anchor
+  - DocumentsTable Date Signed column showing signedAt for Signed documents
+  - Dashboard and client profile queries include signedAt
+affects:
+  - 07-03 (audit trail plan may need to reference download events or document detail state)
+
+# Tech tracking
+tech-stack:
+  added: []
+  patterns:
+    - agentDownloadUrl generated in server component (page.tsx) and passed as prop to 'use client' PreparePanel — token never created in client code
+    - PreparePanel status-aware rendering: Signed branch (green panel + anchor link), Sent/Viewed branch (read-only), Draft branch (prepare form)
+    - Download is a plain <a href> anchor — no fetch/onClick; Content-Disposition:attachment response from API route handles browser download dialog
+
+key-files:
+  created: []
+  modified:
+    - teressa-copeland-homes/src/app/portal/(protected)/documents/[docId]/_components/PreparePanel.tsx
+    - teressa-copeland-homes/src/app/portal/(protected)/documents/[docId]/page.tsx
+    - teressa-copeland-homes/src/app/portal/_components/DocumentsTable.tsx
+    - teressa-copeland-homes/src/app/portal/(protected)/dashboard/page.tsx
+    - teressa-copeland-homes/src/app/portal/_components/ClientProfileClient.tsx
+    - teressa-copeland-homes/src/app/portal/(protected)/clients/[id]/page.tsx
+
+key-decisions:
+  - "agentDownloadUrl generated in server component (page.tsx) not in PreparePanel — PreparePanel is 'use client' and cannot call createAgentDownloadToken"
+  - "Download button is a plain <a href> anchor (no JS handler) — browser follows link directly, Content-Disposition:attachment triggers save dialog"
+  - "signedAt propagated to both dashboard query and client profile query for consistent Date Signed display across all document tables"
+
+patterns-established:
+  - "Server-side token generation pattern: generate adt token in server component → pass as string URL prop to client component → client renders plain anchor"
+
+requirements-completed:
+  - SIGN-07
+  - LEGAL-03
+
+# Metrics
+duration: 2min
+completed: 2026-03-21
+---
+
+# Phase 7 Plan 02: Agent Download UI and signedAt Dashboard Column Summary
+
+**agentDownloadUrl generated server-side in document detail page, green Download Signed PDF panel added to PreparePanel for Signed status, and Date Signed column added to dashboard and client profile document tables**
+
+## Performance
+
+- **Duration:** 2 min
+- **Started:** 2026-03-21T16:37:02Z
+- **Completed:** 2026-03-21T16:39:16Z
+- **Tasks:** 2
+- **Files modified:** 6
+
+## Accomplishments
+- PreparePanel extended with `agentDownloadUrl` and `signedAt` props; Signed status renders a green panel with formatted signed timestamp and a plain anchor Download Signed PDF button
+- Document detail page (server component) now imports `createAgentDownloadToken`, generates `agentDownloadUrl` server-side for documents with `signedFilePath`, and passes it to PreparePanel — token never created in client code
+- `DocumentsTable` type updated with `signedAt: Date | null`; Date Signed column added to table header and rows (formatted as "Mar 21, 2026", America/Denver timezone)
+- Dashboard and client profile queries both select `signedAt` so all document tables display signed date
+
+## Task Commits
+
+Each task was committed atomically:
+
+1. **Task 1: Update PreparePanel props interface and add Download button for Signed status** - `b823ae5` (feat)
+2. **Task 2: Wire document detail page, update dashboard table for signedAt** - `68d94a7` (feat)
+
+## Files Created/Modified
+- `teressa-copeland-homes/src/app/portal/(protected)/documents/[docId]/_components/PreparePanel.tsx` - Extended interface with agentDownloadUrl/signedAt; added Signed branch (green panel + download anchor) before Sent/Viewed read-only branch
+- `teressa-copeland-homes/src/app/portal/(protected)/documents/[docId]/page.tsx` - Added createAgentDownloadToken import; generates agentDownloadUrl server-side; passes agentDownloadUrl and signedAt to PreparePanel
+- `teressa-copeland-homes/src/app/portal/_components/DocumentsTable.tsx` - Added signedAt to DocumentRow type; added Date Signed column header and cell
+- `teressa-copeland-homes/src/app/portal/(protected)/dashboard/page.tsx` - Added signedAt to db select
+- `teressa-copeland-homes/src/app/portal/_components/ClientProfileClient.tsx` - Added signedAt to local DocumentRow type (kept in sync with DocumentsTable)
+- `teressa-copeland-homes/src/app/portal/(protected)/clients/[id]/page.tsx` - Added signedAt to query select
+
+## Decisions Made
+- agentDownloadUrl is generated in the server component (page.tsx), not in PreparePanel — PreparePanel is a 'use client' component and cannot call `createAgentDownloadToken` (server-only)
+- Download button is a plain `<a href>` anchor, not a fetch/onClick handler — the API route's `Content-Disposition: attachment` header drives the browser download dialog
+- signedAt propagated to both dashboard and client profile tables for consistency — agents see signed date in all document views
+
+## Deviations from Plan
+
+### Auto-fixed Issues
+
+**1. [Rule 1 - Bug] Fixed DocumentRow type mismatch in ClientProfileClient and client profile page query**
+- **Found during:** Task 2 (TypeScript check after DocumentsTable update)
+- **Issue:** `ClientProfileClient.tsx` declares its own local `DocumentRow` type without `signedAt`; it passes `docs` to `DocumentsTable` which now requires `signedAt`. TypeScript error: "Property 'signedAt' is missing in type 'DocumentRow' but required in type 'DocumentRow'"
+- **Fix:** Added `signedAt: Date | null` to local `DocumentRow` in `ClientProfileClient.tsx`; added `signedAt: documents.signedAt` to the select in `clients/[id]/page.tsx`
+- **Files modified:** `src/app/portal/_components/ClientProfileClient.tsx`, `src/app/portal/(protected)/clients/[id]/page.tsx`
+- **Verification:** `tsc --noEmit` passes with zero errors; `npm run build` completes cleanly
+- **Committed in:** `68d94a7` (Task 2 commit)
+
+---
+
+**Total deviations:** 1 auto-fixed (Rule 1 - type mismatch caused by our DocumentsTable change)
+**Impact on plan:** Necessary fix — both files share the same DocumentRow type contract. No scope creep; client profile documents table now also shows Date Signed column, which is a bonus.
+
+## Issues Encountered
+
+None.
+
+## User Setup Required
+
+None - no external service configuration required.
+
+## Next Phase Readiness
+- Download UI is fully wired: agent can navigate to a Signed document detail page, see the green "Document Signed" panel with signed timestamp, and click "Download Signed PDF" to trigger browser download via the API route from Plan 01
+- Dashboard and client profile tables show Date Signed column for Signed documents, "—" for others
+- Phase 7 Plan 03 (audit trail) can build on the established download route and document state
+
+---
+*Phase: 07-audit-trail-and-download*
+*Completed: 2026-03-21*