feat: Pushed 3 new wiki pages (Chat-Engine, Search-Retrieval, Highlight…

- "Chat-Engine.md" - "Search-Retrieval.md" - "Highlights.md" - "Home.md" - "Architecture.md" - "Data-Model.md" - "API-Surface.md" - "Frontend.md" GSD-Task: S08/T01
2026-04-04 06:42:02 +00:00 · 2026-04-04 06:42:02 +00:00 · 79e144ff89
commit 79e144ff89
parent 4bda29705d
8 changed files with 496 additions and 2 deletions
--- a/.gsd/milestones/M021/M021-ROADMAP.md
+++ b/.gsd/milestones/M021/M021-ROADMAP.md
@ -12,5 +12,5 @@ LightRAG becomes the primary search engine. Chat engine goes live (encyclopedic
 | S04 | [B] Highlight Detection v1 | medium | — | ✅ | Scored highlight candidates generated from existing pipeline data for a sample of videos |
 | S05 | [A] Audio Mode + Chapter Markers | medium | — | ✅ | Media player with waveform visualization in audio mode and chapter markers on the timeline |
 | S06 | [A] Auto-Chapters Review UI | low | — | ✅ | Creator reviews detected chapters: drag boundaries, rename, reorder, approve for publication |
-| S07 | [A] Impersonation Polish + Write Mode | low | — | ⬜ | Impersonation write mode with confirmation modal. Audit log admin view shows all sessions. |
+| S07 | [A] Impersonation Polish + Write Mode | low | — | ✅ | Impersonation write mode with confirmation modal. Audit log admin view shows all sessions. |
 | S08 | Forgejo KB Update — Chat, Retrieval, Highlights | low | S01, S02, S03, S04, S05, S06, S07 | ⬜ | Forgejo wiki updated with chat engine, retrieval routing, and highlight detection docs |
--- a/.gsd/milestones/M021/slices/S07/S07-SUMMARY.md
+++ b/.gsd/milestones/M021/slices/S07/S07-SUMMARY.md
@ -0,0 +1,121 @@
+---
+id: S07
+parent: M021
+milestone: M021
+provides:
+  - write_mode impersonation token support
+  - reject_impersonation conditional write gating
+  - ConfirmModal reusable component
+  - fetchImpersonationLog API function
+  - isWriteMode auth context value
+  - /admin/audit-log route
+requires:
+  []
+affects:
+  - S08
+key_files:
+  - backend/auth.py
+  - backend/models.py
+  - backend/routers/admin.py
+  - backend/tests/test_impersonation.py
+  - frontend/src/components/ConfirmModal.tsx
+  - frontend/src/components/ConfirmModal.module.css
+  - frontend/src/api/auth.ts
+  - frontend/src/context/AuthContext.tsx
+  - frontend/src/pages/AdminUsers.tsx
+  - frontend/src/components/ImpersonationBanner.tsx
+  - frontend/src/components/ImpersonationBanner.module.css
+  - frontend/src/pages/AdminAuditLog.tsx
+  - frontend/src/pages/AdminAuditLog.module.css
+  - frontend/src/App.tsx
+  - frontend/src/components/AdminDropdown.tsx
+key_decisions:
+  - StartImpersonationRequest body is optional for backward compatibility
+  - write_mode only added to JWT payload when True to keep read-only tokens minimal
+  - ConfirmModal uses data-variant attribute for confirm button color instead of separate CSS classes
+  - isWriteMode state reset on exitImpersonation rather than derived from token
+  - Disabled Next button when current page returns zero entries as simple end-of-data signal
+patterns_established:
+  - Reusable ConfirmModal component with variant prop for warning/danger confirmation dialogs
+  - data-attribute based CSS variant styling (data-variant, data-action, data-write-mode) for badge/button coloring
+  - Optional request body pattern for backward-compatible API evolution
+observability_surfaces:
+  - GET /admin/impersonation-log endpoint provides full audit trail of all impersonation sessions with admin/target names, write mode flag, and IP addresses
+drill_down_paths:
+  - .gsd/milestones/M021/slices/S07/tasks/T01-SUMMARY.md
+  - .gsd/milestones/M021/slices/S07/tasks/T02-SUMMARY.md
+  - .gsd/milestones/M021/slices/S07/tasks/T03-SUMMARY.md
+duration: ""
+verification_result: passed
+completed_at: 2026-04-04T06:31:35.852Z
+blocker_discovered: false
+---
+
+# S07: [A] Impersonation Polish + Write Mode
+
+**Added write-mode impersonation with confirmation modal, red/amber banner differentiation, and paginated admin audit log page.**
+
+## What Happened
+
+This slice upgraded the impersonation system from read-only to support an explicit write mode, and added admin visibility into impersonation sessions.
+
+**T01 (Backend):** Added `write_mode` boolean column to `ImpersonationLog` model. Modified `create_impersonation_token()` to embed `write_mode` in JWT payloads. Updated `reject_impersonation()` to be conditional — allows write operations when `write_mode=True`, blocks when False or absent. Added `StartImpersonationRequest` body model (optional for backward compatibility), `ImpersonationLogItem` response schema, and `GET /admin/impersonation-log` endpoint with aliased User joins for admin/target display names and `?page=&page_size=` pagination. Created 5 integration tests covering all must-haves (write block, write allow, log entries, non-admin forbidden, pagination).
+
+**T02 (Frontend — Modal + Banner):** Created reusable `ConfirmModal` component with backdrop, Escape/backdrop-click dismiss, and warning/danger variants via `data-variant` attribute. Updated `impersonateUser()` API to accept optional `writeMode` param sending `{ write_mode: true }` as JSON body. Added `ImpersonationLogEntry` interface and `fetchImpersonationLog()` for T03. Extended `AuthContext` with `isWriteMode` state. Split AdminUsers buttons into "View As" (read-only, no modal) and "Edit As" (opens ConfirmModal with danger variant). Updated `ImpersonationBanner` to show red background with ✏️ "Editing as" in write mode vs amber 👁 "Viewing as" in read mode, plus `body.impersonating-write` class toggle.
+
+**T03 (Frontend — Audit Log Page):** Created `AdminAuditLog.tsx` with six-column table (Date/Time, Admin, Target User, Action, Write Mode, IP Address), badge styling via data-attributes, loading/error/empty states, and Previous/Next pagination. Added lazy import and `/admin/audit-log` route in App.tsx. Added "Audit Log" link in AdminDropdown after "Users".
+
+## Verification
+
+**Backend tests:** All 5 impersonation integration tests pass via SSH tunnel against real PostgreSQL (test_impersonation_without_write_mode_blocks_writes, test_impersonation_with_write_mode_allows_writes, test_impersonation_log_returns_entries, test_impersonation_log_non_admin_forbidden, test_impersonation_log_pagination). Tests fail locally due to no PostgreSQL on localhost:5433 — expected, DB runs on ub01.
+
+**Frontend build:** `npx vite build` exits 0. All S07 files compile cleanly. Pre-existing TypeScript errors in ChapterReview.tsx are unrelated.
+
+**File verification:** All 14 key files confirmed present.
+
+## Requirements Advanced
+
+None.
+
+## Requirements Validated
+
+None.
+
+## New Requirements Surfaced
+
+None.
+
+## Requirements Invalidated or Re-scoped
+
+None.
+
+## Deviations
+
+StartImpersonationRequest body parameter made optional (defaults to None) for backward compatibility with existing callers that POST without a body.
+
+## Known Limitations
+
+Pre-existing TypeScript errors in ChapterReview.tsx cause `npm run build` (which runs tsc before vite) to exit non-zero. Vite build itself succeeds. Unrelated to this slice.
+
+## Follow-ups
+
+None.
+
+## Files Created/Modified
+
+- `backend/auth.py` — Added write_mode param to create_impersonation_token, _impersonation_write_mode to get_current_user, conditional logic in reject_impersonation
+- `backend/models.py` — Added write_mode boolean column to ImpersonationLog
+- `backend/routers/admin.py` — Added StartImpersonationRequest body, ImpersonationLogItem schema, GET /impersonation-log endpoint
+- `backend/tests/test_impersonation.py` — New file — 5 integration tests for write mode and audit log
+- `frontend/src/components/ConfirmModal.tsx` — New reusable confirmation modal with warning/danger variants
+- `frontend/src/components/ConfirmModal.module.css` — Modal styling matching dark theme
+- `frontend/src/api/auth.ts` — Added writeMode param to impersonateUser, ImpersonationLogEntry interface, fetchImpersonationLog function
+- `frontend/src/context/AuthContext.tsx` — Added isWriteMode state, writeMode param to startImpersonation
+- `frontend/src/pages/AdminUsers.tsx` — Split View As / Edit As buttons, Edit As opens ConfirmModal
+- `frontend/src/pages/AdminUsers.module.css` — Styles for dual impersonation buttons
+- `frontend/src/components/ImpersonationBanner.tsx` — Red/amber banner mode switching based on isWriteMode
+- `frontend/src/components/ImpersonationBanner.module.css` — Write-mode red banner styling
+- `frontend/src/pages/AdminAuditLog.tsx` — New admin page with paginated impersonation log table
+- `frontend/src/pages/AdminAuditLog.module.css` — Audit log table styling
+- `frontend/src/App.tsx` — Added lazy import and /admin/audit-log route
+- `frontend/src/components/AdminDropdown.tsx` — Added Audit Log link after Users
--- a/.gsd/milestones/M021/slices/S07/S07-UAT.md
+++ b/.gsd/milestones/M021/slices/S07/S07-UAT.md
@ -0,0 +1,84 @@
+# S07: [A] Impersonation Polish + Write Mode — UAT
+
+**Milestone:** M021
+**Written:** 2026-04-04T06:31:35.852Z
+
+# S07 UAT — Impersonation Polish + Write Mode
+
+## Preconditions
+- Chrysopedia running on ub01:8096
+- Logged in as admin user
+- At least one non-admin user exists in the system
+
+---
+
+## TC-01: Read-Only Impersonation Blocks Writes
+1. Navigate to `/admin/users`
+2. Click **View As** next to any non-admin user
+3. **Expected:** Amber banner appears: 👁 "Viewing as {name}"
+4. Attempt a write operation (e.g. PUT /auth/me via DevTools)
+5. **Expected:** 403 Forbidden response — writes blocked in read-only mode
+6. Click **Stop** on the banner to exit impersonation
+
+## TC-02: Write-Mode Impersonation via Confirmation Modal
+1. Navigate to `/admin/users`
+2. Click **Edit As** next to any non-admin user
+3. **Expected:** Confirmation modal appears with:
+   - Warning message about editing as the target user
+   - "Cancel" and "Confirm" buttons (confirm in red/danger style)
+4. Press **Escape** key
+5. **Expected:** Modal closes, no impersonation started
+6. Click **Edit As** again
+7. Click the backdrop (outside the modal card)
+8. **Expected:** Modal closes, no impersonation started
+9. Click **Edit As** again, then click **Confirm**
+10. **Expected:** Red banner appears: ✏️ "Editing as {name}"
+11. Attempt a write operation
+12. **Expected:** Write is NOT blocked by reject_impersonation (may still get validation errors — that's fine)
+13. Click **Stop** on the banner to exit
+
+## TC-03: Banner Color Differentiation
+1. Start read-only impersonation (View As)
+2. **Expected:** Amber (#b45309) banner with 👁 icon and "Viewing as" text
+3. Exit impersonation
+4. Start write-mode impersonation (Edit As → Confirm)
+5. **Expected:** Red (#dc2626) banner with ✏️ icon and "Editing as" text
+6. Inspect `<body>` classes
+7. **Expected:** `body.impersonating-write` class present in write mode
+
+## TC-04: Audit Log Page Renders
+1. Navigate to `/admin/audit-log`
+2. **Expected:** Page title is "Audit Log — Admin" (check browser tab)
+3. **Expected:** Table with columns: Date/Time, Admin, Target User, Action, Write Mode, IP Address
+4. **Expected:** Previous impersonation sessions from TC-01/TC-02 appear as log entries
+5. **Expected:** Action column shows colored badges (start=cyan, stop=slate)
+6. **Expected:** Write Mode column shows yes (red) or no (muted) badges
+
+## TC-05: Audit Log Pagination
+1. Navigate to `/admin/audit-log`
+2. If fewer than 50 entries exist, **Expected:** Next button is disabled
+3. Click Previous when on page 1
+4. **Expected:** Previous button disabled on page 1
+5. (If 50+ entries exist) Click Next
+6. **Expected:** Page 2 loads with next batch of entries
+
+## TC-06: Audit Log Link in Admin Dropdown
+1. Open the Admin dropdown in the navigation bar
+2. **Expected:** "Audit Log" link appears after "Users" link
+3. Click "Audit Log"
+4. **Expected:** Navigates to `/admin/audit-log`
+
+## TC-07: Non-Admin Cannot Access Audit Log
+1. Log in as a non-admin user (or use read-only impersonation of a non-admin)
+2. Navigate to `/admin/audit-log`
+3. **Expected:** Access denied or redirect — non-admins cannot view the audit log
+
+## TC-08: Backward Compatibility — View As Without Body
+1. Using DevTools/curl, POST to `/admin/impersonate/{userId}` with no request body
+2. **Expected:** 200 OK — impersonation starts in read-only mode (backward compatible)
+3. **Expected:** `write_mode` defaults to false in the ImpersonationLog entry
+
+## Edge Cases
+- **Rapid mode switching:** Start read-only, stop, immediately start write-mode — banner should correctly switch colors
+- **Multiple audit log entries:** Each start/stop pair should produce two entries with matching admin/target
+- **Empty audit log:** If no impersonation has occurred, table should show empty state message
--- a/.gsd/milestones/M021/slices/S07/tasks/T03-VERIFY.json
+++ b/.gsd/milestones/M021/slices/S07/tasks/T03-VERIFY.json
@ -0,0 +1,16 @@
+{
+  "schemaVersion": 1,
+  "taskId": "T03",
+  "unitId": "M021/S07/T03",
+  "timestamp": 1775284187583,
+  "passed": true,
+  "discoverySource": "task-plan",
+  "checks": [
+    {
+      "command": "cd frontend",
+      "exitCode": 0,
+      "durationMs": 4,
+      "verdict": "pass"
+    }
+  ]
+}
--- a/.gsd/milestones/M021/slices/S08/S08-PLAN.md
+++ b/.gsd/milestones/M021/slices/S08/S08-PLAN.md
@ -1,6 +1,33 @@
 # S08: Forgejo KB Update — Chat, Retrieval, Highlights

-**Goal:** Document new systems in Forgejo knowledgebase
+**Goal:** Forgejo wiki updated with M021 feature documentation: 3 new pages (Chat-Engine, Search-Retrieval, Highlights) and 8 updated pages reflecting chat engine, retrieval cascade, highlight detection, audio mode, chapter review, and impersonation write mode.
 **Demo:** After this: Forgejo wiki updated with chat engine, retrieval routing, and highlight detection docs

 ## Tasks
+- [x] **T01: Pushed 3 new wiki pages (Chat-Engine, Search-Retrieval, Highlights) and updated 10 existing pages documenting M021 features to Forgejo wiki** — Clone the Forgejo wiki repo via HTTPS, create 3 new markdown pages (Chat-Engine.md, Search-Retrieval.md, Highlights.md), update 8 existing pages (Home, Architecture, Data-Model, API-Surface, Frontend, Pipeline, Player, Impersonation, Decisions) and _Sidebar, then commit and push.
+
+This is a documentation-only task. All content comes from the S01-S07 slice summaries preloaded in context. The git workflow is established from M019/S06 and M020/S07: clone via HTTPS, write files, commit, push. Never use the Forgejo PATCH API (it corrupted pages in M019).
+
+## Steps
+
+1. Clone the wiki repo: `git clone https://git.xpltd.co/xpltdco/chrysopedia.wiki.git /tmp/chrysopedia-wiki-m021`
+2. Create **Chat-Engine.md** covering: SSE protocol (sources→token→done→error events), ChatService retrieve-prompt-stream pipeline, citation format [N] with technique page links, POST /api/v1/chat endpoint (query, creator params), ChatPage frontend (/chat route), cascade_tier in done event
+3. Create **Search-Retrieval.md** covering: LightRAG cutover from Qdrant as primary, 4-tier creator-scoped cascade (creator→domain→global→none), ll_keywords scoping, post-filtering with 3x oversampling, config fields (lightrag_url, lightrag_search_timeout, lightrag_min_query_length), fallback_used and cascade_tier response fields, D039/D040 decision references
+4. Create **Highlights.md** covering: 7-dimension heuristic scoring (duration_fitness 0.25, content_type 0.20, specificity_density 0.20, plugin_richness 0.10, transcript_energy 0.10, source_quality 0.10, video_type 0.05), HighlightCandidate model (UUID PK, unique FK to key_moments, score, score_breakdown JSONB, status enum), 4 admin API endpoints (POST detect/{video_id}, POST detect-all, GET candidates, GET candidates/{id}), Celery task stage_highlight_detection, migration 019
+5. Update **Home.md**: add Chat, Highlights, Audio Mode to feature list; update page/endpoint counts
+6. Update **Architecture.md**: add ChatService, HighlightScorer to component diagram; mention LightRAG integration
+7. Update **Data-Model.md**: add HighlightCandidate model, HighlightStatus enum, ChapterStatus enum, sort_order on KeyMoment, write_mode on ImpersonationLog
+8. Update **API-Surface.md**: add POST /api/v1/chat, GET /videos/{id}/stream, GET /videos/{id}/chapters, 4 creator chapter endpoints (GET/PATCH/PUT/POST under /creator/chapters), 4 highlight admin endpoints, GET /admin/impersonation-log. Update total endpoint count.
+9. Update **Frontend.md**: add ChatPage (/chat), ChapterReview (/creator/chapters/:videoId), AdminAuditLog (/admin/audit-log), AudioWaveform, ChapterMarkers, ConfirmModal components
+10. Update **Pipeline.md**: add stage_highlight_detection stage with 7 scoring dimensions
+11. Update **Player.md**: add chapter markers on seek bar, AudioWaveform conditional rendering, wavesurfer.js dependency
+12. Update **Impersonation.md**: add write_mode token support, ConfirmModal danger variant, red/amber banner differentiation, audit log page at /admin/audit-log
+13. Update **Decisions.md**: add D039 (LightRAG position-based scoring, sequential fallback) and D040 (4-tier cascade strategy)
+14. Update **_Sidebar.md**: add Chat-Engine, Search-Retrieval, Highlights links in appropriate position
+15. `cd /tmp/chrysopedia-wiki-m021 && git add -A && git commit -m 'M021: Chat engine, retrieval cascade, highlights, audio mode, chapters, impersonation write mode docs'`
+16. `git push origin master`
+17. Verify push exit code is 0
+18. Verify page count: `curl -s 'https://git.xpltd.co/api/v1/repos/xpltdco/chrysopedia/wiki/pages' | python3 -c 'import sys,json; pages=json.load(sys.stdin); print(len(pages))'`
+  - Estimate: 45m
+  - Files: /tmp/chrysopedia-wiki-m021/Chat-Engine.md, /tmp/chrysopedia-wiki-m021/Search-Retrieval.md, /tmp/chrysopedia-wiki-m021/Highlights.md, /tmp/chrysopedia-wiki-m021/Home.md, /tmp/chrysopedia-wiki-m021/Architecture.md, /tmp/chrysopedia-wiki-m021/Data-Model.md, /tmp/chrysopedia-wiki-m021/API-Surface.md, /tmp/chrysopedia-wiki-m021/Frontend.md, /tmp/chrysopedia-wiki-m021/Pipeline.md, /tmp/chrysopedia-wiki-m021/Player.md, /tmp/chrysopedia-wiki-m021/Impersonation.md, /tmp/chrysopedia-wiki-m021/Decisions.md, /tmp/chrysopedia-wiki-m021/_Sidebar.md
+  - Verify: git push exits 0 AND curl -s 'https://git.xpltd.co/api/v1/repos/xpltdco/chrysopedia/wiki/pages' returns 15+ pages
--- a/.gsd/milestones/M021/slices/S08/S08-RESEARCH.md
+++ b/.gsd/milestones/M021/slices/S08/S08-RESEARCH.md
@ -0,0 +1,81 @@
+# S08 Research: Forgejo KB Update — Chat, Retrieval, Highlights
+
+## Summary
+
+This is a documentation-only slice. Update the Forgejo wiki at `git.xpltd.co/xpltdco/chrysopedia` with M021 feature documentation. Straightforward application of the established wiki update pattern used in M019/S06 and M020/S07.
+
+## Recommendation
+
+Single task: clone wiki repo, create new pages + update existing pages, push. The git workflow is proven. Content comes entirely from the S01-S07 summaries preloaded above.
+
+## Implementation Landscape
+
+### Established Pattern (from M019/S06, M020/S07)
+
+1. **Git clone** the wiki repo: `git clone https://git.xpltd.co/xpltdco/chrysopedia.wiki.git`
+2. **Write/update** markdown files in the clone
+3. **Git commit + push** via HTTPS with Forgejo personal access token
+4. **Never use the PATCH API** — it corrupted pages in M019 (hard lesson)
+5. Push uses HTTPS (SSH port 2222 is unreachable from ub01 per M020/S07)
+
+### Wiki URL
+
+`https://git.xpltd.co/xpltdco/chrysopedia/wiki/`
+
+### Existing Wiki Pages (12 + sidebar)
+
+| Page | Source Milestone | Needs Update? |
+|------|-----------------|---------------|
+| Home | M018 | Yes — update stats, add Chat/Highlights to feature list |
+| Architecture | M018, updated M019 | Yes — add Chat service, Highlight scoring to diagram |
+| Data-Model | M018, updated M019 | Yes — add HighlightCandidate model, ChapterStatus enum, write_mode on ImpersonationLog |
+| API-Surface | M018, updated M019 | Yes — add chat endpoint, highlight endpoints, video stream/chapters, creator chapters |
+| Frontend | M018 | Yes — add ChatPage, ChapterReview, AdminAuditLog, AudioWaveform, ChapterMarkers, ConfirmModal |
+| Pipeline | M018 | Yes — add highlight detection stage |
+| Deployment | M018, updated M019 | No change needed |
+| Development-Guide | M018 | No change needed |
+| Decisions | M018 | Yes — add D039, D040 |
+| Authentication | M019 | Yes — update Impersonation section with write mode |
+| Player | M020 | Yes — add chapter markers, audio waveform mode |
+| Impersonation | M020 | Yes — add write mode, ConfirmModal, audit log |
+| _Sidebar | all | Yes — add new pages |
+
+### New Pages to Create
+
+1. **Chat-Engine.md** — SSE protocol, ChatService retrieve-prompt-stream pipeline, citation format, frontend ChatPage, cascade_tier in responses
+2. **Search-Retrieval.md** — LightRAG cutover, 4-tier creator-scoped cascade, fallback behavior, config fields, cascade_tier field
+3. **Highlights.md** — Highlight detection v1, 7-dimension scoring, HighlightCandidate model, admin API, Celery task, migration 019
+
+### Pages to Update
+
+1. **Data-Model.md** — HighlightCandidate model, HighlightStatus enum, ChapterStatus enum, sort_order on KeyMoment, write_mode on ImpersonationLog
+2. **API-Surface.md** — POST /api/v1/chat, GET /videos/{id}/stream, GET /videos/{id}/chapters, 4 creator chapter endpoints, 4 highlight admin endpoints. Update endpoint count.
+3. **Frontend.md** — ChatPage (/chat), ChapterReview (/creator/chapters/:videoId), AdminAuditLog (/admin/audit-log), AudioWaveform, ChapterMarkers, ConfirmModal components
+4. **Pipeline.md** — stage_highlight_detection, 7 scoring dimensions
+5. **Player.md** — Chapter markers on seek bar, AudioWaveform conditional rendering, wavesurfer.js
+6. **Impersonation.md** — write_mode token support, ConfirmModal danger variant, red/amber banner, audit log page
+7. **Decisions.md** — D039 (LightRAG scoring), D040 (cascade strategy)
+8. **_Sidebar.md** — Add Chat-Engine, Search-Retrieval, Highlights links
+
+### Content Sources
+
+All content comes from the S01-S07 summaries (already preloaded in context). Key decisions D039, D040 from DECISIONS.md. No need to read source code — the summaries contain exact file names, method names, API shapes, and config fields.
+
+### Verification
+
+- `git push` succeeds (exit 0)
+- Confirm page count via Forgejo wiki API: `curl https://git.xpltd.co/api/v1/repos/xpltdco/chrysopedia/wiki/pages`
+
+### Constraints
+
+- Must run on ub01 (that's where the git credentials are configured)
+- Use HTTPS not SSH for push
+- Forgejo personal access token needed (was set up in M020/S07)
+
+### Task Decomposition Suggestion
+
+**Single task (T01):** Clone wiki, write 3 new pages + update 8 existing pages + sidebar, commit, push. This is ~30 min of markdown writing — no code, no tests, no builds. Splitting into multiple tasks would just add overhead for a doc-only slice.
+
+### Risk
+
+Effectively zero. This is markdown file creation following an established pattern with no code changes.
--- a/.gsd/milestones/M021/slices/S08/tasks/T01-PLAN.md
+++ b/.gsd/milestones/M021/slices/S08/tasks/T01-PLAN.md
@ -0,0 +1,65 @@
+---
+estimated_steps: 21
+estimated_files: 13
+skills_used: []
+---
+
+# T01: Clone wiki, write 3 new pages + update 8 existing pages + sidebar, push
+
+Clone the Forgejo wiki repo via HTTPS, create 3 new markdown pages (Chat-Engine.md, Search-Retrieval.md, Highlights.md), update 8 existing pages (Home, Architecture, Data-Model, API-Surface, Frontend, Pipeline, Player, Impersonation, Decisions) and _Sidebar, then commit and push.
+
+This is a documentation-only task. All content comes from the S01-S07 slice summaries preloaded in context. The git workflow is established from M019/S06 and M020/S07: clone via HTTPS, write files, commit, push. Never use the Forgejo PATCH API (it corrupted pages in M019).
+
+## Steps
+
+1. Clone the wiki repo: `git clone https://git.xpltd.co/xpltdco/chrysopedia.wiki.git /tmp/chrysopedia-wiki-m021`
+2. Create **Chat-Engine.md** covering: SSE protocol (sources→token→done→error events), ChatService retrieve-prompt-stream pipeline, citation format [N] with technique page links, POST /api/v1/chat endpoint (query, creator params), ChatPage frontend (/chat route), cascade_tier in done event
+3. Create **Search-Retrieval.md** covering: LightRAG cutover from Qdrant as primary, 4-tier creator-scoped cascade (creator→domain→global→none), ll_keywords scoping, post-filtering with 3x oversampling, config fields (lightrag_url, lightrag_search_timeout, lightrag_min_query_length), fallback_used and cascade_tier response fields, D039/D040 decision references
+4. Create **Highlights.md** covering: 7-dimension heuristic scoring (duration_fitness 0.25, content_type 0.20, specificity_density 0.20, plugin_richness 0.10, transcript_energy 0.10, source_quality 0.10, video_type 0.05), HighlightCandidate model (UUID PK, unique FK to key_moments, score, score_breakdown JSONB, status enum), 4 admin API endpoints (POST detect/{video_id}, POST detect-all, GET candidates, GET candidates/{id}), Celery task stage_highlight_detection, migration 019
+5. Update **Home.md**: add Chat, Highlights, Audio Mode to feature list; update page/endpoint counts
+6. Update **Architecture.md**: add ChatService, HighlightScorer to component diagram; mention LightRAG integration
+7. Update **Data-Model.md**: add HighlightCandidate model, HighlightStatus enum, ChapterStatus enum, sort_order on KeyMoment, write_mode on ImpersonationLog
+8. Update **API-Surface.md**: add POST /api/v1/chat, GET /videos/{id}/stream, GET /videos/{id}/chapters, 4 creator chapter endpoints (GET/PATCH/PUT/POST under /creator/chapters), 4 highlight admin endpoints, GET /admin/impersonation-log. Update total endpoint count.
+9. Update **Frontend.md**: add ChatPage (/chat), ChapterReview (/creator/chapters/:videoId), AdminAuditLog (/admin/audit-log), AudioWaveform, ChapterMarkers, ConfirmModal components
+10. Update **Pipeline.md**: add stage_highlight_detection stage with 7 scoring dimensions
+11. Update **Player.md**: add chapter markers on seek bar, AudioWaveform conditional rendering, wavesurfer.js dependency
+12. Update **Impersonation.md**: add write_mode token support, ConfirmModal danger variant, red/amber banner differentiation, audit log page at /admin/audit-log
+13. Update **Decisions.md**: add D039 (LightRAG position-based scoring, sequential fallback) and D040 (4-tier cascade strategy)
+14. Update **_Sidebar.md**: add Chat-Engine, Search-Retrieval, Highlights links in appropriate position
+15. `cd /tmp/chrysopedia-wiki-m021 && git add -A && git commit -m 'M021: Chat engine, retrieval cascade, highlights, audio mode, chapters, impersonation write mode docs'`
+16. `git push origin master`
+17. Verify push exit code is 0
+18. Verify page count: `curl -s 'https://git.xpltd.co/api/v1/repos/xpltdco/chrysopedia/wiki/pages' | python3 -c 'import sys,json; pages=json.load(sys.stdin); print(len(pages))'`
+
+## Inputs
+
+- ``/tmp/chrysopedia-wiki-m021/Home.md` — existing wiki home page to update`
+- ``/tmp/chrysopedia-wiki-m021/Architecture.md` — existing architecture page to update`
+- ``/tmp/chrysopedia-wiki-m021/Data-Model.md` — existing data model page to update`
+- ``/tmp/chrysopedia-wiki-m021/API-Surface.md` — existing API surface page to update`
+- ``/tmp/chrysopedia-wiki-m021/Frontend.md` — existing frontend page to update`
+- ``/tmp/chrysopedia-wiki-m021/Pipeline.md` — existing pipeline page to update`
+- ``/tmp/chrysopedia-wiki-m021/Player.md` — existing player page to update`
+- ``/tmp/chrysopedia-wiki-m021/Impersonation.md` — existing impersonation page to update`
+- ``/tmp/chrysopedia-wiki-m021/Decisions.md` — existing decisions page to update`
+- ``/tmp/chrysopedia-wiki-m021/_Sidebar.md` — existing sidebar to update`
+
+## Expected Output
+
+- ``/tmp/chrysopedia-wiki-m021/Chat-Engine.md` — new wiki page documenting chat engine`
+- ``/tmp/chrysopedia-wiki-m021/Search-Retrieval.md` — new wiki page documenting LightRAG + cascade`
+- ``/tmp/chrysopedia-wiki-m021/Highlights.md` — new wiki page documenting highlight detection`
+- ``/tmp/chrysopedia-wiki-m021/Home.md` — updated with M021 features`
+- ``/tmp/chrysopedia-wiki-m021/Architecture.md` — updated with chat + highlights`
+- ``/tmp/chrysopedia-wiki-m021/Data-Model.md` — updated with new models/enums`
+- ``/tmp/chrysopedia-wiki-m021/API-Surface.md` — updated with new endpoints`
+- ``/tmp/chrysopedia-wiki-m021/Frontend.md` — updated with new pages/components`
+- ``/tmp/chrysopedia-wiki-m021/Pipeline.md` — updated with highlight stage`
+- ``/tmp/chrysopedia-wiki-m021/Player.md` — updated with chapters + audio`
+- ``/tmp/chrysopedia-wiki-m021/Impersonation.md` — updated with write mode`
+- ``/tmp/chrysopedia-wiki-m021/Decisions.md` — updated with D039, D040`
+- ``/tmp/chrysopedia-wiki-m021/_Sidebar.md` — updated with new page links`
+
+## Verification
+
+git push exits 0 AND curl -s 'https://git.xpltd.co/api/v1/repos/xpltdco/chrysopedia/wiki/pages' returns 15+ pages
--- a/.gsd/milestones/M021/slices/S08/tasks/T01-SUMMARY.md
+++ b/.gsd/milestones/M021/slices/S08/tasks/T01-SUMMARY.md
@ -0,0 +1,100 @@
+---
+id: T01
+parent: S08
+milestone: M021
+provides: []
+requires: []
+affects: []
+key_files: ["Chat-Engine.md", "Search-Retrieval.md", "Highlights.md", "Home.md", "Architecture.md", "Data-Model.md", "API-Surface.md", "Frontend.md", "Pipeline.md", "Player.md", "Impersonation.md", "Decisions.md", "_Sidebar.md"]
+key_decisions: ["Added Features section to wiki sidebar for M021 feature pages", "Used SSH remote for push since HTTPS lacked credentials"]
+patterns_established: []
+drill_down_paths: []
+observability_surfaces: []
+duration: ""
+verification_result: "git push origin main exits 0 (commit eec99b6). Forgejo wiki API returns 19 pages, above the 15+ threshold. All 3 new pages and 10 updates confirmed in single commit."
+completed_at: 2026-04-04T06:41:58.884Z
+blocker_discovered: false
+---
+
+# T01: Pushed 3 new wiki pages (Chat-Engine, Search-Retrieval, Highlights) and updated 10 existing pages documenting M021 features to Forgejo wiki
+
+> Pushed 3 new wiki pages (Chat-Engine, Search-Retrieval, Highlights) and updated 10 existing pages documenting M021 features to Forgejo wiki
+
+## What Happened
+---
+id: T01
+parent: S08
+milestone: M021
+key_files:
+  - Chat-Engine.md
+  - Search-Retrieval.md
+  - Highlights.md
+  - Home.md
+  - Architecture.md
+  - Data-Model.md
+  - API-Surface.md
+  - Frontend.md
+  - Pipeline.md
+  - Player.md
+  - Impersonation.md
+  - Decisions.md
+  - _Sidebar.md
+key_decisions:
+  - Added Features section to wiki sidebar for M021 feature pages
+  - Used SSH remote for push since HTTPS lacked credentials
+duration: ""
+verification_result: passed
+completed_at: 2026-04-04T06:41:58.884Z
+blocker_discovered: false
+---
+
+# T01: Pushed 3 new wiki pages (Chat-Engine, Search-Retrieval, Highlights) and updated 10 existing pages documenting M021 features to Forgejo wiki
+
+**Pushed 3 new wiki pages (Chat-Engine, Search-Retrieval, Highlights) and updated 10 existing pages documenting M021 features to Forgejo wiki**
+
+## What Happened
+
+Cloned the Chrysopedia Forgejo wiki, read all 7 M021 slice summaries for source material, created 3 new documentation pages (Chat-Engine.md covering SSE protocol and ChatService, Search-Retrieval.md covering LightRAG and 4-tier cascade, Highlights.md covering 7-dimension scoring), updated 10 existing pages (Home, Architecture, Data-Model, API-Surface, Frontend, Pipeline, Player, Impersonation, Decisions, _Sidebar) with M021 features including chat engine, retrieval cascade, highlight detection, audio mode, chapter review, and impersonation write mode. Committed 13 files and pushed to Forgejo via SSH.
+
+## Verification
+
+git push origin main exits 0 (commit eec99b6). Forgejo wiki API returns 19 pages, above the 15+ threshold. All 3 new pages and 10 updates confirmed in single commit.
+
+## Verification Evidence
+
+| # | Command | Exit Code | Verdict | Duration |
+|---|---------|-----------|---------|----------|
+| 1 | `git push origin main` | 0 | ✅ pass | 2000ms |
+| 2 | `curl wiki/pages API → 19 pages (≥15)` | 0 | ✅ pass | 500ms |
+
+
+## Deviations
+
+Switched git remote from HTTPS to SSH for push since HTTPS had no credential config. Updated 10 pages instead of 8+1 as planned (_Sidebar counted separately).
+
+## Known Issues
+
+None.
+
+## Files Created/Modified
+
+- `Chat-Engine.md`
+- `Search-Retrieval.md`
+- `Highlights.md`
+- `Home.md`
+- `Architecture.md`
+- `Data-Model.md`
+- `API-Surface.md`
+- `Frontend.md`
+- `Pipeline.md`
+- `Player.md`
+- `Impersonation.md`
+- `Decisions.md`
+- `_Sidebar.md`
+
+
+## Deviations
+Switched git remote from HTTPS to SSH for push since HTTPS had no credential config. Updated 10 pages instead of 8+1 as planned (_Sidebar counted separately).
+
+## Known Issues
+None.