docs: create milestone v1.3 roadmap (3 phases, 16 requirements)

.planning/REQUIREMENTS.md

@@ -270,14 +270,31 @@ Which phases cover which requirements. Updated during roadmap creation.
 | DEPLOY-03 | Phase 17 | Complete |
 | DEPLOY-04 | Phase 17 | Complete |
 | DEPLOY-05 | Phase 17 | Complete |
+| TMPL-01 | Phase 18 | Pending |
+| TMPL-02 | Phase 18 | Pending |
+| TMPL-03 | Phase 18 | Pending |
+| TMPL-04 | Phase 18 | Pending |
+| TMPL-05 | Phase 19 | Pending |
+| TMPL-06 | Phase 19 | Pending |
+| TMPL-07 | Phase 19 | Pending |
+| TMPL-08 | Phase 19 | Pending |
+| TMPL-09 | Phase 19 | Pending |
+| TMPL-10 | Phase 20 | Pending |
+| TMPL-11 | Phase 20 | Pending |
+| TMPL-12 | Phase 20 | Pending |
+| TMPL-13 | Phase 20 | Pending |
+| TMPL-14 | Phase 20 | Pending |
+| TMPL-15 | Phase 20 | Pending |
+| TMPL-16 | Phase 20 | Pending |
 
 **Coverage:**
 - v1.0 requirements: 28 total — mapped to phases 1-7 — all Complete
 - v1.1 requirements: 17 total — mapped to phases 8-13 — 15 Complete, 2 In Progress (AI-01, AI-02)
 - v1.2 requirements: 16 total — mapped to phases 14-17 — all Pending
-- Total mapped: 61
+- v1.3 requirements: 16 total — mapped to phases 18-20 — all Pending
+- Total mapped: 77
 - Unmapped: 0
 
 ---
 *Requirements defined: 2026-03-19*
-*Last updated: 2026-04-03 — v1.2 traceability added (MSIGN-01–11 → Phases 14–16, DEPLOY-01–05 → Phase 17)*
+*Last updated: 2026-04-06 — v1.3 traceability added (TMPL-01–04 → Phase 18, TMPL-05–09 → Phase 19, TMPL-10–16 → Phase 20)*

.planning/ROADMAP.md

@@ -8,11 +8,14 @@ v1.1 extends the platform with AI-assisted field placement, expanded field types
 
 v1.2 extends the platform to multiple signers in parallel and ships a production-ready Docker Compose deployment with correct SMTP and secret injection.
 
+v1.3 adds a document template system — agent creates reusable field layouts with signer role labels and text hints, then applies them when starting new client documents so the same PDF never needs to be field-mapped from scratch.
+
 ## Milestones
 
 - ✅ **v1.0 Core Document Signing Platform** - Phases 1-7 (shipped 2026-03-21)
 - 🚧 **v1.1 Smart Document Preparation** - Phases 8-13 (in progress)
 - 📋 **v1.2 Multi-Signer and Deployment Hardening** - Phases 14-17 (planned)
+- 📋 **v1.3 Document Templates** - Phases 18-20 (planned)
 
 ## Phases
 
@@ -179,6 +182,14 @@ Plans:
 - [x] **Phase 16: Multi-Signer UI** - PreparePanel signer list, FieldPlacer signer assignment and color-coding, send-block validation, per-signer dashboard status (completed 2026-04-03)
 - [x] **Phase 17: Docker Deployment** - Three-stage Dockerfile, docker-compose.yml with named uploads volume and env_file secrets, health endpoint, SMTP fix (completed 2026-04-03)
 
