DEMO.md

# Boss demo — v2 (legacy UI + past-report mapping)

This guide is for **non-developers** testing the system in a browser.

Open **http://localhost:8000** for the full **legacy UI** (`index.html`), now wired to the v2 backend. A simplified UI is at **`/v2.html`**.

## What you are testing

- Surveyor **field notes** mapped onto **full paragraphs from your firm's past reports**
- Three AI levels: **minimum**, **medium**, **maximum**
- **Section photos** (up to 5 stored, 2 for AI vision)
- **Source attribution** — each section shows which past report, section, and paragraph it came from
- **DOCX export** with photos placed like past reports

## Start the demo (Docker)

1. Install [Docker Desktop](https://www.docker.com/products/docker-desktop/).
2. Copy `.env.example` to `.env` in the project root.
3. Set `OPENAI_API_KEY=sk-...` in `.env` (required for medium/maximum AI and photo vision; minimum works without it for basic mapping).
4. From the project folder:

```powershell
docker compose -f docker-compose.v2.yml up --build
```

5. Open **http://localhost:8000** in Chrome or Edge.

First startup may take 1–2 minutes while the operator template and reference documents are ingested.

## Start the demo (local Python)

```powershell
pip install -r backend/requirements.txt
$env:OPENAI_API_KEY = "sk-your-key"
$env:MASTER_TEMPLATE_AUTO_INGEST = "true"
$env:REFERENCE_AUTO_INGEST_ENABLED = "true"
uvicorn backend.main:app --reload --port 8000
```

Open http://localhost:8000

## Walkthrough for your boss

### 1. Sign in

- Tenant ID: `default` (recommended for first demo — uses pre-loaded template)
- Click **Register** once with any password (6+ characters), then **Log in** next time

New tenants are auto-provisioned from the default template but should upload their own past reports.

### 2. Setup — past reports

- Check the green **Ready** health line.
- If reference count is 0, upload 1–2 **completed survey DOCX/PDF** files (anonymised past reports).
- Click **Refresh list** to confirm filenames appear.

### 3. Notes

- Enter property type and tenure.
- Paste messy field notes, e.g.:

```
E2: concrete tile slipped south slope
D1: chimney mortar open at crown
```

- Choose **Minimum**, **Medium**, or **Maximum** AI.
- Click **Start report draft** (needed before photos).

### 4. Photos (optional)

- Expand a section (e.g. E2 Roof).
- Upload site photos.
- Click thumbnails to select up to **2 for AI** (gold border).

### 5. Preview & export

- **Generate preview** — review section text and **Source:** lines (past report + paragraph).
- **Download DOCX** — open in Word; check photos and source footnotes.

## Automated smoke test (engineers)

With the server running on port 8000:

```powershell
python scripts/demo_v2_http.py
```

Exit code 0 = demo path healthy.

## Troubleshooting

| Issue | Fix |
|-------|-----|
| "No past reports ingested" | Upload reference DOCX/PDF in step 1 |
| Preview fails with 400 | Ensure at least one reference document is ingested |
| Empty / generic sections | Upload past reports with matching section headings (E2, D1, etc.) |
| Vision not working | Set `OPENAI_API_KEY`; select 2 photos for AI |
| Slow first run | FAISS ingest + embedding model download on cold start |

## What is *not* in this demo UI

- **Proofread / Enhance** modes map to medium/maximum interference (same v2 engine).
- **Document manager / similarity** return empty stubs.
- **Notes file upload** (`extract-notes`) is stubbed — paste notes into section fields.
- Per-section async jobs are simulated; generation runs one v2 full-report pass per batch.

## Acceptance checklist (for sign-off)

- [ ] Health shows reference chunks > 0
- [ ] Notes about roof appear in roof section, not chimney
- [ ] Preview shows `Past report "…", section …, paragraph …`
- [ ] DOCX downloads and opens in Word
- [ ] Photos appear in relevant sections
- [ ] Sections with no notes keep past-report wording (for manual completion)