red/teressa-copeland-homes/.planning/research/FEATURES.md

# Feature Research

**Domain:** Document template system for real estate e-signing app — v1.3 Document Templates
**Researched:** 2026-04-06
**Confidence:** HIGH for DocuSign/PandaDoc/OpenSign template model (multiple sources); HIGH for real estate re-use patterns (domain confirmed by project context); MEDIUM for edge case behaviors (version-skew risk in competitor analysis)

---

## Scope Note

This file covers only the v1.3 milestone features. Prior features (forms library, drag-drop field placement, AI auto-place, agent signature, multi-signer document sending, signing flow) are already built and validated.

**New feature under research: Document Templates**

A template is a saved "shell" of a prepared document: PDF source + field layout + signer role assignments + text fill hints (label + blank, no filled values). When Teressa starts a document for a new client, she picks a template instead of a blank PDF. The document is created pre-loaded with all fields; she fills in client-specific text values and assigns signer emails, then sends.

---

## Feature Landscape

### Table Stakes (Users Expect These)

Features a real estate agent expects from any template system. Missing these makes v1.3 feel like it does not solve the re-use problem.

| Feature | Why Expected | Complexity | Notes |
|---------|--------------|------------|-------|
| Save a prepared document as a template | Core premise — if you cannot save the field layout you just placed, there is no product | MEDIUM | Agent places fields on a PDF (manually or via AI auto-place), names the template, clicks Save. Stores: formTemplateId (source PDF), signatureFields JSONB (field layout with types + signer roles), textFillData JSONB (hint labels only — no client values), template name. No new PDF copy needed — template references the existing form_templates record. |
| Template list in portal (browse, rename, delete) | DocuSign, PandaDoc, OpenSign all provide a template library as a first-class section. Agents cannot maintain templates without list management. | LOW | Separate "Templates" nav section. List shows template name, source form name, created date, field count. Rename (modal), delete (confirm dialog). Matches the existing ClientCard/ConfirmDialog UI pattern. |
| Apply template when adding a document to a client | This is the entire value delivery — one click to get a pre-loaded document instead of starting blank | MEDIUM | When agent creates a document for a client, offer: "Start from template" vs "Start from blank PDF." Picking a template copies the field layout to the new document record. Text fill hints show as placeholder/label in PreparePanel — not as filled values. Agent fills client-specific text and assigns signer emails, then sends as normal. |
| Field layout is copied, not referenced | A template is a snapshot, not a live link. Editing the template later must not retroactively change documents already in flight. | LOW | On apply: deep-copy signatureFields and textFillData hint labels into the new documents record. The template row is just a source — documents are independent after creation. This is the industry standard (DocuSign, OpenSign both copy on apply). |
| Signer roles (not emails) stored in template | Template cannot store a specific client's email — that changes every time. Templates store a role label ("Buyer", "Seller", "Agent") on each field. Agent assigns real emails to roles when applying the template. | MEDIUM | The existing SignatureFieldData already has `signerEmail?: string`. Templates will store role labels (e.g., "signer:buyer", "signer:seller") in this field instead of real emails. On apply, agent maps roles to real emails. For solo-agent, single-signer use case the mapping step can default to the client's email automatically. |
| Text fill hints (not filled values) | Template stores the label a field should be pre-filled with ("Property Address", "Client Name") but NOT the actual values. Values come from the client record on apply. | LOW | textFillData in the template stores `{ fieldId: "hint:propertyAddress" }` or similar hint keys. On apply, known hints (propertyAddress, clientName) auto-populate from the client record. Unknown hint labels surface as PreparePanel prompts. |
| Agent can re-edit template (update the field layout) | Agents refine templates over time. DocuSign supports template editing as a standard operation. | LOW | Template editor is the same FieldPlacer UI used for document preparation, opened against the template record instead of a live document. Save overwrites the template's signatureFields and textFillData. No versioning needed at v1. |

---

### Differentiators (Competitive Advantage)