+### 📋 v1.3 Document Templates (Planned)
+
+**Milestone Goal:** Agent creates reusable document templates with pre-placed fields (including AI auto-placement) so the same PDF never needs to be field-mapped from scratch for every client.
+
+- [ ] **Phase 18: Template Schema and CRUD API** - New `document_templates` table with Drizzle migration; list, create, rename, and soft-delete API routes
+- [ ] **Phase 19: Template Editor UI** - FieldPlacer `onPersist` abstraction, template editor page at `/portal/templates/[id]`, AI auto-place wired to template context, signer role label support, save template
+- [ ] **Phase 20: Apply Template and Portal Nav** - "Start from template" option in AddDocumentModal, apply operation with field snapshot and role-to-email mapping, text hint quick-fill, Templates portal nav section and list page
+
 ## Phase Details
 
 ### Phase 8: Schema Foundation and Signing Page Safety
@@ -359,10 +370,6 @@ Plans:
 - [ ] 16-04-PLAN.md — Dashboard N/M signed badge (signingTokens count query, DocumentsTable badge rendering)
 **UI hint**: yes
 
-
-
-
-
 ### Phase 17: Docker Deployment
 **Goal**: The application runs reliably in a Docker container on the production server — secrets are injected at runtime, email delivers correctly, uploaded files survive container restarts, and a health check confirms database connectivity
 **Depends on**: Phase 16
@@ -380,10 +387,48 @@ Plans:
 - [x] 17-02-PLAN.md — Dockerfile (three-stage, node:20-slim, linux/amd64), docker-compose.yml (env_file, DNS fix, named volume), .dockerignore, .env.production.example
 **UI hint**: no
 
+### Phase 18: Template Schema and CRUD API
+**Goal**: The `document_templates` table exists in the database and agents can create, rename, list, and soft-delete templates via API — every subsequent template feature depends on this foundation
+**Depends on**: Phase 17
+**Requirements**: TMPL-01, TMPL-02, TMPL-03, TMPL-04
+**Success Criteria** (what must be TRUE):
+  1. Agent can create a new template by selecting a PDF from the forms library — a `document_templates` row is inserted with the chosen `formTemplateId` FK and an empty field layout
+  2. Agent can rename a template and the new name is persisted and reflected immediately in the template list
+  3. Agent can delete a template — the row is soft-deleted (`archivedAt` set, not removed from DB) and disappears from the active list; no `ON DELETE CASCADE` touches any documents created from it
+  4. Agent can retrieve a list of all active templates showing form name and field count — archived templates are filtered out
+**Plans**: TBD
+**UI hint**: no
+
+### Phase 19: Template Editor UI
+**Goal**: Agent can open any template in a full field-placement editor, use AI auto-place, assign signer role labels instead of real emails, set text hints on text fields, and save the template — reusing the existing FieldPlacer component without duplication
+**Depends on**: Phase 18
+**Requirements**: TMPL-05, TMPL-06, TMPL-07, TMPL-08, TMPL-09
+**Success Criteria** (what must be TRUE):
+  1. Agent can open a template at `/portal/templates/[id]` and see the source PDF rendered with any previously saved fields overlaid — the editor uses the existing FieldPlacer drag-drop interface unchanged
+  2. Agent can click "AI Auto-place" in the template editor and fields are placed on the template (routed through a `/api/templates/[id]/ai-prepare` route, not the document route)
+  3. Signer assignment in the template editor accepts role labels ("Buyer", "Seller", "Agent") rather than email addresses — role strings are stored in the `signerEmail` slot and the editor does not reject them as invalid emails
+  4. Agent can set a text hint on any text field — the hint is stored in the template and is visible as a placeholder label in the editor
+  5. Agent can click Save and the current field layout (with role labels and text hints) is persisted to `document_templates.signatureFields` — a subsequent page reload shows the saved state
+**Plans**: TBD
+**UI hint**: yes
+
+### Phase 20: Apply Template and Portal Nav
+**Goal**: Agent can start any new client document from a saved template — all fields are pre-loaded with fresh IDs, roles map to real signer emails, text hints appear as quick-fill suggestions — and "Templates" is a top-level portal destination
+**Depends on**: Phase 19
+**Requirements**: TMPL-10, TMPL-11, TMPL-12, TMPL-13, TMPL-14, TMPL-15, TMPL-16
+**Success Criteria** (what must be TRUE):
+  1. "Start from template" tab is available in AddDocumentModal; agent can pick a template from the list and create a document with all template fields pre-loaded at their saved positions
+  2. Every field copied from the template has a freshly generated UUID — none of the template's original field IDs appear in the new document; editing the template afterward does not change the document's fields
+  3. Template signer roles are automatically pre-mapped to the client's contacts (first role to primary contact, second role to co-buyer if present); agent can override any mapping before sending
+  4. Text hints from the template appear as quick-fill suggestion buttons in the new document's PreparePanel
+  5. "Templates" appears in the portal top nav and `/portal/templates` lists all active templates with form name, field count, and last-updated date
+**Plans**: TBD
+**UI hint**: yes
+
 ## Progress
 
 **Execution Order:**
