feat(learn): widget production-ready + prof config

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.

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,

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