diff --git a/.s2s/BACKLOG.md b/.s2s/BACKLOG.md
index fa32efba..1e9a46bb 100644
--- a/.s2s/BACKLOG.md
+++ b/.s2s/BACKLOG.md
@@ -664,6 +664,62 @@ As a result, `conversation.j2` and `TemplateRenderer.render_conversation()` are
 
 ---
 
+### DEBT-017: Consolidate namespace-resolution logic in vektra-learn
+
+**Status**: planned | **Priority**: low | **Created**: 2026-04-21
+**Origin**: CodeRabbit review on PR #66 (v0.5.0), `vektra-learn/src/vektra_learn/api.py:498-512`
+
+**Context**: `_resolve_namespace_from_token()` (added for WI-1 in v0.5.0) re-implements the same fallback chain that `course_query` does inline around lines 663-673 and 694-695: read `course_id` from the JWT, fall back to `namespace` claim, default to `course_id`. The learn-query path additionally performs an enrollment lookup when `VEKTRA_LEARN_REQUIRE_ENROLLMENT=true` which is interleaved with the plain resolution, so a naive extraction would miss that branch.
+
+**Proposed approach**: extend `_resolve_namespace_from_token` to return a `(course_id, namespace, namespace_source)` tuple, then refactor `course_query` to call it for the non-enrollment branch while keeping the enrollment path inline. Both endpoints stay in lockstep if the JWT schema evolves (e.g., a new claim is added).
+
+**Acceptance criteria**:
+- [ ] Single helper used by both `get_conversation_turns` and `course_query` (non-enrollment branch)
+- [ ] Enrollment-required branch unchanged
+- [ ] Tests cover both call sites against a shared fixture set
+- [ ] No behaviour change to error codes (ERR-LEARN-003 on missing course_id)
+
+---
+
+### DEBT-018: Scope widget `--vektra-primary` override and dedupe style node
+
+**Status**: planned | **Priority**: low | **Created**: 2026-04-21
+**Origin**: CodeRabbit review on PR #66 (v0.5.0), `vektra-learn/widget/src/chat-ui.js:138-144`
+
+**Context**: `ChatUI._injectStyles()` appends a new `<style>` element setting `:root { --vektra-primary: <color> }` on every instantiation. Two consequences:
+
+1. Repeated construction (hot reload, multi-instance embedding, host-page re-init) accumulates style nodes.
+2. The override lives on `:root`, so if the host page already defines `--vektra-primary` for an unrelated purpose, the widget now wins document-wide.
+
+In today's deploy there is one widget per page and init fires once, so the impact is theoretical. Filing as debt so it's tracked when we eventually support embedding multiple instances or host pages that reuse the custom property.
+
+**Proposed approach**:
+1. Scope the override to the widget roots: `.vektra-chat-btn, .vektra-chat-panel { --vektra-primary: <color> }`.
+2. Cache/replace a single `<style id="vektra-primary-override">` node rather than appending on every construction.
+
+**Acceptance criteria**:
+- [ ] Custom property no longer leaks to `:root` when a widget is initialised
+- [ ] Re-initialising a widget replaces the style node instead of appending a new one
+- [ ] Default-color deploys render identically (no visual regression)
+
+---
+
+### DEBT-019: Unit assertion for `document_name` on streaming sources
+
+**Status**: planned | **Priority**: low | **Created**: 2026-04-21
+**Origin**: CodeRabbit review on PR #66 (v0.5.0), `vektra-core/tests/test_pipeline.py:423-497`
+
+**Context**: the streaming path (`execute_stream` in both `SimpleQueryPipeline` and `AdvancedQueryPipeline`) was the regression vector fixed by commit `45437c8` (missing `document_name` in `sources_data` dict of `AdvancedQueryPipeline.execute_stream`). Current unit coverage exercises `execute()` via `test_execute_populates_document_name` and is cross-checked end-to-end by the Kalypso smoke test. Adding a dedicated unit assertion on the streamed `sources` payload would catch the same regression at fastest feedback.
+
+**Proposed approach**: mirror `test_execute_populates_document_name` using the existing `_collect_stream()` helper: monkeypatch `pipeline_mod._fetch_document_names` to the same hit/miss fakes and assert each streamed `QueryChunk(type="sources", ...).data[*]["document_name"]` matches expectations. Add the same test for `AdvancedQueryPipeline`.
+
+**Acceptance criteria**:
+- [ ] Unit test covers `SimpleQueryPipeline.execute_stream` sources payload
+- [ ] Unit test covers `AdvancedQueryPipeline.execute_stream` sources payload
+- [ ] Both tests use the same mapping / empty-dict monkeypatches as the non-stream test for parity
+
+---
+
 ### INFRA-005: Docker log persistence across container restarts
 
 **Status**: planned | **Priority**: medium | **Created**: 2026-03-23
@@ -1147,6 +1203,8 @@ Plan generation follows a three-phase approach (lesson learned from Phase 1):
 **Status**: draft | **Priority**: medium | **Created**: 2026-03-17
 **Origin**: Moodle integration testing — greetings like "ciao", "buongiorno" trigger `no_relevant_context` and produce empty/unhelpful responses
 
+**Note (2026-04-18)**: FEAT-020 (`grounding_mode=hybrid`) partially overlaps: in hybrid mode the pipeline no longer short-circuits on `no_relevant_context` and calls the LLM. However, the system prompt is generic (training-data fallback), not tailored to greetings/meta-questions/off-topic with an explicit "redirect to course" behavior. FEAT-005 remains open for the dedicated no-context system prompt variant described in the acceptance criteria.
+
 **Context**: Both `SimpleQueryPipeline` and `AdvancedQueryPipeline` short-circuit when no chunks pass the relevance threshold (`min_relevance_score`): they return `answer: null` + `no_relevant_context: true` without ever calling the LLM. This is correct for retrieval quality (ARCH-056, REQ-066) — the system should not hallucinate answers from non-relevant chunks.
 
 However, for the learn chatbot widget (and any conversational interface), this creates a poor UX for:
@@ -1179,7 +1237,7 @@ The existing **SafeguardHook** (`pre_query`, `post_retrieval`, `pre_response`) c
 
 ### FEAT-007: Markdown rendering in widget chat messages
 
-**Status**: in_progress | **Priority**: medium | **Created**: 2026-03-20
+**Status**: completed | **Priority**: medium | **Created**: 2026-03-20 | **Completed**: 2026-03-23 | **PR**: #50
 **Origin**: Moodle integration testing (2026-03-20)
 
 **Context**: The learn chatbot widget (`vektra-chat.js`) renders all messages as plain text via `textContent`. LLM responses typically contain Markdown formatting (bold, italic, lists, code blocks, headings) which is displayed as raw syntax. This makes responses harder to read, especially for structured answers with bullet points or code examples.
@@ -1280,7 +1338,7 @@ If no custom template exists, the global system.j2 still has access to the same
 
 ### FEAT-006: Widget error feedback when Vektra API is unreachable
 
-**Status**: draft | **Priority**: medium | **Created**: 2026-03-20
+**Status**: completed | **Priority**: medium | **Created**: 2026-03-20 | **Completed**: 2026-03-23 | **PR**: #50
 **Origin**: Moodle integration testing on remote machine (2026-03-20)
 
 **Context**: When the chatbot widget JS (`vektra-chat.js`) cannot reach the Vektra API (missing SSH tunnel, CORS misconfiguration, Vektra container down), the floating chat button silently fails to appear. No error is shown to the user or the admin. The Moodle block still displays "AI Assistant is active" because the server-side token generation succeeded (PHP runs inside Docker, reaches Vektra on the internal network), but the browser-side widget cannot load or connect.
@@ -1303,7 +1361,7 @@ This makes troubleshooting difficult: the admin sees "active" but students see n
 
 ### FEAT-012: Include document name in query source citations
 
-**Status**: draft | **Priority**: medium | **Created**: 2026-03-20
+**Status**: completed | **Priority**: medium | **Created**: 2026-03-20 | **Completed**: 2026-04-21 | **Plan**: 20260418-v050-widget-and-prof-config
 **Origin**: Moodle integration testing - sources show chunk_id (UUID) instead of document name
 
 **Context**: The learn query response includes source citations with `doc_id`, `chunk_id`, `score`, and `snippet`. The widget renders these as `[1] chunk_id (score)` with a snippet preview. The `chunk_id` is a UUID which is meaningless to the user. The original document filename (e.g., "Escapologia Fiscale - 59 segreti.pdf") is not included in the source data.
@@ -1347,9 +1405,11 @@ Approach 1 (keyword proximity) is the best cost/benefit trade-off for a first im
 
 ### FEAT-016: White-label widget customization (name, colors, branding)
 
-**Status**: draft | **Priority**: medium | **Created**: 2026-03-20
+**Status**: partial (data-attrs) | **Priority**: medium | **Created**: 2026-03-20 | **Updated**: 2026-04-21 | **Plan**: 20260418-v050-widget-and-prof-config
 **Origin**: vertical deployment requirements - universities and organizations need chatbot with their own branding
 