-Phases execute in numeric order: 1 → 2 → 3 → 4 → 5 → 6 → 7 → 8 → 9 → 10 → 11 → 11.1 → 12 → 12.1 → 13 → 14 → 15 → 16 → 17
+Phases execute in numeric order: 1 → 2 → 3 → 4 → 5 → 6 → 7 → 8 → 9 → 10 → 11 → 11.1 → 12 → 12.1 → 13 → 14 → 15 → 16 → 17 → 18 → 19 → 20
 
 | Phase | Milestone | Plans Complete | Status | Completed |
 |-------|-----------|----------------|--------|-----------|
@@ -406,3 +451,6 @@ Phases execute in numeric order: 1 → 2 → 3 → 4 → 5 → 6 → 7 → 8 →
 | 15. Multi-Signer Backend | v1.2 | 3/3 | Complete    | 2026-04-03 |
 | 16. Multi-Signer UI | v1.2 | 1/4 | Complete    | 2026-04-03 |
 | 17. Docker Deployment | v1.2 | 2/2 | Complete   | 2026-04-03 |
+| 18. Template Schema and CRUD API | v1.3 | 0/TBD | Not started | - |
+| 19. Template Editor UI | v1.3 | 0/TBD | Not started | - |
+| 20. Apply Template and Portal Nav | v1.3 | 0/TBD | Not started | - |

.planning/STATE.md

@@ -2,16 +2,16 @@
 gsd_state_version: 1.0
 milestone: v1.3
 milestone_name: Document Templates
-status: defining requirements
+status: roadmap defined
-stopped_at: Milestone v1.3 started — Document Templates
+stopped_at: v1.3 roadmap created — Phases 18-20 defined, ready for plan-phase 18
 last_updated: "2026-04-06T00:00:00.000Z"
 last_activity: 2026-04-06
 progress:
-  total_phases: 19
+  total_phases: 22
   completed_phases: 18
   total_plans: 58
   completed_plans: 57
-  percent: 100
+  percent: 82
 ---
 
 # Project State
@@ -24,10 +24,10 @@ See: .planning/PROJECT.md (updated 2026-04-03)
 
 ## Current Position
 
-Phase: 17 (docker-deployment) — EXECUTING
+Phase: 18 (template-schema-and-crud-api) — NOT STARTED
-Plan: 2 of 2
+Plan: 0 of TBD
-Status: Phase complete — ready for verification
+Status: Roadmap defined — awaiting plan-phase 18
-Last activity: 2026-04-03
+Last activity: 2026-04-06
 
 ## Note on v1.1
 
@@ -44,14 +44,25 @@ v1.2 (Multi-Signer and Deployment Hardening) roadmap is defined. Four phases pla
 
 Start v1.2 after Phase 13 Plan 04 completes: `/gsd:plan-phase 14`
 
