# Document Management

## Two Scopes, One Convention

All customer documents use phone-number scoping. Documents that customers receive go in the shared user folder. Internal business documents go in the admin-only folder.

| Scope | Path | Visibility | Use for |
|-------|------|-----------|---------|
| **Customer-facing** | `memory/users/{phone}/documents/` | Both agents can see | Invoices, quotes, contracts — anything sent to the customer |
| **Internal** | `memory/admin/customers/{phone}/` | Admin agent only | Research, pricing analysis, internal notes — never shared with customers |

## Directory Structure

### Customer-facing documents
```
memory/users/{phone}/documents/
  invoices/          <- Sent invoices (HTML + PDF pairs)
  quotes/            <- Sent quotes (HTML + PDF if formal, or markdown)
  contracts/         <- Signed contracts, terms
```

### Internal documents
```
memory/admin/customers/{phone}/
  research/          <- Background research, competitor analysis
  pricing-notes.md   <- Internal pricing decisions, cost calculations
  internal-notes.md  <- Admin-only observations, strategy notes
```

## Naming Convention

`{TYPE}-{YYYYMMDD}-{SLUG}.{ext}`

| Component | Rule | Example |
|-----------|------|---------|
| **TYPE** | 3-letter document type code | `INV`, `QUO`, `PRO`, `CON` |
| **YYYYMMDD** | Date of creation | `20260224` |
| **SLUG** | Customer name or project, uppercased, hyphens for spaces, max 20 chars | `MUVIN`, `KITCHEN-REFIT` |
| **ext** | File extension | `.html`, `.pdf`, `.md` |

**Type codes:**
- `INV` — Invoice
- `QUO` — Quote
- `PRO` — Proposal
- `CON` — Contract

**Examples:**
- `INV-20260224-MUVIN.html` / `INV-20260224-MUVIN.pdf`
- `QUO-20260301-KITCHEN-REFIT.html`
- `PRO-20260315-JENKINS-BATHROOM.html`

## Phone Number Scoping

Always use the full international format with `+` prefix: `+447734875155`

This matches the existing `memory/users/{phone}/` pattern used for profiles and conversations. The phone number in the folder path must match the phone number in the contact record.

## Print-Friendly HTML for PDF Conversion

All HTML documents intended for PDF conversion must include `@media print` styles and an `@page` directive. The PDF renderer uses the print stylesheet — without it, the output inherits screen styles with wrong sizing and no page control.

Required structure:
- `<!DOCTYPE html>` declaration
- `@media print` block: set `font-size: 12pt`, `line-height: 1.4`, `color: black`, `background: white !important`, and zero out any screen-only padding
- `@page { size: A4; margin: 1in; }` for correct page dimensions
- `page-break-inside: avoid` on tables, signature blocks, payment sections, and any content that should not split across pages
- `page-break-before: always` on section headings that should start a new page (e.g. legal terms, signature page)
- No external resources — all styles inline in a `<style>` block, images referenced by absolute local path

## Document Creation Workflow

1. Verify the customer's contact record exists (`contact_lookup`)
2. Create the appropriate directory if it doesn't exist (the `memory_write` tool creates parent directories automatically)
3. Write the document (HTML for invoices/quotes that need PDF conversion, markdown for simpler documents)
4. For HTML documents: convert to PDF using `document_to_pdf`
5. Update the contact record status via `contact_update`

## Sending Documents

Use the `message` tool with the PDF path as an attachment. The `message` parameter (caption) is required even for attachments — always include a brief message explaining what the document is.

> "Hi [customer], here's your invoice for [work description]. Payment details are included. Any questions, just let me know!"

## Classification Guide

**Customer-facing (shared scope):**
- Anything you would email or WhatsApp to the customer
- Invoices, quotes, proposals, contracts, receipts
- Documents the customer needs to reference

**Internal (admin scope):**
- Pricing calculations and margin analysis
- Research about a customer's property or business
- Notes about negotiation strategy
- Internal assessments ("quote high, this is a complex job")
- Anything you wouldn't want the customer to see