+**v0.5.0 progress**: data-* attributes implemented (`data-title`, `data-primary-color`, `data-icon`, `data-welcome-message`, `data-powered-by`). Namespace-backed branding (category B) and JWT-claim precedence remain open — see FEAT-008.
+
 **Context**: The widget currently supports only `theme` (light/dark) and `language` (en/it) as visual customization. Everything else is hardcoded: title ("Course Assistant"), primary color (#2563eb blue), icon (speech bubble emoji), and no welcome message. ADR-0025 defines the `data-*` attribute contract as the configuration API, and the "configuration over fork" principle requires that customization happens via config, not code changes.
 
 For vertical deployments (e.g., a university running Vektra for their students), the chatbot should be brandable to match the institution's identity. The same applies to any organization deploying Vektra as infrastructure behind their own product.
@@ -1469,7 +1529,7 @@ Phase 2 (skip_retrieval flag):
 
 ### FEAT-009: Widget token auto-refresh on expiry
 
-**Status**: draft | **Priority**: high | **Created**: 2026-03-20
+**Status**: completed | **Priority**: high | **Created**: 2026-03-20 | **Completed**: 2026-03-23 | **PR**: #50
 **Origin**: Moodle integration testing - "invalid or expired dashboard token" after ~1h session
 
 **Context**: The JWT dashboard token has a 1h TTL (default). The token is generated server-side by the Moodle plugin (or any LMS) at page load and embedded in the widget via `data-token` attribute. Once expired, all subsequent queries fail with "signature has expired". The user must manually reload the page to get a fresh token.
@@ -1498,7 +1558,7 @@ For Moodle specifically, the plugin would expose a lightweight AJAX endpoint (`/
 
 ### FEAT-010: Enable SSE streaming in widget
 
-**Status**: draft | **Priority**: medium | **Created**: 2026-03-20
+**Status**: completed | **Priority**: medium | **Created**: 2026-03-20 | **Completed**: 2026-03-23 | **PR**: #50
 **Origin**: Moodle integration testing - responses arrive as a single block, no progressive rendering
 
 **Context**: The widget's api-client.js already has a complete SSE streaming parser (lines 65-107) with `onToken`, `onSources`, `onDone` callbacks. The chat-ui.js has `createStreamMessage()` and `appendToken()` methods that progressively append text to the DOM. However, the query is sent with `stream: false` (hardcoded, line 33), so all responses arrive as a single JSON blob.
@@ -1548,6 +1608,54 @@ This does not violate REQ-051 if data is aggregated (no individual conversations
 
 ---
 
+### FEAT-022: Suggested questions as quick-start chips in widget
+
+**Status**: draft | **Priority**: low | **Created**: 2026-04-18
+**Origin**: v0.5.0 scoping discussion - instructor wants to guide students toward typical questions without crafting a new conversation each time
+
+**Context**: students opening the chatbot often do not know how to start. A short list of instructor-curated prompts, rendered as clickable chips above the input box on first open, lowers the barrier and steers usage toward pedagogically useful questions (e.g., "Riassumi la lezione 3", "Quali sono i punti chiave del capitolo?", "Fammi un quiz su questo argomento").
+
+**Proposed approach**: purely client-side, category (A) config (visual, no backend involvement). Passed via `data-suggested-questions` attribute on the script tag as a JSON array. The Moodle block config form exposes a textarea (one question per line) that the plugin serializes into the attribute. The widget renders chips on first open; clicking one fills the input and submits as if typed.
+
+**Traceability**: ADR-0025, FEAT-016
+
+**Acceptance Criteria** (tentative):
+- [ ] `data-suggested-questions` attribute parsed as JSON array of strings
+- [ ] Chips rendered above the input on first open only (hidden after first message)
+- [ ] Click fills input and submits
+- [ ] Chips respect theme (light/dark) and primary color from FEAT-016
+- [ ] Missing/malformed attribute falls back to no chips (no error)
+- [ ] Moodle block config exposes a textarea for instructor to edit the list
+
+---
+
+### FEAT-023: Socratic interaction mode for guided learning
+
+**Status**: draft | **Priority**: medium | **Created**: 2026-04-18
+**Origin**: v0.5.0 scoping discussion - pedagogical need to differentiate "answer giver" from "learning guide" per course
+
+**Context**: in some courses the instructor wants the chatbot to act as a Socratic tutor — asking the student guiding questions instead of delivering the answer directly. This supports active learning and prevents the chatbot from becoming a shortcut that bypasses the learning process. Other courses (reference-style, FAQ-style) want the chatbot to give direct answers. The choice is per-course and must be configurable by the instructor.
+
+Implementation approach is deliberately deferred. Questions to resolve when designing this feature:
+- Is Socratic mode a third `grounding_mode` value (alongside `strict` and `hybrid`), or an orthogonal `interaction_mode` dimension?
+- How do the two interact when combined (strict + socratic, hybrid + socratic)?
+- Does the Socratic prompt need worked examples or is a system-prompt instruction enough?
+- How does it behave across multi-turn conversations (when does it "reveal" the answer)?
+- Should the instructor configure the depth of Socratic questioning (light nudging vs full inquiry)?
+
+Storage aligns with the same model as grounding mode: persisted in `namespaces.config` JSONB (category B config, backend-enforced), configurable via the Moodle block config form → `PATCH /api/v1/namespaces/{id}/config`. The widget does not need to know — the difference is entirely in the system prompt selected server-side.
+
+**Traceability**: FEAT-020 (grounding mode), ADR-0020 (prompt template architecture)
+
+**Acceptance Criteria** (tentative, pending design):
+- [ ] Per-namespace Socratic mode flag in `namespaces.config`
+- [ ] System prompt variant that implements Socratic dialogue
+- [ ] Works alongside strict/hybrid grounding modes
+- [ ] Validated with representative course scenarios
+- [ ] Instructor can enable/disable from Moodle block config
+
+---
+
 ## In Progress
 
 ### BUG-011: ~~Ingest pipeline does not generate sparse embeddings for hybrid search~~
@@ -1590,10 +1698,12 @@ The core API (`POST /api/v1/query`) has the same design — it's documented as "
 
 ### FEAT-004: Widget conversation lifecycle improvements
 
-**Status**: draft | **Priority**: medium | **Created**: 2026-03-16
+**Status**: partial (persistence + new chat) | **Priority**: medium | **Created**: 2026-03-16 | **Updated**: 2026-04-21 | **Plan**: 20260418-v050-widget-and-prof-config
 **Origin**: Moodle integration testing (2026-03-16)
 **Depends on**: BUG-010
 
+**v0.5.0 progress**: sessionStorage persistence with 24h stale cutoff (tab-scoped, keyed by course_id), history replay via new `GET /conversations/{id}/turns`, explicit "New chat" button. Remaining open: idle timeout, cross-device continuity, token-refresh interaction policy. Sources are returned empty for v0.5.0 — extending turns response with citations requires joining query_traces and is deferred.
+
 **Context**: After BUG-010 is fixed, the widget will support multi-turn conversations within a single page load. However, the `conversation_id` lives only in JS memory (`ApiClient._conversationId`) and is lost on page refresh, navigation, or tab close. Additionally, there is no explicit way for the user to start a fresh conversation. These are UX improvements to evaluate for the learn chatbot widget.
 
 **Areas to evaluate**:
diff --git a/.s2s/plans/20260418-v050-widget-and-prof-config.md b/.s2s/plans/20260418-v050-widget-and-prof-config.md
new file mode 100644
index 00000000..78ed8bdd
--- /dev/null
+++ b/.s2s/plans/20260418-v050-widget-and-prof-config.md
@@ -0,0 +1,306 @@
+# Plan: v0.5.0 - Widget production-ready + instructor configuration
+
+**Status**: active
+**Plan ID**: 20260418-v050-widget-and-prof-config
+**Branch**: feat/v050-widget-and-prof-config
+**Created**: 2026-04-18T12:40:00Z
+**Updated**: 2026-04-18T12:40:00Z
+**Source**: v0.5.0 milestone scoping discussion (2026-04-18)
+**Source type**: milestone
+
+## Traceability
+
+- **Requirements**: REQ-049 (multi-turn conversations), REQ-053 (QueryPipeline Protocol), REQ-066 (no relevant context)
+- **Architecture**: ARCH-047 (namespace metadata as JSONB), ARCH-063 (widget architecture), ARCH-054 (composable prompt templates)
+- **Decisions**: ADR-0025 (learn chatbot widget as backend-served JS bundle), ADR-0020 (prompt template architecture), ADR-0010 (authentication gateway)
+- **Backlog items**: FEAT-016, FEAT-012, FEAT-004
+- **Related (deferred)**: FEAT-008 (per-namespace prompt templates), FEAT-014 (source visibility), FEAT-022 (suggested questions), FEAT-023 (socratic mode)
+- **Builds on**: FEAT-020 (grounding mode already reads from `namespaces.config`)
+- **Dependencies**: none (all infrastructure in place)
+
+## Overview
+
+v0.5.0 closes the gap between "widget works" (v0.4.0) and "widget is production-ready for real courses". Three user-visible gaps remain:
+
+1. **White-label** (FEAT-016): every course looks identical. Universities need their own title, color, welcome message.
+2. **Citation clarity** (FEAT-012): sources show `chunk_id` UUIDs — meaningless to students. Document filename must be shown.
+3. **Conversation persistence** (FEAT-004): refresh or accidental tab close loses the conversation. Unacceptable for courses where students ask follow-up questions.
+
+Plus one foundational backend addition: **instructor configuration API** — professors need to toggle grounding mode (strict/hybrid) per course from inside Moodle without admin intervention. The `namespaces.config` JSONB column and pipeline resolution already exist (FEAT-020); only the write API and the Moodle integration are missing.
+
+**Repositories touched**: vektra-stack (this plan), vektra-moodle (separate plan in the plugin repo).
+
+**Not in scope**: FEAT-022 (suggested questions), FEAT-023 (socratic mode), FEAT-014 (source visibility toggle), FEAT-008 (per-namespace prompt templates), full admin UI for namespace config. These are deliberately deferred.
+
+## Architecture decisions for this plan
+
+### Two-category configuration model
+
+All course customization splits cleanly into two categories, persisted in different places:
+
+| Category | Examples | Storage | Read by | Write path |
+|---|---|---|---|---|
+| **(A) Visual** | title, color, welcome message, icon | Moodle block config | Widget via `data-*` attrs | Moodle block edit form → stays in Moodle |
+| **(B) Behavioral** | `grounding_mode`, future `show_sources`, `top_k` override | `namespaces.config` JSONB | Vektra pipeline server-side | Moodle block edit form → AJAX → `PATCH /api/v1/namespaces/{id}/config` |
+
+Rationale: behavioral config must be server-enforced to prevent clients from bypassing (e.g., a browser can't be trusted to enforce strict mode). Visual config has no security implications and can stay in the host plugin.
+
+### Authentication model for namespace PATCH
+
+Same trust model already used for token generation (FEAT-003):
+
+1. Moodle plugin holds `VEKTRA_API_KEY` (admin scope) in its server-side PHP config.
+2. Moodle's native auth verifies "user X is a teacher of course Y" before showing/accepting the block edit form.
+3. When a teacher saves the form, Moodle PHP calls `PATCH /api/v1/namespaces/{course_id}/config` authenticated with the admin API key.
+4. Vektra does not know individual professors. It trusts the upstream auth (same philosophy as `VEKTRA_LEARN_REQUIRE_ENROLLMENT=false`).
+
+No new Vektra-side auth primitive needed. No "teacher scope" API key type to invent.
+
+### Conversation persistence: tab-scoped, no cross-device
+
+- Storage: `sessionStorage` keyed by `course_id` (tab-scoped per browser tab, wiped on tab close).
+- Not `localStorage`: shared computers in university labs must not leak conversations across students.
+- Not server-side "last conversation for this student": avoids privacy debate and keeps the widget stateless from Vektra's perspective (conversation turns are already persisted encrypted server-side per ADR-0011, this is just a UI convenience).
+- On load: if `sessionStorage[course_id]` has a `conversation_id`, widget fetches turns from `GET /api/v1/conversations/{id}/turns` and renders them before the user types.
+- "New chat" button: explicit reset (clears sessionStorage + DOM).
+
+## Work items
+
+### WI-1 - Backend: GET /api/v1/conversations/{id}/turns (JWT-scoped)
+
+FEAT-004 prerequisite. Admin equivalent already exists at `vektra-admin/src/vektra_admin/api.py:463`; this is the student-scoped mirror in `vektra-learn`.
+
+**Endpoint**:
+- Method: `GET`
+- Path: `/api/v1/conversations/{conversation_id}/turns`
+- Auth: JWT (learn dashboard token)
+- Path param: `conversation_id: UUID`
+- Response: `200 OK` with `{"turns": [{"turn_id": UUID, "question": str, "answer": str, "created_at": ISO8601, "sources": [...] }], "conversation_id": UUID, "namespace": str}`
+- Errors: `404` if conversation does not exist, `403` if JWT namespace does not match conversation namespace, `401` if JWT invalid/expired
+
+**Authorization rule**: the JWT contains `namespace` (or `course_id` fallback per FEAT-003). The endpoint MUST verify `conversation.namespace_id == jwt.namespace` before returning turns. This is the only authorization gate — we do not also check `student_id` because a student may legitimately reload a conversation started in a previous session with the same course.
+
+**Files**:
+- `vektra-learn/src/vektra_learn/api.py` - add endpoint
+- `vektra-learn/src/vektra_learn/models.py` - add `ConversationTurnsResponse` Pydantic model if not present
+- `vektra-core/src/vektra_core/conversations.py` (or wherever `conversation_turns` table is queried) - add `get_turns_by_conversation_id(conversation_id, namespace) -> list[Turn]` helper that decrypts `question` and `answer` via `pgp_sym_decrypt` (see CLAUDE.md DB investigation notes)
+- Tests: `vektra-learn/tests/test_conversations.py`
+
+**Decryption note**: `conversation_turns.question` and `conversation_turns.answer` are encrypted with `pgp_sym_encrypt()` using `VEKTRA_CONVERSATION_KEY`. The helper must decrypt before serializing. See `.claude/CLAUDE.md` → "Conversation turns are encrypted".
+
+**Test gates** (acceptance):
+- [ ] Valid JWT + matching namespace returns decrypted turns ordered by `created_at` ASC
+- [ ] Valid JWT + different namespace returns `403` (no data leak across courses)
+- [ ] Expired JWT returns `401`
+- [ ] Non-existent `conversation_id` returns `404`
+- [ ] Response includes `sources` field (even if empty array) so widget does not need a conditional render
+- [ ] Integration test uses a real Postgres (per `feedback_no_mock_database` memory)
+
+### WI-2 - Backend: document name in source citations (FEAT-012)
+
+Currently `SourceRef` returns `chunk_id` (UUID). Students see `[1] 4a2f3b... (0.82)`. They need to see the document name.
+
+**Data source**: `document_chunks.document_id` → `documents.source_file` (or `documents.title` if we want a human-friendlier field). The Qdrant payload also carries `source_file` per audit earlier.
+
+**Changes**:
+- Extend `SourceRef` schema to include `document_name: str` (derived from `documents.source_file`, fallback to `documents.id[:8]` if null)
+- Update the pipeline source assembly to fetch `source_file` from the document referenced by each chunk. Prefer a JOIN in the existing query over a second round-trip per chunk.
+- Widget change: render `[1] document_name (score)` instead of `[1] chunk_id (score)`. Tooltip on hover can keep the chunk UUID for debugging.
+
+**Files**:
+- `vektra-core/src/vektra_core/api.py` or `pipeline.py` - `SourceRef` schema + assembly
+- `vektra-learn/src/vektra_learn/query.py` - ensure the field passes through to the learn response
+- `vektra-learn/widget/src/chat-ui.js` (or wherever sources render) - use `document_name`
+- Tests: both backend (pipeline returns document_name) and widget (renders correctly)
+
+**Edge cases**:
+- Document soft-deleted (REQ-057): still render the name, append " (archived)" marker. Do NOT hide the citation — it must match what was retrieved.
+- Document name with special chars (e.g., emoji, Italian accents): must survive JSON round-trip. Widget uses `textContent`, not `innerHTML`, for the citation label.
+
+**Test gates**:
+- [ ] `/api/v1/query` response includes `document_name` for each source
+- [ ] `/api/v1/learn/query` response propagates the field
+- [ ] Widget displays `[1] <name> (<score>)` — no UUID visible in normal UI
+- [ ] Falls back gracefully if `source_file` is null
+
+### WI-3 - Backend: PATCH /api/v1/namespaces/{id}/config (instructor config)
+
+Foundation for category (B) config. Writes into the existing `namespaces.config` JSONB column. Read path already exists (`resolve_grounding_mode` at `vektra-shared/src/vektra_shared/namespace.py:19`).
+
+**Endpoint**:
+- Method: `PATCH`
+- Path: `/api/v1/namespaces/{namespace_id}/config`
+- Auth: admin API key (via `require_admin` dependency pattern already used elsewhere)
+- Body: `{"grounding_mode": "strict" | "hybrid" | null}` (null = unset, falls back to env var). Explicitly allow partial updates — only keys present in the body are updated, others are preserved. Unknown keys rejected with `400`.
+- Response: `200 OK` with the current full `config` object after merge
+- Errors: `404` if namespace does not exist, `400` if value invalid (not in enum), `401`/`403` for auth
+
+**Design choice — allowed keys**:
+Keep the whitelist tight. For v0.5.0, only `grounding_mode` is a valid key. Adding more keys is a later patch-release change. The endpoint must reject unknown keys (not silently ignore) so that typos from the Moodle plugin surface immediately during development.
+
+```python
+ALLOWED_CONFIG_KEYS = {"grounding_mode"}  # extend cautiously; each key is a public contract
+ALLOWED_GROUNDING_MODES = {"strict", "hybrid"}
+```
+
+**Files**:
+- `vektra-admin/src/vektra_admin/api.py` (namespace routes already live here) - add PATCH
+- `vektra-admin/src/vektra_admin/service.py` (or similar) - `update_namespace_config(namespace_id, partial_config) -> dict`
+- Tests: `vektra-admin/tests/test_namespaces.py`
+
+**Why admin API (not a new "teacher" scope)**: Moodle acts as the trusted upstream (see "Authentication model" above). Inventing a new scope here adds complexity without benefit — Moodle's admin key is already stored server-side and never reaches the browser.
+
+**Test gates**:
+- [ ] PATCH with `{"grounding_mode": "hybrid"}` updates the value in `namespaces.config`
+- [ ] Subsequent query to that namespace uses hybrid mode (end-to-end: write → resolve → pipeline)
+- [ ] PATCH with unknown key returns `400` with the rejected key name
+- [ ] PATCH with invalid value (e.g., `"grounding_mode": "banana"`) returns `400`
+- [ ] PATCH with `null` value for a key removes it from config (fallback to env var)
+- [ ] PATCH is partial: existing keys not in the body are preserved
+- [ ] Non-admin API key returns `403`
+
+### WI-4 - Widget: white-label data-attrs (FEAT-016)
+
+Client-side only. Read additional `data-*` attributes from the script tag, expose them as CSS custom properties + template values.
+
+**New data-* attributes**:
+
+| Attribute | Default | Applied to |
+|---|---|---|
+| `data-title` | "Course Assistant" / i18n | Chat panel header |
+| `data-primary-color` | `#2563eb` | Button, links, accents (as `--vektra-primary` CSS var) |
+| `data-icon` | speech bubble emoji | Floating button icon (URL or emoji) |
+| `data-welcome-message` | (none) | First assistant message on open |
+| `data-powered-by` | "true" | If "false", hide "Powered by Vektra" footer |
+
+**Files**:
+- `vektra-learn/widget/src/index.js` - parse new attributes in the constructor
+- `vektra-learn/widget/src/styles.js` - replace hardcoded `#2563eb` with `var(--vektra-primary, #2563eb)`
+- `vektra-learn/widget/src/chat-ui.js` - render title from config, inject welcome message on first open
+- Tests: `vektra-learn/widget/tests/` - verify each attribute changes the rendered output, missing attributes fall back to defaults
+
+**Fallback chain** (consistent with FEAT-016 backlog spec): `data-* attribute > hardcoded default`. Namespace metadata override is deferred to a later release (would require category-B endpoint extension, not worth it for visual fields).
+
+**Test gates**:
+- [ ] Each `data-*` attribute individually changes the widget output
+- [ ] Missing attributes fall back to current v0.4.0 defaults (no breaking change for existing Moodle installs)
+- [ ] Light/dark theme still works when `data-primary-color` is set
+- [ ] `data-icon` accepts both emoji and URL; URL shows image, emoji shows text
+- [ ] XSS: `data-title` with `<script>` injected is rendered as text (verify via `textContent`, not `innerHTML`)
+
+### WI-5 - Widget: conversation persistence (FEAT-004)
+
+Consumes WI-1 endpoint. Client-side logic for `sessionStorage` + history reload + "New chat" button.
+
+**Storage schema**:
+```js
+sessionStorage[`vektra-conv-${courseId}`] = JSON.stringify({
+  conversation_id: "...",
+  created_at: "2026-04-18T..."  // for optional stale-after-N-hours cleanup
+});
+```
+
+**Lifecycle**:
+- On widget init: read sessionStorage for this `course_id`. If present and not stale (configurable TTL, default 24h), call `GET /conversations/{id}/turns` and render them before enabling input.
+- On each successful query response: persist `conversation_id` (comes back in the response / SSE `done` event).
+- On "New chat" button: clear sessionStorage entry, clear DOM, reset `_conversationId`.
+- On `404` from turns endpoint (conversation deleted server-side): clear sessionStorage, start fresh, do not show error to user.
+- On `403`: log and start fresh (likely namespace mismatch after course change).
+
+**Token expiry and conversation continuity**: the existing `onTokenExpired` callback (FEAT-009) already handles transparent token refresh. Conversation ID is independent of JWT — it survives a refresh. This is the correct behavior.
+
+**Idle timeout**: deferred. Do not auto-reset conversations after N minutes. Sessions in university contexts may include long reading breaks; forcing a new conversation frustrates follow-up questions.
+
+**Files**:
+- `vektra-learn/widget/src/index.js` - init-time history restore, persistence hook
+- `vektra-learn/widget/src/chat-ui.js` - "New chat" button in header, message replay renderer
+- `vektra-learn/widget/src/api-client.js` - `getConversationTurns(id)` method
+
+**Test gates**:
+- [ ] After sending a message and refreshing the page, the message history reappears
+- [ ] Closing the tab and reopening loses the history (sessionStorage is tab-scoped — expected)
+- [ ] "New chat" button resets conversation_id and DOM
+- [ ] Different `course_id` on the same tab does NOT share history (keyed by course)
+- [ ] `403` response triggers silent reset, not error UI
+- [ ] History replay renders assistant messages with Markdown (FEAT-007 already in place) and sources (FEAT-012)
+
+## Implementation order
+
+Strict ordering to minimize rework:
+
+1. **WI-3** first (PATCH /namespaces/config). Foundation. Also the easiest to test standalone.
+2. **WI-2** (document name). Independent of WI-3. Small backend change, small widget change.
+3. **WI-1** (GET turns endpoint). Prerequisite for WI-5.
+4. **WI-4** (data-attrs). Independent of backend work. Can be done in parallel with WI-1/2/3 if convenient but not required.
+5. **WI-5** (conversation persistence widget). Last, depends on WI-1. Also benefits from WI-2 being done (so replayed history shows document names, not UUIDs).
+
+Each WI gets its own commit (Conventional Commits) on the `feat/v050-widget-and-prof-config` branch. Do not squash during development; squash-or-merge is a PR-time decision.
+
+## Handoff to vektra-moodle
+
+A sibling plan lives in `vektra-moodle` covering:
+
+- Block edit form with two sections (visual / behavioral) that separate category (A) data-attrs from category (B) namespace config
+- AJAX endpoint `/blocks/vektra/save_config.php` that receives the form, validates teacher auth, and fans out:
+  - Visual fields → persisted as block instance config (Moodle native)
+  - Behavioral fields → POST to `PATCH /api/v1/namespaces/{course_id}/config` with stored admin API key
+- AJAX endpoint `/blocks/vektra/refresh_token.php` for FEAT-009 (if not yet implemented)
+- Page render: read block config, emit `<script data-title="..." data-primary-color="..." ...>` on each course page
+
+Vektra-stack plan (this file) is independent and can be completed and merged before the Moodle work starts. The widget's data-attr contract is stable (ADR-0025); Moodle consumes it.
+
+## Test strategy
+
+Three layers:
+
+1. **Unit tests**: each WI has its own. Backend uses pytest + real Postgres (per the `feedback_no_mock_database` memory — do NOT mock the DB). Widget uses the existing Jest-like setup.
+2. **Integration tests**: extend `tests/integration/` with a flow that:
+   - Creates a namespace
+   - PATCHes `grounding_mode=hybrid`
+   - Runs a query against a namespace with no ingested content
+   - Asserts the response is non-null (hybrid fallback engaged) — proves end-to-end persistence → read path works
+3. **Manual smoke test before PR** (documented in PR description):
+   - Kalypso Docker stack up, Moodle + Vektra reachable
+   - Open a course page with the widget
+   - Set a custom title + color via data-attrs (hardcoded in test Moodle block for now)
+   - Send a message, refresh, verify history returns
+   - Click "New chat", verify reset
+   - Manually PATCH namespace to hybrid, ask an off-topic question, verify hybrid behavior kicks in
+
+Lint/test gate per `feedback_lint_before_push`: `make lint && make test` must pass before any push.
+
+## Risks and mitigations
+
+| Risk | Mitigation |
+|---|---|
+| GET /conversations/turns decryption key unavailable in vektra-learn container | Keys loaded from same env var (`VEKTRA_CONVERSATION_KEY`) already used by core — single source of truth. Verify in startup check. |
+| `namespaces.config` overwrite: concurrent PATCH from two professor edits races | Out of scope for v0.5.0 — last-write-wins is acceptable for instructor config. Add row-level locking if seen in practice. |
+| Widget `sessionStorage` quota exhaustion on public computers | Quota is ~5MB per origin; storing only conversation_id + timestamp is a few hundred bytes. Not a realistic concern. |
+| XSS via `data-title` or `data-welcome-message` | All data-attrs rendered via `textContent`, never `innerHTML`. Add explicit test case. |
+| Decrypted conversation history exposed to wrong student via bad JWT scoping | Enforce `conversation.namespace_id == jwt.namespace` check + integration test that asserts 403 on mismatch. |
+
+## Acceptance criteria (aggregate)
+
+Plan is complete when:
+- [ ] All 5 WIs merged to `feat/v050-widget-and-prof-config` (one commit per WI)
+- [ ] `make lint && make test` pass
+- [ ] Integration test for PATCH → hybrid query flow passes
+- [ ] Manual smoke test checklist executed and documented
+- [ ] Backlog statuses updated: FEAT-016, FEAT-012, FEAT-004 → completed; add new FEAT for "instructor namespace config API" if we want explicit tracking separate from FEAT-008
+- [ ] vektra-moodle sibling plan referenced
+- [ ] CHANGELOG.md updated with v0.5.0 section
+- [ ] Version bumped to `0.5.0` in `pyproject.toml` and wherever else
+
+## Integration and deployment notes
+
+- No DB migration needed: `namespaces.config` column already exists.
+- No new environment variables: all config flows through the existing admin API key.
+- No new dependencies in `pyproject.toml`.
+- Widget bundle size may grow ~1-2KB for data-attr parsing + history replay; acceptable (ADR-0025 sets no hard limit).
+- Moodle plugin release is independent — v0.5.0 of vektra-stack works unchanged for a Moodle plugin still on v0.4.0 (all new data-attrs fall back gracefully, all new endpoints return 404 cleanly if the plugin does not call them).
+
+## Next actions
+
+1. Confirm this plan covers the intent (especially: WI-1/2/3 backend endpoints as specified, no hidden surprises).
+2. Start WI-3 (PATCH endpoint) as the first implementation task.
+3. Create corresponding plan in vektra-moodle repo before touching that codebase.
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 9c679a36..6dcebbc0 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,6 +4,22 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
+## [Unreleased] — v0.5.0 "Widget production-ready + instructor configuration"
+
+### Added
+
+- **vektra-admin**: `PATCH /api/v1/admin/namespaces/{id}/config` endpoint for instructor configuration. Admin-scoped, whitelisted (v0.5.0 accepts `grounding_mode` only), partial updates, null removes a key. Backs the Moodle block form that lets teachers toggle strict/hybrid RAG per course without admin intervention.
+- **vektra-learn**: `GET /api/v1/learn/conversations/{id}/turns` JWT-scoped endpoint so the widget can restore a conversation after a page reload. Returns decrypted question/answer + created_at; admin-only metadata is not exposed. 403 on namespace mismatch, 404 on missing.
+- **vektra-core**: `document_name` field on every source citation, joined from `source_documents.filename` so the widget renders `[1] lecture-07.pdf` instead of chunk UUIDs. Propagates through both `SimpleQueryPipeline` and `AdvancedQueryPipeline`, JSON and SSE paths. Soft-deleted source documents (REQ-057) keep their citation with an `(archived)` suffix so answers stay traceable.
+- **vektra-learn**: content-access audit entry (`learn_conversation_turns_read`) written on every successful turns fetch via the shared `vektra_shared.audit` interface (NFR-007).
+- **widget**: white-label `data-*` attributes — `data-title`, `data-primary-color`, `data-icon` (emoji or URL), `data-welcome-message`, `data-powered-by`. All rendered via `textContent` / safe color whitelist to avoid XSS.
+- **widget**: tab-scoped conversation persistence via `sessionStorage` keyed by `course_id` (24h cutoff); history replay on load via the new turns endpoint; explicit "New chat" button in the header.
+- **errors**: new codes `ERR-ADMIN-005/006/007` (namespace config) and `ERR-LEARN-005/006` (conversation turns).
+
+### Changed
+
+- **widget styles**: button and accent colors now use `var(--vektra-primary, …)` so `data-primary-color` takes effect without rebuilding the bundle. Hover states use `filter: brightness()` so custom colors still feel interactive.
+
 ## [0.3.0] - 2026-03-21
 
 E-learning vertical refinements, widget UX improvements, and Phase 2 stabilization.
diff --git a/docs/reference/api.md b/docs/reference/api.md
index d686797d..5ebae5d1 100644
--- a/docs/reference/api.md
+++ b/docs/reference/api.md
@@ -140,6 +140,45 @@ curl -s -X DELETE \
 
 Returns HTTP 204 (no body).
 
+## Namespaces
+
+### PATCH /api/v1/admin/namespaces/{namespace_id}/config
+
+Partially update a namespace's behavioral config (JSONB). Requires `admin` scope.
+
+**Scopes**: `admin`
+
+Used by upstream plugins (e.g. the Moodle block) to toggle per-course settings such as the grounding mode without touching environment variables. The read path is `resolve_grounding_mode()` in `vektra-shared/src/vektra_shared/namespace.py`.
+
+```bash
+curl -s -X PATCH \
+  -H "Authorization: Bearer $VEKTRA_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"grounding_mode":"hybrid"}' \
+  http://localhost:8000/api/v1/admin/namespaces/default/config | python3 -m json.tool
+```
+
+Request body (flat dict, one entry per config key):
+
+| Field | Type | Allowed values | Description |
+|-------|------|----------------|-------------|
+| `grounding_mode` | string or null | `"strict"`, `"hybrid"`, `null` | RAG grounding policy. `null` removes the key and falls back to `VEKTRA_PROMPT_GROUNDING_MODE`. |
+
+Behavior:
+- **Partial update**: keys not present in the body are preserved.
+- **Unknown keys rejected** with `400 ERR-ADMIN-006` (not silently ignored — surfaces typos early).
+- **Invalid values rejected** with `400 ERR-ADMIN-007`.
+- **Missing namespace** returns `404 ERR-ADMIN-005`.
+
+Response (HTTP 200):
+
+```json
+{
+    "namespace_id": "default",
+    "config": {"grounding_mode": "hybrid"}
+}
+```
+
 ## Ingest
 
 ### POST /api/v1/ingest
@@ -254,7 +293,8 @@ Response:
             "score": 0.912,
             "snippet": "...",
             "citation_id": "d4e5f6-...",
-            "document_version": 1
+            "document_version": 1,
+            "document_name": "lecture-07.pdf"
         }
     ],
     "conversation_id": null,
