feat(rag): stream grounded RAG answers over SSE with source citations

Phase 03 (Story: Chat RAG Answer — happy path):
- app/rag/retriever.py: top-k cosine search + parent-doc selection with
  per-doc dedupe and BOR_MAX_CONTEXT_CHARS cap ([…truncated…] marker)
- app/rag/prompts.py: locked persona + HIGH/DEFLECT prompt builders
- app/rag/llm.py: LLMError + chat_stream (turbo, temp 0.4, max 700, stream)
- app/api/chat.py: POST /api/chat SSE — delta* then done{deflected,
  sources, suggestions}; query_log row + PLAN §9 per-turn log line;
  structured error event on mid-stream failure, JSON 503 when DB down
- frontend: SSE reader, live bubble streaming, source chips -> /sources.html,
  red role=alert banner, Send button state that always recovers
- fix(scaffold): [hidden] { display: none !important } — .kb-banner's
  display:flex was overriding the hidden attribute (banner always visible)
- tests: unit (retriever/prompts/sse/llm) + integration (real Postgres RAG
  turn, query_log, error + 503 paths, mid-turn failures) + Playwright story
  suite (grounded answer, log row, raw SSE shape); smoke placeholder test
  replaced with the real never-stale-button contract

app/rag/llm.py

@@ -1,7 +1,7 @@
 """Async OpenAI-compatible client for the self-hosted aipi endpoint (PLAN A5).
 
-Phase 02 adds the embeddings surface (the importer — and, from phase 03,
-retrieval — need it). Chat streaming lands in phase 03 on this same client.
+Provides the embeddings surface (importer, retrieval) and chat streaming
+(PLAN A15) for the RAG pipeline.
 
 Fail-loud rule (PLAN A6): the ``chunks.embedding`` column is fixed at 768
 dimensions when the table is created, so a model that returns a different
@@ -11,8 +11,11 @@ vectors that pgvector rejects.
 from __future__ import annotations
 
 import logging
+from collections.abc import AsyncIterator
+from typing import cast
 
 from openai import AsyncOpenAI
+from openai.types.chat import ChatCompletionMessageParam
 
 from app.config import Settings, get_settings
 
@@ -27,6 +30,10 @@ class EmbeddingDimensionError(EmbeddingError):
     """Embedding dimension != BOR_EMBEDDING_DIM — import must fail loudly."""
 
 
+class LLMError(RuntimeError):
+    """The chat-completions endpoint failed (network, HTTP, or mid-stream)."""
+
+
 # aipi's local embedding model rejects requests over ~1024 input tokens
 # ("input is too large to process"). Batch by estimated tokens, with a
 # safety margin under that cap — code-dense text can tokenize at ~3
@@ -157,6 +164,35 @@ class LLMClient:
         return out
 
     async def embed_one(self, text: str) -> list[float]:
-        """Convenience: embed a single text (retrieval path, phase 03)."""
+        """Convenience: embed a single text (retrieval path)."""
         (vec,) = await self.embed([text])
         return vec
+
+    async def chat_stream(self, messages: list[dict[str, str]]) -> AsyncIterator[str]:
+        """Stream assistant text deltas from the chat model (PLAN A5/A15).
+
+        ``stream=True`` against the OpenAI-compatible endpoint; yields only
+        non-empty ``delta.content`` pieces. Any failure (network, HTTP,
+        malformed stream) surfaces as :class:`LLMError` so the API layer can
+        turn it into an SSE ``error`` event instead of a hung request.
+        """
+        try:
+            # ``{role, content}`` dicts are exactly what the message params
+            # accept; the cast keeps pyright honest about the SDK's union.
+            stream = await self._client.chat.completions.create(
+                model=self.settings.llm_chat_model,
+                messages=cast("list[ChatCompletionMessageParam]", messages),
+                temperature=0.4,
+                max_tokens=700,
+                stream=True,
+            )
+            async for chunk in stream:
+                if not chunk.choices:
+                    continue
+                piece = chunk.choices[0].delta.content
+                if piece:
+                    yield piece
+        except LLMError:
+            raise
+        except Exception as e:  # noqa: BLE001 — wrap transport-level failures
+            raise LLMError(f"chat stream from {self.settings.llm_base_url} failed: {e}") from e