Features specific to this app's real estate context that go beyond generic template systems.

| Feature | Value Proposition | Complexity | Notes |
|---------|-------------------|------------|-------|
| AI auto-place works in template editor | Teressa can create a new listing agreement template by clicking "Auto-Place Fields" — AI places all fields on the Utah UAR form in one step, then she saves as template. She never manually places again. | LOW | This is the existing AI auto-place feature run against a template context. No new AI code. The template editor reuses the same FieldPlacer + AI auto-place pipeline that already exists for document preparation. |
| Known hints auto-fill from client record on apply | When applying a template, fields with hint keys `clientName`, `propertyAddress`, `clientEmail`, `todayDate` are silently pre-populated from the client record and system date. Agent sees them already filled in PreparePanel. | MEDIUM | Maps hint keys to client record fields. Extensible as the client schema grows. Removes manual re-typing of the same values across every document for a given client/transaction. |
| "Create from existing document" | If Teressa already has a well-prepared document for a past client, she can promote it to a template — snapshotting its field layout (minus client-specific filled values) into a new template record. | LOW | API: `POST /templates { sourceDocumentId }`. Copy `signatureFields`, convert `textFillData` values to hint labels (or blank them), let agent rename and save. Avoids the need to re-place fields from scratch when a good example already exists. |
| Template name includes form name | Template list shows both the agent-assigned name ("Listing Agreement — Standard") and the underlying form name ("Exclusive Right to Sell Listing Agreement - UAR"). Disambiguates when agent has multiple templates for the same base form. | LOW | UI display only — no schema change. Template record already links to `formTemplateId` which joins to `form_templates.name`. |

---

### Anti-Features (Commonly Requested, Often Problematic)

