enhance rag retrieval + summary

specs/004-rag-retrieval-quality/contracts/chat-api.md

@@ -0,0 +1,33 @@
+# API Contract: Chat (unchanged endpoints)
+
+**Branch**: `004-rag-retrieval-quality` | **Date**: 2026-04-06
+
+## No endpoint changes
+
+This feature makes no changes to the public API surface. All existing `/api/v1/chat/...` endpoints remain identical in path, method, request body, and response shape.
+
+## Message response — `sources` field addition
+
+The only observable change to callers is that each source entry in `Message.sources` gains an optional `refLabel` field. This is backwards-compatible (additive only).
+
+### Existing contract (unchanged)
+
+```
+POST /api/v1/chat/sessions/{sessionId}/messages
+Body: { "content": "..." }
+Response: Message { id, sessionId, role, content, sources: [...], createdAt }
+```
+
+### Source entry schema (additive change)
+
+Before:
+```json
+{ "type": "TEXT", "bookTitle": "...", "page": 142, "chunkText": "..." }
+```
+
+After (new optional field):
+```json
+{ "type": "TEXT", "refLabel": "S1", "bookTitle": "...", "page": 142, "chunkText": "..." }
+```
+
+Frontend consumers that ignore unknown fields are unaffected. `ChatMessage.vue` may optionally use `refLabel` for future inline citation linking.

specs/004-rag-retrieval-quality/contracts/topics-api.md

@@ -0,0 +1,68 @@
+# API Contract: Topics — Summary Persistence
+
+**Base path**: `/api/v1/topics`
+
+---
+
+## Existing endpoint (unchanged behaviour, extended response)
+
+### `POST /api/v1/topics/{id}/summary`
+
+Generates a new summary for the topic, **persists it**, and returns it.
+
+**Path param**: `id` — topic id (e.g. `intracranial-aneurysms`)
+
+**Response** `200 OK`:
+```json
+{
+  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
+  "summaryNumber": 3,
+  "topicId": "intracranial-aneurysms",
+  "topicName": "Intracranial Aneurysms",
+  "summary": "## Key Points\n...",
+  "sources": [
+    { "bookId": "uuid", "bookTitle": "Youmans & Winn", "page": 142 }
+  ],
+  "generatedAt": "2026-04-07T10:23:00Z"
+}
+```
+
+**Error responses**:
+- `404 Not Found` — topic id does not exist
+- `503 Service Unavailable` — no books ready (existing `NoKnowledgeSourceException`)
+
+---
+
+## New endpoints
+
+### `GET /api/v1/topics/{id}/summaries`
+
+Returns the list of saved summaries for a topic (no full text — list metadata only).
+
+**Path param**: `id` — topic id
+
+**Response** `200 OK`:
+```json
+[
+  { "id": "uuid-1", "summaryNumber": 1, "generatedAt": "2026-04-06T08:00:00Z" },
+  { "id": "uuid-2", "summaryNumber": 2, "generatedAt": "2026-04-06T09:15:00Z" }
+]
+```
+
+Ordered ascending by `summaryNumber`. Empty array if no summaries saved yet.
+
+**Error responses**:
+- `404 Not Found` — topic id does not exist
+
+---
+
+### `GET /api/v1/topics/{id}/summaries/{summaryId}`
+
+Fetches the full content of a specific saved summary.
+
+**Path params**: `id` — topic id, `summaryId` — summary UUID
+
+**Response** `200 OK`: same shape as `POST /summary` response above.
+
+**Error responses**:
+- `404 Not Found` — topic or summary not found