diff --git a/docs/reference/error-codes.md b/docs/reference/error-codes.md
index ea6b5cd7..9bb9cd3d 100644
--- a/docs/reference/error-codes.md
+++ b/docs/reference/error-codes.md
@@ -81,11 +81,17 @@ These codes are used by specific components and are not part of the REQ-011 regi
 | ERR-ADMIN-001 | vektra-admin | 422 | Invalid scopes in API key creation request |
 | ERR-ADMIN-002 | vektra-admin | 404 | API key not found |
 | ERR-ADMIN-003 | vektra-admin | 409 | API key already revoked |
+| ERR-ADMIN-004 | vektra-admin | 422 | API key `expires_at` must be in the future |
+| ERR-ADMIN-005 | vektra-admin | 404 | Namespace not found (config PATCH) |
+| ERR-ADMIN-006 | vektra-admin | 400 | Unknown config key in namespace PATCH body |
+| ERR-ADMIN-007 | vektra-admin | 400 | Invalid value for namespace config key |
 | ERR-SAFEGUARD-001 | vektra-core | 400 | Query blocked by safeguard pre-check |
 | ERR-LEARN-001 | vektra-learn | 503 | Learn service unavailable or pipeline not configured |
 | ERR-LEARN-002 | vektra-learn | 404 | No enrollment found for student in course |
 | ERR-LEARN-003 | vektra-learn | 401 | Dashboard token missing required course_id claim |
 | ERR-LEARN-004 | vektra-learn | 422 | Invalid learn request (missing fields, bad format) |
+| ERR-LEARN-005 | vektra-learn | 404 | Conversation not found (GET conversations/turns) |
+| ERR-LEARN-006 | vektra-learn | 403 | Conversation belongs to a different course/namespace |
 
 ## Adding new error codes
 
diff --git a/uv.lock b/uv.lock
index 7928b3a8..652f43f6 100644
--- a/uv.lock
+++ b/uv.lock
@@ -4598,15 +4598,15 @@ dependencies = [
     { name = "typing-extensions", marker = "sys_platform == 'darwin'" },
 ]
 wheels = [
-    { url = "https://download.pytorch.org/whl/cpu/torch-2.10.0-1-cp312-none-macosx_11_0_arm64.whl", hash = "sha256:7fbbf409143a4fe0812a40c0b46a436030a7e1d14fe8c5234dfbe44df47f617e" },
-    { url = "https://download.pytorch.org/whl/cpu/torch-2.10.0-1-cp313-none-macosx_11_0_arm64.whl", hash = "sha256:b39cafff7229699f9d6e172cac74d85fd71b568268e439e08d9c540e54732a3e" },
-    { url = "https://download.pytorch.org/whl/cpu/torch-2.10.0-2-cp312-none-macosx_11_0_arm64.whl", hash = "sha256:358bd7125cbec6e692d60618a5eec7f55a51b29e3652a849fd42af021d818023" },
-    { url = "https://download.pytorch.org/whl/cpu/torch-2.10.0-2-cp313-none-macosx_11_0_arm64.whl", hash = "sha256:470de4176007c2700735e003a830828a88d27129032a3add07291da07e2a94e8" },
-    { url = "https://download.pytorch.org/whl/cpu/torch-2.10.0-cp312-none-macosx_11_0_arm64.whl", hash = "sha256:45a1c5057629444aeb1c452c18298fa7f30f2f7aeadd4dc41f9d340980294407" },
-    { url = "https://download.pytorch.org/whl/cpu/torch-2.10.0-cp313-cp313t-macosx_14_0_arm64.whl", hash = "sha256:339e05502b6c839db40e88720cb700f5a3b50cda332284873e851772d41b2c1e" },
-    { url = "https://download.pytorch.org/whl/cpu/torch-2.10.0-cp313-none-macosx_11_0_arm64.whl", hash = "sha256:840351da59cedb7bcbc51981880050813c19ef6b898a7fecf73a3afc71aff3fe" },
-    { url = "https://download.pytorch.org/whl/cpu/torch-2.10.0-cp314-cp314-macosx_14_0_arm64.whl", hash = "sha256:c88b1129fd4e14f0f882963c6728315caae35d2f47374d17edeed1edc7697497" },
-    { url = "https://download.pytorch.org/whl/cpu/torch-2.10.0-cp314-cp314t-macosx_14_0_arm64.whl", hash = "sha256:f4bea7dc451267c028593751612ad559299589304e68df54ae7672427893ff2c" },
+    { url = "https://download-r2.pytorch.org/whl/cpu/torch-2.10.0-1-cp312-none-macosx_11_0_arm64.whl", hash = "sha256:7fbbf409143a4fe0812a40c0b46a436030a7e1d14fe8c5234dfbe44df47f617e" },
+    { url = "https://download-r2.pytorch.org/whl/cpu/torch-2.10.0-1-cp313-none-macosx_11_0_arm64.whl", hash = "sha256:b39cafff7229699f9d6e172cac74d85fd71b568268e439e08d9c540e54732a3e" },
+    { url = "https://download-r2.pytorch.org/whl/cpu/torch-2.10.0-2-cp312-none-macosx_11_0_arm64.whl", hash = "sha256:358bd7125cbec6e692d60618a5eec7f55a51b29e3652a849fd42af021d818023" },
+    { url = "https://download-r2.pytorch.org/whl/cpu/torch-2.10.0-2-cp313-none-macosx_11_0_arm64.whl", hash = "sha256:470de4176007c2700735e003a830828a88d27129032a3add07291da07e2a94e8" },
+    { url = "https://download-r2.pytorch.org/whl/cpu/torch-2.10.0-cp312-none-macosx_11_0_arm64.whl", hash = "sha256:45a1c5057629444aeb1c452c18298fa7f30f2f7aeadd4dc41f9d340980294407" },
+    { url = "https://download-r2.pytorch.org/whl/cpu/torch-2.10.0-cp313-cp313t-macosx_14_0_arm64.whl", hash = "sha256:339e05502b6c839db40e88720cb700f5a3b50cda332284873e851772d41b2c1e" },
+    { url = "https://download-r2.pytorch.org/whl/cpu/torch-2.10.0-cp313-none-macosx_11_0_arm64.whl", hash = "sha256:840351da59cedb7bcbc51981880050813c19ef6b898a7fecf73a3afc71aff3fe" },
+    { url = "https://download-r2.pytorch.org/whl/cpu/torch-2.10.0-cp314-cp314-macosx_14_0_arm64.whl", hash = "sha256:c88b1129fd4e14f0f882963c6728315caae35d2f47374d17edeed1edc7697497" },
+    { url = "https://download-r2.pytorch.org/whl/cpu/torch-2.10.0-cp314-cp314t-macosx_14_0_arm64.whl", hash = "sha256:f4bea7dc451267c028593751612ad559299589304e68df54ae7672427893ff2c" },
 ]
 
 [[package]]
