## 1. Local Backend Setup

Actor
Developer / tester
Run Bash
run_documents_api.sh
Python available?
python3 or python
Venv exists?
.venv-documents-api
Install deps
FastAPI / Uvicorn / multipart
Start FastAPI
127.0.0.1:8010

### Python branch

YES
Continue to venv check.
NO
Stop. Backend cannot start.

### Venv branch

YES
Use existing local venv.
NO
Create `.venv-documents-api`, then install dependencies.

### Hosted entry

OK
Open browser at `http://127.0.0.1:8010/`.
NOT TARGET
Double-click `file://` has no backend persistence.

## 2. Browser To Backend Flow

Open hosted page
GET /
Serve HTML
DocumentsIntake.html
Select files
drag-drop or open dialog
POST upload
/api/documents

### Current implementation

NOTE
Backend endpoint exists.
OK
HTML calls `POST /api/documents`.

### Required behavior

TARGET
Browser submits selected files as multipart form data.
TARGET
Server returns JSON result to UI.

### Out of scope

NO
No browser File API persistence as final architecture.
NO
No silent file writes from `file://`.

## 3. Server-Side Persistence Conditions

Files present?
multipart payload
Documents exists?
./Documents
Filename collision?
same saved name
Resolve name
file_1.ext if needed
Save files
server-side ./Documents
Return JSON
status=saved

### Files present?

YES
Continue to folder check.
NO
Reject request. Nothing to persist.

### Documents exists?

YES
Use existing folder.
NO
Create `Documents` dynamically during upload.

### Filename collision?

NO
Save with original sanitized filename.
YES
Save with unique suffix, e.g. `file_1.ext`.

## 4. Verification Matrix

Contract | Current status | Evidence | Validation
--- | --- | --- | ---
Bash runner creates runtime and starts FastAPI. | PASS | `run_documents_api.sh` | Manual run / future smoke test.
Backend serves hosted HTML. | PASS | `documents_api.py`, `GET /` | GET `/` returns HTML.
Backend accepts and saves files to dynamic `Documents` folder. | PASS backend | `POST /api/documents` | API smoke test with multipart file.
Hosted HTML sends selected files to backend. | NEEDS E2E | `uploadToBackend()` uses `fetch('/api/documents')`. | Playwright e2e after implementation.

Green: implemented expected path Amber: condition or pending branch Blue: setup/backend action Red: stop / not target / TODO