# Story: Chat RAG Answer (happy path)

**Phase:** `03_story_chat_rag.md` · **E2E:** `tests/e2e/test_chat_rag.py`

## Narrative

As **a user** (friend, colleague, future me), I want to ask Brain a question
about Reese's setup and get a grounded, chippy answer that points me at the
exact documentation — so I can actually *do* the thing.

- **Given** the knowledge base is imported and I type "How is my Kubernetes
  cluster set up?"
- **When** Brain embeds the question, retrieves the top chunks by cosine
  similarity, maps them to their parent documents, and feeds the **full
  document text** to `turbo`
- **Then** I see a streamed, upbeat answer that cites the source
  (`Homelab/kubernetes.md`), grounded in the doc's specifics (Talos,
  Cilium, the node list) — and never in anything the docs don't say.

## Acceptance criteria
1. `POST /api/chat` streams SSE: `delta` events then a final `done` event
   carrying `{deflected, sources[], suggestions[]}` (PLAN §4).
2. Retrieval: top-4 chunks (`BOR_TOP_K_CHUNKS`), cosine via pgvector
   `<=>`, score = 1 − distance.
3. Context assembly: top-2 **distinct documents** by best-chunk score, full
   content, capped at `BOR_MAX_CONTEXT_CHARS` with truncation marker.
4. System prompt = locked persona + HONESTY GATE rules (PLAN §6), with
   `<relevance>HIGH</relevance>` and `<documents>…</documents>`.
5. The answer arrives **streamed** (multiple deltas), rendered live.
6. Source chips (mono, `source/path`) render under the answer bubble.
7. Per-turn log line emitted (PLAN §9) and a `query_log` row inserted
   (`deflected=false`, top_score, sources, latency).
8. LLM/embedding failure → JSON/SSE error the UI turns into the error banner
   (no hang, no stale button).

## UI Visualization & Structure
- Chat column centered at 46rem (PLAN §7.1); user bubble right (brand
  indigo, white text ≥4.5:1), Brain bubble left (white, ink text, avatar 🧠).
- While generating: typing indicator → live-appended text (see
  loading-feedback story for the full state machine — this story only needs
  "deltas render as they arrive and the button is busy throughout").
- **Source chips:** pill, `font-family: mono`, `bg --brand-soft`,
  `color --brand-ink` (6.3:1), `max-width` + ellipsis; each shows
  `Homelab/kubernetes.md`. `aria-label` when truncated.
- Bubble content is safe-rendered markdown (escape-first local renderer —
  `<script>` in an LLM answer must NOT execute).
- On mobile the bubbles expand to ~92% width; chips wrap.

## Playwright Mapping Rule
**Test Scenario → `tests/e2e/test_chat_rag.py`** (mock LLM, seeded KB):
1. `test_on_topic_question_streams_grounded_answer` — type "How is my
   Kubernetes cluster set up?", submit; assert: answer bubble appears with
   streamed content (mock's answer references the question), a `.source-chip`
   containing `kubernetes.md` is present, send button returns to enabled
   "Send".
2. `test_chat_logs_query` — after the turn, `GET /api/health` is still ok AND
   (via a test-only detail: query the DB directly) a `query_log` row exists
   with `deflected=false` and sources including `kubernetes.md`.
3. `test_sse_stream_shape` — raw `httpx` streaming request to `/api/chat`:
   assert multiple `data:` delta events precede a `done` event with
   `deflected: false` and a non-empty `sources` list.