@@ -4633,33 +4633,33 @@ dependencies = [
     { name = "typing-extensions", marker = "sys_platform != 'darwin'" },
 ]
 wheels = [
-    { url = "https://download.pytorch.org/whl/cpu/torch-2.10.0%2Bcpu-cp312-cp312-linux_aarch64.whl", hash = "sha256:8de5a36371b775e2d4881ed12cc7f2de400b1ad3d728aa74a281f649f87c9b8c" },
-    { url = "https://download.pytorch.org/whl/cpu/torch-2.10.0%2Bcpu-cp312-cp312-linux_s390x.whl", hash = "sha256:9accc30b56cb6756d4a9d04fcb8ebc0bb68c7d55c1ed31a8657397d316d31596" },
-    { url = "https://download.pytorch.org/whl/cpu/torch-2.10.0%2Bcpu-cp312-cp312-manylinux_2_28_aarch64.whl", hash = "sha256:179451716487f8cb09b56459667fa1f5c4c0946c1e75fbeae77cfc40a5768d87" },
-    { url = "https://download.pytorch.org/whl/cpu/torch-2.10.0%2Bcpu-cp312-cp312-manylinux_2_28_x86_64.whl", hash = "sha256:ee40b8a4b4b2cf0670c6fd4f35a7ef23871af956fecb238fbf5da15a72650b1d" },
-    { url = "https://download.pytorch.org/whl/cpu/torch-2.10.0%2Bcpu-cp312-cp312-win_amd64.whl", hash = "sha256:21cb5436978ef47c823b7a813ff0f8c2892e266cfe0f1d944879b5fba81bf4e1" },
-    { url = "https://download.pytorch.org/whl/cpu/torch-2.10.0%2Bcpu-cp312-cp312-win_arm64.whl", hash = "sha256:3eaa727e6a73affa61564d86b9d03191df45c8650d0666bd3d57c8597ef61e78" },
-    { url = "https://download.pytorch.org/whl/cpu/torch-2.10.0%2Bcpu-cp313-cp313-linux_aarch64.whl", hash = "sha256:fd215f3d0f681905c5b56b0630a3d666900a37fcc3ca5b937f95275c66f9fd9c" },
-    { url = "https://download.pytorch.org/whl/cpu/torch-2.10.0%2Bcpu-cp313-cp313-linux_s390x.whl", hash = "sha256:170a0623108055be5199370335cf9b41ba6875b3cb6f086db4aee583331a4899" },
-    { url = "https://download.pytorch.org/whl/cpu/torch-2.10.0%2Bcpu-cp313-cp313-manylinux_2_28_aarch64.whl", hash = "sha256:e51994492cdb76edce29da88de3672a3022f9ef0ffd90345436948d4992be2c7" },
-    { url = "https://download.pytorch.org/whl/cpu/torch-2.10.0%2Bcpu-cp313-cp313-manylinux_2_28_x86_64.whl", hash = "sha256:8d316e5bf121f1eab1147e49ad0511a9d92e4c45cc357d1ab0bee440da71a095" },
-    { url = "https://download.pytorch.org/whl/cpu/torch-2.10.0%2Bcpu-cp313-cp313-win_amd64.whl", hash = "sha256:b719da5af01b59126ac13eefd6ba3dd12d002dc0e8e79b8b365e55267a8189d3" },
-    { url = "https://download.pytorch.org/whl/cpu/torch-2.10.0%2Bcpu-cp313-cp313-win_arm64.whl", hash = "sha256:b67d91326e4ed9eccbd6b7d84ed7ffa43f93103aa3f0b24145f3001f3b11b714" },
-    { url = "https://download.pytorch.org/whl/cpu/torch-2.10.0%2Bcpu-cp313-cp313t-linux_aarch64.whl", hash = "sha256:5af75e5f49de21b0bdf7672bc27139bd285f9e8dbcabe2d617a2eb656514ac36" },
-    { url = "https://download.pytorch.org/whl/cpu/torch-2.10.0%2Bcpu-cp313-cp313t-linux_s390x.whl", hash = "sha256:ba51ef01a510baf8fff576174f702c47e1aa54389a9f1fba323bb1a5003ff0bf" },
-    { url = "https://download.pytorch.org/whl/cpu/torch-2.10.0%2Bcpu-cp313-cp313t-manylinux_2_28_aarch64.whl", hash = "sha256:0fedcb1a77e8f2aaf7bfd21591bf6d1e0b207473268c9be16b17cb7783253969" },
-    { url = "https://download.pytorch.org/whl/cpu/torch-2.10.0%2Bcpu-cp313-cp313t-manylinux_2_28_x86_64.whl", hash = "sha256:106dd1930cb30a4a337366ba3f9b25318ebf940f51fd46f789281dd9e736bdc4" },
-    { url = "https://download.pytorch.org/whl/cpu/torch-2.10.0%2Bcpu-cp313-cp313t-win_amd64.whl", hash = "sha256:eb1bde1ce198f05c8770017de27e001d404499cf552aaaa014569eff56ca25c0" },
-    { url = "https://download.pytorch.org/whl/cpu/torch-2.10.0%2Bcpu-cp314-cp314-linux_aarch64.whl", hash = "sha256:ea2bcc9d1fca66974a71d4bf9a502539283f35d61fcab5a799b4e120846f1e02" },
-    { url = "https://download.pytorch.org/whl/cpu/torch-2.10.0%2Bcpu-cp314-cp314-linux_s390x.whl", hash = "sha256:f8294fd2fc6dd8f4435a891a0122307a043b14b21f0dac1bca63c85bfb59e586" },
-    { url = "https://download.pytorch.org/whl/cpu/torch-2.10.0%2Bcpu-cp314-cp314-manylinux_2_28_aarch64.whl", hash = "sha256:a28fdbcfa2fbacffec81300f24dd1bed2b0ccfdbed107a823cff12bc1db070f6" },
-    { url = "https://download.pytorch.org/whl/cpu/torch-2.10.0%2Bcpu-cp314-cp314-manylinux_2_28_x86_64.whl", hash = "sha256:aada8afc068add586464b2a55adb7cc9091eec55caf5320447204741cb6a0604" },
-    { url = "https://download.pytorch.org/whl/cpu/torch-2.10.0%2Bcpu-cp314-cp314-win_amd64.whl", hash = "sha256:2adc71fe471e98a608723bfc837f7e1929885ebb912c693597711e139c1cda41" },
-    { url = "https://download.pytorch.org/whl/cpu/torch-2.10.0%2Bcpu-cp314-cp314t-linux_aarch64.whl", hash = "sha256:9412bd37b70f5ebd1205242c4ba4cabae35a605947f2b30806d5c9b467936db9" },
-    { url = "https://download.pytorch.org/whl/cpu/torch-2.10.0%2Bcpu-cp314-cp314t-linux_s390x.whl", hash = "sha256:e71c476517c33e7db69825a9ff46c7f47a723ec4dac5b2481cff4246d1c632be" },
-    { url = "https://download.pytorch.org/whl/cpu/torch-2.10.0%2Bcpu-cp314-cp314t-manylinux_2_28_aarch64.whl", hash = "sha256:23882f8d882460aca809882fc42f5e343bf07585274f929ced00177d1be1eb67" },
-    { url = "https://download.pytorch.org/whl/cpu/torch-2.10.0%2Bcpu-cp314-cp314t-manylinux_2_28_x86_64.whl", hash = "sha256:4fcd8b4cc2ae20f2b7749fb275349c55432393868778c2d50a08e81d5ee5591e" },
-    { url = "https://download.pytorch.org/whl/cpu/torch-2.10.0%2Bcpu-cp314-cp314t-win_amd64.whl", hash = "sha256:ffc8da9a1341092d6a90cb5b1c1a33cd61abf0fb43f0cd88443c27fa372c26ae" },
+    { url = "https://download-r2.pytorch.org/whl/cpu/torch-2.10.0%2Bcpu-cp312-cp312-linux_aarch64.whl", hash = "sha256:8de5a36371b775e2d4881ed12cc7f2de400b1ad3d728aa74a281f649f87c9b8c" },
+    { url = "https://download-r2.pytorch.org/whl/cpu/torch-2.10.0%2Bcpu-cp312-cp312-linux_s390x.whl", hash = "sha256:9accc30b56cb6756d4a9d04fcb8ebc0bb68c7d55c1ed31a8657397d316d31596" },
+    { url = "https://download-r2.pytorch.org/whl/cpu/torch-2.10.0%2Bcpu-cp312-cp312-manylinux_2_28_aarch64.whl", hash = "sha256:179451716487f8cb09b56459667fa1f5c4c0946c1e75fbeae77cfc40a5768d87" },
+    { url = "https://download-r2.pytorch.org/whl/cpu/torch-2.10.0%2Bcpu-cp312-cp312-manylinux_2_28_x86_64.whl", hash = "sha256:ee40b8a4b4b2cf0670c6fd4f35a7ef23871af956fecb238fbf5da15a72650b1d" },
+    { url = "https://download-r2.pytorch.org/whl/cpu/torch-2.10.0%2Bcpu-cp312-cp312-win_amd64.whl", hash = "sha256:21cb5436978ef47c823b7a813ff0f8c2892e266cfe0f1d944879b5fba81bf4e1" },
+    { url = "https://download-r2.pytorch.org/whl/cpu/torch-2.10.0%2Bcpu-cp312-cp312-win_arm64.whl", hash = "sha256:3eaa727e6a73affa61564d86b9d03191df45c8650d0666bd3d57c8597ef61e78" },
+    { url = "https://download-r2.pytorch.org/whl/cpu/torch-2.10.0%2Bcpu-cp313-cp313-linux_aarch64.whl", hash = "sha256:fd215f3d0f681905c5b56b0630a3d666900a37fcc3ca5b937f95275c66f9fd9c" },
+    { url = "https://download-r2.pytorch.org/whl/cpu/torch-2.10.0%2Bcpu-cp313-cp313-linux_s390x.whl", hash = "sha256:170a0623108055be5199370335cf9b41ba6875b3cb6f086db4aee583331a4899" },
+    { url = "https://download-r2.pytorch.org/whl/cpu/torch-2.10.0%2Bcpu-cp313-cp313-manylinux_2_28_aarch64.whl", hash = "sha256:e51994492cdb76edce29da88de3672a3022f9ef0ffd90345436948d4992be2c7" },
+    { url = "https://download-r2.pytorch.org/whl/cpu/torch-2.10.0%2Bcpu-cp313-cp313-manylinux_2_28_x86_64.whl", hash = "sha256:8d316e5bf121f1eab1147e49ad0511a9d92e4c45cc357d1ab0bee440da71a095" },
+    { url = "https://download-r2.pytorch.org/whl/cpu/torch-2.10.0%2Bcpu-cp313-cp313-win_amd64.whl", hash = "sha256:b719da5af01b59126ac13eefd6ba3dd12d002dc0e8e79b8b365e55267a8189d3" },
+    { url = "https://download-r2.pytorch.org/whl/cpu/torch-2.10.0%2Bcpu-cp313-cp313-win_arm64.whl", hash = "sha256:b67d91326e4ed9eccbd6b7d84ed7ffa43f93103aa3f0b24145f3001f3b11b714" },
+    { url = "https://download-r2.pytorch.org/whl/cpu/torch-2.10.0%2Bcpu-cp313-cp313t-linux_aarch64.whl", hash = "sha256:5af75e5f49de21b0bdf7672bc27139bd285f9e8dbcabe2d617a2eb656514ac36" },
+    { url = "https://download-r2.pytorch.org/whl/cpu/torch-2.10.0%2Bcpu-cp313-cp313t-linux_s390x.whl", hash = "sha256:ba51ef01a510baf8fff576174f702c47e1aa54389a9f1fba323bb1a5003ff0bf" },
+    { url = "https://download-r2.pytorch.org/whl/cpu/torch-2.10.0%2Bcpu-cp313-cp313t-manylinux_2_28_aarch64.whl", hash = "sha256:0fedcb1a77e8f2aaf7bfd21591bf6d1e0b207473268c9be16b17cb7783253969" },
+    { url = "https://download-r2.pytorch.org/whl/cpu/torch-2.10.0%2Bcpu-cp313-cp313t-manylinux_2_28_x86_64.whl", hash = "sha256:106dd1930cb30a4a337366ba3f9b25318ebf940f51fd46f789281dd9e736bdc4" },
+    { url = "https://download-r2.pytorch.org/whl/cpu/torch-2.10.0%2Bcpu-cp313-cp313t-win_amd64.whl", hash = "sha256:eb1bde1ce198f05c8770017de27e001d404499cf552aaaa014569eff56ca25c0" },
+    { url = "https://download-r2.pytorch.org/whl/cpu/torch-2.10.0%2Bcpu-cp314-cp314-linux_aarch64.whl", hash = "sha256:ea2bcc9d1fca66974a71d4bf9a502539283f35d61fcab5a799b4e120846f1e02" },
+    { url = "https://download-r2.pytorch.org/whl/cpu/torch-2.10.0%2Bcpu-cp314-cp314-linux_s390x.whl", hash = "sha256:f8294fd2fc6dd8f4435a891a0122307a043b14b21f0dac1bca63c85bfb59e586" },
+    { url = "https://download-r2.pytorch.org/whl/cpu/torch-2.10.0%2Bcpu-cp314-cp314-manylinux_2_28_aarch64.whl", hash = "sha256:a28fdbcfa2fbacffec81300f24dd1bed2b0ccfdbed107a823cff12bc1db070f6" },
+    { url = "https://download-r2.pytorch.org/whl/cpu/torch-2.10.0%2Bcpu-cp314-cp314-manylinux_2_28_x86_64.whl", hash = "sha256:aada8afc068add586464b2a55adb7cc9091eec55caf5320447204741cb6a0604" },
+    { url = "https://download-r2.pytorch.org/whl/cpu/torch-2.10.0%2Bcpu-cp314-cp314-win_amd64.whl", hash = "sha256:2adc71fe471e98a608723bfc837f7e1929885ebb912c693597711e139c1cda41" },
+    { url = "https://download-r2.pytorch.org/whl/cpu/torch-2.10.0%2Bcpu-cp314-cp314t-linux_aarch64.whl", hash = "sha256:9412bd37b70f5ebd1205242c4ba4cabae35a605947f2b30806d5c9b467936db9" },
+    { url = "https://download-r2.pytorch.org/whl/cpu/torch-2.10.0%2Bcpu-cp314-cp314t-linux_s390x.whl", hash = "sha256:e71c476517c33e7db69825a9ff46c7f47a723ec4dac5b2481cff4246d1c632be" },
+    { url = "https://download-r2.pytorch.org/whl/cpu/torch-2.10.0%2Bcpu-cp314-cp314t-manylinux_2_28_aarch64.whl", hash = "sha256:23882f8d882460aca809882fc42f5e343bf07585274f929ced00177d1be1eb67" },
+    { url = "https://download-r2.pytorch.org/whl/cpu/torch-2.10.0%2Bcpu-cp314-cp314t-manylinux_2_28_x86_64.whl", hash = "sha256:4fcd8b4cc2ae20f2b7749fb275349c55432393868778c2d50a08e81d5ee5591e" },
+    { url = "https://download-r2.pytorch.org/whl/cpu/torch-2.10.0%2Bcpu-cp314-cp314t-win_amd64.whl", hash = "sha256:ffc8da9a1341092d6a90cb5b1c1a33cd61abf0fb43f0cd88443c27fa372c26ae" },
 ]
 
 [[package]]
