From 7872b7cf95edbf7bba379e3b4007441441b5e791 Mon Sep 17 00:00:00 2001
From: Spencer Wozniak <spencerwozniak@gmail.com>
Date: Mon, 11 May 2026 22:45:24 -0700
Subject: [PATCH] docs: add per-feature reference notes for this branch
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

One markdown file per feature area introduced on this branch:

- README.md — index
- agentation.md — dev-only feedback overlay
- chat-backend-integration.md — ChatWidget ↔ /api/chat
- knowledge-base-ui.md — upload modal + KB browser
- in-chat-command-routing.md — shared detectView() and the
  capability section of the chat system prompt
- generation-endpoints.md — /api/generate/{flashcards,quiz}
- audio-generation.md — /api/generate/audio + TTS playback
- history-panel.md — live session list

Each doc has a "Files touched" section so reviewers can map features
to diffs quickly.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 docs/README.md                   |  33 ++++++
 docs/agentation.md               |  38 +++++++
 docs/audio-generation.md         | 167 +++++++++++++++++++++++++++++++
 docs/chat-backend-integration.md |  47 +++++++++
 docs/generation-endpoints.md     | 143 ++++++++++++++++++++++++++
 docs/history-panel.md            |  81 +++++++++++++++
 docs/in-chat-command-routing.md  |  74 ++++++++++++++
 docs/knowledge-base-ui.md        |  74 ++++++++++++++
 8 files changed, 657 insertions(+)
 create mode 100644 docs/README.md
 create mode 100644 docs/agentation.md
 create mode 100644 docs/audio-generation.md
 create mode 100644 docs/chat-backend-integration.md
 create mode 100644 docs/generation-endpoints.md
 create mode 100644 docs/history-panel.md
 create mode 100644 docs/in-chat-command-routing.md
 create mode 100644 docs/knowledge-base-ui.md