+## Note on v1.3
+
+v1.3 (Document Templates) roadmap created 2026-04-06. Three phases planned:
+
+- Phase 18: Template Schema and CRUD API — `document_templates` table (Drizzle migration), GET/POST/PATCH/DELETE API routes, soft-delete pattern
+- Phase 19: Template Editor UI — FieldPlacer `onPersist` abstraction, template editor page, AI auto-place via `/api/templates/[id]/ai-prepare`, signer role label support, save
+- Phase 20: Apply Template and Portal Nav — "Start from template" in AddDocumentModal, field snapshot with fresh UUIDs, role-to-email mapping, text hint quick-fill, Templates nav + list page
+
+Start v1.3 with: `/gsd:plan-phase 18`
+
 ## Accumulated Context
 
 ### Roadmap Evolution
 
 - Phase 11.1 inserted after Phase 11: Agent and Client Initials (URGENT)
 - v1.2 roadmap created 2026-04-03: Phases 14-17 (Multi-Signer + Docker Deployment)
+- v1.3 roadmap created 2026-04-06: Phases 18-20 (Document Templates)
 
-Progress: [█████████████] 100% (13/13 phases complete — v1.1 scope)
+Progress: [████████████░░░] 82% (18/22 phases complete — counting v1.3 scope)
 
 ## Performance Metrics
 
@@ -189,6 +200,17 @@ Recent decisions affecting v1.1 work:
 - [v1.2 Research]: Neon connection pool set to max:5 — prevents connection exhaustion on free tier
 - [v1.2 Research]: @vercel/blob is a dead dependency — remove before Phase 17 to prevent accidental use in Docker deployment
 
+### v1.3 Pre-decisions (from research)
+
+- [v1.3 Research]: `document_templates` is a separate table from `form_templates` — form_templates is read-only seeded catalog; document_templates is agent-authored field layouts; FK from new to old
+- [v1.3 Research]: Template fields carry signer role labels ("Buyer", "Seller") in the signerEmail slot — the apply operation enforces a complete role-to-email map before DB INSERT; email format validation must not run during template editing
+- [v1.3 Research]: Field ID collision prevention is mandatory — stamp fresh crypto.randomUUID() on every field at apply time; template field IDs must never appear in documents
+- [v1.3 Research]: `hint` vs `textFillData` distinction — hint is a placeholder label stored in template; textFillData holds values burned into PDFs; never store hints in textFillData
+- [v1.3 Research]: Soft-delete only (`archivedAt` column) — no hard deletes; list API filters `archivedAt IS NULL`; documents.formTemplateId is lineage metadata only, no ON DELETE CASCADE
+- [v1.3 Research]: FieldPlacer `onPersist` callback is a non-breaking addition — existing document consumers pass no prop, behavior unchanged; template editor passes the callback to save to document_templates
+- [v1.3 Research]: `updatedAt` must be set explicitly in update queries — no DB trigger; follows existing pattern in all current tables
+- [v1.3 Research]: Single non-agent signer role auto-maps to assigned client email — reduces friction for solo-agent single-signer templates; agent can override
+
 ### Pending Todos
 
 None yet.
@@ -197,9 +219,10 @@ None yet.
 
 - [Phase 12 - CARRY FORWARD]: Deployment target confirmed as Docker (Phase 17 addresses this) — write-to-disk preview pattern is valid for self-hosted container
 - [Phase 13]: AI coordinate accuracy on real Utah forms is untested — integration test with full 20-page Utah REPC required before Phase 13 ships
+- [Phase 19 - PRE-DECISION NEEDED]: Confirm whether FieldPlacer has any `z.string().email()` or similar validation on `signerEmail` before Phase 19 begins — if so, introduce `mode: "template" | "document"` prop alongside `onPersist`
 
 ## Session Continuity
 
-Last session: 2026-04-03T22:58:03.579Z
+Last session: 2026-04-06T00:00:00.000Z
-Stopped at: Completed 17-02-PLAN.md — Dockerfile, docker-compose.yml, .dockerignore, .env.production.example, DEPLOYMENT.md
+Stopped at: v1.3 roadmap created — Phases 18-20 defined; ROADMAP.md, STATE.md, REQUIREMENTS.md updated
 Resume file: None