| Feature | Why Requested | Why Problematic | Alternative |
|---------|---------------|-----------------|-------------|
| Template versioning | "I want to know what changed between v1 and v2 of my listing agreement template" | Adds schema complexity (version rows, diffs, rollback UI) with near-zero value for a single-agent shop managing ~10 templates. Real change history is in git for the app, not in the product for the agent. | v1: overwrite saves. If agent needs rollback, they re-create from a document that used the old layout. Add versioning in v2 only if specifically requested. |
| Template sharing / team templates | "Multiple agents at the brokerage should share templates" | PROJECT.md explicitly scopes this as a solo-agent tool. Multi-agent support is Out of Scope at v1. Adding sharing requires user roles, permissions, org scoping — a major architectural expansion. | v1: all templates belong to the authenticated agent (single user). |
| Template-level AI pre-fill with actual values | "The template should store the filled values, not just hints" | Templates must be client-agnostic. Storing actual values (Teressa's own name pre-filled, etc.) creates confusion when applied to a new client who needs different values. | Store only hint labels in the template. Actual values always come from the client record at apply time. |
| Template locking (prevent field edits after apply) | "Once I apply a template, the fields should be immutable" | Prevents legitimate corrections before sending. A wrong field position or wrong signer assignment discovered in PreparePanel requires fix-it access. | Documents created from a template are full editable drafts until sent. No locks. |
| Template categories / folder organization | "I need folders for Buyer templates, Seller templates, Addenda" | Premature hierarchy. Teressa has ~10-20 templates at most. A flat list with good names is sufficient. Folders add UI complexity for no meaningful benefit at this scale. | Rely on clear naming conventions ("Buyer — Exclusive Buyer Broker Agreement", "Seller — Listing Agreement"). Add filtering/folders in v2 if template count grows beyond ~20. |
| Public/shareable template links | "Send a template link for clients to self-initiate" | OpenSign supports this but it requires anonymous sessions, role self-assignment by the signer, and a completely different signing flow. It is a distinct product surface. | Out of scope for v1. All documents are still agent-initiated. |

---

## Feature Dependencies

```
[formTemplates table (existing — PDF library)]
    └──referenced by──> [document_templates table (new)]
                            └──enables──> [Template List UI]
                            └──enables──> [Template Editor (save/update)]
                            └──enables──> [Apply Template to Document]

[FieldPlacer + AI auto-place (existing v1.1)]
    └──reused by──> [Template Editor]
                        └──enables──> [AI auto-place in template context]

[documents table (existing)]
    └──extended by──> [templateId FK (nullable, new)]
                          └──enables──> [Apply Template to Document]
                          └──enables──> [Create Template from Existing Document]

[clients table (existing — propertyAddress, name, email)]
    └──feeds──> [Hint auto-fill on template apply]

[PreparePanel (existing)]
    └──receives──> [Pre-populated fields from template apply]
    └──receives──> [Hint-resolved values from client record]
```

### Dependency Notes

- **Template editor reuses FieldPlacer entirely:** No new field-placement UI is needed. The template editor opens FieldPlacer in a "template mode" context where the target is a `document_templates` record instead of a `documents` record. The only new code is the route and the save action.

- **Signer role mapping is required before fields can be copied:** On apply, each field's `signerEmail` role label ("signer:buyer") must be replaced with a real email address before the document is usable. For single-signer documents, this defaults to the client's email automatically. For multi-signer documents (v1.2 feature), agent maps roles to emails in a quick assignment step.

- **textFillData hint keys must be defined before auto-fill works:** The known hint key set (`clientName`, `clientEmail`, `propertyAddress`, `todayDate`) must be documented and stable. The PreparePanel must recognize hint keys and resolve them from the client record.

---

## MVP Definition

### Launch With (v1.3)

Minimum viable template system — must match what DocuSign and PandaDoc offer for the core save/reuse loop.

- [ ] `document_templates` table — stores template name, `formTemplateId` FK, `signatureFields` JSONB (with signer role labels, not emails), `textFillData` JSONB (hint keys only), `createdAt`, `updatedAt`
- [ ] Template list page in portal (`/portal/templates`) — shows name, source form, field count, created date; rename and delete actions
- [ ] Template editor — FieldPlacer opened in template context; Save button writes to `document_templates`; AI auto-place works the same as in document prep
- [ ] Apply template when creating a document — "Start from template" option in the new-document flow; copies fields to new document record; replaces signer role labels with real emails; resolves known hint keys from client record
- [ ] Agent can update a template — re-open template in editor, save overwrites (no versioning)

### Add After Validation (v1.x)

- [ ] "Create template from existing document" — promote a prepared document to a template after the agent confirms it; useful when good examples already exist in the system
- [ ] Template preview — read-only PDF view of the source form with field overlays, so agent can verify field layout before applying to a new client

### Future Consideration (v2+)

- [ ] Template versioning — change log, rollback — defer until agent has >10 templates and reports that overwrite saves cause pain
- [ ] Template sharing / team access — requires multi-agent architecture; out of scope for solo agent
- [ ] Template categories / folders — defer until template count makes flat list unwieldy (unlikely before ~20 templates)
- [ ] Public template links (client self-initiate) — distinct product surface; requires anonymous session handling
- [ ] Template usage analytics — "this template has been used 12 times" — low value for single-agent

---

## Feature Prioritization Matrix

| Feature | User Value | Implementation Cost | Priority |
|---------|------------|---------------------|----------|
| Save template (editor + save action) | HIGH | MEDIUM | P1 |
| Template list (browse, rename, delete) | HIGH | LOW | P1 |
| Apply template to new document | HIGH | MEDIUM | P1 |
| Field copy on apply (not live reference) | HIGH | LOW | P1 |
| Signer role labels in template | HIGH | LOW | P1 |
| Hint key auto-fill from client record | HIGH | MEDIUM | P1 |
| AI auto-place in template editor | HIGH | LOW (reuse) | P1 |
| Template update / re-edit | MEDIUM | LOW | P1 |
| Create template from existing document | MEDIUM | LOW | P2 |
| Template preview (read-only) | MEDIUM | LOW | P2 |
| Template versioning | LOW | HIGH | P3 |
| Template sharing | LOW | HIGH | P3 |

**Priority key:**
- P1: Must have for launch — defines whether v1.3 solves the re-use problem
- P2: Should have — reduces friction once core works
- P3: Future — defer until explicitly requested

---

## Competitor Feature Analysis

| Feature | DocuSign | PandaDoc | OpenSign (open source) | Our Approach |
|---------|----------|----------|------------------------|--------------|
| Template library | Dedicated "Templates" section, flat or folder organization | Dedicated "Templates" section, folder support | Dedicated "Templates" section, flat list | Flat list (`/portal/templates`), named by agent |
| Signer roles | Named roles ("Signer 1", "Agent") assigned at template creation; real emails assigned at send time | Variables + roles; variables can be pre-populated or left blank for sender | Named roles assigned at template creation; emails mapped on send | Role labels in `signerEmail` field ("signer:buyer"); mapped to real emails on apply |
| Field layout | Saved with template; editor is full drag-drop interface | Saved with template; drag-drop editor | Saved with template; same editor as document prep | Saved in `signatureFields` JSONB; template editor reuses existing FieldPlacer |
| AI field placement | Available in some tiers (2025) | Available via AI agents (separate product tier) | Not built-in; community feature requests | Existing AI auto-place pipeline reused directly in template editor |
| Apply to document | Copy fields to new envelope; sender fills recipient-specific data | "Use template" creates a new document; variables prompt for values | "Use template" creates a new document; signer emails assigned per send | Deep copy `signatureFields` + resolve hints from client record |
| Template editing | Full editor; overwrites existing template | Full editor; no versioning in standard tier | Edit available; overwrites | Overwrite save; no versioning at v1 |
| Versioning | Enterprise tier only | Not in standard tier | Not implemented in open source | v2+ if needed |
| Template sharing | Team/org templates in Business tier | Team templates with permission scoping | Shared templates supported | v2+ only; not in scope for solo agent |
| "Use existing doc as template" | Not standard; must recreate from scratch | "Save as template" from a document | Not documented in open source | P2 feature: "Create template from document" |

---

## Sources

- [DocuSign: Working with Templates](https://support.docusign.com/en/guides/ndse-user-guide-working-with-templates) — HIGH confidence
- [DocuSign: Learn Basics of How to Use a Template](https://www.docusign.com/en-gb/blog/learn-basics-of-e-signature-how-to-use-document-templates) — HIGH confidence
- [PandaDoc: Save Time with a Reusable Template](https://support.pandadoc.com/en/articles/9714616-save-time-with-a-reusable-template) — HIGH confidence
- [PandaDoc: Creating Dynamic Document Templates](https://www.pandadoc.com/blog/creating-dynamic-document-templates/) — MEDIUM confidence
- [OpenSign: Create Templates](https://docs.opensignlabs.com/docs/help/Templates/create-template/) — HIGH confidence
- [OpenSign: Use Template to Create Documents](https://docs.opensignlabs.com/docs/help/Templates/use-template/) — HIGH confidence
- [OpenSign: Manage Templates](https://docs.opensignlabs.com/docs/help/Templates/manage-templates/) — HIGH confidence
- [Xodo Sign: Document Templates for E-Signatures](https://eversign.com/features/templates) — MEDIUM confidence
- [BoldSign: Create eSignature Templates for Unlimited Reuse](https://boldsign.com/electronic-signature-features/templates/) — MEDIUM confidence
- [Adobe Sign: Apply a Form Field Template](https://helpx.adobe.com/sign/authoring/apply-field-template.html) — HIGH confidence
- Codebase audit: `src/lib/db/schema.ts` — confirmed `SignatureFieldData` interface, `documents.signatureFields` JSONB, `formTemplates` table, `textFillData` JSONB — HIGH confidence
- Codebase audit: `.planning/PROJECT.md` — confirmed solo-agent scope, v1.3 template goals, out-of-scope items — HIGH confidence

---
*Feature research for: Document template system — real estate signing portal*
*Researched: 2026-04-06*