Replace Vite/React scaffold with Go build spec

- AGENTS.md: build spec for Paperclip (constraints, conventions, 7 phases)
- docs/phase-1..7: per-phase work, DoD, out-of-scope, risks
- reference/: frozen decisions, stack+ports+budgets, content map, acceptance tests
- agents/: persona and security policy drafts
- Retires the React scaffold; history retained as record of the false start

docs/phase-5-ai-overlay.md

@@ -0,0 +1,82 @@
+# Phase 5 — Mode B console (the AI overlay)
+
+**Goal:** a prompt box that streams a short, cited answer and can take over the stage panel. The AI is a second driver for the same panel, not a second site.
+
+**Depends on:** Phase 3 (live URL), Phase 4 (corpus).
+
+---
+
+## Work
+
+### 5.1 Query path
+
+```
+question
+  → rate limit (per IP)
+  → CLASSIFY    fast tier   intent · injection score · off-topic · PII
+      ├─ refuse  → fixed message, zero model spend
+      └─ allow
+  → ROUTE       fast tier   which area(s) to search
+  → RETRIEVE    Qdrant (payload-filtered) + SQLite FTS5
+                → reciprocal rank fusion → cross-encoder rerank top-20 → top-5
+  → COMPOSE     mid tier    answer ONLY from context, inline citations
+  → VERIFY      citation presence + claim supported by context
+  → STREAM      SSE
+```
+
+Four nodes. If the graph needs more than four to work, stop and report — complexity growth here is the failure mode this project exists to avoid.
+
+### 5.2 Transport
+- `GET /api/ask` as Server-Sent Events.
+- Three event types: `token`, `meta` (route, timings, tokens, cost), `done`.
+- **Never buffer SSE.** Verify with `flush_interval -1` on the proxy if streams stall. No gzip on the API path.
+
+### 5.3 The console (the only client-side code in the project)
+One hand-written TypeScript island, ES modules, no framework, no bundler.
+
+- `xterm.js` console showing the pipeline live: route, retrieval count, timings, tokens, cost.
+- Prompt box with submit and stop.
+- Stage panel driven by the `token` stream — the driver built in Phase 2 §2.4.
+- Panel clears on new response and on navigation.
+- Footer strip: model · latency · tokens · cost.
+
+### 5.4 Citations
+- Every factual claim carries a citation to a `content/` page or artefact.
+- Citation URLs validated against the known-artefact allow-list; unknown URLs dropped, not rendered.
+- Answer shape: direct answer → specifics → evidence pointer → optional single suggestion (per `agents/persona.md`).
+
+### 5.5 Persona
+- Load `agents/persona.md` at runtime. It is a file, versioned, not a string in code.
+- Test the tone: a short answer, an honest "not in the corpus" answer, and a "here's the better example for your role" answer.
+
+---
+
+## Definition of Done
+
+- [ ] First token < 4 s; complete answer < 15 s at p90, measured and recorded.
+- [ ] Every claim in ten sample answers resolves to a real page or artefact. No dangling citations.
+- [ ] The panel is driven by the SSE stream without changes to layout code (proves Phase 2 §2.4 held).
+- [ ] The island is the **only** client-side application code; no framework, no bundler, no `node_modules`.
+- [ ] A and B do not drift: for any question, the answer's claims exist on the site.
+- [ ] SSE streams untruncated at p90 with no cancellation leak when the client disconnects.
+- [ ] All model calls go through OmniRoute; grep proves no direct provider call exists.
+- [ ] Asking an off-topic question produces a short refusal and costs nothing.
+
+---
+
+## Out of scope
+
+- Guardrail hardening, cost ceilings and the kill switch — **Phase 6**. Phase 5 runs with a permissive guard and no public traffic.
+- Voice input.
+- Hub `/ask` registration (a follow-on task, not this phase).
+
+---
+
+## Risks
+
+| Risk | Mitigation |
+|---|---|
+| Graph grows past four nodes | Hard review gate: report and justify before adding a fifth |
+| Panel refactor needed | Phase 2 §2.4 contract; if it fails, fix the panel contract, do not fork the UI |
+| Streaming stalls behind Caddy | Explicit flush settings; p90 measurement, not a spot check |
+| Answers drift from the site | Citation verification is a node, not a hope |