@@ -4955,7 +4955,7 @@ wheels = [
 
 [[package]]
 name = "vektra-admin"
-version = "0.4.0.dev0"
+version = "0.5.0.dev0"
 source = { editable = "vektra-admin" }
 dependencies = [
     { name = "argon2-cffi" },
@@ -5004,7 +5004,7 @@ dev = [
 
 [[package]]
 name = "vektra-analytics"
-version = "0.4.0.dev0"
+version = "0.5.0.dev0"
 source = { editable = "vektra-analytics" }
 dependencies = [
     { name = "fastapi" },
@@ -5039,7 +5039,7 @@ dev = [
 
 [[package]]
 name = "vektra-app"
-version = "0.4.0.dev0"
+version = "0.5.0.dev0"
 source = { editable = "vektra-app" }
 dependencies = [
     { name = "alembic" },
@@ -5088,7 +5088,7 @@ dev = [
 
 [[package]]
 name = "vektra-core"
-version = "0.4.0.dev0"
+version = "0.5.0.dev0"
 source = { editable = "vektra-core" }
 dependencies = [
     { name = "fastapi" },
@@ -5131,7 +5131,7 @@ dev = [
 
 [[package]]
 name = "vektra-index"
-version = "0.4.0.dev0"
+version = "0.5.0.dev0"
 source = { editable = "vektra-index" }
 dependencies = [
     { name = "asyncpg" },
@@ -5186,7 +5186,7 @@ dev = [
 
 [[package]]
 name = "vektra-ingest"
-version = "0.4.0.dev0"
+version = "0.5.0.dev0"
 source = { editable = "vektra-ingest" }
 dependencies = [
     { name = "arq" },
@@ -5248,7 +5248,7 @@ dev = [
 
 [[package]]
 name = "vektra-learn"
-version = "0.4.0.dev0"
+version = "0.5.0.dev0"
 source = { editable = "vektra-learn" }
 dependencies = [
     { name = "fastapi" },
@@ -5285,7 +5285,7 @@ dev = [
 
 [[package]]
 name = "vektra-shared"
-version = "0.4.0.dev0"
+version = "0.5.0.dev0"
 source = { editable = "vektra-shared" }
 dependencies = [
     { name = "asyncpg" },
diff --git a/vektra-admin/pyproject.toml b/vektra-admin/pyproject.toml
index be40f26a..18c28b92 100644
--- a/vektra-admin/pyproject.toml
+++ b/vektra-admin/pyproject.toml
@@ -1,6 +1,6 @@
 [project]
 name = "vektra-admin"
-version = "0.4.0-dev"
+version = "0.5.0-dev"
 description = "System administration interface: health, API key management, audit log"
 readme = "README.md"
 requires-python = ">=3.12"
diff --git a/vektra-admin/src/vektra_admin/api.py b/vektra-admin/src/vektra_admin/api.py
index 60154039..1fbe30e2 100644
--- a/vektra-admin/src/vektra_admin/api.py
+++ b/vektra-admin/src/vektra_admin/api.py
@@ -29,6 +29,7 @@
 from pydantic import BaseModel, field_validator
 from sqlalchemy import select
 from sqlalchemy.ext.asyncio import AsyncSession
+from sqlalchemy.orm.attributes import flag_modified
 
 from vektra_admin import audit as _audit
 from vektra_admin import bootstrap as _bootstrap
@@ -43,6 +44,17 @@
     http_status_for,
 )
 
+# ---------------------------------------------------------------------------
+# Namespace config whitelist (WI-3)
+# ---------------------------------------------------------------------------
+# Tight whitelist: unknown keys are rejected (not silently ignored) so that
+# typos from upstream clients (e.g. Moodle plugin) surface immediately. Each
+# key is a public contract — extend cautiously.
+ALLOWED_CONFIG_KEYS: set[str] = {"grounding_mode"}
+ALLOWED_CONFIG_VALUES: dict[str, set[str]] = {
+    "grounding_mode": {"strict", "hybrid"},
+}
+
 log = structlog.get_logger(__name__)
 
 router = APIRouter()
@@ -510,6 +522,126 @@ async def get_conversation_turns(
     return turns
 
 
+# ---------------------------------------------------------------------------
+# Namespace configuration (WI-3, FEAT-020 write path)
+# ---------------------------------------------------------------------------
+
+
+class NamespaceConfigResponse(BaseModel):
+    """Full namespace config after a PATCH merge."""
+
+    namespace_id: str
+    config: dict[str, Any]
+
+
+@router.patch(
+    "/api/v1/admin/namespaces/{namespace_id}/config",
+    response_model=NamespaceConfigResponse,
+)
+async def patch_namespace_config(
+    namespace_id: str,
+    body: dict[str, Any],
+    request: Request,
+    background_tasks: BackgroundTasks,
+    session: AsyncSession = Depends(get_session),
+    key_info: ApiKeyInfo = Depends(require_scope("admin")),
+) -> NamespaceConfigResponse:
+    """Partially update a namespace's config JSONB.
+
+    Behavior:
+      - Flat body, one entry per config key (e.g. ``{"grounding_mode": "hybrid"}``).
+      - Partial update: keys not present in the body are preserved.
+      - ``null`` value removes the key from config (falls back to env default
+        when resolved downstream, see :mod:`vektra_shared.namespace`).
+      - Unknown keys are rejected with 400 (not silently ignored) to surface
+        typos from upstream clients (e.g. Moodle plugin) during development.
+    """
+    from vektra_admin.models import NamespaceOrm  # late import
+
+    # --- Validate body: unknown keys rejected (ERR-ADMIN-006) ---
+    unknown_keys = set(body.keys()) - ALLOWED_CONFIG_KEYS
+    if unknown_keys:
+        err = ErrorResponse(
+            category=ErrorCategory.PERMANENT,
+            code="ERR-ADMIN-006",
+            message=f"Unknown config keys: {sorted(unknown_keys)}.",
+            remediation=(
+                f"Use only allowed keys: {sorted(ALLOWED_CONFIG_KEYS)}. "
+                "Unknown keys are rejected to surface typos early."
+            ),
+        )
+        raise HTTPException(status_code=400, detail=err.to_envelope())
+
+    # --- Validate each value: must be in per-key enum or null (ERR-ADMIN-007) ---
+    for key, value in body.items():
+        if value is None:
+            continue  # null = remove the key
+        allowed_values = ALLOWED_CONFIG_VALUES.get(key)
+        if allowed_values is not None and value not in allowed_values:
+            err = ErrorResponse(
+                category=ErrorCategory.PERMANENT,
+                code="ERR-ADMIN-007",
+                message=f"Invalid value for '{key}': {value!r}.",
+                remediation=(
+                    f"Use one of: {sorted(allowed_values)}, or null to unset."
+                ),
+            )
+            raise HTTPException(status_code=400, detail=err.to_envelope())
+
+    # --- Load namespace (ERR-ADMIN-005 if missing) ---
+    result = await session.execute(
+        select(NamespaceOrm).where(NamespaceOrm.id == namespace_id)
+    )
+    ns = result.scalar_one_or_none()
+    if ns is None:
+        err = ErrorResponse(
+            category=ErrorCategory.PERMANENT,
+            code="ERR-ADMIN-005",
+            message=f"Namespace '{namespace_id}' not found.",
+            remediation="Verify the namespace id or create it via the admin UI.",
+        )
+        raise HTTPException(status_code=404, detail=err.to_envelope())
+
+    # --- Merge: null removes, non-null sets ---
+    current_config: dict[str, Any] = dict(ns.ns_config or {})
+    for key, value in body.items():
+        if value is None:
+            current_config.pop(key, None)
+        else:
+            current_config[key] = value
+
+    ns.ns_config = current_config
+    ns.updated_at = datetime.now(UTC)
+    # JSONB mutation tracking: reassignment above is sufficient, but be explicit
+    flag_modified(ns, "ns_config")
+    await session.commit()
+
+    # --- Audit log (NFR-007): config change is an administrative event ---
+    request_id = getattr(request.state, "request_id", None)
+    if request_id:
+        background_tasks.add_task(
+            _audit.log_event,
+            key_id=key_info.key_id,
+            endpoint=f"/api/v1/admin/namespaces/{namespace_id}/config",
+            method="PATCH",
+            status_code=200,
+            request_id=request_id,
+            action="namespace_config_updated",
+            log_metadata={
+                "namespace_id": namespace_id,
+                "updated_keys": sorted(body.keys()),
+            },
+        )
+
+    log.info(
+        "namespace_config_updated",
+        namespace_id=namespace_id,
+        updated_keys=sorted(body.keys()),
+    )
+
+    return NamespaceConfigResponse(namespace_id=namespace_id, config=current_config)
+
+
 # ---------------------------------------------------------------------------
 # Admin HTML dashboard (REQ-006)
 # ---------------------------------------------------------------------------
diff --git a/vektra-admin/tests/test_integration.py b/vektra-admin/tests/test_integration.py
index 09ac9cb4..d52325f4 100644
--- a/vektra-admin/tests/test_integration.py
+++ b/vektra-admin/tests/test_integration.py
@@ -531,3 +531,240 @@ async def test_ui_config_page(client, bootstrap_key):
     assert resp.status_code == 200
     assert "System configuration" in resp.text
     assert "Active providers" in resp.text
+
+
+# ---------------------------------------------------------------------------
+# Namespace config PATCH (WI-3)
+# ---------------------------------------------------------------------------
+#
+# These tests use short-lived sessions (via ``fresh_engine`` factory) for DB
+# setup and verification instead of the long-lived ``session`` fixture. The
+# test engine has ``pool_size=2, max_overflow=0``; holding the session while
+# the HTTP request path also needs a connection (plus the audit background
+# task scheduled inside the PATCH handler) can exhaust the pool and time out.
+
+
+async def _seed_namespace(fresh_engine, ns_id: str, config: dict | None = None) -> None:
+    """Insert (or replace) a namespace with the given config, releasing the
+    connection immediately after commit."""
+    import json
+
+    cfg_json = json.dumps(config or {})
+    async with fresh_engine() as s:
+        await s.execute(text("DELETE FROM namespaces WHERE id = :ns"), {"ns": ns_id})
+        await s.execute(
+            text(
+                "INSERT INTO namespaces (id, display_name, config) "
+                "VALUES (:ns, :name, CAST(:cfg AS jsonb))"
+            ),
+            {"ns": ns_id, "name": f"Test {ns_id}", "cfg": cfg_json},
+        )
+        await s.commit()
+
+
+async def _read_namespace_config(fresh_engine, ns_id: str) -> dict:
+    async with fresh_engine() as s:
+        result = await s.execute(
+            text("SELECT config FROM namespaces WHERE id = :ns"), {"ns": ns_id}
+        )
+        return result.scalar_one()
+
+
+async def test_namespace_config_patch_sets_grounding_mode(
+    client, bootstrap_key, fresh_engine
+):
+    """PATCH with grounding_mode=hybrid persists in namespaces.config JSONB."""
+    admin_key = await _create_admin_key(client, bootstrap_key)
+    ns_id = "wi3-set-grounding"
+    await _seed_namespace(fresh_engine, ns_id)
+
+    resp = await client.patch(
+        f"/api/v1/admin/namespaces/{ns_id}/config",
+        json={"grounding_mode": "hybrid"},
+        headers={"Authorization": f"Bearer {admin_key}"},
+    )
+    assert resp.status_code == 200, resp.text
+    body = resp.json()
+    assert body["namespace_id"] == ns_id
+    assert body["config"] == {"grounding_mode": "hybrid"}
+
+    # Allow the audit background task to complete before reading the DB
+    await asyncio.sleep(0.2)
+    stored = await _read_namespace_config(fresh_engine, ns_id)
+    assert stored == {"grounding_mode": "hybrid"}
+
+
+async def test_namespace_config_patch_rejects_unknown_key(
+    client, bootstrap_key, fresh_engine
+):
+    """PATCH with unknown key returns 400 + ERR-ADMIN-006, includes key in message."""
+    admin_key = await _create_admin_key(client, bootstrap_key)
+    ns_id = "wi3-unknown-key"
+    await _seed_namespace(fresh_engine, ns_id)
+
+    resp = await client.patch(
+        f"/api/v1/admin/namespaces/{ns_id}/config",
+        json={"not_a_real_key": "whatever"},
+        headers={"Authorization": f"Bearer {admin_key}"},
+    )
+    assert resp.status_code == 400, resp.text
+    err = resp.json()["detail"]["error"]
+    assert err["code"] == "ERR-ADMIN-006"
+    assert "not_a_real_key" in err["message"]
+
+
+async def test_namespace_config_patch_rejects_invalid_value(
+    client, bootstrap_key, fresh_engine
+):
+    """PATCH with grounding_mode='banana' returns 400 + ERR-ADMIN-007."""
+    admin_key = await _create_admin_key(client, bootstrap_key)
+    ns_id = "wi3-invalid-value"
+    await _seed_namespace(fresh_engine, ns_id)
+
+    resp = await client.patch(
+        f"/api/v1/admin/namespaces/{ns_id}/config",
+        json={"grounding_mode": "banana"},
+        headers={"Authorization": f"Bearer {admin_key}"},
+    )
+    assert resp.status_code == 400, resp.text
+    err = resp.json()["detail"]["error"]
+    assert err["code"] == "ERR-ADMIN-007"
+    assert "banana" in err["message"]
+
+
+async def test_namespace_config_patch_rejects_non_string_value(
+    client, bootstrap_key, fresh_engine
+):
+    """Guard against clients (e.g. Moodle plugin) sending the wrong JSON type.
+
+    42 is not in the allowed enum; the whitelist check rejects it regardless
+    of runtime type. Without this test the behaviour would silently work
+    today but could regress to a permissive type-coercing check.
+    """
+    admin_key = await _create_admin_key(client, bootstrap_key)
+    ns_id = "wi3-nonstring-value"
+    await _seed_namespace(fresh_engine, ns_id)
+
+    resp = await client.patch(
+        f"/api/v1/admin/namespaces/{ns_id}/config",
+        json={"grounding_mode": 42},
+        headers={"Authorization": f"Bearer {admin_key}"},
+    )
+    assert resp.status_code == 400, resp.text
+    err = resp.json()["detail"]["error"]
+    assert err["code"] == "ERR-ADMIN-007"
+
+
+async def test_namespace_config_patch_null_removes_key(
+    client, bootstrap_key, fresh_engine
+):
+    """PATCH with null value removes the key from config (falls back to env default)."""
+    admin_key = await _create_admin_key(client, bootstrap_key)
+    ns_id = "wi3-null-removes"
+    await _seed_namespace(fresh_engine, ns_id)
+
+    r1 = await client.patch(
+        f"/api/v1/admin/namespaces/{ns_id}/config",
+        json={"grounding_mode": "strict"},
+        headers={"Authorization": f"Bearer {admin_key}"},
+    )
+    assert r1.status_code == 200
+    assert r1.json()["config"] == {"grounding_mode": "strict"}
+
+    r2 = await client.patch(
+        f"/api/v1/admin/namespaces/{ns_id}/config",
+        json={"grounding_mode": None},
+        headers={"Authorization": f"Bearer {admin_key}"},
+    )
+    assert r2.status_code == 200, r2.text
+    assert r2.json()["config"] == {}
+
+    await asyncio.sleep(0.2)
+    stored = await _read_namespace_config(fresh_engine, ns_id)
+    assert stored == {}
+
+
+async def test_namespace_config_patch_is_partial(client, bootstrap_key, fresh_engine):
+    """PATCH merges: existing keys not in the body are preserved.
+
+    Seed with a "legacy" key that the whitelist does not recognise; it must
+    survive the PATCH even though it is not writable via the API.
+    """
+    admin_key = await _create_admin_key(client, bootstrap_key)
+    ns_id = "wi3-partial-merge"
+    await _seed_namespace(
+        fresh_engine,
+        ns_id,
+        config={"grounding_mode": "strict", "legacy_field": "keep"},
+    )
+
+    resp = await client.patch(
+        f"/api/v1/admin/namespaces/{ns_id}/config",
+        json={"grounding_mode": "hybrid"},
+        headers={"Authorization": f"Bearer {admin_key}"},
+    )
+    assert resp.status_code == 200, resp.text
+    body = resp.json()
+    assert body["config"]["grounding_mode"] == "hybrid"
+    assert body["config"]["legacy_field"] == "keep"
+
+
+async def test_namespace_config_patch_not_found(client, bootstrap_key):
+    """PATCH on non-existent namespace returns 404 + ERR-ADMIN-005."""
+    admin_key = await _create_admin_key(client, bootstrap_key)
+    resp = await client.patch(
+        "/api/v1/admin/namespaces/does-not-exist/config",
+        json={"grounding_mode": "strict"},
+        headers={"Authorization": f"Bearer {admin_key}"},
+    )
+    assert resp.status_code == 404, resp.text
+    assert resp.json()["detail"]["error"]["code"] == "ERR-ADMIN-005"
+
+
+async def test_namespace_config_patch_requires_admin_scope(
+    client, bootstrap_key, fresh_engine
+):
+    """PATCH with a non-admin (query-only) key returns 403."""
+    admin_key = await _create_admin_key(client, bootstrap_key)
+    ns_id = "wi3-scope-check"
+    await _seed_namespace(fresh_engine, ns_id)
+
+    resp = await client.post(
+        "/api/v1/api-keys",
+        json={"label": "query-only", "scopes": ["query"]},
+        headers={"Authorization": f"Bearer {admin_key}"},
+    )
+    assert resp.status_code == 201
+    query_key = resp.json()["key"]
+
+    resp = await client.patch(
+        f"/api/v1/admin/namespaces/{ns_id}/config",
+        json={"grounding_mode": "hybrid"},
+        headers={"Authorization": f"Bearer {query_key}"},
+    )
+    assert resp.status_code == 403, resp.text
+
+
+async def test_namespace_config_patch_resolves_via_shared_helper(
+    client, bootstrap_key, fresh_engine
+):
+    """End-to-end: PATCH → resolve_grounding_mode returns the persisted value.
+
+    Proves WI-3 write path is read by FEAT-020's resolver with no cache in between.
+    """
+    from vektra_shared.namespace import resolve_grounding_mode
+
+    admin_key = await _create_admin_key(client, bootstrap_key)
+    ns_id = "wi3-end-to-end"
+    await _seed_namespace(fresh_engine, ns_id)
+
+    resp = await client.patch(
+        f"/api/v1/admin/namespaces/{ns_id}/config",
+        json={"grounding_mode": "hybrid"},
+        headers={"Authorization": f"Bearer {admin_key}"},
+    )
+    assert resp.status_code == 200
+    await asyncio.sleep(0.2)  # let audit background task complete before re-using pool
+
+    mode = await resolve_grounding_mode(ns_id, fresh_engine, default_mode="strict")
+    assert mode == "hybrid"
diff --git a/vektra-analytics/pyproject.toml b/vektra-analytics/pyproject.toml
index 6deb1c90..3481f016 100644
--- a/vektra-analytics/pyproject.toml
+++ b/vektra-analytics/pyproject.toml
@@ -1,6 +1,6 @@
 [project]
 name = "vektra-analytics"
-version = "0.4.0-dev"
+version = "0.5.0-dev"
 description = "QueryTrace storage, metrics aggregation, and reporting API"
 readme = "README.md"
 requires-python = ">=3.12"
diff --git a/vektra-app/pyproject.toml b/vektra-app/pyproject.toml
index 4aab9522..a5c76358 100644
--- a/vektra-app/pyproject.toml
+++ b/vektra-app/pyproject.toml
@@ -1,6 +1,6 @@
 [project]
 name = "vektra-app"
-version = "0.4.0-dev"
+version = "0.5.0-dev"
 description = "FastAPI application assembly and startup validation (ARCH-015, ARCH-057)"
 readme = "README.md"
 requires-python = ">=3.12"
diff --git a/vektra-core/pyproject.toml b/vektra-core/pyproject.toml
index a14a1d12..500c77b1 100644
--- a/vektra-core/pyproject.toml
+++ b/vektra-core/pyproject.toml
@@ -1,6 +1,6 @@
 [project]
 name = "vektra-core"
-version = "0.4.0-dev"
+version = "0.5.0-dev"
 description = "RAG engine, LLM abstraction, and conversation management"
 readme = "README.md"
 requires-python = ">=3.12"
diff --git a/vektra-core/src/vektra_core/advanced_pipeline.py b/vektra-core/src/vektra_core/advanced_pipeline.py
index 4e1984c5..68cee4aa 100644
--- a/vektra-core/src/vektra_core/advanced_pipeline.py
+++ b/vektra-core/src/vektra_core/advanced_pipeline.py
@@ -32,6 +32,7 @@
     _context_window_impl,
     _count_tokens_impl,
     _elapsed_ms,
+    _fetch_document_names,
     _history_to_messages,
     _trace_to_dict,
 )
@@ -544,6 +545,18 @@ async def execute(
         steps.append(prompt_step)
 
         # Sources from budget-selected chunks only (not all filtered)
+        t0 = time.monotonic()
+        name_map = await _fetch_document_names([r.document_id for r in selected_chunks])
+        steps.append(
+            StepTrace(
+                name="document_names",
+                duration_ms=_elapsed_ms(t0),
+                metadata={
+                    "requested": len(selected_chunks),
+                    "resolved": len(name_map),
+                },
+            )
+        )
         sources = [
             SourceRef(
                 doc_id=r.document_id,
@@ -552,6 +565,7 @@ async def execute(
                 snippet=r.text_snippet,
                 citation_id=uuid4(),
                 document_version=r.document_version,
+                document_name=name_map.get(str(r.document_id)),
             )
             for r in selected_chunks
         ]
@@ -791,6 +805,18 @@ async def _stream(
                 log.warning("conversation_turn_store_failed", error=str(exc))
 
         # Yield sources (only budget-selected chunks, not all filtered)
+        t0 = time.monotonic()
+        name_map = await _fetch_document_names([r.document_id for r in selected_chunks])
+        steps.append(
+            StepTrace(
+                name="document_names",
+                duration_ms=_elapsed_ms(t0),
+                metadata={
+                    "requested": len(selected_chunks),
+                    "resolved": len(name_map),
+                },
+            )
+        )
         sources_data = [
             {
                 "doc_id": str(r.document_id),
@@ -799,6 +825,7 @@ async def _stream(
                 "snippet": r.text_snippet,
                 "citation_id": str(uuid4()),
                 "document_version": r.document_version,
+                "document_name": name_map.get(str(r.document_id)),
             }
             for r in selected_chunks
         ]
diff --git a/vektra-core/src/vektra_core/api.py b/vektra-core/src/vektra_core/api.py
index f1b39b16..023c563d 100644
--- a/vektra-core/src/vektra_core/api.py
+++ b/vektra-core/src/vektra_core/api.py
@@ -76,6 +76,7 @@ class SourceRefBody(BaseModel):
     snippet: str
     citation_id: UUID
     document_version: int = 1
+    document_name: str | None = None  # FEAT-012
 
 
 class QueryResponseBody(BaseModel):
@@ -354,6 +355,7 @@ async def query(
                 snippet=s.snippet,
                 citation_id=s.citation_id,
                 document_version=s.document_version,
+                document_name=s.document_name,
             )
             for s in response.sources
         ],
diff --git a/vektra-core/src/vektra_core/pipeline.py b/vektra-core/src/vektra_core/pipeline.py
index e8d58f6a..cd950372 100644
--- a/vektra-core/src/vektra_core/pipeline.py
+++ b/vektra-core/src/vektra_core/pipeline.py
@@ -24,6 +24,7 @@
 
 import litellm
 import structlog
+from sqlalchemy import text
 
 from vektra_core.budget import allocate_token_budget
 from vektra_core.conversation import ConversationStore
@@ -70,6 +71,60 @@ def _history_to_messages(history: list[dict[str, str | None]]) -> list[Message]:
     return messages
 
 
+async def _fetch_document_names(
+    doc_ids: list[Any],
+) -> dict[str, str]:
+    """Resolve document IDs to their filenames for source citations (FEAT-012).
+
+    Batch lookup against ``source_documents``. Soft-deleted documents
+    (REQ-057) are still returned with an ``(archived)`` suffix rather than
+    hidden: the citation must match what was actually retrieved from the
+    vector store, otherwise students see answers with no traceable source.
+
+    Keys are always stringified: asyncpg returns ``uuid.UUID`` objects for
+    UUID columns and callers may pass either ``UUID`` or ``str`` ids, so
+    the map is normalised to ``str`` on both ends to avoid silent lookup
+    misses. Call sites use ``name_map.get(str(r.document_id))``.
+
+    Returns an empty map on any failure (DB not initialized in tests,
+    transient DB error, etc.) — the pipeline must continue to respond even
+    if citations lose their human-readable label. Widget falls back to
+    ``chunk_id`` when a name is missing.
+    """
+    if not doc_ids:
+        return {}
+
+    # Late import to avoid initialization ordering issues in tests that stub
+    # out the DB layer.
+    from vektra_shared.db import get_session_factory
+
+    try:
+        factory = get_session_factory()
+    except RuntimeError:
+        return {}
+
+    unique_ids = list({str(d) for d in doc_ids})
+    try:
+        async with factory() as session:
+            result = await session.execute(
+                text(
+                    "SELECT id, filename, deleted_at FROM source_documents "
+                    "WHERE id = ANY(CAST(:ids AS uuid[]))"
+                ),
+                {"ids": unique_ids},
+            )
+            out: dict[str, str] = {}
+            for row in result.all():
+                name = row[1]
+                if row[2] is not None:
+                    name = f"{name} (archived)"
+                out[str(row[0])] = name
+            return out
+    except Exception as exc:
+        log.debug("document_names_fetch_failed", error=str(exc))
+        return {}
+
+
 # ---------------------------------------------------------------------------
 # Retrieval filter (ARCH-056)
 # ---------------------------------------------------------------------------
@@ -519,6 +574,18 @@ async def execute(
         )
 
         # Sources from budget-selected chunks only (not all filtered)
+        t0 = time.monotonic()
+        name_map = await _fetch_document_names([r.document_id for r in selected_chunks])
+        steps.append(
+            StepTrace(
+                name="document_names",
+                duration_ms=_elapsed_ms(t0),
+                metadata={
+                    "requested": len(selected_chunks),
+                    "resolved": len(name_map),
+                },
+            )
+        )
         sources = [
             SourceRef(
                 doc_id=r.document_id,
@@ -527,6 +594,7 @@ async def execute(
                 snippet=r.text_snippet,
                 citation_id=uuid4(),
                 document_version=r.document_version,
+                document_name=name_map.get(str(r.document_id)),
             )
             for r in selected_chunks
         ]
@@ -912,6 +980,18 @@ async def _stream(self, query: QueryRequest) -> AsyncGenerator[QueryChunk, None]
                 log.warning("conversation_turn_store_failed", error=str(exc))
 
         # Yield sources (only budget-selected chunks)
+        t0 = time.monotonic()
+        name_map = await _fetch_document_names([r.document_id for r in selected_chunks])
+        steps.append(
+            StepTrace(
+                name="document_names",
+                duration_ms=_elapsed_ms(t0),
+                metadata={
+                    "requested": len(selected_chunks),
+                    "resolved": len(name_map),
+                },
+            )
+        )
         sources_data = [
             {
                 "doc_id": str(r.document_id),
@@ -920,6 +1000,7 @@ async def _stream(self, query: QueryRequest) -> AsyncGenerator[QueryChunk, None]
                 "snippet": r.text_snippet,
                 "citation_id": str(uuid4()),
                 "document_version": r.document_version,
+                "document_name": name_map.get(str(r.document_id)),
             }
             for r in selected_chunks
         ]
diff --git a/vektra-core/tests/test_pipeline.py b/vektra-core/tests/test_pipeline.py
index b3d42807..8e8c578b 100644
--- a/vektra-core/tests/test_pipeline.py
+++ b/vektra-core/tests/test_pipeline.py
@@ -183,13 +183,14 @@ async def test_execute_returns_response_and_trace():
     assert response.answer == "The answer."
     assert len(response.sources) == 1
     assert trace.response_id == response.response_id
-    assert (
-        len(trace.steps) == 8
-    )  # pre_query, embed, search, filter, post_retrieval, build_prompt, llm, safeguard
+    # pre_query, embed, search, filter, post_retrieval, build_prompt,
+    # document_names, llm, safeguard
+    assert len(trace.steps) == 9
     step_names = [s.name for s in trace.steps]
     assert "pre_query_safeguard" in step_names
     assert "embed_query" in step_names
     assert "post_retrieval_safeguard" in step_names
+    assert "document_names" in step_names
     assert "llm_call" in step_names
     assert "safeguard" in step_names
 
@@ -420,6 +421,83 @@ async def test_execute_post_retrieval_blocked():
     assert sg_steps[0].metadata.get("allowed") is False
 
 
+async def test_execute_populates_document_name(monkeypatch):
+    """FEAT-012: execute() attaches document filename to each SourceRef when the
+    DB lookup succeeds, and leaves document_name=None when it returns an empty map
+    (DB not initialised or all documents missing)."""
+    from vektra_core import pipeline as pipeline_mod
+
+    doc_a = uuid4()
+    doc_b = uuid4()
+    results = [
+        _make_search_result(0.9, "chunk from A", doc_id=doc_a),
+        _make_search_result(0.8, "chunk from B", doc_id=doc_b),
+    ]
+    vector_store = AsyncMock()
+    vector_store.search = AsyncMock(return_value=results)
+
+    # Case 1: DB lookup returns a mapping (keys stringified per helper contract)
+    async def _fake_fetch_hit(doc_ids):
+        # Called with the list of document ids from selected_chunks
+        assert set(doc_ids) == {doc_a, doc_b}
+        return {str(doc_a): "lecture-07.pdf", str(doc_b): "slides.pptx"}
+
+    monkeypatch.setattr(pipeline_mod, "_fetch_document_names", _fake_fetch_hit)
+
+    pipeline = _make_pipeline(vector_store=vector_store)
+    response, _ = await pipeline.execute(QueryRequest(question="Q?"))
+    names = {s.doc_id: s.document_name for s in response.sources}
+    assert names == {doc_a: "lecture-07.pdf", doc_b: "slides.pptx"}
+
+    # Case 2: DB lookup returns empty → document_name stays None for all sources
+    async def _fake_fetch_miss(doc_ids):
+        return {}
+
+    monkeypatch.setattr(pipeline_mod, "_fetch_document_names", _fake_fetch_miss)
+    response2, _ = await pipeline.execute(QueryRequest(question="Q?"))
+    assert all(s.document_name is None for s in response2.sources)
+
+
+async def test_fetch_document_names_marks_archived(monkeypatch):
+    """Soft-deleted documents are returned with ``(archived)`` suffix (REQ-057).
+
+    The citation must still match what was retrieved from the vector store;
+    we append a marker rather than hiding the document so students can see
+    that the source exists but is no longer available.
+    """
+    from vektra_core import pipeline as pipeline_mod
+
+    rows = [
+        ("doc-a", "active.pdf", None),
+        ("doc-b", "gone.pdf", "2026-04-20T10:00:00+00:00"),
+    ]
+
+    class _FakeResult:
+        def all(self_inner):
+            return rows
+
+    class _FakeSession:
+        async def __aenter__(self_inner):
+            return self_inner
+
+        async def __aexit__(self_inner, *_):
+            return False
+
+        async def execute(self_inner, *_a, **_k):
+            return _FakeResult()
+
+    def _factory():
+        return _FakeSession()
+
+    # Bypass get_session_factory() so the helper uses our fake session
+    from vektra_shared import db as db_mod
+
+    monkeypatch.setattr(db_mod, "get_session_factory", lambda: _factory)
+
+    result = await pipeline_mod._fetch_document_names(["doc-a", "doc-b"])
+    assert result == {"doc-a": "active.pdf", "doc-b": "gone.pdf (archived)"}
+
+
 # ---------------------------------------------------------------------------
 # Streaming tests (_stream / execute_stream)
 # ---------------------------------------------------------------------------
diff --git a/vektra-index/pyproject.toml b/vektra-index/pyproject.toml
index d894e32f..2883ad1b 100644
--- a/vektra-index/pyproject.toml
+++ b/vektra-index/pyproject.toml
@@ -1,6 +1,6 @@
 [project]
 name = "vektra-index"
-version = "0.4.0-dev"
+version = "0.5.0-dev"
 description = "Vector store abstraction and semantic search for the Vektra platform"
 readme = "README.md"
 requires-python = ">=3.12"
diff --git a/vektra-ingest/pyproject.toml b/vektra-ingest/pyproject.toml
index 185800ef..770e033c 100644
--- a/vektra-ingest/pyproject.toml
+++ b/vektra-ingest/pyproject.toml
@@ -1,6 +1,6 @@
 [project]
 name = "vektra-ingest"
-version = "0.4.0-dev"
+version = "0.5.0-dev"
 description = "Document processing pipeline for the Vektra platform"
 readme = "README.md"
 requires-python = ">=3.12"
diff --git a/vektra-learn/pyproject.toml b/vektra-learn/pyproject.toml
index ea184cfe..b8fcb4d3 100644
--- a/vektra-learn/pyproject.toml
+++ b/vektra-learn/pyproject.toml
@@ -1,6 +1,6 @@
 [project]
 name = "vektra-learn"
-version = "0.4.0-dev"
+version = "0.5.0-dev"
 description = "E-learning vertical: LMS-agnostic API and chatbot widget"
 readme = "README.md"
 requires-python = ">=3.12"
diff --git a/vektra-learn/src/vektra_learn/api.py b/vektra-learn/src/vektra_learn/api.py
index 2d325cf5..4d5bac26 100644
--- a/vektra-learn/src/vektra_learn/api.py
+++ b/vektra-learn/src/vektra_learn/api.py
@@ -10,6 +10,7 @@
 import json
 import socket
 from collections.abc import AsyncGenerator
+from datetime import datetime
 from typing import Any
 from urllib.parse import urlparse
 from uuid import UUID, uuid4
@@ -17,7 +18,7 @@
 import httpx
 import jwt
 import structlog
-from fastapi import APIRouter, Depends, HTTPException, Query, Request
+from fastapi import APIRouter, BackgroundTasks, Depends, HTTPException, Query, Request
 from fastapi.responses import StreamingResponse
 from fastapi.security import HTTPAuthorizationCredentials, HTTPBearer
 from pydantic import BaseModel
@@ -37,12 +38,15 @@
     TokenRequest,
     TokenResponse,
 )
+from vektra_shared.audit import log_event as _audit_log_event
 from vektra_shared.auth import ApiKeyInfo, require_scope
 from vektra_shared.errors import (
     ERR_LEARN_001,
     ERR_LEARN_002,
     ERR_LEARN_003,
     ERR_LEARN_004,
+    ERR_LEARN_005,
+    ERR_LEARN_006,
     ErrorCategory,
     ErrorResponse,
     http_status_for,
@@ -465,6 +469,176 @@ async def generate_token(
     return token_resp
 
 
+# ---------------------------------------------------------------------------
+# Conversation turns (WI-1, FEAT-004)
+# ---------------------------------------------------------------------------
+
+
+class ConversationTurnItem(BaseModel):
+    """Decrypted student-facing conversation turn.
+
+    Intentionally omits admin-only metadata (model, prompt_tokens,
+    completion_tokens, response_id). v0.5.0 returns an empty ``sources``
+    list; source enrichment from query_traces is deferred.
+    """
+
+    turn_number: int
+    question: str
+    answer: str | None
+    created_at: datetime
+    sources: list[dict[str, Any]] = []
+
+
+class ConversationTurnsResponse(BaseModel):
+    conversation_id: UUID
+    namespace: str
+    turns: list[ConversationTurnItem]
+
+
+def _resolve_namespace_from_token(
+    token_payload: dict[str, Any], request: Request
+) -> str:
+    """Same fallback chain used by /query: namespace claim, else course_id."""
+    course_id = token_payload.get("course_id")
+    if not course_id:
+        err = ErrorResponse(
+            category=ErrorCategory.PERMANENT,
+            code=ERR_LEARN_003,
+            message="Dashboard token is missing 'course_id' claim.",
+            remediation="Request a new dashboard token with a valid 'course_id'.",
+        )
+        raise HTTPException(status_code=http_status_for(err), detail=err.to_envelope())
+    ns = token_payload.get("namespace") or course_id
+    return str(ns)
+
+
+@router.get(
+    "/conversations/{conversation_id}/turns",
+    response_model=ConversationTurnsResponse,
+)
+async def get_conversation_turns(
+    conversation_id: UUID,
+    request: Request,
+    background_tasks: BackgroundTasks,
+    token_payload: dict[str, Any] = Depends(_validate_dashboard_token),
+) -> ConversationTurnsResponse:
+    """Return decrypted turns for a conversation belonging to the token's course.
+
+    Authorization is namespace-scoped: the conversation must match the namespace
+    derived from the JWT (``namespace`` claim or ``course_id`` fallback). A
+    mismatch returns 403 so the widget can distinguish "wrong course" from
+    "deleted conversation" (404) and reset its local state accordingly.
+    """
+    namespace = _resolve_namespace_from_token(token_payload, request)
+
+    registry = getattr(request.app.state, "registry", None)
+    if registry is None:
+        err = ErrorResponse(
+            category=ErrorCategory.TRANSIENT,
+            code=ERR_LEARN_001,
+            message="Conversation store not available.",
+            remediation="The service may be starting up. Try again shortly.",
+        )
+        raise HTTPException(status_code=http_status_for(err), detail=err.to_envelope())
+
+    try:
+        conv_store = registry.get("conversation_store", "default")
+    except ValueError:
+        err = ErrorResponse(
+            category=ErrorCategory.TRANSIENT,
+            code=ERR_LEARN_001,
+            message="Conversation store not configured.",
+            remediation="The service may be starting up. Try again shortly.",
+        )
+        raise HTTPException(status_code=http_status_for(err), detail=err.to_envelope())
+
+    # In-memory store (test/dev) does not support decryption — treat as 501-ish.
+    if not hasattr(conv_store, "get_metadata") or not hasattr(
+        conv_store, "get_turns_detail"
+    ):
+        err = ErrorResponse(
+            category=ErrorCategory.CONFIGURATION,
+            code=ERR_LEARN_001,
+            message="Conversation store does not support turn retrieval.",
+            remediation=(
+                "Configure a persistent conversation store "
+                "(VEKTRA_CONVERSATION_KEY must be set)."
+            ),
+        )
+        raise HTTPException(status_code=http_status_for(err), detail=err.to_envelope())
+
+    meta = await conv_store.get_metadata(conversation_id)
+    if meta is None or meta.get("deleted_at") is not None:
+        err = ErrorResponse(
+            category=ErrorCategory.PERMANENT,
+            code=ERR_LEARN_005,
+            message=f"Conversation '{conversation_id}' not found.",
+            remediation="Start a new conversation from the widget.",
+        )
+        raise HTTPException(status_code=http_status_for(err), detail=err.to_envelope())
+
+    if meta["namespace_id"] != namespace:
+        err = ErrorResponse(
+            category=ErrorCategory.PERMANENT,
+            code=ERR_LEARN_006,
+            message="Conversation belongs to a different course.",
+            remediation="Open the course this conversation was created in.",
+        )
+        raise HTTPException(status_code=http_status_for(err), detail=err.to_envelope())
+
+    turns = await conv_store.get_turns_detail(conversation_id)
+    if turns is None:
+        # Race: metadata said present, now it's gone. Same envelope as 404.
+        err = ErrorResponse(
+            category=ErrorCategory.PERMANENT,
+            code=ERR_LEARN_005,
+            message=f"Conversation '{conversation_id}' not found.",
+            remediation="Start a new conversation from the widget.",
+        )
+        raise HTTPException(status_code=http_status_for(err), detail=err.to_envelope())
+
+    items = [
+        ConversationTurnItem(
+            turn_number=t["turn_number"],
+            question=t["question"],
+            answer=t.get("answer"),
+            created_at=t["created_at"],
+            sources=[],
+        )
+        for t in turns
+    ]
+
+    # NFR-007: log sensitive content access (decrypted conversation turns).
+    # Learn endpoints authenticate via JWT and do not carry a key_id, so we
+    # use the sentinel defined for learn-originated rows. Fire the audit
+    # unconditionally with a synthesized request_id if the middleware hasn't
+    # set one — a missing correlation id must not silently skip the audit
+    # row (compliance gap otherwise invisible).
+    request_id = getattr(request.state, "request_id", None) or uuid4()
+    background_tasks.add_task(
+        _audit_log_event,
+        key_id=_LEARN_SENTINEL_KEY_ID,
+        endpoint=f"/api/v1/learn/conversations/{conversation_id}/turns",
+        method="GET",
+        status_code=200,
+        request_id=request_id,
+        action="learn_conversation_turns_read",
+        log_metadata={
+            "namespace": namespace,
+            "conversation_id": str(conversation_id),
+            "turn_count": len(items),
+            "student_id": token_payload.get("sub"),
+            "course_id": token_payload.get("course_id"),
+        },
+    )
+
+    return ConversationTurnsResponse(
+        conversation_id=conversation_id,
+        namespace=namespace,
+        turns=items,
+    )
+
+
 # ---------------------------------------------------------------------------
 # Course-scoped query
 # ---------------------------------------------------------------------------
diff --git a/vektra-learn/src/vektra_learn/query.py b/vektra-learn/src/vektra_learn/query.py
index 9c0cec88..1af025b6 100644
--- a/vektra-learn/src/vektra_learn/query.py
+++ b/vektra-learn/src/vektra_learn/query.py
@@ -70,6 +70,7 @@ def pipeline_response_to_course_response(
                 "chunk_id": s.chunk_id,
                 "score": s.score,
                 "snippet": s.snippet,
+                "document_name": s.document_name,  # FEAT-012
             }
             for s in resp.sources
         ],
diff --git a/vektra-learn/tests/test_api.py b/vektra-learn/tests/test_api.py
index 984365eb..fe7aa2d3 100644
--- a/vektra-learn/tests/test_api.py
+++ b/vektra-learn/tests/test_api.py
@@ -440,3 +440,256 @@ def test_learn_error_status_codes(self):
             remediation="Check existing",
         )
         assert http_status_for(err_dup) == 409
+
+
+# ---------------------------------------------------------------------------
+# Conversation turns endpoint (WI-1 / FEAT-004)
+# ---------------------------------------------------------------------------
+
+
+class TestConversationTurnsEndpoint:
+    """JWT-scoped GET /api/v1/learn/conversations/{id}/turns."""
+
+    @staticmethod
+    def _make_request(conv_store):
+        app = MagicMock()
+        registry = MagicMock()
+        registry.get = MagicMock(return_value=conv_store)
+        app.state.registry = registry
+        request = MagicMock()
+        request.app = app
+        return request
+
+    async def test_returns_decrypted_turns_on_namespace_match(self):
+        from vektra_learn.api import get_conversation_turns
+
+        cid = uuid4()
+        conv_store = MagicMock()
+        conv_store.get_metadata = AsyncMock(
+            return_value={
+                "id": cid,
+                "namespace_id": "CS101",
+                "deleted_at": None,
+                "turn_count": 2,
+            }
+        )
+        conv_store.get_turns_detail = AsyncMock(
+            return_value=[
+                {
+                    "turn_number": 1,
+                    "question": "What is RAG?",
+                    "answer": "Retrieval-augmented generation.",
+                    "response_id": uuid4(),
+                    "model": "gpt-4o",
+                    "prompt_tokens": 10,
+                    "completion_tokens": 20,
+                    "created_at": datetime.now(UTC),
+                },
+                {
+                    "turn_number": 2,
+                    "question": "Follow up?",
+                    "answer": "Sure.",
+                    "response_id": None,
+                    "model": None,
+                    "prompt_tokens": None,
+                    "completion_tokens": None,
+                    "created_at": datetime.now(UTC),
+                },
+            ]
+        )
+
+        request = self._make_request(conv_store)
+        bg = MagicMock()
+        token_payload = {"sub": "s1", "course_id": "CS101"}
+
+        resp = await get_conversation_turns(cid, request, bg, token_payload)
+        assert resp.conversation_id == cid
+        assert resp.namespace == "CS101"
+        assert len(resp.turns) == 2
+        assert resp.turns[0].question == "What is RAG?"
+        assert resp.turns[0].answer == "Retrieval-augmented generation."
+        assert resp.turns[0].sources == []
+        # Admin-only metadata must not be exposed
+        assert not hasattr(resp.turns[0], "model")
+        assert not hasattr(resp.turns[0], "response_id")
+        # Audit log scheduled for content access (NFR-007)
+        bg.add_task.assert_called_once()
+        call_kwargs = bg.add_task.call_args.kwargs
+        assert call_kwargs["action"] == "learn_conversation_turns_read"
+        assert call_kwargs["log_metadata"]["conversation_id"] == str(cid)
+        assert call_kwargs["log_metadata"]["namespace"] == "CS101"
+        assert call_kwargs["log_metadata"]["turn_count"] == 2
+        assert call_kwargs["log_metadata"]["student_id"] == "s1"
+
+    async def test_403_on_namespace_mismatch(self):
+        """Conversation exists but belongs to a different course."""
+        from vektra_learn.api import get_conversation_turns
+
+        cid = uuid4()
+        conv_store = MagicMock()
+        conv_store.get_metadata = AsyncMock(
+            return_value={
+                "id": cid,
+                "namespace_id": "OTHER-COURSE",
+                "deleted_at": None,
+                "turn_count": 1,
+            }
+        )
+        conv_store.get_turns_detail = AsyncMock()
+
+        request = self._make_request(conv_store)
+        bg = MagicMock()
+        token_payload = {"sub": "s1", "course_id": "CS101"}
+
+        with pytest.raises(HTTPException) as exc_info:
+            await get_conversation_turns(cid, request, bg, token_payload)
+        assert exc_info.value.status_code == 403
+        assert exc_info.value.detail["error"]["code"] == "ERR-LEARN-006"
+        # Must not leak the actual content of the other-namespace conversation
+        conv_store.get_turns_detail.assert_not_awaited()
+        # No audit log on denied access (we only log successful reads)
+        bg.add_task.assert_not_called()
+
+    async def test_404_on_missing_conversation(self):
+        from vektra_learn.api import get_conversation_turns
+
+        conv_store = MagicMock()
+        conv_store.get_metadata = AsyncMock(return_value=None)
+        conv_store.get_turns_detail = AsyncMock()
+
+        request = self._make_request(conv_store)
+        bg = MagicMock()
+        token_payload = {"sub": "s1", "course_id": "CS101"}
+
+        with pytest.raises(HTTPException) as exc_info:
+            await get_conversation_turns(uuid4(), request, bg, token_payload)
+        assert exc_info.value.status_code == 404
+        assert exc_info.value.detail["error"]["code"] == "ERR-LEARN-005"
+        conv_store.get_turns_detail.assert_not_awaited()
+
+    async def test_404_on_soft_deleted_conversation(self):
+        """Soft-deleted conversations behave as if they don't exist."""
+        from vektra_learn.api import get_conversation_turns
+
+        cid = uuid4()
+        conv_store = MagicMock()
+        conv_store.get_metadata = AsyncMock(
+            return_value={
+                "id": cid,
+                "namespace_id": "CS101",
+                "deleted_at": datetime.now(UTC),  # soft-deleted
+                "turn_count": 0,
+            }
+        )
+        conv_store.get_turns_detail = AsyncMock()
+
+        request = self._make_request(conv_store)
+        bg = MagicMock()
+        token_payload = {"sub": "s1", "course_id": "CS101"}
+
+        with pytest.raises(HTTPException) as exc_info:
+            await get_conversation_turns(cid, request, bg, token_payload)
+        assert exc_info.value.status_code == 404
+
+    async def test_rejects_token_without_course_id(self):
+        from vektra_learn.api import get_conversation_turns
+
+        conv_store = MagicMock()
+        request = self._make_request(conv_store)
+        bg = MagicMock()
+        token_payload = {"sub": "s1"}  # no course_id
+
+        with pytest.raises(HTTPException) as exc_info:
+            await get_conversation_turns(uuid4(), request, bg, token_payload)
+        assert exc_info.value.status_code == 401
+        assert exc_info.value.detail["error"]["code"] == "ERR-LEARN-003"
+
+    async def test_respects_namespace_claim_over_course_id(self):
+        """Namespace claim in JWT takes precedence over course_id."""
+        from vektra_learn.api import get_conversation_turns
+
+        cid = uuid4()
+        conv_store = MagicMock()
+        conv_store.get_metadata = AsyncMock(
+            return_value={
+                "id": cid,
+                "namespace_id": "shared-materials",
+                "deleted_at": None,
+                "turn_count": 0,
+            }
+        )
+        conv_store.get_turns_detail = AsyncMock(return_value=[])
+
+        request = self._make_request(conv_store)
+        bg = MagicMock()
+        token_payload = {
+            "sub": "s1",
+            "course_id": "CS101",
+            "namespace": "shared-materials",
+        }
+
+        resp = await get_conversation_turns(cid, request, bg, token_payload)
+        assert resp.namespace == "shared-materials"
+
+    async def test_500_err_learn_001_when_store_lacks_decryption(self):
+        """In-memory store (no get_metadata / get_turns_detail) returns 500.
+
+        ERR-LEARN-001 is CONFIGURATION → 500.
+        """
+        from vektra_learn.api import get_conversation_turns
+
+        # bare object with none of the required methods
+        class _BareStore:
+            pass
+
+        conv_store = _BareStore()
+        request = self._make_request(conv_store)
+        bg = MagicMock()
+        token_payload = {"sub": "s1", "course_id": "CS101"}
+
+        with pytest.raises(HTTPException) as exc_info:
+            await get_conversation_turns(uuid4(), request, bg, token_payload)
+        assert exc_info.value.status_code == 500
+        assert exc_info.value.detail["error"]["code"] == "ERR-LEARN-001"
+
+    async def test_audit_fires_even_without_request_id(self):
+        """NFR-007: audit must fire unconditionally on successful turns read.
+
+        If the RequestIdMiddleware isn't wired (tests, early boot), a missing
+        request.state.request_id must not silently skip the audit row — the
+        handler synthesizes a UUID fallback so every authenticated content
+        access leaves an audit trail.
+        """
+        from vektra_learn.api import get_conversation_turns
+
+        cid = uuid4()
+        conv_store = MagicMock()
+        conv_store.get_metadata = AsyncMock(
+            return_value={
+                "id": cid,
+                "namespace_id": "CS101",
+                "deleted_at": None,
+                "turn_count": 0,
+            }
+        )
+        conv_store.get_turns_detail = AsyncMock(return_value=[])
+
+        # Simulate middleware not wired: request.state has no attribute
+        request = self._make_request(conv_store)
+
+        class _EmptyState:
+            pass
+
+        request.state = _EmptyState()
+
+        bg = MagicMock()
+        token_payload = {"sub": "s1", "course_id": "CS101"}
+
+        await get_conversation_turns(cid, request, bg, token_payload)
+        bg.add_task.assert_called_once()
+        call_kwargs = bg.add_task.call_args.kwargs
+        assert call_kwargs["action"] == "learn_conversation_turns_read"
+        # Synthesized request_id must still be a UUID (not None)
+        from uuid import UUID as _UUID
+
+        assert isinstance(call_kwargs["request_id"], _UUID)
diff --git a/vektra-learn/widget/src/api-client.js b/vektra-learn/widget/src/api-client.js
index b24ecdf9..e2c86953 100644
--- a/vektra-learn/widget/src/api-client.js
+++ b/vektra-learn/widget/src/api-client.js
@@ -32,6 +32,51 @@ export class ApiClient {
     return this._conversationId;
   }
 
+  /**
+   * Manually set the current conversation ID (e.g. restored from sessionStorage).
+   * Use null to clear it.
+   */
+  setConversationId(id) {
+    this._conversationId = id || null;
+  }
+
+  /**
+   * Fetch decrypted turns for a stored conversation (WI-1 / FEAT-004).
+   * Returns null on 404/403 (so the caller can reset local state silently),
+   * throws on other errors so that a transient network failure does not
+   * wipe the sessionStorage entry.
+   *
+   * @param {string} conversationId
+   * @returns {Promise<{conversation_id: string, namespace: string, turns: Array}|null>}
+   */
+  async getConversationTurns(conversationId, _retried = false) {
+    // Bounded timeout so a stalled backend doesn't block widget init.
+    // AbortSignal.timeout rejects the fetch with an AbortError; callers
+    // already handle thrown errors by leaving stored state untouched.
+    const resp = await fetch(
+      `${this._apiUrl}/api/v1/learn/conversations/${encodeURIComponent(conversationId)}/turns`,
+      {
+        method: "GET",
+        headers: { Authorization: `Bearer ${this._token}` },
+        signal: AbortSignal.timeout(8000),
+      }
+    );
+    if (resp.status === 401 && !_retried) {
+      const newToken = await this._refreshToken();
+      if (newToken) {
+        this._token = newToken;
+        return this.getConversationTurns(conversationId, true);
+      }
+    }
+    if (resp.status === 404 || resp.status === 403) {
+      return null; // caller clears local state, no error surfaced to the user
+    }
+    if (!resp.ok) {
+      throw new Error(`HTTP ${resp.status}`);
+    }
+    return resp.json();
+  }
+
   /**
    * Check if the Vektra API is reachable.
    * @returns {Promise<boolean>}
diff --git a/vektra-learn/widget/src/chat-ui.js b/vektra-learn/widget/src/chat-ui.js
index 402ac345..7a2f9f08 100644
--- a/vektra-learn/widget/src/chat-ui.js
+++ b/vektra-learn/widget/src/chat-ui.js
@@ -20,6 +20,8 @@ const I18N = {
     reconnecting: "Reconnecting...",
     sessionExpired: "Your session has expired. Please reload the page.",
     close: "Close",
+    newChat: "New chat",
+    poweredBy: "Powered by",
   },
   it: {
     title: "Assistente del corso",
@@ -34,24 +36,98 @@ const I18N = {
     reconnecting: "Riconnessione...",
     sessionExpired: "La sessione è scaduta. Ricarica la pagina.",
     close: "Chiudi",
+    newChat: "Nuova chat",
+    poweredBy: "Offerto da",
   },
 };
 
+// Accept CSS colors that are hex (#rgb, #rgba, #rrggbb, #rrggbbaa),
+// rgb[a](), hsl[a](), or named (alphanumeric). Rejects anything with
+// quotes, semicolons, or whitespace that could break out into a style rule.
+// Matches the conservative set proposed by the plan's XSS mitigation.
+const _VALID_COLOR_RE =
+  /^(#[0-9a-fA-F]{3,8}|rgba?\([0-9.,\s%]+\)|hsla?\([0-9.,\s%]+\)|[a-zA-Z]+)$/;
+
+function _isSafeColor(value) {
+  return typeof value === "string" && _VALID_COLOR_RE.test(value.trim());
+}
+
+// An icon value that looks like a URL becomes an <img>; otherwise it is
+// rendered as plain text (emoji or short string) via textContent to avoid
+// HTML injection via data-icon.
+function _iconIsUrl(value) {
+  if (typeof value !== "string") return false;
+  const v = value.trim();
+  return (
+    v.startsWith("http://") ||
+    v.startsWith("https://") ||
+    v.startsWith("/") ||
+    v.startsWith("data:image/")
+  );
+}
+
+// Only http(s) and same-origin paths are allowed as link targets. Rejects
+// javascript:, data:, and other schemes that could enable XSS when the
+// operator-controlled attribute is combined with custom text.
+function _isSafeLinkUrl(value) {
+  if (typeof value !== "string") return false;
+  const v = value.trim();
+  return (
+    v.startsWith("http://") || v.startsWith("https://") || v.startsWith("/")
+  );
+}
+
 export class ChatUI {
   /**
    * @param {object} opts
    * @param {string} opts.theme - "light" or "dark"
    * @param {string} opts.language - "en" or "it"
+   * @param {string|null} [opts.customTitle] - overrides the localized title
+   * @param {string|null} [opts.customPrimaryColor] - CSS color for accents
+   * @param {string|null} [opts.customIcon] - emoji or image URL for the button
+   * @param {string|null} [opts.welcomeMessage] - first assistant message on open
+   * @param {boolean} [opts.showPoweredBy=true] - show attribution footer
+   * @param {string|null} [opts.poweredByText] - custom footer text (plain text)
+   * @param {string|null} [opts.poweredByUrl] - custom footer link target
    * @param {function} opts.onSend - callback(question: string)
+   * @param {function} [opts.onNewChat] - callback invoked when "New chat" is clicked
    */
-  constructor({ theme = "light", language = "en", onSend }) {
+  constructor({
+    theme = "light",
+    language = "en",
+    customTitle = null,
+    customPrimaryColor = null,
+    customIcon = null,
+    welcomeMessage = null,
+    showPoweredBy = true,
+    poweredByText = null,
+    poweredByUrl = null,
+    onSend,
+    onNewChat = null,
+  }) {
     this._theme = theme;
     this._lang = I18N[language] || I18N.en;
     this._onSend = onSend;
+    this._onNewChat = onNewChat;
     this._isOpen = false;
     this._sending = false;
+    this._restoring = false; // true while a conversation history is being fetched
     this._status = null; // "unavailable" | "reconnecting" | "sessionExpired" | null
 
+    this._title = customTitle || this._lang.title;
+    this._icon = customIcon;
+    this._welcomeMessage = welcomeMessage;
+    this._showPoweredBy = showPoweredBy;
+    this._poweredByText = poweredByText;
+    this._poweredByUrl = poweredByUrl;
+    this._welcomeShown = false;
+    // Accept color only if it matches the conservative whitelist; anything
+    // else is silently ignored (falls back to theme default) to prevent CSS
+    // injection via data-primary-color.
+    this._primaryColor = _isSafeColor(customPrimaryColor)
+      ? customPrimaryColor.trim()
+      : null;
+
     this._injectStyles();
     this._createElements();
     this._bindEvents();
@@ -61,23 +137,44 @@ export class ChatUI {
     const style = document.createElement("style");
     style.textContent = buildStyles(this._theme);
     document.head.appendChild(style);
+
+    if (this._primaryColor) {
+      const override = document.createElement("style");
+      // Single CSS custom property; styles.js uses var(--vektra-primary, ...)
+      // so an invalid value (filtered above) never reaches the DOM.
+      override.textContent = `:root { --vektra-primary: ${this._primaryColor}; }`;
+      document.head.appendChild(override);
+    }
   }
 
   _createElements() {
-    // Floating button
+    // Floating button (aria-label + icon set via safe APIs — no innerHTML of user input)
     this._btn = document.createElement("button");
     this._btn.className = "vektra-chat-btn";
-    this._btn.setAttribute("aria-label", this._lang.title);
-    this._btn.innerHTML = "&#128172;"; // speech bubble emoji
+    this._btn.setAttribute("aria-label", this._title);
+    if (this._icon && _iconIsUrl(this._icon)) {
+      const img = document.createElement("img");
+      img.src = this._icon;
+      img.alt = "";
+      img.className = "vektra-chat-btn-icon";
+      this._btn.appendChild(img);
+    } else if (this._icon) {
+      this._btn.textContent = this._icon;
+    } else {
+      this._btn.innerHTML = "&#128172;"; // speech bubble emoji
+    }
     document.body.appendChild(this._btn);
 
-    // Chat panel
+    // Chat panel — scaffold built with safe APIs; title uses textContent below.
     this._panel = document.createElement("div");
     this._panel.className = "vektra-chat-panel";
     this._panel.innerHTML = `
       <div class="vektra-chat-header">
-        <span class="vektra-chat-header-title">${this._lang.title}</span>
-        <button class="vektra-chat-close" aria-label="${this._lang.close}">&times;</button>
+        <span class="vektra-chat-header-title"></span>
+        <div class="vektra-chat-header-actions">
+          <button class="vektra-chat-new" aria-label="${this._lang.newChat}" title="${this._lang.newChat}">&#10227;</button>
+          <button class="vektra-chat-close" aria-label="${this._lang.close}">&times;</button>
+        </div>
       </div>
       <div class="vektra-chat-messages"></div>
       <div class="vektra-chat-input-area">
@@ -87,6 +184,35 @@ export class ChatUI {
         <button class="vektra-chat-send">${this._lang.send}</button>
       </div>
     `;
+    // Title: set via textContent so data-title cannot inject HTML
+    const titleEl = this._panel.querySelector(".vektra-chat-header-title");
+    titleEl.textContent = this._title;
+
+    if (this._showPoweredBy) {
+      const footer = document.createElement("div");
+      footer.className = "vektra-chat-powered-by";
+      // If poweredByText is set, the whole footer is a single link with that
+      // text. Otherwise the footer is "<i18n: Powered by> <link>Vektra</link>".
+      // A blank or invalid poweredByUrl falls back to the Vektra default URL.
+      const url = _isSafeLinkUrl(this._poweredByUrl)
+        ? this._poweredByUrl.trim()
+        : "https://vektralabs.github.io";
+      const link = document.createElement("a");
+      link.href = url;
+      link.target = "_blank";
+      link.rel = "noopener noreferrer";
+
+      if (this._poweredByText) {
+        link.textContent = this._poweredByText;
+        footer.appendChild(link);
+      } else {
+        link.textContent = "Vektra";
+        footer.textContent = `${this._lang.poweredBy} `;
+        footer.appendChild(link);
+      }
+      this._panel.appendChild(footer);
+    }
+
     document.body.appendChild(this._panel);
 
     // Cache references
@@ -94,6 +220,7 @@ export class ChatUI {
     this._inputEl = this._panel.querySelector(".vektra-chat-input");
     this._sendBtn = this._panel.querySelector(".vektra-chat-send");
     this._closeBtn = this._panel.querySelector(".vektra-chat-close");
+    this._newChatBtn = this._panel.querySelector(".vektra-chat-new");
   }
 
   _bindEvents() {
@@ -106,6 +233,55 @@ export class ChatUI {
         this._handleSend();
       }
     });
+    if (this._newChatBtn) {
+      this._newChatBtn.addEventListener("click", () => this._handleNewChat());
+    }
+  }
+
+  _handleNewChat() {
+    if (this._sending || this._restoring) return;
+    this.reset();
+    if (this._onNewChat) this._onNewChat();
+  }
+
+  /**
+   * Reset the chat panel: clear messages, re-arm welcome message, allow input.
+   * Does NOT call the onNewChat callback; use _handleNewChat for that.
+   */
+  reset() {
+    this._messagesEl.textContent = "";
+    this._welcomeShown = false;
+    if (this._isOpen && this._welcomeMessage) {
+      // Re-inject welcome message so the cleared panel isn't blank
+      this._welcomeShown = true;
+      const msg = document.createElement("div");
+      msg.className = "vektra-chat-msg assistant";
+      msg.textContent = this._welcomeMessage;
+      this._messagesEl.appendChild(msg);
+    }
+  }
+
+  /**
+   * Replay a list of stored turns as user/assistant message bubbles (WI-5).
+   * Call after restoring a conversation from sessionStorage but before
+   * enabling user input. Each turn is a plain object with
+   * { question, answer, sources }. Sources may be empty for now.
+   */
+  replayTurns(turns) {
+    if (!Array.isArray(turns)) return;
+    // Replaying takes ownership of the message list — clear any welcome msg
+    // so the history is the first thing the student sees.
+    this._messagesEl.textContent = "";
+    this._welcomeShown = true; // don't re-emit welcome on first open
+    for (const turn of turns) {
+      if (turn.question) this.addMessage("user", turn.question);
+      if (turn.answer) {
+        const msgEl = this.addMessage("assistant", turn.answer);
+        if (Array.isArray(turn.sources) && turn.sources.length > 0) {
+          this.addSources(msgEl, turn.sources);
+        }
+      }
+    }
   }
 
   toggle() {
@@ -115,6 +291,16 @@ export class ChatUI {
   open() {
     this._isOpen = true;
     this._panel.classList.add("open");
+    // Emit welcome message on first open (WI-4). Rendered as an assistant
+    // bubble so it flows naturally with subsequent conversation turns.
+    if (this._welcomeMessage && !this._welcomeShown) {
+      this._welcomeShown = true;
+      const msg = document.createElement("div");
+      msg.className = "vektra-chat-msg assistant";
+      msg.textContent = this._welcomeMessage;
+      this._messagesEl.appendChild(msg);
+      this._scrollToBottom();
+    }
     this._inputEl.focus();
   }
 
@@ -124,7 +310,7 @@ export class ChatUI {
   }
 
   _handleSend() {
-    if (this._sending) return;
+    if (this._sending || this._restoring) return;
     const question = this._inputEl.value.trim();
     if (!question) return;
 
@@ -142,9 +328,21 @@ export class ChatUI {
     this._updateControlsDisabled();
   }
 
+  /**
+   * Toggle the "restoring history" state (WI-5). While active, the input
+   * and send button are disabled so a fast user cannot preempt a pending
+   * replay — otherwise `replayTurns` would wipe a user message that was
+   * already rendered, and a new_chat click would race the restore.
+   */
+  setRestoring(restoring) {
+    this._restoring = restoring;
+    this._updateControlsDisabled();
+  }
+
   _updateControlsDisabled() {
     const blocked =
       this._sending ||
+      this._restoring ||
       this._status === "unavailable" ||
       this._status === "sessionExpired";
     this._sendBtn.disabled = blocked;
diff --git a/vektra-learn/widget/src/index.js b/vektra-learn/widget/src/index.js
index 9f0613b5..45b7f32e 100644
--- a/vektra-learn/widget/src/index.js
+++ b/vektra-learn/widget/src/index.js
@@ -12,12 +12,75 @@
  *     data-theme="light"
  *     data-language="en"
  *     data-token-refresh-url="/my-app/refresh-token"
+ *     data-title="My course helper"
+ *     data-primary-color="#9333ea"
+ *     data-icon="https://example.com/bot.png"
+ *     data-welcome-message="Hi! Ask me anything about the course."
+ *     data-powered-by="true"
+ *     data-powered-by-text="Supported by University of X"
+ *     data-powered-by-url="https://univ.example/help"
  *   ></script>
+ *
+ * White-label attributes (all optional):
+ *   data-title             - header title and button aria-label
+ *   data-primary-color     - hex/rgb/named color used for buttons and accents
+ *   data-icon              - emoji or image URL for the floating button
+ *   data-welcome-message   - assistant message shown on first open
+ *   data-powered-by        - "true" (default) shows the attribution footer,
+ *                            "false" hides it
+ *   data-powered-by-text   - overrides the footer text (plain text, no HTML).
+ *                            Default: "Powered by Vektra" as a link.
+ *   data-powered-by-url    - overrides the footer link target. Default:
+ *                            https://vektralabs.github.io
  */
 
 import { ApiClient } from "./api-client.js";
 import { ChatUI } from "./chat-ui.js";
 
+// Storage key for per-course conversation persistence (WI-5). Tab-scoped
+// via sessionStorage so that shared university computers don't leak a
+// student's conversation to the next user.
+const STORAGE_PREFIX = "vektra-conv:";
+// Tabs kept open for days shouldn't silently resurface yesterday's chat.
+const STALE_AFTER_MS = 24 * 60 * 60 * 1000;
+
+function _readStored(courseId) {
+  try {
+    const raw = window.sessionStorage.getItem(STORAGE_PREFIX + courseId);
+    if (!raw) return null;
+    const parsed = JSON.parse(raw);
+    if (!parsed || !parsed.conversation_id) return null;
+    const age = Date.now() - (parsed.stored_at || 0);
+    if (age < 0 || age > STALE_AFTER_MS) return null;
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+
+function _writeStored(courseId, conversationId) {
+  try {
+    window.sessionStorage.setItem(
+      STORAGE_PREFIX + courseId,
+      JSON.stringify({
+        conversation_id: conversationId,
+        stored_at: Date.now(),
+      })
+    );
+  } catch {
+    // Storage full or unavailable — silently ignore; persistence is a
+    // convenience, not a correctness requirement.
+  }
+}
+
+function _clearStored(courseId) {
+  try {
+    window.sessionStorage.removeItem(STORAGE_PREFIX + courseId);
+  } catch {
+    // ignore
+  }
+}
+
 (function () {
   // Capture the script tag synchronously (before DOMContentLoaded)
   const scripts = document.querySelectorAll('script[src*="vektra-chat"]');
@@ -35,6 +98,20 @@ import { ChatUI } from "./chat-ui.js";
   const language = scriptTag.getAttribute("data-language") || "en";
   const tokenRefreshUrl = scriptTag.getAttribute("data-token-refresh-url") || null;
 
+  // White-label attributes (all optional). See file header for semantics.
+  const customTitle = scriptTag.getAttribute("data-title") || null;
+  const customPrimaryColor =
+    scriptTag.getAttribute("data-primary-color") || null;
+  const customIcon = scriptTag.getAttribute("data-icon") || null;
+  const welcomeMessage = scriptTag.getAttribute("data-welcome-message") || null;
+  const poweredByAttr = scriptTag.getAttribute("data-powered-by");
+  // Default ON; only "false" (case-insensitive) hides attribution.
+  const showPoweredBy = poweredByAttr === null
+    ? true
+    : poweredByAttr.toLowerCase() !== "false";
+  const poweredByText = scriptTag.getAttribute("data-powered-by-text") || null;
+  const poweredByUrl = scriptTag.getAttribute("data-powered-by-url") || null;
+
   if (!apiUrl || !courseId || !token) {
     console.error(
       "[vektra-chat] Missing required attributes: data-api-url, data-course-id, data-token"
@@ -42,12 +119,19 @@ import { ChatUI } from "./chat-ui.js";
     return;
   }
 
-  function init() {
+  async function init() {
     const client = new ApiClient(apiUrl, token, courseId, { tokenRefreshUrl });
 
     const ui = new ChatUI({
       theme,
       language,
+      customTitle,
+      customPrimaryColor,
+      customIcon,
+      welcomeMessage,
+      showPoweredBy,
+      poweredByText,
+      poweredByUrl,
       onSend(question) {
         const stream = ui.createStreamMessage();
 
@@ -63,6 +147,10 @@ import { ChatUI } from "./chat-ui.js";
           },
           onDone() {
             ui.doneSending();
+            // Persist conversation ID for history restore on next load (WI-5).
+            if (client.conversationId) {
+              _writeStored(courseId, client.conversationId);
+            }
           },
           onError(errMsg) {
             // Show session expired message for auth failures
@@ -75,8 +163,46 @@ import { ChatUI } from "./chat-ui.js";
           },
         });
       },
+      onNewChat() {
+        // Reset both storage and client-side state so the next query
+        // creates a fresh conversation.
+        _clearStored(courseId);
+        client.setConversationId(null);
+      },
     });
 
+    // Restore a conversation from a prior load (WI-5 / FEAT-004). Awaited,
+    // with input+send disabled via ui.setRestoring(true) for the duration
+    // of the fetch. This closes a race the earlier "just await" fix did
+    // not fully handle: the UI is already mounted when the await starts,
+    // so without the input lock a fast user could type+send during the
+    // fetch — _handleSend would paint the user bubble into the DOM, then
+    // replayTurns would clear it when the restore resolved, losing the
+    // message. The fetch has an 8s timeout (api-client.js) so the input
+    // lock never persists indefinitely. Any failure keeps the stored id
+    // for the next load.
+    async function restoreConversation() {
+      const stored = _readStored(courseId);
+      if (!stored) return;
+      ui.setRestoring(true);
+      try {
+        const payload = await client.getConversationTurns(stored.conversation_id);
+        if (payload && Array.isArray(payload.turns) && payload.turns.length > 0) {
+          client.setConversationId(stored.conversation_id);
+          ui.replayTurns(payload.turns);
+        } else {
+          // Returned null (404/403) or empty turns — abandon stored id
+          _clearStored(courseId);
+        }
+      } catch {
+        // Network/transient error (incl. AbortError on timeout): keep
+        // stored id, try again next load.
+      } finally {
+        ui.setRestoring(false);
+      }
+    }
+    await restoreConversation();
+
     // Check API connectivity on startup and show status if unreachable
     let retryTimer = null;
 
@@ -110,10 +236,15 @@ import { ChatUI } from "./chat-ui.js";
     checkConnection();
   }
 
-  // Wait for DOM to be ready before creating UI elements
+  // Wait for DOM to be ready before creating UI elements. init is async
+  // (awaits restoreConversation); wrap with .catch so any unexpected
+  // rejection surfaces in the console rather than as an unhandled promise.
+  function runInit() {
+    init().catch((err) => console.error("[vektra-chat] init failed:", err));
+  }
   if (document.readyState === "loading") {
-    document.addEventListener("DOMContentLoaded", init);
+    document.addEventListener("DOMContentLoaded", runInit);
   } else {
-    init();
+    runInit();
   }
 })();
diff --git a/vektra-learn/widget/src/styles.js b/vektra-learn/widget/src/styles.js
index 22296cb0..944c7a3f 100644
--- a/vektra-learn/widget/src/styles.js
+++ b/vektra-learn/widget/src/styles.js
@@ -52,7 +52,7 @@ export function buildStyles(theme) {
   width: 56px;
   height: 56px;
   border-radius: 50%;
-  background: ${t.primary};
+  background: var(--vektra-primary, ${t.primary});
   color: #fff;
   border: none;
   cursor: pointer;
@@ -66,7 +66,8 @@ export function buildStyles(theme) {
   line-height: 1;
 }
 .vektra-chat-btn:hover {
-  background: ${t.primaryHover};
+  background: var(--vektra-primary, ${t.primaryHover});
+  filter: brightness(0.92);
   transform: scale(1.05);
 }
 
@@ -107,6 +108,12 @@ export function buildStyles(theme) {
   font-weight: 600;
   font-size: 15px;
 }
+.vektra-chat-header-actions {
+  display: flex;
+  align-items: center;
+  gap: 4px;
+}
+.vektra-chat-new,
 .vektra-chat-close {
   background: none;
   border: none;
@@ -116,6 +123,13 @@ export function buildStyles(theme) {
   padding: 4px;
   line-height: 1;
 }
+.vektra-chat-new {
+  font-size: 16px;
+}
+.vektra-chat-new:hover,
+.vektra-chat-close:hover {
+  color: ${t.text};
+}
 
 .vektra-chat-messages {
   flex: 1;
@@ -135,7 +149,7 @@ export function buildStyles(theme) {
 }
 .vektra-chat-msg.user {
   align-self: flex-end;
-  background: ${t.userBubble};
+  background: var(--vektra-primary, ${t.userBubble});
   color: ${t.userText};
   border-bottom-right-radius: 4px;
 }
@@ -188,7 +202,7 @@ export function buildStyles(theme) {
   font-size: 12px;
 }
 .vektra-chat-msg.assistant a {
-  color: ${t.primary};
+  color: var(--vektra-primary, ${t.primary});
   text-decoration: underline;
 }
 .vektra-chat-msg.assistant strong {
@@ -206,7 +220,7 @@ export function buildStyles(theme) {
   background: none;
   border: none;
   cursor: pointer;
-  color: ${t.primary};
+  color: var(--vektra-primary, ${t.primary});
   font-size: 12px;
   padding: 0;
   font-family: inherit;
@@ -215,7 +229,7 @@ export function buildStyles(theme) {
   text-decoration: underline;
 }
 .vektra-chat-sources-toggle:focus-visible {
-  outline: 2px solid ${t.primary};
+  outline: 2px solid var(--vektra-primary, ${t.primary});
   outline-offset: 2px;
   border-radius: 4px;
 }
@@ -235,7 +249,7 @@ export function buildStyles(theme) {
 }
 .vektra-chat-source-num {
   font-weight: 600;
-  color: ${t.primary};
+  color: var(--vektra-primary, ${t.primary});
   margin-right: 4px;
 }
 .vektra-chat-source-text {
@@ -280,14 +294,14 @@ export function buildStyles(theme) {
   font-family: inherit;
 }
 .vektra-chat-input:focus-visible {
-  outline: 2px solid ${t.primary};
+  outline: 2px solid var(--vektra-primary, ${t.primary});
   outline-offset: -1px;
 }
 .vektra-chat-input::placeholder {
   color: ${t.textSecondary};
 }
 .vektra-chat-send {
-  background: ${t.primary};
+  background: var(--vektra-primary, ${t.primary});
   color: #fff;
   border: none;
   border-radius: 8px;
@@ -298,13 +312,34 @@ export function buildStyles(theme) {
   transition: background 0.2s;
 }
 .vektra-chat-send:hover {
-  background: ${t.primaryHover};
+  background: var(--vektra-primary, ${t.primaryHover});
+  filter: brightness(0.92);
 }
 .vektra-chat-send:disabled {
   opacity: 0.5;
   cursor: not-allowed;
 }
 
+.vektra-chat-btn-icon {
+  width: 28px;
+  height: 28px;
+  display: block;
+}
+
+.vektra-chat-powered-by {
+  padding: 6px 12px;
+  text-align: center;
+  font-size: 11px;
+  color: ${t.textSecondary};
+  background: ${t.bgSecondary};
+  border-top: 1px solid ${t.border};
+  flex-shrink: 0;
+}
+.vektra-chat-powered-by a {
+  color: ${t.textSecondary};
+  text-decoration: underline;
+}
+
 @media (max-width: 480px) {
   .vektra-chat-panel {
     width: calc(100vw - 16px);
diff --git a/vektra-shared/pyproject.toml b/vektra-shared/pyproject.toml
index f8e2eb62..233c1246 100644
--- a/vektra-shared/pyproject.toml
+++ b/vektra-shared/pyproject.toml
@@ -1,6 +1,6 @@
 [project]
 name = "vektra-shared"
-version = "0.4.0-dev"
+version = "0.5.0-dev"
 description = "Shared protocols and types for the Vektra platform"
 readme = "README.md"
 requires-python = ">=3.12"
diff --git a/vektra-shared/src/vektra_shared/errors.py b/vektra-shared/src/vektra_shared/errors.py
index 9eb648c3..f7510b06 100644
--- a/vektra-shared/src/vektra_shared/errors.py
+++ b/vektra-shared/src/vektra_shared/errors.py
@@ -110,6 +110,8 @@ def to_envelope(self) -> dict[str, Any]:
 ERR_LEARN_002 = "ERR-LEARN-002"  # Enrollment not found
 ERR_LEARN_003 = "ERR-LEARN-003"  # Invalid or expired dashboard token
 ERR_LEARN_004 = "ERR-LEARN-004"  # Duplicate enrollment
+ERR_LEARN_005 = "ERR-LEARN-005"  # Conversation not found (WI-1)
+ERR_LEARN_006 = "ERR-LEARN-006"  # Conversation belongs to another course (WI-1)
 
 
 # ---------------------------------------------------------------------------
@@ -135,6 +137,8 @@ def to_envelope(self) -> dict[str, Any]:
     ERR_LEARN_002: 404,
     ERR_LEARN_003: 401,
     ERR_LEARN_004: 409,
+    ERR_LEARN_005: 404,
+    ERR_LEARN_006: 403,
 }
 
 
diff --git a/vektra-shared/src/vektra_shared/types.py b/vektra-shared/src/vektra_shared/types.py
index 3f25d42a..d1d90342 100644
--- a/vektra-shared/src/vektra_shared/types.py
+++ b/vektra-shared/src/vektra_shared/types.py
@@ -283,6 +283,11 @@ class SourceRef:
     snippet: str
     citation_id: UUID
     document_version: int = 1  # from SearchResult (REQ-056)
+    # FEAT-012: filename of the source document so students can see citations
+    # like "[1] lecture-07.pdf (0.82)" instead of a chunk UUID. Soft-deleted
+    # documents (REQ-057) appear with an " (archived)" suffix; None only when
+    # the DB lookup failed (transient error, DB not initialised in tests).
+    document_name: str | None = None
 
 
 @dataclass