red/.planning/phases/04-pdf-ingest/04-04-PLAN.md

---
phase: 04-pdf-ingest
plan: 04
type: execute
wave: 4
depends_on:
  - 04-01
  - 04-02
  - 04-03
files_modified: []
autonomous: false
requirements:
  - DOC-01
  - DOC-02
  - DOC-03
must_haves:
  truths:
    - "Agent can open 'Add Document' modal from a client profile page"
    - "Forms library list appears in the modal (either seeded forms or empty-state message)"
    - "Agent can search/filter the forms list by name"
    - "Agent can add a document via template selection and see it appear in the documents list"
    - "Agent can upload a custom PDF via the file picker and see it appear in the documents list"
    - "Agent can click a document name and reach the document detail page"
    - "PDF renders in the browser on the document detail page — pages visible, not blank"
    - "Page navigation (Prev/Next) and Zoom In/Out controls work"
    - "Download button downloads the PDF"
  artifacts:
    - path: "teressa-copeland-homes/uploads/clients/"
      provides: "Confirms files are being stored at the correct path"
  key_links:
    - from: "Client profile Add Document button"
      to: "Document detail page PDF render"
      via: "modal → POST /api/documents → documents list → /portal/documents/{id} → PdfViewer → /api/documents/{id}/file"
---

<objective>
Human verification of the complete Phase 4 PDF ingest flow. Agent (Teressa) confirms the end-to-end workflow works in the browser before Phase 4 is declared complete.

Purpose: Functional verification catches UI/UX issues that automated checks miss — blank PDFs, missing form items, broken nav controls.
Output: Phase 4 approved or issues logged for gap closure.
</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/phases/04-pdf-ingest/04-CONTEXT.md
</context>

<tasks>

<task type="checkpoint:human-verify" gate="blocking">
  <what-built>
    Complete Phase 4 PDF ingest pipeline:
    - forms_templates DB table + seed script (npm run seed:forms)
    - GET /api/forms-library — authenticated template list
    - POST /api/documents — creates document record + copies PDF to uploads/clients/{id}/
    - GET /api/documents/[id]/file — authenticated PDF streaming with path traversal protection
    - "Add Document" modal on client profile page with searchable library + file picker fallback
    - Document detail page with react-pdf viewer (page nav, zoom, download)
  </what-built>
  <how-to-verify>
    Run the dev server if not already running:
    ```
    cd teressa-copeland-homes && npm run dev
    ```

    **Step 1 — Seed a test form (if seeds/forms/ is empty):**
    - Download any real estate PDF (or use any PDF) and copy it to `teressa-copeland-homes/seeds/forms/purchase-agreement.pdf`
    - Run: `npm run seed:forms`
    - Confirm output: "Seeded 1 forms into form_templates."

    **Step 2 — Open a client profile:**
    - Log in at http://localhost:3000/login
    - Navigate to Clients, click on any client
    - Confirm: "Add Document" button is visible on the client profile page

    **Step 3 — Add document from library:**
    - Click "Add Document"
    - Confirm: modal opens with a searchable list (shows "purchase agreement" or whatever was seeded, OR "No forms found" if seeds are empty)
    - Type in the search box — confirm list filters
    - Click a form to select it — confirm document name pre-fills
    - Edit the name to something like "Test Purchase Agreement"
    - Click "Add Document"
    - Confirm: modal closes, new document appears in the documents list on the profile page

    **Step 4 — Add custom PDF via file picker:**
    - Click "Add Document" again
    - Click "Browse files" / the file input
    - Select any PDF from your computer
    - Confirm: name pre-fills from filename
    - Edit name, submit
    - Confirm: document appears in the list

    **Step 5 — View PDF in browser:**
    - Click a document name from the documents list
    - Confirm: navigates to `/portal/documents/{id}`
    - Confirm: PDF renders (pages visible — NOT blank white)
    - Confirm: "Prev" / "Next" buttons work for multi-page PDFs
    - Confirm: "Zoom In" / "Zoom Out" buttons change page size
    - Confirm: "Download" button downloads the PDF
    - Confirm: "Back to [Client Name]" link returns to the client profile

    **Step 6 — Verify file storage:**
    - Check that `teressa-copeland-homes/uploads/clients/{clientId}/` directory contains `.pdf` files
    - Confirm files persist after stopping and restarting the dev server

    **Step 7 — Verify authentication:**
    - In an incognito window (no session), try: http://localhost:3000/api/forms-library
    - Confirm: returns "Unauthorized" (not a PDF list)
    - Try: http://localhost:3000/api/documents/any-id/file
    - Confirm: returns "Unauthorized" (not a file)
  </how-to-verify>
  <resume-signal>
    Type "approved" if all 7 steps pass.
    Or describe any issues found (e.g., "PDF renders blank", "modal list empty", "upload fails").
  </resume-signal>
</task>

</tasks>

<verification>
All 7 verification steps pass as described above.
</verification>

<success_criteria>
Agent confirms: forms library accessible, document creation from template works, custom upload works, PDF renders with navigation controls, files stored in uploads/, unauthenticated API access blocked.
</success_criteria>

<output>
After completion, create `.planning/phases/04-pdf-ingest/04-04-SUMMARY.md`
</output>