diff --git a/docs/README.md b/docs/README.md
new file mode 100644
index 0000000..73e4e11
--- /dev/null
+++ b/docs/README.md
@@ -0,0 +1,33 @@
+# Sage docs
+
+Reference notes for changes made on this branch (`add-backend-requirements-txt`)
+since the last commit on `main` (`92b46c8 build: add backend/requirements.txt`).
+Each file documents one feature area: what was added, where it lives, and how
+to use it.
+
+## Contents
+
+- [agentation-install.md](./agentation-install.md) — installing the Agentation
+  dev panel in the Next.js app.
+- [chat-backend-integration.md](./chat-backend-integration.md) — wiring
+  `ChatWidget` to the live `/api/chat` endpoint (replaces the simulated reply).
+- [knowledge-base-ui.md](./knowledge-base-ui.md) — the upload modal next to the
+  command bar and the `KnowledgeBaseWidget` for browsing ingested documents.
+- [in-chat-command-routing.md](./in-chat-command-routing.md) — shared verb
+  detection so the command bar *and* the chat input both route "quiz",
+  "flashcards", "knowledge", etc. to the right view.
+- [generation-endpoints.md](./generation-endpoints.md) — backend
+  `/api/generate/flashcards` and `/api/generate/quiz` plus the
+  `FlashcardsView` / `QuizView` wrappers that consume them.
+- [audio-generation.md](./audio-generation.md) — `/api/generate/audio`
+  narration scripts, OpenAI TTS synthesis, and the dual-mode
+  `AudioPlayerWidget` (`<audio>` element when TTS is available, browser
+  `SpeechSynthesis` otherwise).
+
+## Conventions used here
+
+- File paths are relative to the repository root.
+- Code snippets are illustrative — read the actual files for current source of
+  truth; this folder documents intent and shape, not exhaustive APIs.
+- Each doc has a **Files touched** list at the bottom so reviewers can map
+  features to diffs quickly.
diff --git a/docs/agentation.md b/docs/agentation.md
new file mode 100644
index 0000000..2f481bc
--- /dev/null
+++ b/docs/agentation.md
@@ -0,0 +1,38 @@
+# Agentation dev panel
+
+Added the [Agentation](https://www.agentation.com/install) overlay so feedback
+posted from the running app surfaces in this Claude Code session via the
+`mcp__agentation__*` tool family.
+
+## What it does
+
+- `npm install agentation -D` was run inside `frontend/`.
+- A small client wrapper (`AgentationDev`) renders `<Agentation />` only when
+  `process.env.NODE_ENV === "development"`, so the overlay never ships in a
+  production build.
+- The wrapper is mounted at the end of `<body>` in the root layout, after
+  `{children}`, to keep its DOM out of the app tree.
+
+## Files touched
+
+- `frontend/package.json` — added `agentation` to `devDependencies`.
+- `frontend/src/components/AgentationDev.tsx` — new, dev-only wrapper.
+- `frontend/src/app/layout.tsx` — imports and renders `<AgentationDev />`.
+
+## Optional MCP server
+
+The npm package exposes a UI overlay only. To expose the agent feedback bridge
+to a CLI agent (Claude Code), the user runs the MCP install separately —
+this repo does not commit the server config:
+
+```
+npx agentation-mcp init      # interactive setup
+npx agentation-mcp doctor    # verify
+```
+
+The default MCP server listens on `http://localhost:4747`. If you want the
+React panel to talk to a non-default endpoint, pass it explicitly:
+
+```tsx
+<Agentation endpoint="http://localhost:4747" />
+```
diff --git a/docs/audio-generation.md b/docs/audio-generation.md
new file mode 100644
index 0000000..5468df5
--- /dev/null
+++ b/docs/audio-generation.md
@@ -0,0 +1,167 @@
+# Audio (TTS) generation
+
+The audio view used to render a hard-coded `SAMPLE_TRACK` and fake playback
+with a `setInterval` timer. It now generates a real, KB-grounded narration
+script and plays actual audio.
+
+## End-to-end flow
+
+1. User types something containing `audio`, `listen`, or `podcast` (in the
+   command bar or in chat). The prompt is captured as `generationPrompt`.
+2. `<AudioView prompt={generationPrompt} />` renders a loading card and
+   `POST`s to `/api/generate/audio`.
+3. Backend retrieves KB chunks (semantic search if a topic is given, random
+   sample otherwise — same helper as flashcards/quiz), prompts the configured
+   provider for a spoken-style script, and splits it into sentence segments
+   with estimated timings (~2.5 words/sec).
+4. If an OpenAI API key is configured, the backend also synthesizes the
+   script to an MP3 via OpenAI TTS (`tts-1`) and caches it to disk; the
+   response includes `audio_url: "/api/audio/{id}.mp3"`.
+5. If no key is configured, `audio_url` is `null` and the frontend falls
+   back to the browser's `SpeechSynthesis` API for playback.
+6. `AudioPlayerWidget` plays the real `<audio>` element or speaks via
+   `SpeechSynthesis`, advances the transcript highlight in lockstep, and
+   updates the "Download" affordance accordingly.
+
+## Backend
+
+### `POST /api/generate/audio`
+
+Request:
+
+```json
+{
+  "topic": "string | null",
+  "tome_id": "string | null",
+  "voice": "alloy | echo | fable | onyx | nova | shimmer | null",
+  "provider": "string | null",
+  "model":    "string | null"
+}
+```
+
+Response:
+
+```json
+{
+  "id":       "<audio_id or local-…>",
+  "title":   "Audio: <topic>",
+  "voice":    "alloy" | "Browser",
+  "provider": "<resolved>",
+  "model":    "<resolved>",
+  "script":   "Full narration…",
+  "segments": [{"id":"s1","text":"…","startTime":0.0,"endTime":4.4}, …],
+  "duration": 217.8,
+  "audio_url": "/api/audio/<id>.mp3" | null,
+  "sources":  [{"document_id":"…","document_title":"…","chunk_index":3,
+                "similarity":0.81}, …],
+  "topic":    "<echoed>"
+}
+```
+
+- Segments are produced by a simple sentence regex; durations are
+  proportional to word count. They are not word-accurate but are good
+  enough for transcript scroll-lock.
+- `voice` is the OpenAI TTS voice that was used. Defaults to `alloy`.
+  Unknown voices are coerced to `alloy`. When no OpenAI key is present,
+  the response labels it `Browser` so the UI can show a "Browser TTS"
+  badge in place of the Download button.
+
+### `GET /api/audio/{audio_id}.mp3`
+
+Streams a previously-synthesized file from
+`SAGE_AUDIO_CACHE` (defaults to `/tmp/sage_audio`). The id is validated
+against `[a-f0-9-]{8,}` to keep the route from being abused as a
+directory traversal.
+
+### Empty KB
+
+Same behavior as the other generation endpoints: if the user's KB (or the
+scoped tome) has no chunks, the endpoint returns `400` with a pointer to
+the upload button.
+
+### Helper reuse
+
+`backend/api/audio.py` imports `_gather_context` and `_empty_kb_error`
+from `backend/api/generate.py` (the underscore is a hint, not a hard
+boundary). A new `llm_text(...)` helper in `generate.py` does a plain
+content-only completion (no JSON-mode), used by audio for the narration
+script.
+
+## Frontend
+
+### `AudioPlayerWidget`
+
+Two new props:
+
+- `audioUrl?: string | null` — when set, a hidden `<audio>` element is
+  rendered and used as the playback source of truth (`timeupdate` /
+  `ended` events drive `currentTime` and `isPlaying`).
+- `script?: string` — full narration text. Used by the
+  `SpeechSynthesis` fallback so it can speak the remaining text after a
+  seek (it can't restart mid-utterance).
+
+Playback semantics differ a bit between the two modes:
+
+|                   | `<audio>` mode                  | SpeechSynthesis mode              |
+|-------------------|---------------------------------|------------------------------------|
+| Play / pause      | `el.play()` / `el.pause()`      | `synth.speak()` / `synth.cancel()` |
+| Seek bar          | Sets `el.currentTime`           | Cancels and restarts speech from the nearest segment |
+| ±15s buttons      | Same as seek                    | Same as seek                       |
+| Transcript timing | Driven by `timeupdate`          | Driven by a 100ms interval and word-count-based segment times |
+| Footer affordance | `<a download>` for the MP3      | "Browser TTS" pill                 |
+
+### `AudioView`
+
+Same shape as the existing `FlashcardsView` / `QuizView` — loading,
+error-with-retry, and success states. The sources footer lists distinct
+source document titles.
+
+### API client
+
+`generateAudio({ topic, tomeId, voice, provider, model })` in
+`frontend/src/lib/sage-api.ts` returns an `AudioGeneration`. A small
+`resolveAudioUrl(path)` helper joins the relative audio path with the
+active API base (so it works both from the Next.js dev server hitting
+`http://localhost:8000` and the Tauri sidecar on `http://127.0.0.1:8080`).
+
+## Limitations
+
+- Word-level subtitle accuracy isn't possible from `/v1/audio/speech`;
+  segment timings are an estimate. They're tightly correlated to the
+  actual playback rate for `tts-1`, but a long sentence with technical
+  jargon will lag slightly.
+- The MP3 cache is on local disk (`/tmp/sage_audio` by default). Nothing
+  evicts it — fine for dev, but a long-running deployment will want a
+  TTL / size cap.
+- No streaming yet: the user waits for the script to finish generating
+  *and* the MP3 to finish synthesizing before playback can start. Could
+  be split into "play once script is ready (SpeechSynthesis)" while the
+  MP3 synthesizes in the background, but that's a follow-up.
+
+## Files touched
+
+### Backend
+
+- `backend/api/audio.py` (new) — narration + TTS endpoints.
+- `backend/api/generate.py` — added `llm_text(...)` helper.
+- `backend/api/chat.py` — updated the "audio" capability description in
+  the system prompt so the agent stops calling it a sample track.
+- `backend/main.py` — `include_router(audio.router)`.
+
+### Frontend
+
+- `frontend/src/components/AudioPlayerWidget.tsx` — added `audioUrl` and
+  `script` props, real `<audio>` mode, SpeechSynthesis fallback,
+  conditional Download / Browser-TTS badge.
+- `frontend/src/components/AudioView.tsx` (new) — fetch wrapper with
+  loading/error states and source footer.
+- `frontend/src/lib/sage-api.ts` — added `generateAudio`, `AudioGeneration`,
+  `AudioSegment`, `resolveAudioUrl`.
+- `frontend/src/app/page.tsx` — uses `<AudioView />` in the audio view-state;
+  audio prompts are stored in `generationPrompt` like flashcards/quiz.
+
+## How to enable server-side TTS
+
+Set `OPENAI_API_KEY` in the backend's environment (or `openai.api_key` in
+`SageConfig`). The endpoint will automatically synthesize MP3s; otherwise
+playback uses the browser voice with no extra setup.
diff --git a/docs/chat-backend-integration.md b/docs/chat-backend-integration.md
new file mode 100644
index 0000000..764860d
--- /dev/null
+++ b/docs/chat-backend-integration.md
@@ -0,0 +1,47 @@
+# Chat backend integration
+
+`ChatWidget` previously faked replies with a `setTimeout` that echoed the
+user's message back. It now drives a real round-trip against the FastAPI
+`/api/chat` endpoint via the existing `sendChat()` helper in
+`frontend/src/lib/sage-api.ts`.
+
+## Behavior
+
+- The widget tracks a `sessionId` returned from the first request and reuses
+  it on follow-up turns, so the backend can persist the conversation in
+  `KnowledgeStore`.
+- The typing indicator now reflects actual backend latency instead of a
+  hard-coded 1.5s delay.
+- Backend errors are surfaced inline as an assistant-style message
+  (`**Error reaching backend:** …`) instead of being swallowed.
+- A new `initialQuery` prop lets the parent auto-send a prompt on mount —
+  this is how `page.tsx` forwards the user's first command-bar query into
+  the chat view.
+- Optional `tomeId` / `provider` / `model` props pass through to `sendChat`
+  for future tome-aware UI.
+
+## Provider/model badge
+
+`ChatWidget` and `CommandBar` both call `getRuntimeConfig()`
+(`GET /api/config`) on mount to label the current provider/model in the
+header pill, instead of the hard-coded "GPT-4o" string.
+
+## Files touched
+
+- `frontend/src/components/ChatWidget.tsx` — replaced simulated reply with
+  `sendChat()`, added session/loading/error state, `initialQuery`,
+  `onCommand` (see [in-chat-command-routing.md](./in-chat-command-routing.md)).
+- `frontend/src/components/CommandBar.tsx` — model label is now driven by
+  `getRuntimeConfig()`.
+- `frontend/src/app/page.tsx` — tracks the user's command-bar prompt and
+  forwards it to `ChatWidget` as `initialQuery`.
+
+## Running locally
+
+1. Backend: `cd backend && python main.py` (defaults to port 8000).
+2. Frontend: `cd frontend && npm run dev` (defaults to port 3000).
+
+CORS for `http://localhost:3000` is already allowed in `backend/main.py`.
+The `/api/chat` endpoint uses whichever provider is configured as
+`providers.default` in `SageConfig` (Ollama by default); see
+`backend/config.py` for the per-provider settings.
diff --git a/docs/generation-endpoints.md b/docs/generation-endpoints.md
new file mode 100644
index 0000000..a219437
--- /dev/null
+++ b/docs/generation-endpoints.md
@@ -0,0 +1,143 @@
+# Generation endpoints: flashcards & quizzes
+
+Previously `FlashcardWidget` and `QuizWidget` rendered hard-coded
+`SAMPLE_FLASHCARDS` / `SAMPLE_QUESTIONS` regardless of what the user typed.
+Two new backend endpoints generate real artifacts grounded in the knowledge
+base, and two new view wrappers (`FlashcardsView`, `QuizView`) consume them.
+
+## Backend: `backend/api/generate.py`
+
+Single router mounted at `/api/generate`, registered from
+`backend/main.py`.
+
+### `POST /api/generate/flashcards`
+
+Request body (all fields optional except by validation):
+
+```json
+{
+  "topic": "string | null",
+  "tome_id": "string | null",
+  "count": 6,
+  "provider": "string | null",
+  "model":    "string | null"
+}
+```
+
+Response:
+
+```json
+{
+  "cards": [{"id": "fc-…", "front": "…", "back": "…"}],
+  "topic": "…",
+  "sources": [
+    {"document_id": "…", "document_title": "…", "chunk_index": 0,
+     "similarity": 0.812}
+  ]
+}
+```
+
+`count` is clamped to `[1, 20]`.
+
+### `POST /api/generate/quiz`
+
+Same request shape. Response:
+
+```json
+{
+  "questions": [
+    {"id": "q-…",
+     "question": "…",
+     "options": [{"id":"a","text":"…"}, …],
+     "correctOptionId": "b",
+     "explanation": "…"}
+  ],
+  "topic": "…",
+  "sources": [ … ]
+}
+```
+
+`count` is clamped to `[1, 15]`. Each question is validated to have ≥2
+options and a `correctOptionId` matching one of them; questions that fail
+validation are dropped before responding.
+
+### How grounding works
+
+`_gather_context()` decides what excerpts to feed the model:
+
+1. If `topic` is non-empty, it runs the existing `SearchDocsSkill` (semantic
+   search over chunk embeddings, optionally scoped to the tome) and uses
+   the top results.
+2. If no topic — or the semantic search returned nothing — it falls back to
+   a random sample of chunks from the tome (or the whole KB if no tome is
+   set). This is what lets a bare "make flashcards" command still work.
+3. If the KB has zero chunks in scope, the endpoint returns `400` with a
+   hint to upload documents first.
+
+### How the JSON is produced
+
+`_llm_json()` calls the configured provider via `providers/factory.py`
+with no tools and a strongly-worded system prompt. For OpenAI-compatible
+providers (`openai`, `deepseek`) it also passes
+`response_format={"type": "json_object"}`. The model output is then run
+through `_extract_json()`, which tries (in order):
+
+1. Any ` ```json … ``` ` fenced blocks.
+2. The whole stripped response.
+3. The widest `{ … }` or `[ … ]` substring.
+
+If nothing parses, the endpoint returns `502` with the parser error so
+the UI can surface a useful retry.
+
+## Frontend wrappers
+
+- `frontend/src/components/FlashcardsView.tsx` — calls `generateFlashcards`,
+  shows a loading card, an error card with retry, or `FlashcardWidget`
+  with the real cards. Appends a "Grounded in:" footer listing distinct
+  source document titles.
+- `frontend/src/components/QuizView.tsx` — mirror of the above for
+  `generateQuiz` + `QuizWidget`.
+
+`page.tsx` renders these instead of the original widgets in the
+`"flashcards"` / `"quiz"` view-states, passing the user's command text in
+as `prompt`. The same `prompt` is captured whether the user invoked the
+verb from the command bar or from inside the chat (see
+[in-chat-command-routing.md](./in-chat-command-routing.md)).
+
+### API client
+
+`frontend/src/lib/sage-api.ts` exposes:
+
+- `generateFlashcards(opts)` → `FlashcardGeneration`
+- `generateQuiz(opts)` → `QuizGeneration`
+
+Both share `GenerateOpts = { topic?, tomeId?, count?, provider?, model? }`
+and `GeneratedSource` shape.
+
+## Limitations
+
+- Generation latency depends entirely on the configured provider/model. The
+  defaults (`ollama` + `llama3.1:8b`) need a local Ollama server running;
+  if it's unreachable the error surfaces in the view's error card.
+- The "topic" is currently the verbatim command string ("make flashcards on
+  attention"). The model is told what to do via the system prompt, so this
+  works, but a smarter parse (e.g., stripping the verb) would tighten the
+  retrieval query.
+- No persistence yet — generated flashcards and quizzes only live in the
+  view's React state and are regenerated on every visit.
+
+## Files touched
+
+### Backend
+
+- `backend/api/generate.py` (new) — router with both endpoints.
+- `backend/main.py` — import + `include_router(generate.router)`.
+
+### Frontend
+
+- `frontend/src/lib/sage-api.ts` — added `generateFlashcards`,
+  `generateQuiz`, and matching types.
+- `frontend/src/components/FlashcardsView.tsx` (new).
+- `frontend/src/components/QuizView.tsx` (new).
+- `frontend/src/app/page.tsx` — uses the new view wrappers; tracks
+  `generationPrompt`; added `\btest(s|ing)?\b` to the quiz route.
diff --git a/docs/history-panel.md b/docs/history-panel.md
new file mode 100644
index 0000000..d8dc866
--- /dev/null
+++ b/docs/history-panel.md
@@ -0,0 +1,81 @@
+# History panel
+
+The history view (`HistoryPanel.tsx`) used to render a hard-coded
+`SAMPLE_HISTORY` array. It now reads live chat-session data from the
+backend so every conversation the user has had with Sage shows up here.
+
+## Data flow
+
+```
+HistoryPanel ──▶ listChatSessions()      (src/lib/sage-api.ts)
+              ──▶ GET /api/chat/sessions (backend/api/chat.py)
+              ──▶ KnowledgeStore.list_sessions()
+                      (backend/store/db.py — SQL over sessions + messages + tomes)
+```
+
+## Backend
+
+### `KnowledgeStore.list_sessions(limit=100)`
+
+Single SQL query over `sessions`, `messages`, and `tomes`. For each
+session it returns:
+
+| field                | source                                              |
+| -------------------- | --------------------------------------------------- |
+| `id`                 | `sessions.id`                                       |
+| `tome_id`            | `sessions.tome_id`                                  |
+| `tome_name`          | `tomes.name` via `LEFT JOIN`                        |
+| `provider`, `model`  | `sessions.provider`, `sessions.model`               |
+| `created_at`         | `sessions.created_at`                               |
+| `first_user_message` | earliest `messages.content` with `role='user'`      |
+| `last_message_at`    | most recent `messages.created_at` (or session ts)   |
+| `message_count`      | `COUNT(*)` of messages in the session               |
+
+Results are sorted by `last_message_at DESC` so the freshest activity
+appears first.
+
+### `GET /api/chat/sessions?limit=<n>`
+
+Thin FastAPI wrapper around `list_sessions`. Returns
+`{ "sessions": [...] }`. Default `limit` is 100, the same as the store.
+
+## Frontend
+
+### `listChatSessions()` (src/lib/sage-api.ts)
+
+Typed client wrapper that returns `ChatSessionSummary[]`. The shape
+mirrors the backend dict exactly.
+
+### `HistoryPanel` (src/components/HistoryPanel.tsx)
+
+- On mount, fetches up to 200 sessions.
+- Filters out sessions with `message_count === 0` or no
+  `first_user_message` — those are stub sessions created by the chat
+  endpoint that never received a user turn.
+- Derives a row title from the first user message (truncated to 90
+  chars, first line only).
+- Groups rows into "Today", "Yesterday", "Earlier this week", "Older"
+  buckets using local time. The bucket label and per-row timestamp
+  share a single `formatTimestamp` helper so they stay consistent.
+- Search input filters by title or tome name (client-side).
+- Empty/loading/error states are handled inline.
+- `onSelect` is still exposed as a prop for the eventual "resume this
+  session" hand-off, but `page.tsx` does not yet pass one — clicking a
+  row is a no-op for now.
+
+## SQLite timestamp gotcha
+
+`sessions.created_at` defaults to `datetime('now')`, which returns
+`YYYY-MM-DD HH:MM:SS` in UTC with no `Z` suffix. `Message.created_at`
+uses Python `datetime.utcnow().isoformat()` which *does* include a `T`.
+`formatTimestamp` normalises both forms before constructing a `Date`,
+so mixed records render correctly.
+
+## Why no quiz / flashcard / audio / report rows yet?
+
+The schema only persists chat sessions. Quiz and flashcard generations
+are stateless POSTs (`/api/generate/...`) — nothing is written to disk.
+Audio and report views still render sample fixtures. When any of those
+gain server-side persistence, extend `list_sessions` (or add sibling
+endpoints) and widen the `HistoryItem["type"]` union — the `ICONS` map
+already follows that shape.
diff --git a/docs/in-chat-command-routing.md b/docs/in-chat-command-routing.md
new file mode 100644
index 0000000..476eec1
--- /dev/null
+++ b/docs/in-chat-command-routing.md
@@ -0,0 +1,74 @@
+# In-chat command routing
+
+The verb router used to live only in the command bar. Once the user was in
+the chat view, typing "make flashcards on attention" into the chat textarea
+went straight to `/api/chat` and came back as markdown describing flashcards,
+instead of switching to the flashcards view.
+
+This refactor lifts the verb-detection logic into a shared
+`detectView(text)` helper at the page level and exposes it to `ChatWidget`
+through an `onCommand` callback.
+
+## Behavior
+
+- `detectView(text)` returns one of the non-chat view states (or `null`).
+  Supported keyword groups:
+
+  | Keyword(s)                                                  | View         |
+  |-------------------------------------------------------------|--------------|
+  | `quiz`, whole-word `test` / `tests` / `testing`             | `quiz`       |
+  | `flashcard`, `flash card`                                   | `flashcards` |
+  | `audio`, `listen`, `podcast`                                | `audio`      |
+  | `report`, `study guide`, `summary`                          | `report`     |
+  | `history`                                                   | `history`    |
+  | `tome`, `collection`, `library`                             | `tomes`      |
+  | `knowledge`, `kb`, `docs`, `documents`, `knowledge base`, … | `knowledge`  |
+
+  Anything else falls through to chat.
+
+- `page.tsx` passes `handleChatCommand(text)` into `ChatWidget` as
+  `onCommand`. Inside `ChatWidget`, `handleSend` (and the `initialQuery`
+  effect) call `onCommand?.(text)` first — if it returns `true`, the chat
+  call is skipped and the page has already switched view.
+
+- For `quiz` / `flashcards`, the matching prompt is also stored as
+  `generationPrompt` so `FlashcardsView` / `QuizView` can pass it as the
+  `topic` to the generation endpoints. See
+  [generation-endpoints.md](./generation-endpoints.md).
+
+## Agent self-awareness of routing
+
+The frontend intercepts and routes verb-containing prompts *before* they
+reach the chat endpoint, so the chat model never actually executes a
+"make flashcards" instruction itself. But users still ask "what can you
+do?" inside chat, and the model needs to answer correctly.
+
+To handle that, `SYSTEM_PROMPT` in `backend/api/chat.py` includes an
+"App capabilities you should know about" section that lists every routing
+keyword and the view it opens, plus the upload-modal flow for getting
+documents into the knowledge base. The prompt also tells the model:
+
+- *Do not* try to render quizzes, flashcards, audio, etc., as markdown —
+  point the user at the keyword and let the app open the real view.
+- If the user invokes a routed feature inside chat, the app switches views
+  before the model's reply is needed, so the model can safely no-op.
+
+Keep this section in sync with `detectView` in `frontend/src/app/page.tsx`
+whenever a new keyword group is added — they are the single source of
+truth pair for in-app capabilities.
+
+## Why "test" uses a word boundary
+
+`test` appears mid-word a lot ("testimony", "latest"). The detector uses
+`/\btest(s|ing)?\b/` so only `test`, `tests`, or `testing` as standalone
+words trigger the quiz view.
+
+## Files touched
+
+- `frontend/src/app/page.tsx` — extracted `detectView`, added
+  `handleChatCommand`, threaded `generationPrompt` state.
+- `frontend/src/components/ChatWidget.tsx` — added `onCommand` prop and
+  short-circuit in `handleSend` / initial-query effect.
+- `backend/api/chat.py` — extended `SYSTEM_PROMPT` with the
+  "App capabilities you should know about" section so the agent can
+  describe its own routed features when asked.
diff --git a/docs/knowledge-base-ui.md b/docs/knowledge-base-ui.md
new file mode 100644
index 0000000..438614b
--- /dev/null
+++ b/docs/knowledge-base-ui.md
@@ -0,0 +1,74 @@
+# Knowledge base UI
+
+Two related additions: a way to add documents *into* the knowledge base, and
+a way to view what's already in it.
+
+## 1. Upload modal
+
+A circular icon button now sits to the right of the command-bar pill.
+Clicking it opens `UploadModal`, which lets the user:
+
+- Paste raw text into a textarea.
+- Drag-and-drop or "Choose file" a plain-text file. Supported extensions:
+  `.txt`, `.md`, `.markdown`, `.rst`, `.csv`, `.json`, `.log`, plus any
+  file with a `text/*` MIME type.
+- Edit the auto-derived title.
+- Submit, which calls `ingestDocument()` → `POST /api/knowledge/ingest`.
+
+The backend deduplicates by SHA-256 of the content, so re-uploading the
+same file is safe and surfaces "already in knowledge base" instead of
+double-indexing.
+
+### Caveats
+
+- **Binary formats (PDF, DOCX, images) are not supported through this UI**.
+  The ingest endpoint takes `content: string`. The backend already has
+  `services/pdf.py::PDFService.extract_text` used by the arXiv flow — if you
+  want PDF upload from the UI, the cleanest path is a new `multipart/form-data`
+  endpoint that calls `PDFService.extract_text` and then forwards into the
+  existing ingest pipeline.
+- The modal accepts an optional `tomeId` so the new document can be linked
+  to the active tome. The `CommandBar` plumbs the prop through but there is
+  no "active tome" state at the page level yet, so uploads currently go to
+  the global knowledge base.
+
+## 2. Knowledge-base viewer
+
+Typing any of `knowledge`, `kb`, `docs`, `documents`, `knowledge base`,
+`view/show/list documents` into the command bar switches the view to
+`KnowledgeBaseWidget`. Two-pane layout:
+
+- **Left**: scrollable list of every ingested document (title, doc_type,
+  source, ingest time). Calls `listDocuments({ limit: 200 })`.
+- **Right**: detail panel for the selected document. Calls
+  `getDocument(id)` and shows source, type, chunk count, content hash,
+  linked tomes, and a 200-char content preview.
+- **Header actions**: Refresh button. Per-document Delete button in the
+  detail panel (`deleteDocument(id)`).
+
+The content preview comes from the backend's
+`GET /api/knowledge/documents/{id}` response, which returns
+`chunks[0].content[:200]` (`backend/api/knowledge.py`). If you want full
+chunk text in the UI, extend that endpoint to return all chunk content.
+
+## Files touched
+
+### Backend
+
+No changes — these UI flows reuse existing endpoints:
+- `POST /api/knowledge/ingest`
+- `GET  /api/knowledge/documents`
+- `GET  /api/knowledge/documents/{id}`
+- `DELETE /api/knowledge/documents/{id}`
+
+### Frontend
+
+- `frontend/src/components/UploadModal.tsx` (new) — paste / drop / choose-file
+  modal that POSTs to `/api/knowledge/ingest`.
+- `frontend/src/components/CommandBar.tsx` — adds the round upload button to
+  the right of the pill and renders `UploadModal`.
+- `frontend/src/components/KnowledgeBaseWidget.tsx` (new) — list + detail view.
+- `frontend/src/lib/sage-api.ts` — added `listDocuments`, `getDocument`,
+  `deleteDocument`, and matching types.
+- `frontend/src/app/page.tsx` — registered the `"knowledge"` view-state and
+  command-verb routing.