From 324e9336707a12c616fa42b4d2d31c4d3b3e1544 Mon Sep 17 00:00:00 2001
From: jlightner <jlightner@ub01.a.xpltd.co>
Date: Mon, 30 Mar 2026 02:53:56 -0500
Subject: [PATCH 1/8] =?UTF-8?q?feat:=20Content=20issue=20reporting=20?=
 =?UTF-8?q?=E2=80=94=20submit=20from=20technique=20pages,=20manage=20in=20?=
 =?UTF-8?q?admin=20reports=20page?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- ContentReport model with generic content_type/content_id (supports any entity)
- Alembic migration 003: content_reports table with status + content indexes
- POST /reports (public), GET/PATCH /admin/reports (admin triage)
- Report modal on technique pages with issue type dropdown + description
- Admin reports page with status filter, expand/collapse detail, triage actions
- All CSS uses var(--*) tokens, dark theme consistent
---
 alembic/versions/003_content_reports.py      |  47 +++
 backend/main.py                              |   3 +-
 backend/models.py                            |  59 ++++
 backend/routers/reports.py                   | 147 ++++++++
 backend/schemas.py                           |  60 ++++
 frontend/src/App.css                         | 332 +++++++++++++++++++
 frontend/src/App.tsx                         |   5 +-
 frontend/src/api/public-client.ts            |  69 ++++
 frontend/src/components/ReportIssueModal.tsx | 135 ++++++++
 frontend/src/pages/AdminReports.tsx          | 246 ++++++++++++++
 frontend/src/pages/TechniquePage.tsx         |  19 ++
 11 files changed, 1120 insertions(+), 2 deletions(-)
 create mode 100644 alembic/versions/003_content_reports.py
 create mode 100644 backend/routers/reports.py
 create mode 100644 frontend/src/components/ReportIssueModal.tsx
 create mode 100644 frontend/src/pages/AdminReports.tsx

diff --git a/alembic/versions/003_content_reports.py b/alembic/versions/003_content_reports.py
new file mode 100644
index 0000000..c24bdd8
--- /dev/null
+++ b/alembic/versions/003_content_reports.py
@@ -0,0 +1,47 @@
+"""Create content_reports table.
+
+Revision ID: 003_content_reports
+Revises: 002_technique_page_versions
+"""
+from alembic import op
+import sqlalchemy as sa
+from sqlalchemy.dialects.postgresql import UUID
+
+revision = "003_content_reports"
+down_revision = "002_technique_page_versions"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.create_table(
+        "content_reports",
+        sa.Column("id", UUID(as_uuid=True), primary_key=True, server_default=sa.func.gen_random_uuid()),
+        sa.Column("content_type", sa.String(50), nullable=False),
+        sa.Column("content_id", UUID(as_uuid=True), nullable=True),
+        sa.Column("content_title", sa.String(500), nullable=True),
+        sa.Column("report_type", sa.Enum(
+            "inaccurate", "missing_info", "wrong_attribution", "formatting", "other",
+            name="report_type", create_constraint=True,
+        ), nullable=False),
+        sa.Column("description", sa.Text(), nullable=False),
+        sa.Column("status", sa.Enum(
+            "open", "acknowledged", "resolved", "dismissed",
+            name="report_status", create_constraint=True,
+        ), nullable=False, server_default="open"),
+        sa.Column("admin_notes", sa.Text(), nullable=True),
+        sa.Column("page_url", sa.String(1000), nullable=True),
+        sa.Column("created_at", sa.DateTime(), server_default=sa.func.now(), nullable=False),
+        sa.Column("resolved_at", sa.DateTime(), nullable=True),
+    )
+
+    op.create_index("ix_content_reports_status_created", "content_reports", ["status", "created_at"])
+    op.create_index("ix_content_reports_content", "content_reports", ["content_type", "content_id"])
+
+
+def downgrade() -> None:
+    op.drop_index("ix_content_reports_content")
+    op.drop_index("ix_content_reports_status_created")
+    op.drop_table("content_reports")
+    sa.Enum(name="report_status").drop(op.get_bind(), checkfirst=True)
+    sa.Enum(name="report_type").drop(op.get_bind(), checkfirst=True)
diff --git a/backend/main.py b/backend/main.py
index 32977cd..7e93318 100644
--- a/backend/main.py
+++ b/backend/main.py
@@ -12,7 +12,7 @@ from fastapi import FastAPI
 from fastapi.middleware.cors import CORSMiddleware
 
 from config import get_settings
-from routers import creators, health, ingest, pipeline, review, search, techniques, topics, videos
+from routers import creators, health, ingest, pipeline, reports, review, search, techniques, topics, videos
 
 
 def _setup_logging() -> None:
@@ -82,6 +82,7 @@ app.include_router(creators.router, prefix="/api/v1")
 app.include_router(ingest.router, prefix="/api/v1")
 app.include_router(pipeline.router, prefix="/api/v1")
 app.include_router(review.router, prefix="/api/v1")
+app.include_router(reports.router, prefix="/api/v1")
 app.include_router(search.router, prefix="/api/v1")
 app.include_router(techniques.router, prefix="/api/v1")
 app.include_router(topics.router, prefix="/api/v1")
diff --git a/backend/models.py b/backend/models.py
index 4321417..3935cad 100644
--- a/backend/models.py
+++ b/backend/models.py
@@ -319,3 +319,62 @@ class Tag(Base):
     name: Mapped[str] = mapped_column(String(255), unique=True, nullable=False)
     category: Mapped[str] = mapped_column(String(255), nullable=False)
     aliases: Mapped[list[str] | None] = mapped_column(ARRAY(String), nullable=True)
+
+
+# ── Content Report Enums ─────────────────────────────────────────────────────
+
+class ReportType(str, enum.Enum):
+    """Classification of user-submitted content reports."""
+    inaccurate = "inaccurate"
+    missing_info = "missing_info"
+    wrong_attribution = "wrong_attribution"
+    formatting = "formatting"
+    other = "other"
+
+
+class ReportStatus(str, enum.Enum):
+    """Triage status for content reports."""
+    open = "open"
+    acknowledged = "acknowledged"
+    resolved = "resolved"
+    dismissed = "dismissed"
+
+
+# ── Content Report ───────────────────────────────────────────────────────────
+
+class ContentReport(Base):
+    """User-submitted report about a content issue.
+
+    Generic: content_type + content_id can reference any entity
+    (technique_page, key_moment, creator, or general).
+    """
+    __tablename__ = "content_reports"
+
+    id: Mapped[uuid.UUID] = _uuid_pk()
+    content_type: Mapped[str] = mapped_column(
+        String(50), nullable=False, doc="Entity type: technique_page, key_moment, creator, general"
+    )
+    content_id: Mapped[uuid.UUID | None] = mapped_column(
+        UUID(as_uuid=True), nullable=True, doc="FK to the reported entity (null for general reports)"
+    )
+    content_title: Mapped[str | None] = mapped_column(
+        String(500), nullable=True, doc="Snapshot of entity title at report time"
+    )
+    report_type: Mapped[ReportType] = mapped_column(
+        Enum(ReportType, name="report_type", create_constraint=True),
+        nullable=False,
+    )
+    description: Mapped[str] = mapped_column(Text, nullable=False)
+    status: Mapped[ReportStatus] = mapped_column(
+        Enum(ReportStatus, name="report_status", create_constraint=True),
+        default=ReportStatus.open,
+        server_default="open",
+    )
+    admin_notes: Mapped[str | None] = mapped_column(Text, nullable=True)
+    page_url: Mapped[str | None] = mapped_column(
+        String(1000), nullable=True, doc="URL the user was on when reporting"
+    )
+    created_at: Mapped[datetime] = mapped_column(
+        default=_now, server_default=func.now()
+    )
+    resolved_at: Mapped[datetime | None] = mapped_column(nullable=True)
diff --git a/backend/routers/reports.py b/backend/routers/reports.py
new file mode 100644
index 0000000..9bdbd76
--- /dev/null
+++ b/backend/routers/reports.py
@@ -0,0 +1,147 @@
+"""Content reports router — public submission + admin management.
+
+Public:
+  POST /reports              Submit a content issue report
+
+Admin:
+  GET  /admin/reports        List reports (filterable by status, content_type)
+  GET  /admin/reports/{id}   Get single report detail
+  PATCH /admin/reports/{id}  Update status / add admin notes
+"""
+
+import logging
+import uuid
+from datetime import datetime, timezone
+from typing import Annotated
+
+from fastapi import APIRouter, Depends, HTTPException, Query
+from sqlalchemy import func, select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from database import get_session
+from models import ContentReport, ReportStatus
+from schemas import (
+    ContentReportCreate,
+    ContentReportListResponse,
+    ContentReportRead,
+    ContentReportUpdate,
+)
+
+logger = logging.getLogger("chrysopedia.reports")
+
+router = APIRouter(tags=["reports"])
+
+
+# ── Public ───────────────────────────────────────────────────────────────────
+
+@router.post("/reports", response_model=ContentReportRead, status_code=201)
+async def submit_report(
+    body: ContentReportCreate,
+    db: AsyncSession = Depends(get_session),
+):
+    """Submit a content issue report (public, no auth)."""
+    report = ContentReport(
+        content_type=body.content_type,
+        content_id=body.content_id,
+        content_title=body.content_title,
+        report_type=body.report_type,
+        description=body.description,
+        page_url=body.page_url,
+    )
+    db.add(report)
+    await db.commit()
+    await db.refresh(report)
+
+    logger.info(
+        "New content report: id=%s type=%s content=%s/%s",
+        report.id, report.report_type, report.content_type, report.content_id,
+    )
+    return report
+
+
+# ── Admin ────────────────────────────────────────────────────────────────────
+
+@router.get("/admin/reports", response_model=ContentReportListResponse)
+async def list_reports(
+    status: Annotated[str | None, Query(description="Filter by status")] = None,
+    content_type: Annotated[str | None, Query(description="Filter by content type")] = None,
+    offset: Annotated[int, Query(ge=0)] = 0,
+    limit: Annotated[int, Query(ge=1, le=100)] = 50,
+    db: AsyncSession = Depends(get_session),
+):
+    """List content reports with optional filters."""
+    stmt = select(ContentReport)
+
+    if status:
+        stmt = stmt.where(ContentReport.status == status)
+    if content_type:
+        stmt = stmt.where(ContentReport.content_type == content_type)
+
+    # Count
+    count_stmt = select(func.count()).select_from(stmt.subquery())
+    total = (await db.execute(count_stmt)).scalar() or 0
+
+    # Fetch page
+    stmt = stmt.order_by(ContentReport.created_at.desc())
+    stmt = stmt.offset(offset).limit(limit)
+    result = await db.execute(stmt)
+    items = result.scalars().all()
+
+    return {"items": items, "total": total, "offset": offset, "limit": limit}
+
+
+@router.get("/admin/reports/{report_id}", response_model=ContentReportRead)
+async def get_report(
+    report_id: uuid.UUID,
+    db: AsyncSession = Depends(get_session),
+):
+    """Get a single content report by ID."""
+    result = await db.execute(
+        select(ContentReport).where(ContentReport.id == report_id)
+    )
+    report = result.scalar_one_or_none()
+    if not report:
+        raise HTTPException(status_code=404, detail="Report not found")
+    return report
+
+
+@router.patch("/admin/reports/{report_id}", response_model=ContentReportRead)
+async def update_report(
+    report_id: uuid.UUID,
+    body: ContentReportUpdate,
+    db: AsyncSession = Depends(get_session),
+):
+    """Update report status and/or admin notes."""
+    result = await db.execute(
+        select(ContentReport).where(ContentReport.id == report_id)
+    )
+    report = result.scalar_one_or_none()
+    if not report:
+        raise HTTPException(status_code=404, detail="Report not found")
+
+    if body.status is not None:
+        # Validate status value
+        try:
+            ReportStatus(body.status)
+        except ValueError:
+            raise HTTPException(
+                status_code=422,
+                detail=f"Invalid status: {body.status}. Must be one of: open, acknowledged, resolved, dismissed",
+            )
+        report.status = body.status
+        if body.status in ("resolved", "dismissed"):
+            report.resolved_at = datetime.now(timezone.utc).replace(tzinfo=None)
+        elif body.status == "open":
+            report.resolved_at = None
+
+    if body.admin_notes is not None:
+        report.admin_notes = body.admin_notes
+
+    await db.commit()
+    await db.refresh(report)
+
+    logger.info(
+        "Report updated: id=%s status=%s",
+        report.id, report.status,
+    )
+    return report
diff --git a/backend/schemas.py b/backend/schemas.py
index 1e6fb9b..256c5ee 100644
--- a/backend/schemas.py
+++ b/backend/schemas.py
@@ -364,3 +364,63 @@ class CreatorBrowseItem(CreatorRead):
     """Creator with technique and video counts for browse pages."""
     technique_count: int = 0
     video_count: int = 0
+
+
+# ── Content Reports ──────────────────────────────────────────────────────────
+
+class ContentReportCreate(BaseModel):
+    """Public submission: report a content issue."""
+    content_type: str = Field(
+        ..., description="Entity type: technique_page, key_moment, creator, general"
+    )
+    content_id: uuid.UUID | None = Field(
+        None, description="ID of the reported entity (null for general reports)"
+    )
+    content_title: str | None = Field(
+        None, description="Title of the reported content (for display context)"
+    )
+    report_type: str = Field(
+        ..., description="inaccurate, missing_info, wrong_attribution, formatting, other"
+    )
+    description: str = Field(
+        ..., min_length=10, max_length=2000,
+        description="Description of the issue"
+    )
+    page_url: str | None = Field(
+        None, description="URL the user was on when reporting"
+    )
+
+
+class ContentReportRead(BaseModel):
+    """Full report for admin views."""
+    model_config = ConfigDict(from_attributes=True)
+
+    id: uuid.UUID
+    content_type: str
+    content_id: uuid.UUID | None = None
+    content_title: str | None = None
+    report_type: str
+    description: str
+    status: str = "open"
+    admin_notes: str | None = None
+    page_url: str | None = None
+    created_at: datetime
+    resolved_at: datetime | None = None
+
+
+class ContentReportUpdate(BaseModel):
+    """Admin update: change status and/or add notes."""
+    status: str | None = Field(
+        None, description="open, acknowledged, resolved, dismissed"
+    )
+    admin_notes: str | None = Field(
+        None, max_length=2000, description="Admin notes about resolution"
+    )
+
+
+class ContentReportListResponse(BaseModel):
+    """Paginated list of content reports."""
+    items: list[ContentReportRead] = Field(default_factory=list)
+    total: int = 0
+    offset: int = 0
+    limit: int = 50
diff --git a/frontend/src/App.css b/frontend/src/App.css
index f6bfec9..28925c8 100644
--- a/frontend/src/App.css
+++ b/frontend/src/App.css
@@ -1929,3 +1929,335 @@ body {
     padding-left: 2rem;
   }
 }
+
+/* ── Report Issue Modal ─────────────────────────────────────────────────── */
+
+.modal-overlay {
+  position: fixed;
+  inset: 0;
+  background: var(--color-overlay);
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  z-index: 1000;
+}
+
+.modal-content {
+  background: var(--color-bg-surface);
+  border: 1px solid var(--color-border);
+  border-radius: 12px;
+  padding: 1.5rem;
+  width: 90%;
+  max-width: 480px;
+  max-height: 90vh;
+  overflow-y: auto;
+}
+
+.report-modal__title {
+  margin: 0 0 0.75rem;
+  color: var(--color-text-primary);
+  font-size: 1.1rem;
+}
+
+.report-modal__context {
+  color: var(--color-text-secondary);
+  font-size: 0.85rem;
+  margin: 0 0 1rem;
+}
+
+.report-modal__context strong {
+  color: var(--color-text-primary);
+}
+
+.report-modal__success {
+  color: var(--color-accent);
+  margin: 0.5rem 0 1.5rem;
+}
+
+.report-modal__label {
+  display: flex;
+  flex-direction: column;
+  gap: 0.35rem;
+  margin-bottom: 1rem;
+  color: var(--color-text-secondary);
+  font-size: 0.85rem;
+}
+
+.report-modal__select {
+  background: var(--color-bg-input);
+  color: var(--color-text-primary);
+  border: 1px solid var(--color-border);
+  border-radius: 6px;
+  padding: 0.5rem;
+  font-size: 0.9rem;
+}
+
+.report-modal__textarea {
+  background: var(--color-bg-input);
+  color: var(--color-text-primary);
+  border: 1px solid var(--color-border);
+  border-radius: 6px;
+  padding: 0.5rem;
+  font-size: 0.9rem;
+  resize: vertical;
+  min-height: 80px;
+  font-family: inherit;
+}
+
+.report-modal__textarea:focus,
+.report-modal__select:focus {
+  outline: none;
+  border-color: var(--color-accent);
+}
+
+.report-modal__error {
+  color: var(--color-error);
+  font-size: 0.85rem;
+  margin: 0 0 0.75rem;
+}
+
+.report-modal__actions {
+  display: flex;
+  gap: 0.5rem;
+  justify-content: flex-end;
+}
+
+.report-issue-btn {
+  margin-top: 0.5rem;
+  align-self: flex-start;
+}
+
+/* ── Buttons ────────────────────────────────────────────────────────────── */
+
+.btn {
+  padding: 0.5rem 1rem;
+  border-radius: 6px;
+  font-size: 0.85rem;
+  cursor: pointer;
+  border: 1px solid var(--color-border);
+  transition: background 0.15s, border-color 0.15s;
+}
+
+.btn--small {
+  padding: 0.3rem 0.7rem;
+  font-size: 0.8rem;
+}
+
+.btn--primary {
+  background: var(--color-accent);
+  color: var(--color-bg-page);
+  border-color: var(--color-accent);
+  font-weight: 600;
+}
+
+.btn--primary:hover:not(:disabled) {
+  background: var(--color-accent-hover);
+}
+
+.btn--primary:disabled {
+  opacity: 0.5;
+  cursor: not-allowed;
+}
+
+.btn--secondary {
+  background: var(--color-bg-input);
+  color: var(--color-text-primary);
+  border-color: var(--color-border);
+}
+
+.btn--secondary:hover:not(:disabled) {
+  background: var(--color-border);
+}
+
+.btn--danger {
+  background: var(--color-badge-rejected-bg);
+  color: var(--color-badge-rejected-text);
+  border-color: var(--color-badge-rejected-bg);
+}
+
+.btn--danger:hover:not(:disabled) {
+  opacity: 0.85;
+}
+
+/* ── Admin Reports ──────────────────────────────────────────────────────── */
+
+.admin-reports {
+  max-width: 900px;
+  margin: 0 auto;
+  padding: 2rem 1rem;
+}
+
+.admin-reports__title {
+  color: var(--color-text-primary);
+  margin: 0 0 0.25rem;
+}
+
+.admin-reports__subtitle {
+  color: var(--color-text-muted);
+  margin: 0 0 1.5rem;
+  font-size: 0.9rem;
+}
+
+.admin-reports__filters {
+  margin-bottom: 1.25rem;
+}
+
+.admin-reports__list {
+  display: flex;
+  flex-direction: column;
+  gap: 0.75rem;
+}
+
+.report-card {
+  background: var(--color-bg-surface);
+  border: 1px solid var(--color-border);
+  border-radius: 8px;
+  overflow: hidden;
+}
+
+.report-card--open {
+  border-left: 3px solid var(--color-accent);
+}
+
+.report-card--acknowledged {
+  border-left: 3px solid var(--color-badge-pending-text);
+}
+
+.report-card--resolved {
+  border-left: 3px solid var(--color-badge-approved-text);
+}
+
+.report-card--dismissed {
+  border-left: 3px solid var(--color-text-muted);
+  opacity: 0.7;
+}
+
+.report-card__header {
+  padding: 0.75rem 1rem;
+  cursor: pointer;
+}
+
+.report-card__header:hover {
+  background: var(--color-bg-input);
+}
+
+.report-card__meta {
+  display: flex;
+  align-items: center;
+  gap: 0.5rem;
+  margin-bottom: 0.35rem;
+  flex-wrap: wrap;
+}
+
+.report-card__date {
+  color: var(--color-text-muted);
+  font-size: 0.8rem;
+  margin-left: auto;
+}
+
+.report-card__summary {
+  display: flex;
+  flex-direction: column;
+  gap: 0.15rem;
+}
+
+.report-card__content-title {
+  color: var(--color-text-primary);
+  font-weight: 500;
+  font-size: 0.9rem;
+}
+
+.report-card__description {
+  color: var(--color-text-secondary);
+  font-size: 0.85rem;
+}
+
+.report-card__detail {
+  padding: 0.75rem 1rem 1rem;
+  border-top: 1px solid var(--color-border);
+  display: flex;
+  flex-direction: column;
+  gap: 0.75rem;
+}
+
+.report-card__full-description {
+  color: var(--color-text-secondary);
+  font-size: 0.85rem;
+}
+
+.report-card__full-description strong {
+  color: var(--color-text-primary);
+}
+
+.report-card__full-description p {
+  margin: 0.25rem 0 0;
+  white-space: pre-wrap;
+}
+
+.report-card__url {
+  font-size: 0.8rem;
+  color: var(--color-text-muted);
+}
+
+.report-card__url a {
+  color: var(--color-accent);
+}
+
+.report-card__info-row {
+  display: flex;
+  gap: 1rem;
+  font-size: 0.8rem;
+  color: var(--color-text-muted);
+  flex-wrap: wrap;
+}
+
+.report-card__notes-label {
+  display: flex;
+  flex-direction: column;
+  gap: 0.25rem;
+  color: var(--color-text-secondary);
+  font-size: 0.85rem;
+}
+
+.report-card__notes {
+  background: var(--color-bg-input);
+  color: var(--color-text-primary);
+  border: 1px solid var(--color-border);
+  border-radius: 6px;
+  padding: 0.5rem;
+  font-size: 0.85rem;
+  font-family: inherit;
+  resize: vertical;
+}
+
+.report-card__notes:focus {
+  outline: none;
+  border-color: var(--color-accent);
+}
+
+.report-card__actions {
+  display: flex;
+  gap: 0.5rem;
+  flex-wrap: wrap;
+}
+
+/* Status pill colors */
+.pill--open {
+  background: var(--color-accent-subtle);
+  color: var(--color-accent);
+}
+
+.pill--acknowledged {
+  background: var(--color-badge-pending-bg);
+  color: var(--color-badge-pending-text);
+}
+
+.pill--resolved {
+  background: var(--color-badge-approved-bg);
+  color: var(--color-badge-approved-text);
+}
+
+.pill--dismissed {
+  background: var(--color-bg-input);
+  color: var(--color-text-muted);
+}
diff --git a/frontend/src/App.tsx b/frontend/src/App.tsx
index 8b7bcd4..1dd122c 100644
--- a/frontend/src/App.tsx
+++ b/frontend/src/App.tsx
@@ -7,6 +7,7 @@ import CreatorDetail from "./pages/CreatorDetail";
 import TopicsBrowse from "./pages/TopicsBrowse";
 import ReviewQueue from "./pages/ReviewQueue";
 import MomentDetail from "./pages/MomentDetail";
+import AdminReports from "./pages/AdminReports";
 import ModeToggle from "./components/ModeToggle";
 
 export default function App() {
@@ -21,7 +22,8 @@ export default function App() {
             <Link to="/">Home</Link>
             <Link to="/topics">Topics</Link>
             <Link to="/creators">Creators</Link>
-            <Link to="/admin/review">Admin</Link>
+            <Link to="/admin/review">Review</Link>
+            <Link to="/admin/reports">Reports</Link>
           </nav>
           <ModeToggle />
         </div>
@@ -42,6 +44,7 @@ export default function App() {
           {/* Admin routes */}
           <Route path="/admin/review" element={<ReviewQueue />} />
           <Route path="/admin/review/:momentId" element={<MomentDetail />} />
+          <Route path="/admin/reports" element={<AdminReports />} />
 
           {/* Fallback */}
           <Route path="*" element={<Navigate to="/" replace />} />
diff --git a/frontend/src/api/public-client.ts b/frontend/src/api/public-client.ts
index 47ecdd0..d7acce0 100644
--- a/frontend/src/api/public-client.ts
+++ b/frontend/src/api/public-client.ts
@@ -272,3 +272,72 @@ export async function fetchCreator(
 ): Promise<CreatorDetailResponse> {
   return request<CreatorDetailResponse>(`${BASE}/creators/${slug}`);
 }
+
+
+// ── Content Reports ─────────────────────────────────────────────────────────
+
+export interface ContentReportCreate {
+  content_type: string;
+  content_id?: string | null;
+  content_title?: string | null;
+  report_type: string;
+  description: string;
+  page_url?: string | null;
+}
+
+export interface ContentReport {
+  id: string;
+  content_type: string;
+  content_id: string | null;
+  content_title: string | null;
+  report_type: string;
+  description: string;
+  status: string;
+  admin_notes: string | null;
+  page_url: string | null;
+  created_at: string;
+  resolved_at: string | null;
+}
+
+export interface ContentReportListResponse {
+  items: ContentReport[];
+  total: number;
+  offset: number;
+  limit: number;
+}
+
+export async function submitReport(
+  body: ContentReportCreate,
+): Promise<ContentReport> {
+  return request<ContentReport>(`${BASE}/reports`, {
+    method: "POST",
+    body: JSON.stringify(body),
+  });
+}
+
+export async function fetchReports(params: {
+  status?: string;
+  content_type?: string;
+  offset?: number;
+  limit?: number;
+} = {}): Promise<ContentReportListResponse> {
+  const qs = new URLSearchParams();
+  if (params.status) qs.set("status", params.status);
+  if (params.content_type) qs.set("content_type", params.content_type);
+  if (params.offset !== undefined) qs.set("offset", String(params.offset));
+  if (params.limit !== undefined) qs.set("limit", String(params.limit));
+  const query = qs.toString();
+  return request<ContentReportListResponse>(
+    `${BASE}/admin/reports${query ? `?${query}` : ""}`,
+  );
+}
+
+export async function updateReport(
+  id: string,
+  body: { status?: string; admin_notes?: string },
+): Promise<ContentReport> {
+  return request<ContentReport>(`${BASE}/admin/reports/${id}`, {
+    method: "PATCH",
+    body: JSON.stringify(body),
+  });
+}
diff --git a/frontend/src/components/ReportIssueModal.tsx b/frontend/src/components/ReportIssueModal.tsx
new file mode 100644
index 0000000..c5be1e2
--- /dev/null
+++ b/frontend/src/components/ReportIssueModal.tsx
@@ -0,0 +1,135 @@
+import { useState } from "react";
+import { submitReport, type ContentReportCreate } from "../api/public-client";
+
+interface ReportIssueModalProps {
+  contentType: string;
+  contentId?: string | null;
+  contentTitle?: string | null;
+  onClose: () => void;
+}
+
+const REPORT_TYPES = [
+  { value: "inaccurate", label: "Inaccurate content" },
+  { value: "missing_info", label: "Missing information" },
+  { value: "wrong_attribution", label: "Wrong attribution" },
+  { value: "formatting", label: "Formatting issue" },
+  { value: "other", label: "Other" },
+];
+
+export default function ReportIssueModal({
+  contentType,
+  contentId,
+  contentTitle,
+  onClose,
+}: ReportIssueModalProps) {
+  const [reportType, setReportType] = useState("inaccurate");
+  const [description, setDescription] = useState("");
+  const [submitting, setSubmitting] = useState(false);
+  const [submitted, setSubmitted] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+
+  const handleSubmit = async (e: React.FormEvent) => {
+    e.preventDefault();
+    if (description.trim().length < 10) {
+      setError("Please provide at least 10 characters describing the issue.");
+      return;
+    }
+
+    setSubmitting(true);
+    setError(null);
+
+    try {
+      const body: ContentReportCreate = {
+        content_type: contentType,
+        content_id: contentId ?? null,
+        content_title: contentTitle ?? null,
+        report_type: reportType,
+        description: description.trim(),
+        page_url: window.location.href,
+      };
+      await submitReport(body);
+      setSubmitted(true);
+    } catch (err) {
+      setError(
+        err instanceof Error ? err.message : "Failed to submit report",
+      );
+    } finally {
+      setSubmitting(false);
+    }
+  };
+
+  return (
+    <div className="modal-overlay" onClick={onClose}>
+      <div className="modal-content report-modal" onClick={(e) => e.stopPropagation()}>
+        {submitted ? (
+          <>
+            <h3 className="report-modal__title">Thank you</h3>
+            <p className="report-modal__success">
+              Your report has been submitted. We'll review it shortly.
+            </p>
+            <button className="btn btn--primary" onClick={onClose}>
+              Close
+            </button>
+          </>
+        ) : (
+          <>
+            <h3 className="report-modal__title">Report an issue</h3>
+            {contentTitle && (
+              <p className="report-modal__context">
+                About: <strong>{contentTitle}</strong>
+              </p>
+            )}
+            <form onSubmit={handleSubmit}>
+              <label className="report-modal__label">
+                Issue type
+                <select
+                  className="report-modal__select"
+                  value={reportType}
+                  onChange={(e) => setReportType(e.target.value)}
+                >
+                  {REPORT_TYPES.map((t) => (
+                    <option key={t.value} value={t.value}>
+                      {t.label}
+                    </option>
+                  ))}
+                </select>
+              </label>
+
+              <label className="report-modal__label">
+                Description
+                <textarea
+                  className="report-modal__textarea"
+                  value={description}
+                  onChange={(e) => setDescription(e.target.value)}
+                  placeholder="Describe the issue…"
+                  rows={4}
+                  maxLength={2000}
+                />
+              </label>
+
+              {error && <p className="report-modal__error">{error}</p>}
+
+              <div className="report-modal__actions">
+                <button
+                  type="button"
+                  className="btn btn--secondary"
+                  onClick={onClose}
+                  disabled={submitting}
+                >
+                  Cancel
+                </button>
+                <button
+                  type="submit"
+                  className="btn btn--primary"
+                  disabled={submitting || description.trim().length < 10}
+                >
+                  {submitting ? "Submitting…" : "Submit report"}
+                </button>
+              </div>
+            </form>
+          </>
+        )}
+      </div>
+    </div>
+  );
+}
diff --git a/frontend/src/pages/AdminReports.tsx b/frontend/src/pages/AdminReports.tsx
new file mode 100644
index 0000000..166cfdb
--- /dev/null
+++ b/frontend/src/pages/AdminReports.tsx
@@ -0,0 +1,246 @@
+/**
+ * Admin content reports management page.
+ *
+ * Lists user-submitted issue reports with filtering by status,
+ * inline triage (acknowledge/resolve/dismiss), and admin notes.
+ */
+
+import { useEffect, useState } from "react";
+import {
+  fetchReports,
+  updateReport,
+  type ContentReport,
+} from "../api/public-client";
+
+const STATUS_OPTIONS = [
+  { value: "", label: "All" },
+  { value: "open", label: "Open" },
+  { value: "acknowledged", label: "Acknowledged" },
+  { value: "resolved", label: "Resolved" },
+  { value: "dismissed", label: "Dismissed" },
+];
+
+const STATUS_ACTIONS: Record<string, { label: string; next: string }[]> = {
+  open: [
+    { label: "Acknowledge", next: "acknowledged" },
+    { label: "Resolve", next: "resolved" },
+    { label: "Dismiss", next: "dismissed" },
+  ],
+  acknowledged: [
+    { label: "Resolve", next: "resolved" },
+    { label: "Dismiss", next: "dismissed" },
+    { label: "Reopen", next: "open" },
+  ],
+  resolved: [{ label: "Reopen", next: "open" }],
+  dismissed: [{ label: "Reopen", next: "open" }],
+};
+
+function formatDate(iso: string): string {
+  return new Date(iso).toLocaleString(undefined, {
+    month: "short",
+    day: "numeric",
+    hour: "2-digit",
+    minute: "2-digit",
+  });
+}
+
+function reportTypeLabel(rt: string): string {
+  return rt.replace(/_/g, " ").replace(/^\w/, (c) => c.toUpperCase());
+}
+
+export default function AdminReports() {
+  const [reports, setReports] = useState<ContentReport[]>([]);
+  const [total, setTotal] = useState(0);
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState<string | null>(null);
+  const [statusFilter, setStatusFilter] = useState("");
+  const [expandedId, setExpandedId] = useState<string | null>(null);
+  const [noteText, setNoteText] = useState("");
+  const [actionLoading, setActionLoading] = useState<string | null>(null);
+
+  const load = async () => {
+    setLoading(true);
+    setError(null);
+    try {
+      const res = await fetchReports({
+        status: statusFilter || undefined,
+        limit: 100,
+      });
+      setReports(res.items);
+      setTotal(res.total);
+    } catch (err) {
+      setError(err instanceof Error ? err.message : "Failed to load reports");
+    } finally {
+      setLoading(false);
+    }
+  };
+
+  useEffect(() => {
+    void load();
+  }, [statusFilter]);
+
+  const handleAction = async (reportId: string, newStatus: string) => {
+    setActionLoading(reportId);
+    try {
+      const updated = await updateReport(reportId, {
+        status: newStatus,
+        ...(noteText.trim() ? { admin_notes: noteText.trim() } : {}),
+      });
+      setReports((prev) =>
+        prev.map((r) => (r.id === reportId ? updated : r)),
+      );
+      setNoteText("");
+      if (newStatus === "resolved" || newStatus === "dismissed") {
+        setExpandedId(null);
+      }
+    } catch (err) {
+      setError(err instanceof Error ? err.message : "Action failed");
+    } finally {
+      setActionLoading(null);
+    }
+  };
+
+  const toggleExpand = (id: string) => {
+    if (expandedId === id) {
+      setExpandedId(null);
+      setNoteText("");
+    } else {
+      setExpandedId(id);
+      const report = reports.find((r) => r.id === id);
+      setNoteText(report?.admin_notes ?? "");
+    }
+  };
+
+  return (
+    <div className="admin-reports">
+      <h2 className="admin-reports__title">Content Reports</h2>
+      <p className="admin-reports__subtitle">
+        {total} report{total !== 1 ? "s" : ""} total
+      </p>
+
+      {/* Status filter */}
+      <div className="admin-reports__filters">
+        <div className="sort-toggle" role="group" aria-label="Filter by status">
+          {STATUS_OPTIONS.map((opt) => (
+            <button
+              key={opt.value}
+              className={`sort-toggle__btn${statusFilter === opt.value ? " sort-toggle__btn--active" : ""}`}
+              onClick={() => setStatusFilter(opt.value)}
+              aria-pressed={statusFilter === opt.value}
+            >
+              {opt.label}
+            </button>
+          ))}
+        </div>
+      </div>
+
+      {/* Content */}
+      {loading ? (
+        <div className="loading">Loading reports…</div>
+      ) : error ? (
+        <div className="loading error-text">Error: {error}</div>
+      ) : reports.length === 0 ? (
+        <div className="empty-state">
+          {statusFilter ? `No ${statusFilter} reports.` : "No reports yet."}
+        </div>
+      ) : (
+        <div className="admin-reports__list">
+          {reports.map((report) => (
+            <div
+              key={report.id}
+              className={`report-card report-card--${report.status}`}
+            >
+              <div
+                className="report-card__header"
+                onClick={() => toggleExpand(report.id)}
+              >
+                <div className="report-card__meta">
+                  <span className={`pill pill--${report.status}`}>
+                    {report.status}
+                  </span>
+                  <span className="pill">{reportTypeLabel(report.report_type)}</span>
+                  <span className="report-card__date">
+                    {formatDate(report.created_at)}
+                  </span>
+                </div>
+                <div className="report-card__summary">
+                  {report.content_title && (
+                    <span className="report-card__content-title">
+                      {report.content_title}
+                    </span>
+                  )}
+                  <span className="report-card__description">
+                    {report.description.length > 120
+                      ? report.description.slice(0, 120) + "…"
+                      : report.description}
+                  </span>
+                </div>
+              </div>
+
+              {expandedId === report.id && (
+                <div className="report-card__detail">
+                  <div className="report-card__full-description">
+                    <strong>Full description:</strong>
+                    <p>{report.description}</p>
+                  </div>
+
+                  {report.page_url && (
+                    <div className="report-card__url">
+                      <strong>Page:</strong>{" "}
+                      <a href={report.page_url} target="_blank" rel="noopener noreferrer">
+                        {report.page_url}
+                      </a>
+                    </div>
+                  )}
+
+                  <div className="report-card__info-row">
+                    <span>Type: {report.content_type}</span>
+                    {report.content_id && <span>ID: {report.content_id.slice(0, 8)}…</span>}
+                    {report.resolved_at && (
+                      <span>Resolved: {formatDate(report.resolved_at)}</span>
+                    )}
+                  </div>
+
+                  {/* Admin notes */}
+                  <label className="report-card__notes-label">
+                    Admin notes:
+                    <textarea
+                      className="report-card__notes"
+                      value={noteText}
+                      onChange={(e) => setNoteText(e.target.value)}
+                      rows={2}
+                      placeholder="Add notes…"
+                    />
+                  </label>
+
+                  {/* Action buttons */}
+                  <div className="report-card__actions">
+                    {(STATUS_ACTIONS[report.status] ?? []).map((action) => (
+                      <button
+                        key={action.next}
+                        className={`btn btn--${action.next === "resolved" ? "primary" : action.next === "dismissed" ? "danger" : "secondary"}`}
+                        onClick={() => handleAction(report.id, action.next)}
+                        disabled={actionLoading === report.id}
+                      >
+                        {actionLoading === report.id ? "…" : action.label}
+                      </button>
+                    ))}
+                    {noteText !== (report.admin_notes ?? "") && (
+                      <button
+                        className="btn btn--secondary"
+                        onClick={() => handleAction(report.id, report.status)}
+                        disabled={actionLoading === report.id}
+                      >
+                        Save notes
+                      </button>
+                    )}
+                  </div>
+                </div>
+              )}
+            </div>
+          ))}
+        </div>
+      )}
+    </div>
+  );
+}
diff --git a/frontend/src/pages/TechniquePage.tsx b/frontend/src/pages/TechniquePage.tsx
index 2487291..9b8f80b 100644
--- a/frontend/src/pages/TechniquePage.tsx
+++ b/frontend/src/pages/TechniquePage.tsx
@@ -18,6 +18,7 @@ import {
   fetchTechnique,
   type TechniquePageDetail as TechniqueDetail,
 } from "../api/public-client";
+import ReportIssueModal from "../components/ReportIssueModal";
 
 function formatTime(seconds: number): string {
   const m = Math.floor(seconds / 60);
@@ -31,6 +32,7 @@ export default function TechniquePage() {
   const [loading, setLoading] = useState(true);
   const [notFound, setNotFound] = useState(false);
   const [error, setError] = useState<string | null>(null);
+  const [showReport, setShowReport] = useState(false);
 
   useEffect(() => {
     if (!slug) return;
@@ -164,8 +166,25 @@ export default function TechniquePage() {
             return parts.join(" · ");
           })()}
         </div>
+        {/* Report issue button */}
+        <button
+          className="btn btn--secondary btn--small report-issue-btn"
+          onClick={() => setShowReport(true)}
+        >
+          ⚑ Report issue
+        </button>
       </header>
 
+      {/* Report modal */}
+      {showReport && (
+        <ReportIssueModal
+          contentType="technique_page"
+          contentId={technique.id}
+          contentTitle={technique.title}
+          onClose={() => setShowReport(false)}
+        />
+      )}
+
       {/* Summary */}
       {technique.summary && (
         <section className="technique-summary">

From b3204bece90c7c2af38c6f32036f906946bebac9 Mon Sep 17 00:00:00 2001
From: jlightner <jlightner@ub01.a.xpltd.co>
Date: Mon, 30 Mar 2026 03:02:31 -0500
Subject: [PATCH 2/8] =?UTF-8?q?feat:=20Version=20switcher=20on=20technique?=
 =?UTF-8?q?=20pages=20=E2=80=94=20view=20historical=20snapshots=20with=20p?=
 =?UTF-8?q?ipeline=20metadata?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Version dropdown appears when version_count > 0 (hidden until first re-run)
- Selecting a historical version overlays snapshot content (title, summary, body, chains, plugins)
- Key moments and related links always show live data (not versioned)
- Pipeline metadata block shows model, capture time, and prompt file hashes (truncated)
- Cyan banner when viewing historical version with "Back to current" button
- fetchTechniqueVersion API function for single version detail
---
 frontend/src/App.css                 | 129 ++++++++++++
 frontend/src/api/public-client.ts    |  16 ++
 frontend/src/pages/TechniquePage.tsx | 282 ++++++++++++++++++++++-----
 3 files changed, 379 insertions(+), 48 deletions(-)

diff --git a/frontend/src/App.css b/frontend/src/App.css
index 28925c8..2b64b2b 100644
--- a/frontend/src/App.css
+++ b/frontend/src/App.css
@@ -2261,3 +2261,132 @@ body {
   background: var(--color-bg-input);
   color: var(--color-text-muted);
 }
+
+/* ── Version Switcher ───────────────────────────────────────────────────── */
+
+.technique-header__actions {
+  display: flex;
+  align-items: center;
+  gap: 0.75rem;
+  margin-top: 0.5rem;
+  flex-wrap: wrap;
+}
+
+.version-switcher {
+  display: flex;
+  align-items: center;
+  gap: 0.4rem;
+}
+
+.version-switcher__label {
+  color: var(--color-text-muted);
+  font-size: 0.8rem;
+}
+
+.version-switcher__select {
+  background: var(--color-bg-input);
+  color: var(--color-text-primary);
+  border: 1px solid var(--color-border);
+  border-radius: 6px;
+  padding: 0.3rem 0.5rem;
+  font-size: 0.8rem;
+  cursor: pointer;
+}
+
+.version-switcher__select:focus {
+  outline: none;
+  border-color: var(--color-accent);
+}
+
+.version-switcher__loading {
+  color: var(--color-text-muted);
+  font-size: 0.75rem;
+  font-style: italic;
+}
+
+.technique-banner--version {
+  background: var(--color-accent-subtle);
+  border: 1px solid var(--color-accent);
+  border-radius: 8px;
+  padding: 0.6rem 1rem;
+  color: var(--color-accent);
+  font-size: 0.85rem;
+  display: flex;
+  align-items: center;
+  flex-wrap: wrap;
+  margin-bottom: 1rem;
+}
+
+/* ── Version Metadata ───────────────────────────────────────────────────── */
+
+.version-metadata {
+  background: var(--color-bg-surface);
+  border: 1px solid var(--color-border);
+  border-radius: 8px;
+  padding: 0.75rem 1rem;
+  margin-bottom: 1.5rem;
+}
+
+.version-metadata__title {
+  color: var(--color-text-secondary);
+  font-size: 0.8rem;
+  font-weight: 600;
+  margin: 0 0 0.5rem;
+  text-transform: uppercase;
+  letter-spacing: 0.04em;
+}
+
+.version-metadata__grid {
+  display: flex;
+  gap: 1.5rem;
+  flex-wrap: wrap;
+}
+
+.version-metadata__item {
+  display: flex;
+  flex-direction: column;
+  gap: 0.15rem;
+}
+
+.version-metadata__item--wide {
+  flex-basis: 100%;
+}
+
+.version-metadata__key {
+  color: var(--color-text-muted);
+  font-size: 0.75rem;
+  text-transform: uppercase;
+  letter-spacing: 0.03em;
+}
+
+.version-metadata__value {
+  color: var(--color-text-primary);
+  font-size: 0.85rem;
+}
+
+.version-metadata__hashes {
+  display: flex;
+  flex-direction: column;
+  gap: 0.2rem;
+  margin-top: 0.15rem;
+}
+
+.version-metadata__hash {
+  display: flex;
+  align-items: center;
+  gap: 0.5rem;
+  font-size: 0.8rem;
+}
+
+.version-metadata__hash-file {
+  color: var(--color-text-secondary);
+}
+
+.version-metadata__hash-value {
+  font-family: "SF Mono", "Fira Code", monospace;
+  color: var(--color-text-muted);
+  font-size: 0.75rem;
+  background: var(--color-bg-input);
+  padding: 0.1rem 0.35rem;
+  border-radius: 3px;
+}
diff --git a/frontend/src/api/public-client.ts b/frontend/src/api/public-client.ts
index d7acce0..7683819 100644
--- a/frontend/src/api/public-client.ts
+++ b/frontend/src/api/public-client.ts
@@ -82,6 +82,13 @@ export interface TechniquePageVersionListResponse {
   total: number;
 }
 
+export interface TechniquePageVersionDetail {
+  version_number: number;
+  content_snapshot: Record<string, unknown>;
+  pipeline_metadata: Record<string, unknown> | null;
+  created_at: string;
+}
+
 export interface TechniqueListItem {
   id: string;
   title: string;
@@ -238,6 +245,15 @@ export async function fetchTechniqueVersions(
   );
 }
 
+export async function fetchTechniqueVersion(
+  slug: string,
+  versionNumber: number,
+): Promise<TechniquePageVersionDetail> {
+  return request<TechniquePageVersionDetail>(
+    `${BASE}/techniques/${slug}/versions/${versionNumber}`,
+  );
+}
+
 // ── Topics ───────────────────────────────────────────────────────────────────
 
 export async function fetchTopics(): Promise<TopicCategory[]> {
diff --git a/frontend/src/pages/TechniquePage.tsx b/frontend/src/pages/TechniquePage.tsx
index 9b8f80b..43bfe45 100644
--- a/frontend/src/pages/TechniquePage.tsx
+++ b/frontend/src/pages/TechniquePage.tsx
@@ -1,22 +1,20 @@
 /**
- * Technique page detail view.
+ * Technique page detail view with version switching.
  *
- * Fetches a single technique by slug. Renders:
- * - Header with title, category badge, tags, creator link, source quality
- * - Amber banner for unstructured (livestream-sourced) content
- * - Study guide prose from body_sections JSONB
- * - Key moments index
- * - Signal chains (if present)
- * - Plugins referenced (if present)
- * - Related techniques (if present)
- * - Loading and 404 states
+ * Fetches a single technique by slug. When historical versions exist,
+ * shows a version switcher that lets admins view previous snapshots
+ * with pipeline metadata (prompt hashes, model config).
  */
 
 import { useEffect, useState } from "react";
 import { Link, useParams } from "react-router-dom";
 import {
   fetchTechnique,
+  fetchTechniqueVersions,
+  fetchTechniqueVersion,
   type TechniquePageDetail as TechniqueDetail,
+  type TechniquePageVersionSummary,
+  type TechniquePageVersionDetail,
 } from "../api/public-client";
 import ReportIssueModal from "../components/ReportIssueModal";
 
@@ -26,6 +24,45 @@ function formatTime(seconds: number): string {
   return `${m}:${s.toString().padStart(2, "0")}`;
 }
 
+function formatDate(iso: string): string {
+  return new Date(iso).toLocaleDateString("en-US", {
+    year: "numeric",
+    month: "short",
+    day: "numeric",
+    hour: "2-digit",
+    minute: "2-digit",
+  });
+}
+
+/** Extract the displayable fields from a version snapshot, matching TechniqueDetail shape. */
+function snapshotToOverlay(snapshot: Record<string, unknown>) {
+  return {
+    title: typeof snapshot.title === "string" ? snapshot.title : undefined,
+    summary: typeof snapshot.summary === "string" ? snapshot.summary : undefined,
+    topic_category:
+      typeof snapshot.topic_category === "string"
+        ? snapshot.topic_category
+        : undefined,
+    topic_tags: Array.isArray(snapshot.topic_tags)
+      ? (snapshot.topic_tags as string[])
+      : undefined,
+    body_sections:
+      typeof snapshot.body_sections === "object" && snapshot.body_sections !== null
+        ? (snapshot.body_sections as Record<string, unknown>)
+        : undefined,
+    signal_chains: Array.isArray(snapshot.signal_chains)
+      ? (snapshot.signal_chains as unknown[])
+      : undefined,
+    plugins: Array.isArray(snapshot.plugins)
+      ? (snapshot.plugins as string[])
+      : undefined,
+    source_quality:
+      typeof snapshot.source_quality === "string"
+        ? snapshot.source_quality
+        : undefined,
+  };
+}
+
 export default function TechniquePage() {
   const { slug } = useParams<{ slug: string }>();
   const [technique, setTechnique] = useState<TechniqueDetail | null>(null);
@@ -34,6 +71,14 @@ export default function TechniquePage() {
   const [error, setError] = useState<string | null>(null);
   const [showReport, setShowReport] = useState(false);
 
+  // Version switching
+  const [versions, setVersions] = useState<TechniquePageVersionSummary[]>([]);
+  const [selectedVersion, setSelectedVersion] = useState<string>("current");
+  const [versionDetail, setVersionDetail] =
+    useState<TechniquePageVersionDetail | null>(null);
+  const [versionLoading, setVersionLoading] = useState(false);
+
+  // Load technique + version list
   useEffect(() => {
     if (!slug) return;
 
@@ -41,17 +86,28 @@ export default function TechniquePage() {
     setLoading(true);
     setNotFound(false);
     setError(null);
+    setSelectedVersion("current");
+    setVersionDetail(null);
+    setVersions([]);
 
     void (async () => {
       try {
         const data = await fetchTechnique(slug);
-        if (!cancelled) setTechnique(data);
+        if (!cancelled) {
+          setTechnique(data);
+          // Load versions if any exist
+          if (data.version_count > 0) {
+            try {
+              const vRes = await fetchTechniqueVersions(slug);
+              if (!cancelled) setVersions(vRes.items);
+            } catch {
+              // Non-critical — version list fails silently
+            }
+          }
+        }
       } catch (err) {
         if (!cancelled) {
-          if (
-            err instanceof Error &&
-            err.message.includes("404")
-          ) {
+          if (err instanceof Error && err.message.includes("404")) {
             setNotFound(true);
           } else {
             setError(
@@ -69,6 +125,35 @@ export default function TechniquePage() {
     };
   }, [slug]);
 
+  // Load version detail when selection changes
+  useEffect(() => {
+    if (!slug || selectedVersion === "current") {
+      setVersionDetail(null);
+      return;
+    }
+
+    let cancelled = false;
+    setVersionLoading(true);
+
+    void (async () => {
+      try {
+        const detail = await fetchTechniqueVersion(
+          slug,
+          Number(selectedVersion),
+        );
+        if (!cancelled) setVersionDetail(detail);
+      } catch {
+        if (!cancelled) setVersionDetail(null);
+      } finally {
+        if (!cancelled) setVersionLoading(false);
+      }
+    })();
+
+    return () => {
+      cancelled = true;
+    };
+  }, [slug, selectedVersion]);
+
   if (loading) {
     return <div className="loading">Loading technique…</div>;
   }
@@ -77,7 +162,7 @@ export default function TechniquePage() {
     return (
       <div className="technique-404">
         <h2>Technique Not Found</h2>
-        <p>The technique "{slug}" doesn't exist.</p>
+        <p>The technique &ldquo;{slug}&rdquo; doesn&rsquo;t exist.</p>
         <Link to="/" className="btn">
           Back to Home
         </Link>
@@ -93,6 +178,21 @@ export default function TechniquePage() {
     );
   }
 
+  // Overlay snapshot fields when viewing a historical version
+  const isHistorical = selectedVersion !== "current" && versionDetail != null;
+  const overlay = isHistorical
+    ? snapshotToOverlay(versionDetail.content_snapshot)
+    : null;
+
+  const displayTitle = overlay?.title ?? technique.title;
+  const displaySummary = overlay?.summary ?? technique.summary;
+  const displayCategory = overlay?.topic_category ?? technique.topic_category;
+  const displayTags = overlay?.topic_tags ?? technique.topic_tags;
+  const displaySections = overlay?.body_sections ?? technique.body_sections;
+  const displayChains = overlay?.signal_chains ?? technique.signal_chains;
+  const displayPlugins = overlay?.plugins ?? technique.plugins;
+  const displayQuality = overlay?.source_quality ?? technique.source_quality;
+
   return (
     <article className="technique-page">
       {/* Back link */}
@@ -100,8 +200,23 @@ export default function TechniquePage() {
         ← Back
       </Link>
 
+      {/* Historical version banner */}
+      {isHistorical && (
+        <div className="technique-banner technique-banner--version">
+          📋 Viewing version {versionDetail.version_number} from{" "}
+          {formatDate(versionDetail.created_at)}
+          <button
+            className="btn btn--small btn--primary"
+            style={{ marginLeft: "1rem" }}
+            onClick={() => setSelectedVersion("current")}
+          >
+            Back to current
+          </button>
+        </div>
+      )}
+
       {/* Unstructured content warning */}
-      {technique.source_quality === "unstructured" && (
+      {displayQuality === "unstructured" && (
         <div className="technique-banner technique-banner--amber">
           ⚠ This technique was sourced from a livestream and may have less
           structured content.
@@ -110,14 +225,12 @@ export default function TechniquePage() {
 
       {/* Header */}
       <header className="technique-header">
-        <h1 className="technique-header__title">{technique.title}</h1>
+        <h1 className="technique-header__title">{displayTitle}</h1>
         <div className="technique-header__meta">
-          <span className="badge badge--category">
-            {technique.topic_category}
-          </span>
-          {technique.topic_tags && technique.topic_tags.length > 0 && (
+          <span className="badge badge--category">{displayCategory}</span>
+          {displayTags && displayTags.length > 0 && (
             <span className="technique-header__tags">
-              {technique.topic_tags.map((tag) => (
+              {displayTags.map((tag) => (
                 <span key={tag} className="pill">
                   {tag}
                 </span>
@@ -132,14 +245,15 @@ export default function TechniquePage() {
               by {technique.creator_info.name}
             </Link>
           )}
-          {technique.source_quality && (
+          {displayQuality && (
             <span
-              className={`badge badge--quality badge--quality-${technique.source_quality}`}
+              className={`badge badge--quality badge--quality-${displayQuality}`}
             >
-              {technique.source_quality}
+              {displayQuality}
             </span>
           )}
         </div>
+
         {/* Meta stats line */}
         <div className="technique-header__stats">
           {(() => {
@@ -166,15 +280,87 @@ export default function TechniquePage() {
             return parts.join(" · ");
           })()}
         </div>
-        {/* Report issue button */}
-        <button
-          className="btn btn--secondary btn--small report-issue-btn"
-          onClick={() => setShowReport(true)}
-        >
-          ⚑ Report issue
-        </button>
+
+        {/* Version switcher + report button row */}
+        <div className="technique-header__actions">
+          {versions.length > 0 && (
+            <div className="version-switcher">
+              <label className="version-switcher__label">Version:</label>
+              <select
+                className="version-switcher__select"
+                value={selectedVersion}
+                onChange={(e) => setSelectedVersion(e.target.value)}
+                disabled={versionLoading}
+              >
+                <option value="current">Current (live)</option>
+                {versions.map((v) => (
+                  <option key={v.version_number} value={String(v.version_number)}>
+                    v{v.version_number} — {formatDate(v.created_at)}
+                  </option>
+                ))}
+              </select>
+              {versionLoading && (
+                <span className="version-switcher__loading">Loading…</span>
+              )}
+            </div>
+          )}
+          <button
+            className="btn btn--secondary btn--small report-issue-btn"
+            onClick={() => setShowReport(true)}
+          >
+            ⚑ Report issue
+          </button>
+        </div>
       </header>
 
+      {/* Pipeline metadata for historical versions */}
+      {isHistorical && versionDetail.pipeline_metadata && (
+        <div className="version-metadata">
+          <h4 className="version-metadata__title">Pipeline metadata (v{versionDetail.version_number})</h4>
+          <div className="version-metadata__grid">
+            {"model" in versionDetail.pipeline_metadata && (
+              <div className="version-metadata__item">
+                <span className="version-metadata__key">Model</span>
+                <span className="version-metadata__value">
+                  {String(versionDetail.pipeline_metadata.model)}
+                </span>
+              </div>
+            )}
+            {"captured_at" in versionDetail.pipeline_metadata && (
+              <div className="version-metadata__item">
+                <span className="version-metadata__key">Captured</span>
+                <span className="version-metadata__value">
+                  {formatDate(String(versionDetail.pipeline_metadata.captured_at))}
+                </span>
+              </div>
+            )}
+            {typeof versionDetail.pipeline_metadata.prompt_hashes === "object" &&
+              versionDetail.pipeline_metadata.prompt_hashes !== null && (
+                <div className="version-metadata__item version-metadata__item--wide">
+                  <span className="version-metadata__key">Prompt hashes</span>
+                  <div className="version-metadata__hashes">
+                    {Object.entries(
+                      versionDetail.pipeline_metadata.prompt_hashes as Record<
+                        string,
+                        string
+                      >,
+                    ).map(([file, hash]) => (
+                      <div key={file} className="version-metadata__hash">
+                        <span className="version-metadata__hash-file">
+                          {file.replace(/^.*\//, "")}
+                        </span>
+                        <code className="version-metadata__hash-value">
+                          {hash.slice(0, 12)}…
+                        </code>
+                      </div>
+                    ))}
+                  </div>
+                </div>
+              )}
+          </div>
+        </div>
+      )}
+
       {/* Report modal */}
       {showReport && (
         <ReportIssueModal
@@ -186,28 +372,28 @@ export default function TechniquePage() {
       )}
 
       {/* Summary */}
-      {technique.summary && (
+      {displaySummary && (
         <section className="technique-summary">
-          <p>{technique.summary}</p>
+          <p>{displaySummary}</p>
         </section>
       )}
 
       {/* Study guide prose — body_sections */}
-      {technique.body_sections &&
-        Object.keys(technique.body_sections).length > 0 && (
+      {displaySections &&
+        Object.keys(displaySections).length > 0 && (
           <section className="technique-prose">
-            {Object.entries(technique.body_sections).map(
-              ([sectionTitle, content]) => (
+            {Object.entries(displaySections).map(
+              ([sectionTitle, content]: [string, unknown]) => (
                 <div key={sectionTitle} className="technique-prose__section">
                   <h2>{sectionTitle}</h2>
                   {typeof content === "string" ? (
-                    <p>{content}</p>
+                    <p>{content as string}</p>
                   ) : typeof content === "object" && content !== null ? (
                     <pre className="technique-prose__json">
                       {JSON.stringify(content, null, 2)}
                     </pre>
                   ) : (
-                    <p>{String(content)}</p>
+                    <p>{String(content as string)}</p>
                   )}
                 </div>
               ),
@@ -215,7 +401,7 @@ export default function TechniquePage() {
           </section>
         )}
 
-      {/* Key moments */}
+      {/* Key moments (always from live data — not versioned) */}
       {technique.key_moments.length > 0 && (
         <section className="technique-moments">
           <h2>Key Moments</h2>
@@ -244,11 +430,11 @@ export default function TechniquePage() {
       )}
 
       {/* Signal chains */}
-      {technique.signal_chains &&
-        technique.signal_chains.length > 0 && (
+      {displayChains &&
+        displayChains.length > 0 && (
           <section className="technique-chains">
             <h2>Signal Chains</h2>
-            {technique.signal_chains.map((chain, i) => {
+            {displayChains.map((chain, i) => {
               const chainObj = chain as Record<string, unknown>;
               const chainName =
                 typeof chainObj["name"] === "string"
@@ -283,11 +469,11 @@ export default function TechniquePage() {
         )}
 
       {/* Plugins */}
-      {technique.plugins && technique.plugins.length > 0 && (
+      {displayPlugins && displayPlugins.length > 0 && (
         <section className="technique-plugins">
           <h2>Plugins Referenced</h2>
           <div className="pill-list">
-            {technique.plugins.map((plugin) => (
+            {displayPlugins.map((plugin) => (
               <span key={plugin} className="pill pill--plugin">
                 {plugin}
               </span>
@@ -296,7 +482,7 @@ export default function TechniquePage() {
         </section>
       )}
 
-      {/* Related techniques */}
+      {/* Related techniques (always from live data) */}
       {technique.related_links.length > 0 && (
         <section className="technique-related">
           <h2>Related Techniques</h2>

From df33d1536034641b778da2a2f8682d28f026d623 Mon Sep 17 00:00:00 2001
From: jlightner <jlightner@ub01.a.xpltd.co>
Date: Mon, 30 Mar 2026 05:55:07 -0500
Subject: [PATCH 3/8] feat: Pipeline events, admin dashboard, and version
 switcher UI
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Add pipeline_events table (migration 004) for structured stage logging
- Add PipelineEvent model with token usage tracking
- Admin pipeline dashboard with video list, event log, worker status,
  trigger/revoke controls, and collapsible JSON payload viewer
- Version switcher on technique pages — view historical snapshots
  with pipeline metadata (model names, prompt hashes)
- Frontend types for pipeline admin and version APIs

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 alembic/versions/004_pipeline_events.py |  37 +++
 backend/models.py                       |  34 ++
 backend/routers/pipeline.py             | 255 +++++++++++++-
 frontend/src/App.css                    | 403 +++++++++++++++++++++-
 frontend/src/App.tsx                    |   3 +
 frontend/src/api/public-client.ts       | 111 +++++++
 frontend/src/pages/AdminPipeline.tsx    | 422 ++++++++++++++++++++++++
 frontend/src/pages/TechniquePage.tsx    |  10 +-
 frontend/tsconfig.app.tsbuildinfo       |   2 +-
 9 files changed, 1255 insertions(+), 22 deletions(-)
 create mode 100644 alembic/versions/004_pipeline_events.py
 create mode 100644 frontend/src/pages/AdminPipeline.tsx

diff --git a/alembic/versions/004_pipeline_events.py b/alembic/versions/004_pipeline_events.py
new file mode 100644
index 0000000..25de8bc
--- /dev/null
+++ b/alembic/versions/004_pipeline_events.py
@@ -0,0 +1,37 @@
+"""Create pipeline_events table.
+
+Revision ID: 004_pipeline_events
+Revises: 003_content_reports
+"""
+from alembic import op
+import sqlalchemy as sa
+from sqlalchemy.dialects.postgresql import UUID, JSONB
+
+revision = "004_pipeline_events"
+down_revision = "003_content_reports"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.create_table(
+        "pipeline_events",
+        sa.Column("id", UUID(as_uuid=True), primary_key=True, server_default=sa.func.gen_random_uuid()),
+        sa.Column("video_id", UUID(as_uuid=True), nullable=False, index=True),
+        sa.Column("stage", sa.String(50), nullable=False),
+        sa.Column("event_type", sa.String(30), nullable=False),
+        sa.Column("prompt_tokens", sa.Integer(), nullable=True),
+        sa.Column("completion_tokens", sa.Integer(), nullable=True),
+        sa.Column("total_tokens", sa.Integer(), nullable=True),
+        sa.Column("model", sa.String(100), nullable=True),
+        sa.Column("duration_ms", sa.Integer(), nullable=True),
+        sa.Column("payload", JSONB(), nullable=True),
+        sa.Column("created_at", sa.DateTime(), server_default=sa.func.now(), nullable=False),
+    )
+    # Composite index for event log queries (video + newest first)
+    op.create_index("ix_pipeline_events_video_created", "pipeline_events", ["video_id", "created_at"])
+
+
+def downgrade() -> None:
+    op.drop_index("ix_pipeline_events_video_created")
+    op.drop_table("pipeline_events")
diff --git a/backend/models.py b/backend/models.py
index 3935cad..714e9bd 100644
--- a/backend/models.py
+++ b/backend/models.py
@@ -142,6 +142,7 @@ class SourceVideo(Base):
         nullable=False,
     )
     transcript_path: Mapped[str | None] = mapped_column(String(1000), nullable=True)
+    content_hash: Mapped[str | None] = mapped_column(String(64), nullable=True, index=True)
     processing_status: Mapped[ProcessingStatus] = mapped_column(
         Enum(ProcessingStatus, name="processing_status", create_constraint=True),
         default=ProcessingStatus.pending,
@@ -378,3 +379,36 @@ class ContentReport(Base):
         default=_now, server_default=func.now()
     )
     resolved_at: Mapped[datetime | None] = mapped_column(nullable=True)
+
+
+# ── Pipeline Event ───────────────────────────────────────────────────────────
+
+class PipelineEvent(Base):
+    """Structured log entry for pipeline execution.
+
+    Captures per-stage start/complete/error/llm_call events with
+    token usage and optional response payloads for debugging.
+    """
+    __tablename__ = "pipeline_events"
+
+    id: Mapped[uuid.UUID] = _uuid_pk()
+    video_id: Mapped[uuid.UUID] = mapped_column(
+        UUID(as_uuid=True), nullable=False, index=True,
+    )
+    stage: Mapped[str] = mapped_column(
+        String(50), nullable=False, doc="stage2_segmentation, stage3_extraction, etc."
+    )
+    event_type: Mapped[str] = mapped_column(
+        String(30), nullable=False, doc="start, complete, error, llm_call"
+    )
+    prompt_tokens: Mapped[int | None] = mapped_column(Integer, nullable=True)
+    completion_tokens: Mapped[int | None] = mapped_column(Integer, nullable=True)
+    total_tokens: Mapped[int | None] = mapped_column(Integer, nullable=True)
+    model: Mapped[str | None] = mapped_column(String(100), nullable=True)
+    duration_ms: Mapped[int | None] = mapped_column(Integer, nullable=True)
+    payload: Mapped[dict | None] = mapped_column(
+        JSONB, nullable=True, doc="LLM response content, error details, stage metadata"
+    )
+    created_at: Mapped[datetime] = mapped_column(
+        default=_now, server_default=func.now()
+    )
diff --git a/backend/routers/pipeline.py b/backend/routers/pipeline.py
index a5b9367..52522f8 100644
--- a/backend/routers/pipeline.py
+++ b/backend/routers/pipeline.py
@@ -1,30 +1,40 @@
-"""Pipeline management endpoints for manual re-trigger and status inspection."""
+"""Pipeline management endpoints — public trigger + admin dashboard.
+
+Public:
+  POST /pipeline/trigger/{video_id}    Trigger pipeline for a video
+
+Admin:
+  GET  /admin/pipeline/videos          Video list with status + event counts
+  POST /admin/pipeline/trigger/{video_id}  Retrigger (same as public but under admin prefix)
+  POST /admin/pipeline/revoke/{video_id}   Revoke/cancel active tasks for a video
+  GET  /admin/pipeline/events/{video_id}   Event log for a video (paginated)
+  GET  /admin/pipeline/worker-status       Active/reserved tasks from Celery inspect
+"""
 
 import logging
+import uuid
+from typing import Annotated
 
-from fastapi import APIRouter, Depends, HTTPException
-from sqlalchemy import select
+from fastapi import APIRouter, Depends, HTTPException, Query
+from sqlalchemy import func, select, case
 from sqlalchemy.ext.asyncio import AsyncSession
 
 from database import get_session
-from models import SourceVideo
+from models import PipelineEvent, SourceVideo, Creator
 
 logger = logging.getLogger("chrysopedia.pipeline")
 
-router = APIRouter(prefix="/pipeline", tags=["pipeline"])
+router = APIRouter(tags=["pipeline"])
 
 
-@router.post("/trigger/{video_id}")
+# ── Public trigger ───────────────────────────────────────────────────────────
+
+@router.post("/pipeline/trigger/{video_id}")
 async def trigger_pipeline(
     video_id: str,
     db: AsyncSession = Depends(get_session),
 ):
-    """Manually trigger (or re-trigger) the LLM extraction pipeline for a video.
-
-    Looks up the SourceVideo by ID, dispatches ``run_pipeline.delay()``,
-    and returns the current processing status. Returns 404 if the video
-    does not exist.
-    """
+    """Manually trigger (or re-trigger) the LLM extraction pipeline for a video."""
     stmt = select(SourceVideo).where(SourceVideo.id == video_id)
     result = await db.execute(stmt)
     video = result.scalar_one_or_none()
@@ -32,16 +42,13 @@ async def trigger_pipeline(
     if video is None:
         raise HTTPException(status_code=404, detail=f"Video not found: {video_id}")
 
-    # Import inside handler to avoid circular import at module level
     from pipeline.stages import run_pipeline
 
     try:
         run_pipeline.delay(str(video.id))
         logger.info("Pipeline manually triggered for video_id=%s", video_id)
     except Exception as exc:
-        logger.warning(
-            "Failed to dispatch pipeline for video_id=%s: %s", video_id, exc
-        )
+        logger.warning("Failed to dispatch pipeline for video_id=%s: %s", video_id, exc)
         raise HTTPException(
             status_code=503,
             detail="Pipeline dispatch failed — Celery/Redis may be unavailable",
@@ -52,3 +59,219 @@ async def trigger_pipeline(
         "video_id": str(video.id),
         "current_processing_status": video.processing_status.value,
     }
+
+
+# ── Admin: Video list ────────────────────────────────────────────────────────
+
+@router.get("/admin/pipeline/videos")
+async def list_pipeline_videos(
+    db: AsyncSession = Depends(get_session),
+):
+    """List all videos with processing status and pipeline event counts."""
+    # Subquery for event counts per video
+    event_counts = (
+        select(
+            PipelineEvent.video_id,
+            func.count().label("event_count"),
+            func.sum(case(
+                (PipelineEvent.event_type == "llm_call", PipelineEvent.total_tokens),
+                else_=0
+            )).label("total_tokens_used"),
+            func.max(PipelineEvent.created_at).label("last_event_at"),
+        )
+        .group_by(PipelineEvent.video_id)
+        .subquery()
+    )
+
+    stmt = (
+        select(
+            SourceVideo.id,
+            SourceVideo.filename,
+            SourceVideo.processing_status,
+            SourceVideo.content_hash,
+            SourceVideo.created_at,
+            SourceVideo.updated_at,
+            Creator.name.label("creator_name"),
+            event_counts.c.event_count,
+            event_counts.c.total_tokens_used,
+            event_counts.c.last_event_at,
+        )
+        .join(Creator, SourceVideo.creator_id == Creator.id)
+        .outerjoin(event_counts, SourceVideo.id == event_counts.c.video_id)
+        .order_by(SourceVideo.updated_at.desc())
+    )
+
+    result = await db.execute(stmt)
+    rows = result.all()
+
+    return {
+        "items": [
+            {
+                "id": str(r.id),
+                "filename": r.filename,
+                "processing_status": r.processing_status.value if hasattr(r.processing_status, 'value') else str(r.processing_status),
+                "content_hash": r.content_hash,
+                "creator_name": r.creator_name,
+                "created_at": r.created_at.isoformat() if r.created_at else None,
+                "updated_at": r.updated_at.isoformat() if r.updated_at else None,
+                "event_count": r.event_count or 0,
+                "total_tokens_used": r.total_tokens_used or 0,
+                "last_event_at": r.last_event_at.isoformat() if r.last_event_at else None,
+            }
+            for r in rows
+        ],
+        "total": len(rows),
+    }
+
+
+# ── Admin: Retrigger ─────────────────────────────────────────────────────────
+
+@router.post("/admin/pipeline/trigger/{video_id}")
+async def admin_trigger_pipeline(
+    video_id: str,
+    db: AsyncSession = Depends(get_session),
+):
+    """Admin retrigger — same as public trigger."""
+    return await trigger_pipeline(video_id, db)
+
+
+# ── Admin: Revoke ────────────────────────────────────────────────────────────
+
+@router.post("/admin/pipeline/revoke/{video_id}")
+async def revoke_pipeline(video_id: str):
+    """Revoke/cancel active Celery tasks for a video.
+    
+    Uses Celery's revoke with terminate=True to kill running tasks.
+    This is best-effort — the task may have already completed.
+    """
+    from worker import celery_app
+    
+    try:
+        # Get active tasks and revoke any matching this video_id
+        inspector = celery_app.control.inspect()
+        active = inspector.active() or {}
+        revoked_count = 0
+        
+        for _worker, tasks in active.items():
+            for task in tasks:
+                task_args = task.get("args", [])
+                if task_args and str(task_args[0]) == video_id:
+                    celery_app.control.revoke(task["id"], terminate=True)
+                    revoked_count += 1
+                    logger.info("Revoked task %s for video_id=%s", task["id"], video_id)
+        
+        return {
+            "status": "revoked" if revoked_count > 0 else "no_active_tasks",
+            "video_id": video_id,
+            "tasks_revoked": revoked_count,
+        }
+    except Exception as exc:
+        logger.warning("Failed to revoke tasks for video_id=%s: %s", video_id, exc)
+        raise HTTPException(
+            status_code=503,
+            detail="Failed to communicate with Celery worker",
+        ) from exc
+
+
+# ── Admin: Event log ─────────────────────────────────────────────────────────
+
+@router.get("/admin/pipeline/events/{video_id}")
+async def list_pipeline_events(
+    video_id: str,
+    offset: Annotated[int, Query(ge=0)] = 0,
+    limit: Annotated[int, Query(ge=1, le=200)] = 100,
+    stage: Annotated[str | None, Query(description="Filter by stage name")] = None,
+    event_type: Annotated[str | None, Query(description="Filter by event type")] = None,
+    db: AsyncSession = Depends(get_session),
+):
+    """Get pipeline events for a video, newest first."""
+    stmt = select(PipelineEvent).where(PipelineEvent.video_id == video_id)
+    
+    if stage:
+        stmt = stmt.where(PipelineEvent.stage == stage)
+    if event_type:
+        stmt = stmt.where(PipelineEvent.event_type == event_type)
+    
+    # Count
+    count_stmt = select(func.count()).select_from(stmt.subquery())
+    total = (await db.execute(count_stmt)).scalar() or 0
+    
+    # Fetch
+    stmt = stmt.order_by(PipelineEvent.created_at.desc())
+    stmt = stmt.offset(offset).limit(limit)
+    result = await db.execute(stmt)
+    events = result.scalars().all()
+    
+    return {
+        "items": [
+            {
+                "id": str(e.id),
+                "video_id": str(e.video_id),
+                "stage": e.stage,
+                "event_type": e.event_type,
+                "prompt_tokens": e.prompt_tokens,
+                "completion_tokens": e.completion_tokens,
+                "total_tokens": e.total_tokens,
+                "model": e.model,
+                "duration_ms": e.duration_ms,
+                "payload": e.payload,
+                "created_at": e.created_at.isoformat() if e.created_at else None,
+            }
+            for e in events
+        ],
+        "total": total,
+        "offset": offset,
+        "limit": limit,
+    }
+
+
+# ── Admin: Worker status ─────────────────────────────────────────────────────
+
+@router.get("/admin/pipeline/worker-status")
+async def worker_status():
+    """Get current Celery worker status — active, reserved, and stats."""
+    from worker import celery_app
+    
+    try:
+        inspector = celery_app.control.inspect()
+        active = inspector.active() or {}
+        reserved = inspector.reserved() or {}
+        stats = inspector.stats() or {}
+        
+        workers = []
+        for worker_name in set(list(active.keys()) + list(reserved.keys()) + list(stats.keys())):
+            worker_active = active.get(worker_name, [])
+            worker_reserved = reserved.get(worker_name, [])
+            worker_stats = stats.get(worker_name, {})
+            
+            workers.append({
+                "name": worker_name,
+                "active_tasks": [
+                    {
+                        "id": t.get("id"),
+                        "name": t.get("name"),
+                        "args": t.get("args", []),
+                        "time_start": t.get("time_start"),
+                    }
+                    for t in worker_active
+                ],
+                "reserved_tasks": len(worker_reserved),
+                "total_completed": worker_stats.get("total", {}).get("tasks.pipeline.stages.stage2_segmentation", 0)
+                    + worker_stats.get("total", {}).get("tasks.pipeline.stages.stage3_extraction", 0)
+                    + worker_stats.get("total", {}).get("tasks.pipeline.stages.stage4_classification", 0)
+                    + worker_stats.get("total", {}).get("tasks.pipeline.stages.stage5_synthesis", 0),
+                "uptime": worker_stats.get("clock", None),
+                "pool_size": worker_stats.get("pool", {}).get("max-concurrency") if isinstance(worker_stats.get("pool"), dict) else None,
+            })
+        
+        return {
+            "online": len(workers) > 0,
+            "workers": workers,
+        }
+    except Exception as exc:
+        logger.warning("Failed to inspect Celery workers: %s", exc)
+        return {
+            "online": False,
+            "workers": [],
+            "error": str(exc),
+        }
diff --git a/frontend/src/App.css b/frontend/src/App.css
index 2b64b2b..7e82800 100644
--- a/frontend/src/App.css
+++ b/frontend/src/App.css
@@ -1028,7 +1028,7 @@ body {
 /* ── Search results page ──────────────────────────────────────────────────── */
 
 .search-results-page {
-  max-width: 48rem;
+  max-width: 64rem;
 }
 
 .search-fallback-banner {
@@ -1177,7 +1177,32 @@ body {
 /* ── Technique page ───────────────────────────────────────────────────────── */
 
 .technique-page {
-  max-width: 48rem;
+  max-width: 64rem;
+}
+
+.technique-columns {
+  display: grid;
+  grid-template-columns: 1fr 22rem;
+  gap: 2rem;
+  align-items: start;
+}
+
+.technique-columns__main {
+  min-width: 0; /* prevent grid blowout */
+}
+
+.technique-columns__sidebar {
+  position: sticky;
+  top: 1.5rem;
+}
+
+@media (max-width: 768px) {
+  .technique-columns {
+    grid-template-columns: 1fr;
+  }
+  .technique-columns__sidebar {
+    position: static;
+  }
 }
 
 .technique-404 {
@@ -1631,7 +1656,7 @@ body {
    ══════════════════════════════════════════════════════════════════════════════ */
 
 .creator-detail {
-  max-width: 48rem;
+  max-width: 64rem;
 }
 
 .creator-detail__header {
@@ -2390,3 +2415,375 @@ body {
   padding: 0.1rem 0.35rem;
   border-radius: 3px;
 }
+
+/* ── Pipeline Admin ─────────────────────────────────────────────────────── */
+
+.admin-pipeline {
+  max-width: 1100px;
+  margin: 0 auto;
+  padding: 2rem 1rem;
+}
+
+.admin-pipeline__header {
+  display: flex;
+  justify-content: space-between;
+  align-items: flex-start;
+  gap: 1rem;
+  margin-bottom: 1.5rem;
+  flex-wrap: wrap;
+}
+
+.admin-pipeline__header-right {
+  display: flex;
+  align-items: center;
+  gap: 1rem;
+  flex-wrap: wrap;
+}
+
+.admin-pipeline__title {
+  color: var(--color-text-primary);
+  margin: 0 0 0.25rem;
+}
+
+.admin-pipeline__subtitle {
+  color: var(--color-text-muted);
+  margin: 0;
+  font-size: 0.9rem;
+}
+
+.admin-pipeline__list {
+  display: flex;
+  flex-direction: column;
+  gap: 0.75rem;
+}
+
+/* ── Worker Status Indicator ────────────────────────────────────────────── */
+
+.worker-status {
+  display: flex;
+  align-items: center;
+  gap: 0.5rem;
+  font-size: 0.8125rem;
+  color: var(--color-text-secondary);
+  padding: 0.35rem 0.75rem;
+  background: var(--color-bg-surface);
+  border: 1px solid var(--color-border);
+  border-radius: 6px;
+  white-space: nowrap;
+}
+
+.worker-status__dot {
+  display: inline-block;
+  width: 8px;
+  height: 8px;
+  border-radius: 50%;
+  flex-shrink: 0;
+}
+
+.worker-status__dot--online {
+  background: var(--color-badge-approved-text);
+  box-shadow: 0 0 6px var(--color-badge-approved-text);
+}
+
+.worker-status__dot--offline {
+  background: var(--color-error);
+  box-shadow: 0 0 6px var(--color-error);
+}
+
+.worker-status__dot--unknown {
+  background: var(--color-text-muted);
+}
+
+.worker-status__label {
+  font-weight: 500;
+}
+
+.worker-status__detail {
+  color: var(--color-text-muted);
+  font-size: 0.75rem;
+}
+
+.worker-status--error {
+  border-color: var(--color-error-border);
+}
+
+/* ── Pipeline Video Row ─────────────────────────────────────────────────── */
+
+.pipeline-video {
+  background: var(--color-bg-surface);
+  border: 1px solid var(--color-border);
+  border-radius: 8px;
+  overflow: hidden;
+}
+
+.pipeline-video__header {
+  display: grid;
+  grid-template-columns: 1fr auto auto;
+  gap: 0.75rem;
+  align-items: center;
+  padding: 0.75rem 1rem;
+  cursor: pointer;
+}
+
+.pipeline-video__header:hover {
+  background: var(--color-bg-input);
+}
+
+.pipeline-video__info {
+  display: flex;
+  flex-direction: column;
+  gap: 0.1rem;
+  min-width: 0;
+}
+
+.pipeline-video__filename {
+  color: var(--color-text-primary);
+  font-weight: 500;
+  font-size: 0.9rem;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.pipeline-video__creator {
+  color: var(--color-text-muted);
+  font-size: 0.8rem;
+}
+
+.pipeline-video__meta {
+  display: flex;
+  align-items: center;
+  gap: 0.625rem;
+  flex-wrap: wrap;
+}
+
+.pipeline-video__stat {
+  color: var(--color-text-muted);
+  font-size: 0.8rem;
+  white-space: nowrap;
+}
+
+.pipeline-video__time {
+  color: var(--color-text-muted);
+  font-size: 0.75rem;
+  white-space: nowrap;
+}
+
+.pipeline-video__actions {
+  display: flex;
+  gap: 0.375rem;
+}
+
+.pipeline-video__message {
+  padding: 0.375rem 1rem;
+  font-size: 0.8rem;
+}
+
+.pipeline-video__message--ok {
+  background: var(--color-badge-approved-bg);
+  color: var(--color-badge-approved-text);
+}
+
+.pipeline-video__message--err {
+  background: var(--color-error-bg);
+  color: var(--color-error);
+}
+
+.pipeline-video__detail {
+  padding: 0.75rem 1rem 1rem;
+  border-top: 1px solid var(--color-border);
+}
+
+.pipeline-video__detail-meta {
+  display: flex;
+  gap: 1.25rem;
+  font-size: 0.8rem;
+  color: var(--color-text-muted);
+  margin-bottom: 1rem;
+  flex-wrap: wrap;
+}
+
+/* ── Pipeline Badges ────────────────────────────────────────────────────── */
+
+.pipeline-badge {
+  display: inline-flex;
+  align-items: center;
+  padding: 0.15rem 0.5rem;
+  border-radius: 4px;
+  font-size: 0.75rem;
+  font-weight: 500;
+  background: var(--color-pill-bg);
+  color: var(--color-pill-text);
+  white-space: nowrap;
+}
+
+.pipeline-badge--success {
+  background: var(--color-badge-approved-bg);
+  color: var(--color-badge-approved-text);
+}
+
+.pipeline-badge--active {
+  background: var(--color-badge-edited-bg);
+  color: var(--color-badge-edited-text);
+}
+
+.pipeline-badge--error {
+  background: var(--color-badge-rejected-bg);
+  color: var(--color-badge-rejected-text);
+}
+
+.pipeline-badge--pending {
+  background: var(--color-badge-pending-bg);
+  color: var(--color-badge-pending-text);
+}
+
+.pipeline-badge--event-start {
+  background: var(--color-badge-edited-bg);
+  color: var(--color-badge-edited-text);
+}
+
+.pipeline-badge--event-complete {
+  background: var(--color-badge-approved-bg);
+  color: var(--color-badge-approved-text);
+}
+
+.pipeline-badge--event-error {
+  background: var(--color-badge-rejected-bg);
+  color: var(--color-badge-rejected-text);
+}
+
+.pipeline-badge--event-llm_call {
+  background: var(--color-pill-plugin-bg);
+  color: var(--color-pill-plugin-text);
+}
+
+/* ── Pipeline Events ────────────────────────────────────────────────────── */
+
+.pipeline-events__header {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  margin-bottom: 0.75rem;
+}
+
+.pipeline-events__count {
+  font-size: 0.85rem;
+  color: var(--color-text-secondary);
+  font-weight: 500;
+}
+
+.pipeline-events__empty {
+  font-size: 0.85rem;
+  color: var(--color-text-muted);
+  padding: 0.5rem 0;
+}
+
+.pipeline-events__list {
+  display: flex;
+  flex-direction: column;
+  gap: 0.25rem;
+}
+
+.pipeline-event {
+  background: var(--color-bg-page);
+  border: 1px solid var(--color-border);
+  border-radius: 6px;
+  padding: 0.5rem 0.75rem;
+}
+
+.pipeline-event--error {
+  border-left: 3px solid var(--color-error);
+}
+
+.pipeline-event__row {
+  display: flex;
+  align-items: center;
+  gap: 0.5rem;
+  flex-wrap: wrap;
+}
+
+.pipeline-event__icon {
+  font-size: 0.85rem;
+  flex-shrink: 0;
+  width: 1.25rem;
+  text-align: center;
+}
+
+.pipeline-event__stage {
+  color: var(--color-text-primary);
+  font-size: 0.8125rem;
+  font-weight: 500;
+}
+
+.pipeline-event__model {
+  color: var(--color-text-muted);
+  font-size: 0.75rem;
+  font-family: monospace;
+}
+
+.pipeline-event__tokens {
+  color: var(--color-pill-plugin-text);
+  font-size: 0.75rem;
+  font-weight: 500;
+}
+
+.pipeline-event__duration {
+  color: var(--color-text-muted);
+  font-size: 0.75rem;
+}
+
+.pipeline-event__time {
+  color: var(--color-text-muted);
+  font-size: 0.75rem;
+  margin-left: auto;
+  white-space: nowrap;
+}
+
+/* ── Pipeline Events Pager ──────────────────────────────────────────────── */
+
+.pipeline-events__pager {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  gap: 0.75rem;
+  margin-top: 0.75rem;
+}
+
+.pipeline-events__pager-info {
+  font-size: 0.8rem;
+  color: var(--color-text-muted);
+}
+
+/* ── Collapsible JSON ───────────────────────────────────────────────────── */
+
+.json-viewer {
+  margin-top: 0.375rem;
+}
+
+.json-viewer__toggle {
+  background: none;
+  border: none;
+  color: var(--color-accent);
+  font-size: 0.75rem;
+  cursor: pointer;
+  padding: 0;
+  font-family: inherit;
+}
+
+.json-viewer__toggle:hover {
+  color: var(--color-accent-hover);
+}
+
+.json-viewer__content {
+  margin: 0.375rem 0 0;
+  padding: 0.5rem 0.75rem;
+  background: var(--color-bg-transcript);
+  border: 1px solid var(--color-border);
+  border-radius: 4px;
+  color: var(--color-text-secondary);
+  font-size: 0.75rem;
+  line-height: 1.5;
+  overflow-x: auto;
+  max-height: 300px;
+  overflow-y: auto;
+}
diff --git a/frontend/src/App.tsx b/frontend/src/App.tsx
index 1dd122c..e96014c 100644
--- a/frontend/src/App.tsx
+++ b/frontend/src/App.tsx
@@ -8,6 +8,7 @@ import TopicsBrowse from "./pages/TopicsBrowse";
 import ReviewQueue from "./pages/ReviewQueue";
 import MomentDetail from "./pages/MomentDetail";
 import AdminReports from "./pages/AdminReports";
+import AdminPipeline from "./pages/AdminPipeline";
 import ModeToggle from "./components/ModeToggle";
 
 export default function App() {
@@ -24,6 +25,7 @@ export default function App() {
             <Link to="/creators">Creators</Link>
             <Link to="/admin/review">Review</Link>
             <Link to="/admin/reports">Reports</Link>
+            <Link to="/admin/pipeline">Pipeline</Link>
           </nav>
           <ModeToggle />
         </div>
@@ -45,6 +47,7 @@ export default function App() {
           <Route path="/admin/review" element={<ReviewQueue />} />
           <Route path="/admin/review/:momentId" element={<MomentDetail />} />
           <Route path="/admin/reports" element={<AdminReports />} />
+          <Route path="/admin/pipeline" element={<AdminPipeline />} />
 
           {/* Fallback */}
           <Route path="*" element={<Navigate to="/" replace />} />
diff --git a/frontend/src/api/public-client.ts b/frontend/src/api/public-client.ts
index 7683819..efce818 100644
--- a/frontend/src/api/public-client.ts
+++ b/frontend/src/api/public-client.ts
@@ -357,3 +357,114 @@ export async function updateReport(
     body: JSON.stringify(body),
   });
 }
+
+
+// ── Pipeline Admin ──────────────────────────────────────────────────────────
+
+export interface PipelineVideoItem {
+  id: string;
+  filename: string;
+  processing_status: string;
+  content_hash: string | null;
+  creator_name: string;
+  created_at: string | null;
+  updated_at: string | null;
+  event_count: number;
+  total_tokens_used: number;
+  last_event_at: string | null;
+}
+
+export interface PipelineVideoListResponse {
+  items: PipelineVideoItem[];
+  total: number;
+}
+
+export interface PipelineEvent {
+  id: string;
+  video_id: string;
+  stage: string;
+  event_type: string;
+  prompt_tokens: number | null;
+  completion_tokens: number | null;
+  total_tokens: number | null;
+  model: string | null;
+  duration_ms: number | null;
+  payload: Record<string, unknown> | null;
+  created_at: string | null;
+}
+
+export interface PipelineEventListResponse {
+  items: PipelineEvent[];
+  total: number;
+  offset: number;
+  limit: number;
+}
+
+export interface WorkerTask {
+  id: string;
+  name: string;
+  args: unknown[];
+  time_start: number | null;
+}
+
+export interface WorkerInfo {
+  name: string;
+  active_tasks: WorkerTask[];
+  reserved_tasks: number;
+  total_completed: number;
+  uptime: string | null;
+  pool_size: number | null;
+}
+
+export interface WorkerStatusResponse {
+  online: boolean;
+  workers: WorkerInfo[];
+  error?: string;
+}
+
+export interface TriggerResponse {
+  status: string;
+  video_id: string;
+  current_processing_status?: string;
+}
+
+export interface RevokeResponse {
+  status: string;
+  video_id: string;
+  tasks_revoked: number;
+}
+
+export async function fetchPipelineVideos(): Promise<PipelineVideoListResponse> {
+  return request<PipelineVideoListResponse>(`${BASE}/admin/pipeline/videos`);
+}
+
+export async function fetchPipelineEvents(
+  videoId: string,
+  params: { offset?: number; limit?: number; stage?: string; event_type?: string } = {},
+): Promise<PipelineEventListResponse> {
+  const qs = new URLSearchParams();
+  if (params.offset !== undefined) qs.set("offset", String(params.offset));
+  if (params.limit !== undefined) qs.set("limit", String(params.limit));
+  if (params.stage) qs.set("stage", params.stage);
+  if (params.event_type) qs.set("event_type", params.event_type);
+  const query = qs.toString();
+  return request<PipelineEventListResponse>(
+    `${BASE}/admin/pipeline/events/${videoId}${query ? `?${query}` : ""}`,
+  );
+}
+
+export async function fetchWorkerStatus(): Promise<WorkerStatusResponse> {
+  return request<WorkerStatusResponse>(`${BASE}/admin/pipeline/worker-status`);
+}
+
+export async function triggerPipeline(videoId: string): Promise<TriggerResponse> {
+  return request<TriggerResponse>(`${BASE}/admin/pipeline/trigger/${videoId}`, {
+    method: "POST",
+  });
+}
+
+export async function revokePipeline(videoId: string): Promise<RevokeResponse> {
+  return request<RevokeResponse>(`${BASE}/admin/pipeline/revoke/${videoId}`, {
+    method: "POST",
+  });
+}
diff --git a/frontend/src/pages/AdminPipeline.tsx b/frontend/src/pages/AdminPipeline.tsx
new file mode 100644
index 0000000..b4dc718
--- /dev/null
+++ b/frontend/src/pages/AdminPipeline.tsx
@@ -0,0 +1,422 @@
+/**
+ * Pipeline admin dashboard — video list with status, retrigger/revoke,
+ * expandable event log with token usage and collapsible JSON viewer.
+ */
+
+import { useCallback, useEffect, useState } from "react";
+import {
+  fetchPipelineVideos,
+  fetchPipelineEvents,
+  fetchWorkerStatus,
+  triggerPipeline,
+  revokePipeline,
+  type PipelineVideoItem,
+  type PipelineEvent,
+  type WorkerStatusResponse,
+} from "../api/public-client";
+
+// ── Helpers ──────────────────────────────────────────────────────────────────
+
+function formatDate(iso: string | null): string {
+  if (!iso) return "—";
+  return new Date(iso).toLocaleString(undefined, {
+    month: "short",
+    day: "numeric",
+    hour: "2-digit",
+    minute: "2-digit",
+    second: "2-digit",
+  });
+}
+
+function formatTokens(n: number): string {
+  if (n === 0) return "0";
+  if (n >= 1_000_000) return `${(n / 1_000_000).toFixed(1)}M`;
+  if (n >= 1_000) return `${(n / 1_000).toFixed(1)}k`;
+  return String(n);
+}
+
+function statusBadgeClass(status: string): string {
+  switch (status) {
+    case "completed":
+    case "indexed":
+      return "pipeline-badge--success";
+    case "processing":
+    case "extracted":
+    case "classified":
+    case "synthesized":
+      return "pipeline-badge--active";
+    case "failed":
+    case "error":
+      return "pipeline-badge--error";
+    case "pending":
+    case "queued":
+      return "pipeline-badge--pending";
+    default:
+      return "";
+  }
+}
+
+function eventTypeIcon(eventType: string): string {
+  switch (eventType) {
+    case "start":
+      return "▶";
+    case "complete":
+      return "✓";
+    case "error":
+      return "✗";
+    case "llm_call":
+      return "🤖";
+    default:
+      return "·";
+  }
+}
+
+// ── Collapsible JSON ─────────────────────────────────────────────────────────
+
+function JsonViewer({ data }: { data: Record<string, unknown> | null }) {
+  const [open, setOpen] = useState(false);
+  if (!data || Object.keys(data).length === 0) return null;
+
+  return (
+    <div className="json-viewer">
+      <button
+        className="json-viewer__toggle"
+        onClick={() => setOpen((v) => !v)}
+        aria-expanded={open}
+      >
+        {open ? "▾ Hide payload" : "▸ Show payload"}
+      </button>
+      {open && (
+        <pre className="json-viewer__content">
+          {JSON.stringify(data, null, 2)}
+        </pre>
+      )}
+    </div>
+  );
+}
+
+// ── Event Log ────────────────────────────────────────────────────────────────
+
+function EventLog({ videoId }: { videoId: string }) {
+  const [events, setEvents] = useState<PipelineEvent[]>([]);
+  const [total, setTotal] = useState(0);
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState<string | null>(null);
+  const [offset, setOffset] = useState(0);
+  const limit = 50;
+
+  const load = useCallback(async () => {
+    setLoading(true);
+    setError(null);
+    try {
+      const res = await fetchPipelineEvents(videoId, { offset, limit });
+      setEvents(res.items);
+      setTotal(res.total);
+    } catch (err) {
+      setError(err instanceof Error ? err.message : "Failed to load events");
+    } finally {
+      setLoading(false);
+    }
+  }, [videoId, offset]);
+
+  useEffect(() => {
+    void load();
+  }, [load]);
+
+  if (loading) return <div className="loading">Loading events…</div>;
+  if (error) return <div className="loading error-text">Error: {error}</div>;
+  if (events.length === 0) return <div className="pipeline-events__empty">No events recorded.</div>;
+
+  const hasNext = offset + limit < total;
+  const hasPrev = offset > 0;
+
+  return (
+    <div className="pipeline-events">
+      <div className="pipeline-events__header">
+        <span className="pipeline-events__count">{total} event{total !== 1 ? "s" : ""}</span>
+        <button className="btn btn--small btn--secondary" onClick={() => void load()}>↻ Refresh</button>
+      </div>
+
+      <div className="pipeline-events__list">
+        {events.map((evt) => (
+          <div key={evt.id} className={`pipeline-event pipeline-event--${evt.event_type}`}>
+            <div className="pipeline-event__row">
+              <span className="pipeline-event__icon">{eventTypeIcon(evt.event_type)}</span>
+              <span className="pipeline-event__stage">{evt.stage}</span>
+              <span className={`pipeline-badge pipeline-badge--event-${evt.event_type}`}>
+                {evt.event_type}
+              </span>
+              {evt.model && <span className="pipeline-event__model">{evt.model}</span>}
+              {evt.total_tokens != null && evt.total_tokens > 0 && (
+                <span className="pipeline-event__tokens" title={`prompt: ${evt.prompt_tokens ?? 0} / completion: ${evt.completion_tokens ?? 0}`}>
+                  {formatTokens(evt.total_tokens)} tok
+                </span>
+              )}
+              {evt.duration_ms != null && (
+                <span className="pipeline-event__duration">{evt.duration_ms}ms</span>
+              )}
+              <span className="pipeline-event__time">{formatDate(evt.created_at)}</span>
+            </div>
+            <JsonViewer data={evt.payload} />
+          </div>
+        ))}
+      </div>
+
+      {(hasPrev || hasNext) && (
+        <div className="pipeline-events__pager">
+          <button
+            className="btn btn--small btn--secondary"
+            disabled={!hasPrev}
+            onClick={() => setOffset((o) => Math.max(0, o - limit))}
+          >
+            ← Prev
+          </button>
+          <span className="pipeline-events__pager-info">
+            {offset + 1}–{Math.min(offset + limit, total)} of {total}
+          </span>
+          <button
+            className="btn btn--small btn--secondary"
+            disabled={!hasNext}
+            onClick={() => setOffset((o) => o + limit)}
+          >
+            Next →
+          </button>
+        </div>
+      )}
+    </div>
+  );
+}
+
+// ── Worker Status ────────────────────────────────────────────────────────────
+
+function WorkerStatus() {
+  const [status, setStatus] = useState<WorkerStatusResponse | null>(null);
+  const [error, setError] = useState<string | null>(null);
+
+  const load = useCallback(async () => {
+    try {
+      setError(null);
+      const res = await fetchWorkerStatus();
+      setStatus(res);
+    } catch (err) {
+      setError(err instanceof Error ? err.message : "Failed");
+    }
+  }, []);
+
+  useEffect(() => {
+    void load();
+    const id = setInterval(() => void load(), 15_000);
+    return () => clearInterval(id);
+  }, [load]);
+
+  if (error) {
+    return (
+      <div className="worker-status worker-status--error">
+        <span className="worker-status__dot worker-status__dot--offline" />
+        Worker: error ({error})
+      </div>
+    );
+  }
+
+  if (!status) {
+    return (
+      <div className="worker-status">
+        <span className="worker-status__dot worker-status__dot--unknown" />
+        Worker: checking…
+      </div>
+    );
+  }
+
+  return (
+    <div className={`worker-status ${status.online ? "worker-status--online" : "worker-status--offline"}`}>
+      <span className={`worker-status__dot ${status.online ? "worker-status__dot--online" : "worker-status__dot--offline"}`} />
+      <span className="worker-status__label">
+        {status.online ? `${status.workers.length} worker${status.workers.length !== 1 ? "s" : ""} online` : "Workers offline"}
+      </span>
+      {status.workers.map((w) => (
+        <span key={w.name} className="worker-status__detail" title={w.name}>
+          {w.active_tasks.length > 0
+            ? `${w.active_tasks.length} active`
+            : "idle"}
+          {w.pool_size != null && ` · pool ${w.pool_size}`}
+        </span>
+      ))}
+    </div>
+  );
+}
+
+// ── Main Page ────────────────────────────────────────────────────────────────
+
+export default function AdminPipeline() {
+  const [videos, setVideos] = useState<PipelineVideoItem[]>([]);
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState<string | null>(null);
+  const [expandedId, setExpandedId] = useState<string | null>(null);
+  const [actionLoading, setActionLoading] = useState<string | null>(null);
+  const [actionMessage, setActionMessage] = useState<{ id: string; text: string; ok: boolean } | null>(null);
+
+  const load = useCallback(async () => {
+    setLoading(true);
+    setError(null);
+    try {
+      const res = await fetchPipelineVideos();
+      setVideos(res.items);
+    } catch (err) {
+      setError(err instanceof Error ? err.message : "Failed to load videos");
+    } finally {
+      setLoading(false);
+    }
+  }, []);
+
+  useEffect(() => {
+    void load();
+  }, [load]);
+
+  const handleTrigger = async (videoId: string) => {
+    setActionLoading(videoId);
+    setActionMessage(null);
+    try {
+      const res = await triggerPipeline(videoId);
+      setActionMessage({ id: videoId, text: `Triggered (${res.status})`, ok: true });
+      // Refresh after short delay to let status update
+      setTimeout(() => void load(), 2000);
+    } catch (err) {
+      setActionMessage({
+        id: videoId,
+        text: err instanceof Error ? err.message : "Trigger failed",
+        ok: false,
+      });
+    } finally {
+      setActionLoading(null);
+    }
+  };
+
+  const handleRevoke = async (videoId: string) => {
+    setActionLoading(videoId);
+    setActionMessage(null);
+    try {
+      const res = await revokePipeline(videoId);
+      setActionMessage({
+        id: videoId,
+        text: res.tasks_revoked > 0
+          ? `Revoked ${res.tasks_revoked} task${res.tasks_revoked !== 1 ? "s" : ""}`
+          : "No active tasks",
+        ok: true,
+      });
+      setTimeout(() => void load(), 2000);
+    } catch (err) {
+      setActionMessage({
+        id: videoId,
+        text: err instanceof Error ? err.message : "Revoke failed",
+        ok: false,
+      });
+    } finally {
+      setActionLoading(null);
+    }
+  };
+
+  const toggleExpand = (id: string) => {
+    setExpandedId((prev) => (prev === id ? null : id));
+  };
+
+  return (
+    <div className="admin-pipeline">
+      <div className="admin-pipeline__header">
+        <div>
+          <h2 className="admin-pipeline__title">Pipeline Management</h2>
+          <p className="admin-pipeline__subtitle">
+            {videos.length} video{videos.length !== 1 ? "s" : ""}
+          </p>
+        </div>
+        <div className="admin-pipeline__header-right">
+          <WorkerStatus />
+          <button className="btn btn--secondary" onClick={() => void load()} disabled={loading}>
+            ↻ Refresh
+          </button>
+        </div>
+      </div>
+
+      {loading ? (
+        <div className="loading">Loading videos…</div>
+      ) : error ? (
+        <div className="loading error-text">Error: {error}</div>
+      ) : videos.length === 0 ? (
+        <div className="empty-state">No videos in pipeline.</div>
+      ) : (
+        <div className="admin-pipeline__list">
+          {videos.map((video) => (
+            <div key={video.id} className="pipeline-video">
+              <div
+                className="pipeline-video__header"
+                onClick={() => toggleExpand(video.id)}
+              >
+                <div className="pipeline-video__info">
+                  <span className="pipeline-video__filename" title={video.filename}>
+                    {video.filename}
+                  </span>
+                  <span className="pipeline-video__creator">{video.creator_name}</span>
+                </div>
+
+                <div className="pipeline-video__meta">
+                  <span className={`pipeline-badge ${statusBadgeClass(video.processing_status)}`}>
+                    {video.processing_status}
+                  </span>
+                  <span className="pipeline-video__stat" title="Events">
+                    {video.event_count} events
+                  </span>
+                  <span className="pipeline-video__stat" title="Total tokens used">
+                    {formatTokens(video.total_tokens_used)} tokens
+                  </span>
+                  <span className="pipeline-video__time">
+                    {formatDate(video.last_event_at)}
+                  </span>
+                </div>
+
+                <div className="pipeline-video__actions" onClick={(e) => e.stopPropagation()}>
+                  <button
+                    className="btn btn--small btn--primary"
+                    onClick={() => void handleTrigger(video.id)}
+                    disabled={actionLoading === video.id}
+                    title="Retrigger pipeline"
+                  >
+                    {actionLoading === video.id ? "…" : "▶ Trigger"}
+                  </button>
+                  <button
+                    className="btn btn--small btn--danger"
+                    onClick={() => void handleRevoke(video.id)}
+                    disabled={actionLoading === video.id}
+                    title="Revoke active tasks"
+                  >
+                    {actionLoading === video.id ? "…" : "■ Revoke"}
+                  </button>
+                </div>
+              </div>
+
+              {actionMessage?.id === video.id && (
+                <div className={`pipeline-video__message ${actionMessage.ok ? "pipeline-video__message--ok" : "pipeline-video__message--err"}`}>
+                  {actionMessage.text}
+                </div>
+              )}
+
+              {expandedId === video.id && (
+                <div className="pipeline-video__detail">
+                  <div className="pipeline-video__detail-meta">
+                    <span>ID: {video.id.slice(0, 8)}…</span>
+                    {video.content_hash && (
+                      <span title={video.content_hash}>
+                        Hash: <code>{video.content_hash.slice(0, 12)}…</code>
+                      </span>
+                    )}
+                    <span>Created: {formatDate(video.created_at)}</span>
+                    <span>Updated: {formatDate(video.updated_at)}</span>
+                  </div>
+                  <EventLog videoId={video.id} />
+                </div>
+              )}
+            </div>
+          ))}
+        </div>
+      )}
+    </div>
+  );
+}
diff --git a/frontend/src/pages/TechniquePage.tsx b/frontend/src/pages/TechniquePage.tsx
index 43bfe45..e892913 100644
--- a/frontend/src/pages/TechniquePage.tsx
+++ b/frontend/src/pages/TechniquePage.tsx
@@ -371,7 +371,9 @@ export default function TechniquePage() {
         />
       )}
 
-      {/* Summary */}
+      <div className="technique-columns">
+        <div className="technique-columns__main">
+          {/* Summary */}
       {displaySummary && (
         <section className="technique-summary">
           <p>{displaySummary}</p>
@@ -401,7 +403,9 @@ export default function TechniquePage() {
           </section>
         )}
 
-      {/* Key moments (always from live data — not versioned) */}
+        </div>
+        <div className="technique-columns__sidebar">
+          {/* Key moments (always from live data — not versioned) */}
       {technique.key_moments.length > 0 && (
         <section className="technique-moments">
           <h2>Key Moments</h2>
@@ -500,6 +504,8 @@ export default function TechniquePage() {
           </ul>
         </section>
       )}
+        </div>
+      </div>
     </article>
   );
 }
diff --git a/frontend/tsconfig.app.tsbuildinfo b/frontend/tsconfig.app.tsbuildinfo
index 38e7477..997c8ec 100644
--- a/frontend/tsconfig.app.tsbuildinfo
+++ b/frontend/tsconfig.app.tsbuildinfo
@@ -1 +1 @@
-{"root":["./src/App.tsx","./src/main.tsx","./src/vite-env.d.ts","./src/api/client.ts","./src/api/public-client.ts","./src/components/ModeToggle.tsx","./src/components/StatusBadge.tsx","./src/pages/CreatorDetail.tsx","./src/pages/CreatorsBrowse.tsx","./src/pages/Home.tsx","./src/pages/MomentDetail.tsx","./src/pages/ReviewQueue.tsx","./src/pages/SearchResults.tsx","./src/pages/TechniquePage.tsx","./src/pages/TopicsBrowse.tsx"],"version":"5.6.3"}
\ No newline at end of file
+{"root":["./src/App.tsx","./src/main.tsx","./src/vite-env.d.ts","./src/api/client.ts","./src/api/public-client.ts","./src/components/ModeToggle.tsx","./src/components/ReportIssueModal.tsx","./src/components/StatusBadge.tsx","./src/pages/AdminPipeline.tsx","./src/pages/AdminReports.tsx","./src/pages/CreatorDetail.tsx","./src/pages/CreatorsBrowse.tsx","./src/pages/Home.tsx","./src/pages/MomentDetail.tsx","./src/pages/ReviewQueue.tsx","./src/pages/SearchResults.tsx","./src/pages/TechniquePage.tsx","./src/pages/TopicsBrowse.tsx"],"version":"5.6.3"}
\ No newline at end of file

From c6c15defee9f9f32b35a70bb94e8d6f7e165be66 Mon Sep 17 00:00:00 2001
From: jlightner <jlightner@ub01.a.xpltd.co>
Date: Mon, 30 Mar 2026 05:55:17 -0500
Subject: [PATCH 4/8] feat: Dynamic token estimation for per-stage max_tokens

- Add estimate_tokens() and estimate_max_tokens() to llm_client with
  stage-specific output ratios (0.3x segmentation, 1.2x extraction,
  0.15x classification, 1.5x synthesis)
- Add max_tokens override parameter to LLMClient.complete()
- Wire all 4 pipeline stages to estimate max_tokens from actual prompt
  content with 20% buffer and 2048 floor
- Add LLM_MAX_TOKENS_HARD_LIMIT=32768 config (dynamic estimator ceiling)
- Log token estimates alongside every LLM request

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 backend/config.py              |   5 +-
 backend/pipeline/llm_client.py | 114 +++++++++++++++++++-
 backend/pipeline/stages.py     | 189 ++++++++++++++++++++++++++++++---
 3 files changed, 287 insertions(+), 21 deletions(-)

diff --git a/backend/config.py b/backend/config.py
index d6e2b6f..482e601 100644
--- a/backend/config.py
+++ b/backend/config.py
@@ -43,8 +43,9 @@ class Settings(BaseSettings):
     llm_stage5_model: str | None = "fyn-llm-agent-think"  # synthesis — reasoning
     llm_stage5_modality: str = "thinking"
 
-    # Max tokens for LLM responses (OpenWebUI defaults to 1000 which truncates pipeline JSON)
-    llm_max_tokens: int = 65536
+    # Dynamic token estimation — each stage calculates max_tokens from input size
+    llm_max_tokens_hard_limit: int = 32768   # Hard ceiling for dynamic estimator
+    llm_max_tokens: int = 65536              # Fallback when no estimate is provided
 
     # Embedding endpoint
     embedding_api_url: str = "http://localhost:11434/v1"
diff --git a/backend/pipeline/llm_client.py b/backend/pipeline/llm_client.py
index f7d23f0..1c26f95 100644
--- a/backend/pipeline/llm_client.py
+++ b/backend/pipeline/llm_client.py
@@ -14,7 +14,10 @@ from __future__ import annotations
 
 import logging
 import re
-from typing import TypeVar
+from typing import TYPE_CHECKING, TypeVar
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
 
 import openai
 from pydantic import BaseModel
@@ -50,6 +53,77 @@ def strip_think_tags(text: str) -> str:
     return cleaned.strip()
 
 
+
+# ── Token estimation ─────────────────────────────────────────────────────────
+
+# Stage-specific output multipliers: estimated output tokens as a ratio of input tokens.
+# These are empirically tuned based on observed pipeline behavior.
+_STAGE_OUTPUT_RATIOS: dict[str, float] = {
+    "stage2_segmentation": 0.3,    # Compact topic groups — much smaller than input
+    "stage3_extraction": 1.2,      # Detailed moments with summaries — can exceed input
+    "stage4_classification": 0.15,  # Index + category + tags per moment — very compact
+    "stage5_synthesis": 1.5,       # Full prose technique pages — heaviest output
+}
+
+# Minimum floor so we never send a trivially small max_tokens
+_MIN_MAX_TOKENS = 2048
+
+
+def estimate_tokens(text: str) -> int:
+    """Estimate token count from text using a chars-per-token heuristic.
+
+    Uses 3.5 chars/token which is conservative for English + JSON markup.
+    """
+    if not text:
+        return 0
+    return max(1, int(len(text) / 3.5))
+
+
+def estimate_max_tokens(
+    system_prompt: str,
+    user_prompt: str,
+    stage: str | None = None,
+    hard_limit: int = 32768,
+) -> int:
+    """Estimate the max_tokens parameter for an LLM call.
+
+    Calculates expected output size based on input size and stage-specific
+    multipliers. The result is clamped between _MIN_MAX_TOKENS and hard_limit.
+
+    Parameters
+    ----------
+    system_prompt:
+        The system prompt text.
+    user_prompt:
+        The user prompt text (transcript, moments, etc.).
+    stage:
+        Pipeline stage name (e.g. "stage3_extraction"). If None or unknown,
+        uses a default 1.0x multiplier.
+    hard_limit:
+        Absolute ceiling — never exceed this value.
+
+    Returns
+    -------
+    int
+        Estimated max_tokens value to pass to the LLM API.
+    """
+    input_tokens = estimate_tokens(system_prompt) + estimate_tokens(user_prompt)
+    ratio = _STAGE_OUTPUT_RATIOS.get(stage or "", 1.0)
+    estimated_output = int(input_tokens * ratio)
+
+    # Add a 20% buffer for JSON overhead and variability
+    estimated_output = int(estimated_output * 1.2)
+
+    # Clamp to [_MIN_MAX_TOKENS, hard_limit]
+    result = max(_MIN_MAX_TOKENS, min(estimated_output, hard_limit))
+
+    logger.info(
+        "Token estimate: input≈%d, stage=%s, ratio=%.2f, estimated_output=%d, max_tokens=%d (hard_limit=%d)",
+        input_tokens, stage or "default", ratio, estimated_output, result, hard_limit,
+    )
+    return result
+
+
 class LLMClient:
     """Sync LLM client that tries a primary endpoint and falls back on failure."""
 
@@ -73,6 +147,8 @@ class LLMClient:
         response_model: type[BaseModel] | None = None,
         modality: str = "chat",
         model_override: str | None = None,
+        on_complete: "Callable | None" = None,
+        max_tokens: int | None = None,
     ) -> str:
         """Send a chat completion request, falling back on connection/timeout errors.
 
@@ -92,6 +168,9 @@ class LLMClient:
         model_override:
             Model name to use instead of the default. If None, uses the
             configured default for the endpoint.
+        max_tokens:
+            Override for max_tokens on this call. If None, falls back to
+            the configured ``llm_max_tokens`` from settings.
 
         Returns
         -------
@@ -123,12 +202,14 @@ class LLMClient:
 
         primary_model = model_override or self.settings.llm_model
         fallback_model = self.settings.llm_fallback_model
+        effective_max_tokens = max_tokens if max_tokens is not None else self.settings.llm_max_tokens
 
         logger.info(
-            "LLM request: model=%s, modality=%s, response_model=%s",
+            "LLM request: model=%s, modality=%s, response_model=%s, max_tokens=%d",
             primary_model,
             modality,
             response_model.__name__ if response_model else None,
+            effective_max_tokens,
         )
 
         # --- Try primary endpoint ---
@@ -136,7 +217,7 @@ class LLMClient:
             response = self._primary.chat.completions.create(
                 model=primary_model,
                 messages=messages,
-                max_tokens=self.settings.llm_max_tokens,
+                max_tokens=effective_max_tokens,
                 **kwargs,
             )
             raw = response.choices[0].message.content or ""
@@ -149,6 +230,18 @@ class LLMClient:
                 )
             if modality == "thinking":
                 raw = strip_think_tags(raw)
+            if on_complete is not None:
+                try:
+                    on_complete(
+                        model=primary_model,
+                        prompt_tokens=usage.prompt_tokens if usage else None,
+                        completion_tokens=usage.completion_tokens if usage else None,
+                        total_tokens=usage.total_tokens if usage else None,
+                        content=raw,
+                        finish_reason=response.choices[0].finish_reason if response.choices else None,
+                    )
+                except Exception as cb_exc:
+                    logger.warning("on_complete callback failed: %s", cb_exc)
             return raw
 
         except (openai.APIConnectionError, openai.APITimeoutError) as exc:
@@ -164,7 +257,7 @@ class LLMClient:
             response = self._fallback.chat.completions.create(
                 model=fallback_model,
                 messages=messages,
-                max_tokens=self.settings.llm_max_tokens,
+                max_tokens=effective_max_tokens,
                 **kwargs,
             )
             raw = response.choices[0].message.content or ""
@@ -177,6 +270,19 @@ class LLMClient:
                 )
             if modality == "thinking":
                 raw = strip_think_tags(raw)
+            if on_complete is not None:
+                try:
+                    on_complete(
+                        model=fallback_model,
+                        prompt_tokens=usage.prompt_tokens if usage else None,
+                        completion_tokens=usage.completion_tokens if usage else None,
+                        total_tokens=usage.total_tokens if usage else None,
+                        content=raw,
+                        finish_reason=response.choices[0].finish_reason if response.choices else None,
+                        is_fallback=True,
+                    )
+                except Exception as cb_exc:
+                    logger.warning("on_complete callback failed: %s", cb_exc)
             return raw
 
         except (openai.APIConnectionError, openai.APITimeoutError, openai.APIError) as exc:
diff --git a/backend/pipeline/stages.py b/backend/pipeline/stages.py
index 3a49f86..fdc2204 100644
--- a/backend/pipeline/stages.py
+++ b/backend/pipeline/stages.py
@@ -26,6 +26,7 @@ from config import get_settings
 from models import (
     KeyMoment,
     KeyMomentContentType,
+    PipelineEvent,
     ProcessingStatus,
     SourceVideo,
     TechniquePage,
@@ -33,7 +34,7 @@ from models import (
     TranscriptSegment,
 )
 from pipeline.embedding_client import EmbeddingClient
-from pipeline.llm_client import LLMClient
+from pipeline.llm_client import LLMClient, estimate_max_tokens
 from pipeline.qdrant_client import QdrantManager
 from pipeline.schemas import (
     ClassificationResult,
@@ -45,6 +46,68 @@ from worker import celery_app
 
 logger = logging.getLogger(__name__)
 
+
+# ── Pipeline event persistence ───────────────────────────────────────────────
+
+def _emit_event(
+    video_id: str,
+    stage: str,
+    event_type: str,
+    *,
+    prompt_tokens: int | None = None,
+    completion_tokens: int | None = None,
+    total_tokens: int | None = None,
+    model: str | None = None,
+    duration_ms: int | None = None,
+    payload: dict | None = None,
+) -> None:
+    """Persist a pipeline event to the DB. Best-effort -- failures logged, not raised."""
+    try:
+        session = _get_sync_session()
+        try:
+            event = PipelineEvent(
+                video_id=video_id,
+                stage=stage,
+                event_type=event_type,
+                prompt_tokens=prompt_tokens,
+                completion_tokens=completion_tokens,
+                total_tokens=total_tokens,
+                model=model,
+                duration_ms=duration_ms,
+                payload=payload,
+            )
+            session.add(event)
+            session.commit()
+        finally:
+            session.close()
+    except Exception as exc:
+        logger.warning("Failed to emit pipeline event: %s", exc)
+
+
+def _make_llm_callback(video_id: str, stage: str):
+    """Create an on_complete callback for LLMClient that emits llm_call events."""
+    def callback(*, model=None, prompt_tokens=None, completion_tokens=None,
+                 total_tokens=None, content=None, finish_reason=None,
+                 is_fallback=False, **_kwargs):
+        # Truncate content for storage — keep first 2000 chars for debugging
+        truncated = content[:2000] if content and len(content) > 2000 else content
+        _emit_event(
+            video_id=video_id,
+            stage=stage,
+            event_type="llm_call",
+            model=model,
+            prompt_tokens=prompt_tokens,
+            completion_tokens=completion_tokens,
+            total_tokens=total_tokens,
+            payload={
+                "content_preview": truncated,
+                "content_length": len(content) if content else 0,
+                "finish_reason": finish_reason,
+                "is_fallback": is_fallback,
+            },
+        )
+    return callback
+
 # ── Helpers ──────────────────────────────────────────────────────────────────
 
 _engine = None
@@ -175,6 +238,7 @@ def stage2_segmentation(self, video_id: str) -> str:
     """
     start = time.monotonic()
     logger.info("Stage 2 (segmentation) starting for video_id=%s", video_id)
+    _emit_event(video_id, "stage2_segmentation", "start")
 
     session = _get_sync_session()
     try:
@@ -207,9 +271,11 @@ def stage2_segmentation(self, video_id: str) -> str:
 
         llm = _get_llm_client()
         model_override, modality = _get_stage_config(2)
-        logger.info("Stage 2 using model=%s, modality=%s", model_override or "default", modality)
-        raw = llm.complete(system_prompt, user_prompt, response_model=SegmentationResult,
-                           modality=modality, model_override=model_override)
+        hard_limit = get_settings().llm_max_tokens_hard_limit
+        max_tokens = estimate_max_tokens(system_prompt, user_prompt, stage="stage2_segmentation", hard_limit=hard_limit)
+        logger.info("Stage 2 using model=%s, modality=%s, max_tokens=%d", model_override or "default", modality, max_tokens)
+        raw = llm.complete(system_prompt, user_prompt, response_model=SegmentationResult, on_complete=_make_llm_callback(video_id, "stage2_segmentation"),
+                           modality=modality, model_override=model_override, max_tokens=max_tokens)
         result = _safe_parse_llm_response(raw, SegmentationResult, llm, system_prompt, user_prompt,
                                           modality=modality, model_override=model_override)
 
@@ -222,6 +288,7 @@ def stage2_segmentation(self, video_id: str) -> str:
 
         session.commit()
         elapsed = time.monotonic() - start
+        _emit_event(video_id, "stage2_segmentation", "complete")
         logger.info(
             "Stage 2 (segmentation) completed for video_id=%s in %.1fs — %d topic groups found",
             video_id, elapsed, len(result.segments),
@@ -232,6 +299,7 @@ def stage2_segmentation(self, video_id: str) -> str:
         raise  # Don't retry missing prompt files
     except Exception as exc:
         session.rollback()
+        _emit_event(video_id, "stage2_segmentation", "error", payload={"error": str(exc)})
         logger.error("Stage 2 failed for video_id=%s: %s", video_id, exc)
         raise self.retry(exc=exc)
     finally:
@@ -251,6 +319,7 @@ def stage3_extraction(self, video_id: str) -> str:
     """
     start = time.monotonic()
     logger.info("Stage 3 (extraction) starting for video_id=%s", video_id)
+    _emit_event(video_id, "stage3_extraction", "start")
 
     session = _get_sync_session()
     try:
@@ -278,6 +347,7 @@ def stage3_extraction(self, video_id: str) -> str:
         system_prompt = _load_prompt("stage3_extraction.txt")
         llm = _get_llm_client()
         model_override, modality = _get_stage_config(3)
+        hard_limit = get_settings().llm_max_tokens_hard_limit
         logger.info("Stage 3 using model=%s, modality=%s", model_override or "default", modality)
         total_moments = 0
 
@@ -295,8 +365,9 @@ def stage3_extraction(self, video_id: str) -> str:
                 f"<segment>\n{segment_text}\n</segment>"
             )
 
-            raw = llm.complete(system_prompt, user_prompt, response_model=ExtractionResult,
-                               modality=modality, model_override=model_override)
+            max_tokens = estimate_max_tokens(system_prompt, user_prompt, stage="stage3_extraction", hard_limit=hard_limit)
+            raw = llm.complete(system_prompt, user_prompt, response_model=ExtractionResult, on_complete=_make_llm_callback(video_id, "stage3_extraction"),
+                               modality=modality, model_override=model_override, max_tokens=max_tokens)
             result = _safe_parse_llm_response(raw, ExtractionResult, llm, system_prompt, user_prompt,
                                               modality=modality, model_override=model_override)
 
@@ -329,6 +400,7 @@ def stage3_extraction(self, video_id: str) -> str:
 
         session.commit()
         elapsed = time.monotonic() - start
+        _emit_event(video_id, "stage3_extraction", "complete")
         logger.info(
             "Stage 3 (extraction) completed for video_id=%s in %.1fs — %d moments created",
             video_id, elapsed, total_moments,
@@ -339,6 +411,7 @@ def stage3_extraction(self, video_id: str) -> str:
         raise
     except Exception as exc:
         session.rollback()
+        _emit_event(video_id, "stage3_extraction", "error", payload={"error": str(exc)})
         logger.error("Stage 3 failed for video_id=%s: %s", video_id, exc)
         raise self.retry(exc=exc)
     finally:
@@ -361,6 +434,7 @@ def stage4_classification(self, video_id: str) -> str:
     """
     start = time.monotonic()
     logger.info("Stage 4 (classification) starting for video_id=%s", video_id)
+    _emit_event(video_id, "stage4_classification", "start")
 
     session = _get_sync_session()
     try:
@@ -404,9 +478,11 @@ def stage4_classification(self, video_id: str) -> str:
 
         llm = _get_llm_client()
         model_override, modality = _get_stage_config(4)
-        logger.info("Stage 4 using model=%s, modality=%s", model_override or "default", modality)
-        raw = llm.complete(system_prompt, user_prompt, response_model=ClassificationResult,
-                           modality=modality, model_override=model_override)
+        hard_limit = get_settings().llm_max_tokens_hard_limit
+        max_tokens = estimate_max_tokens(system_prompt, user_prompt, stage="stage4_classification", hard_limit=hard_limit)
+        logger.info("Stage 4 using model=%s, modality=%s, max_tokens=%d", model_override or "default", modality, max_tokens)
+        raw = llm.complete(system_prompt, user_prompt, response_model=ClassificationResult, on_complete=_make_llm_callback(video_id, "stage4_classification"),
+                           modality=modality, model_override=model_override, max_tokens=max_tokens)
         result = _safe_parse_llm_response(raw, ClassificationResult, llm, system_prompt, user_prompt,
                                           modality=modality, model_override=model_override)
 
@@ -437,6 +513,7 @@ def stage4_classification(self, video_id: str) -> str:
         _store_classification_data(video_id, classification_data)
 
         elapsed = time.monotonic() - start
+        _emit_event(video_id, "stage4_classification", "complete")
         logger.info(
             "Stage 4 (classification) completed for video_id=%s in %.1fs — %d moments classified",
             video_id, elapsed, len(classification_data),
@@ -447,6 +524,7 @@ def stage4_classification(self, video_id: str) -> str:
         raise
     except Exception as exc:
         session.rollback()
+        _emit_event(video_id, "stage4_classification", "error", payload={"error": str(exc)})
         logger.error("Stage 4 failed for video_id=%s: %s", video_id, exc)
         raise self.retry(exc=exc)
     finally:
@@ -539,6 +617,7 @@ def stage5_synthesis(self, video_id: str) -> str:
     """
     start = time.monotonic()
     logger.info("Stage 5 (synthesis) starting for video_id=%s", video_id)
+    _emit_event(video_id, "stage5_synthesis", "start")
 
     settings = get_settings()
     session = _get_sync_session()
@@ -576,6 +655,7 @@ def stage5_synthesis(self, video_id: str) -> str:
         system_prompt = _load_prompt("stage5_synthesis.txt")
         llm = _get_llm_client()
         model_override, modality = _get_stage_config(5)
+        hard_limit = get_settings().llm_max_tokens_hard_limit
         logger.info("Stage 5 using model=%s, modality=%s", model_override or "default", modality)
         pages_created = 0
 
@@ -600,17 +680,39 @@ def stage5_synthesis(self, video_id: str) -> str:
 
             user_prompt = f"<moments>\n{moments_text}\n</moments>"
 
-            raw = llm.complete(system_prompt, user_prompt, response_model=SynthesisResult,
-                               modality=modality, model_override=model_override)
+            max_tokens = estimate_max_tokens(system_prompt, user_prompt, stage="stage5_synthesis", hard_limit=hard_limit)
+            raw = llm.complete(system_prompt, user_prompt, response_model=SynthesisResult, on_complete=_make_llm_callback(video_id, "stage5_synthesis"),
+                               modality=modality, model_override=model_override, max_tokens=max_tokens)
             result = _safe_parse_llm_response(raw, SynthesisResult, llm, system_prompt, user_prompt,
                                               modality=modality, model_override=model_override)
 
+            # Load prior pages from this video (snapshot taken before pipeline reset)
+            prior_page_ids = _load_prior_pages(video_id)
+
             # Create/update TechniquePage rows
             for page_data in result.pages:
-                # Check if page with this slug already exists
-                existing = session.execute(
-                    select(TechniquePage).where(TechniquePage.slug == page_data.slug)
-                ).scalar_one_or_none()
+                existing = None
+
+                # First: check prior pages from this video by creator + category
+                if prior_page_ids:
+                    existing = session.execute(
+                        select(TechniquePage).where(
+                            TechniquePage.id.in_(prior_page_ids),
+                            TechniquePage.creator_id == video.creator_id,
+                            TechniquePage.topic_category == (page_data.topic_category or category),
+                        )
+                    ).scalar_one_or_none()
+                    if existing:
+                        logger.info(
+                            "Stage 5: Matched prior page '%s' (id=%s) by creator+category for video_id=%s",
+                            existing.slug, existing.id, video_id,
+                        )
+
+                # Fallback: check by slug (handles cross-video dedup)
+                if existing is None:
+                    existing = session.execute(
+                        select(TechniquePage).where(TechniquePage.slug == page_data.slug)
+                    ).scalar_one_or_none()
 
                 if existing:
                     # Snapshot existing content before overwriting
@@ -690,6 +792,7 @@ def stage5_synthesis(self, video_id: str) -> str:
 
         session.commit()
         elapsed = time.monotonic() - start
+        _emit_event(video_id, "stage5_synthesis", "complete")
         logger.info(
             "Stage 5 (synthesis) completed for video_id=%s in %.1fs — %d pages created/updated",
             video_id, elapsed, pages_created,
@@ -700,6 +803,7 @@ def stage5_synthesis(self, video_id: str) -> str:
         raise
     except Exception as exc:
         session.rollback()
+        _emit_event(video_id, "stage5_synthesis", "error", payload={"error": str(exc)})
         logger.error("Stage 5 failed for video_id=%s: %s", video_id, exc)
         raise self.retry(exc=exc)
     finally:
@@ -837,6 +941,58 @@ def stage6_embed_and_index(self, video_id: str) -> str:
         session.close()
 
 
+
+
+def _snapshot_prior_pages(video_id: str) -> None:
+    """Save existing technique_page_ids linked to this video before pipeline resets them.
+
+    When a video is reprocessed, stage 3 deletes and recreates key_moments,
+    breaking the link to technique pages. This snapshots the page IDs to Redis
+    so stage 5 can find and update prior pages instead of creating duplicates.
+    """
+    import redis
+
+    session = _get_sync_session()
+    try:
+        # Find technique pages linked via this video's key moments
+        rows = session.execute(
+            select(KeyMoment.technique_page_id)
+            .where(
+                KeyMoment.source_video_id == video_id,
+                KeyMoment.technique_page_id.isnot(None),
+            )
+            .distinct()
+        ).scalars().all()
+
+        page_ids = [str(pid) for pid in rows]
+
+        if page_ids:
+            settings = get_settings()
+            r = redis.Redis.from_url(settings.redis_url)
+            key = f"chrysopedia:prior_pages:{video_id}"
+            r.set(key, json.dumps(page_ids), ex=86400)
+            logger.info(
+                "Snapshot %d prior technique pages for video_id=%s: %s",
+                len(page_ids), video_id, page_ids,
+            )
+        else:
+            logger.info("No prior technique pages for video_id=%s", video_id)
+    finally:
+        session.close()
+
+
+def _load_prior_pages(video_id: str) -> list[str]:
+    """Load prior technique page IDs from Redis."""
+    import redis
+
+    settings = get_settings()
+    r = redis.Redis.from_url(settings.redis_url)
+    key = f"chrysopedia:prior_pages:{video_id}"
+    raw = r.get(key)
+    if raw is None:
+        return []
+    return json.loads(raw)
+
 # ── Orchestrator ─────────────────────────────────────────────────────────────
 
 @celery_app.task
@@ -870,6 +1026,9 @@ def run_pipeline(video_id: str) -> str:
     finally:
         session.close()
 
+    # Snapshot prior technique pages before pipeline resets key_moments
+    _snapshot_prior_pages(video_id)
+
     # Build the chain based on current status
     stages = []
     if status in (ProcessingStatus.pending, ProcessingStatus.transcribed):

From c6f69019cf49ac847c142880a54a0c9dd3bbbbc2 Mon Sep 17 00:00:00 2001
From: jlightner <jlightner@ub01.a.xpltd.co>
Date: Mon, 30 Mar 2026 05:55:27 -0500
Subject: [PATCH 5/8] feat: Content hash dedup and prior-page versioning

- Add content_hash (SHA-256 of transcript text) to source_videos (migration 005)
- 3-tier duplicate detection at ingest: exact filename, content hash,
  then normalized filename + duration (handles yt-dlp re-downloads)
- Snapshot prior technique_page_ids to Redis before pipeline dispatch
- Stage 5 matches prior pages by creator+category before slug fallback,
  enabling version snapshots on reprocessing even when LLM generates
  different slugs
- Expose content_hash in API responses and admin pipeline dashboard

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 alembic/versions/005_content_hash.py | 29 +++++++++++
 backend/routers/ingest.py            | 78 ++++++++++++++++++++++++++++
 backend/schemas.py                   |  2 +
 3 files changed, 109 insertions(+)
 create mode 100644 alembic/versions/005_content_hash.py

diff --git a/alembic/versions/005_content_hash.py b/alembic/versions/005_content_hash.py
new file mode 100644
index 0000000..fe49ce2
--- /dev/null
+++ b/alembic/versions/005_content_hash.py
@@ -0,0 +1,29 @@
+"""Add content_hash to source_videos for duplicate detection.
+
+Revision ID: 005_content_hash
+Revises: 004_pipeline_events
+"""
+from alembic import op
+import sqlalchemy as sa
+
+revision = "005_content_hash"
+down_revision = "004_pipeline_events"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.add_column(
+        "source_videos",
+        sa.Column("content_hash", sa.String(64), nullable=True),
+    )
+    op.create_index(
+        "ix_source_videos_content_hash",
+        "source_videos",
+        ["content_hash"],
+    )
+
+
+def downgrade() -> None:
+    op.drop_index("ix_source_videos_content_hash")
+    op.drop_column("source_videos", "content_hash")
diff --git a/backend/routers/ingest.py b/backend/routers/ingest.py
index 77b1d1a..61b3e30 100644
--- a/backend/routers/ingest.py
+++ b/backend/routers/ingest.py
@@ -5,6 +5,7 @@ creates a Creator, upserts a SourceVideo, bulk-inserts TranscriptSegments,
 persists the raw JSON to disk, and returns a structured response.
 """
 
+import hashlib
 import json
 import logging
 import os
@@ -36,6 +37,20 @@ def slugify(value: str) -> str:
     return value
 
 
+
+def compute_content_hash(segments: list[dict]) -> str:
+    """Compute a stable SHA-256 hash from transcript segment text.
+
+    Hashes only the segment text content in order, ignoring metadata like
+    filenames, timestamps, or dates. Two transcripts of the same audio will
+    produce identical hashes even if ingested with different filenames.
+    """
+    h = hashlib.sha256()
+    for seg in segments:
+        h.update(str(seg.get("text", "")).encode("utf-8"))
+    return h.hexdigest()
+
+
 @router.post("", response_model=TranscriptIngestResponse)
 async def ingest_transcript(
     file: UploadFile,
@@ -85,6 +100,9 @@ async def ingest_transcript(
     if not isinstance(segments_data, list):
         raise HTTPException(status_code=422, detail="'segments' must be an array")
 
+    content_hash = compute_content_hash(segments_data)
+    logger.info("Content hash for %s: %s", source_file, content_hash)
+
     # ── 2. Find-or-create Creator ────────────────────────────────────────
     stmt = select(Creator).where(Creator.folder_name == creator_folder)
     result = await db.execute(stmt)
@@ -100,6 +118,7 @@ async def ingest_transcript(
         await db.flush()  # assign id
 
     # ── 3. Upsert SourceVideo ────────────────────────────────────────────
+    # First check for exact filename match (original behavior)
     stmt = select(SourceVideo).where(
         SourceVideo.creator_id == creator.id,
         SourceVideo.filename == source_file,
@@ -107,7 +126,49 @@ async def ingest_transcript(
     result = await db.execute(stmt)
     existing_video = result.scalar_one_or_none()
 
+    # Tier 2: content hash match (same audio, different filename/metadata)
+    matched_video = None
+    match_reason = None
+    if existing_video is None:
+        stmt = select(SourceVideo).where(
+            SourceVideo.content_hash == content_hash,
+        )
+        result = await db.execute(stmt)
+        matched_video = result.scalar_one_or_none()
+        if matched_video:
+            match_reason = "content_hash"
+
+    # Tier 3: filename + duration match (same yt-dlp download, re-encoded)
+    if existing_video is None and matched_video is None and duration_seconds is not None:
+        # Strip common prefixes like dates (e.g. "2023-07-19 ") and extensions
+        # to get a normalized base name for fuzzy matching
+        base_name = re.sub(r"^\d{4}-\d{2}-\d{2}\s+", "", source_file)
+        base_name = re.sub(r"\s*\(\d+p\).*$", "", base_name)  # strip resolution suffix
+        base_name = os.path.splitext(base_name)[0].strip()
+
+        stmt = select(SourceVideo).where(
+            SourceVideo.creator_id == creator.id,
+            SourceVideo.duration_seconds == duration_seconds,
+        )
+        result = await db.execute(stmt)
+        candidates = result.scalars().all()
+        for candidate in candidates:
+            cand_name = re.sub(r"^\d{4}-\d{2}-\d{2}\s+", "", candidate.filename)
+            cand_name = re.sub(r"\s*\(\d+p\).*$", "", cand_name)
+            cand_name = os.path.splitext(cand_name)[0].strip()
+            if cand_name == base_name:
+                matched_video = candidate
+                match_reason = "filename+duration"
+                break
+
     is_reupload = existing_video is not None
+    is_duplicate_content = matched_video is not None
+
+    if is_duplicate_content:
+        logger.info(
+            "Duplicate detected via %s: '%s' matches existing video '%s' (%s)",
+            match_reason, source_file, matched_video.filename, matched_video.id,
+        )
 
     if is_reupload:
         video = existing_video
@@ -118,7 +179,22 @@ async def ingest_transcript(
             )
         )
         video.duration_seconds = duration_seconds
+        video.content_hash = content_hash
         video.processing_status = ProcessingStatus.transcribed
+    elif is_duplicate_content:
+        # Same content, different filename — update the existing record
+        video = matched_video
+        await db.execute(
+            delete(TranscriptSegment).where(
+                TranscriptSegment.source_video_id == video.id
+            )
+        )
+        video.filename = source_file
+        video.file_path = f"{creator_folder}/{source_file}"
+        video.duration_seconds = duration_seconds
+        video.content_hash = content_hash
+        video.processing_status = ProcessingStatus.transcribed
+        is_reupload = True  # Treat as reupload for response
     else:
         video = SourceVideo(
             creator_id=creator.id,
@@ -126,6 +202,7 @@ async def ingest_transcript(
             file_path=f"{creator_folder}/{source_file}",
             duration_seconds=duration_seconds,
             content_type=ContentType.tutorial,
+            content_hash=content_hash,
             processing_status=ProcessingStatus.transcribed,
         )
         db.add(video)
@@ -203,4 +280,5 @@ async def ingest_transcript(
         segments_stored=len(segment_objs),
         processing_status=video.processing_status.value,
         is_reupload=is_reupload,
+        content_hash=content_hash,
     )
diff --git a/backend/schemas.py b/backend/schemas.py
index 256c5ee..2a9b29c 100644
--- a/backend/schemas.py
+++ b/backend/schemas.py
@@ -63,6 +63,7 @@ class SourceVideoRead(SourceVideoBase):
 
     id: uuid.UUID
     creator_id: uuid.UUID
+    content_hash: str | None = None
     processing_status: str = "pending"
     created_at: datetime
     updated_at: datetime
@@ -184,6 +185,7 @@ class TranscriptIngestResponse(BaseModel):
     segments_stored: int
     processing_status: str
     is_reupload: bool
+    content_hash: str
 
 
 # ── Pagination wrapper ───────────────────────────────────────────────────────

From 08d7d19d0efdd3fef6694aa7b9f7c484bb6e2e87 Mon Sep 17 00:00:00 2001
From: jlightner <jlightner@ub01.a.xpltd.co>
Date: Mon, 30 Mar 2026 05:55:42 -0500
Subject: [PATCH 6/8] =?UTF-8?q?fix:=20Nginx=20resolver=20for=20Docker=20DN?=
 =?UTF-8?q?S=20=E2=80=94=20prevent=20stale=20upstream=20IPs?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Use Docker embedded DNS (127.0.0.11) with 30s TTL and variable-based
proxy_pass so nginx re-resolves the API container IP after recreates
instead of caching the startup IP forever.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 docker/nginx.conf | 12 +++++++++---
 1 file changed, 9 insertions(+), 3 deletions(-)

diff --git a/docker/nginx.conf b/docker/nginx.conf
index 8efc8a8..3dd642d 100644
--- a/docker/nginx.conf
+++ b/docker/nginx.conf
@@ -4,14 +4,19 @@ server {
     root /usr/share/nginx/html;
     index index.html;
 
+    # Use Docker's embedded DNS with 30s TTL so upstream IPs refresh
+    # after container recreates
+    resolver 127.0.0.11 valid=30s ipv6=off;
+
     # SPA fallback
     location / {
         try_files $uri $uri/ /index.html;
     }
 
-    # API proxy
+    # API proxy — variable forces nginx to re-resolve on each request
     location /api/ {
-        proxy_pass http://chrysopedia-api:8000;
+        set $backend http://chrysopedia-api:8000;
+        proxy_pass $backend;
         proxy_set_header Host $host;
         proxy_set_header X-Real-IP $remote_addr;
         proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
@@ -19,6 +24,7 @@ server {
     }
 
     location /health {
-        proxy_pass http://chrysopedia-api:8000;
+        set $backend http://chrysopedia-api:8000;
+        proxy_pass $backend;
     }
 }

From e8bc3fd9a2d03a27934df35a8fc93b50fceed96b Mon Sep 17 00:00:00 2001
From: jlightner <jlightner@ub01.a.xpltd.co>
Date: Mon, 30 Mar 2026 11:46:52 -0500
Subject: [PATCH 7/8] feat(whisper): add batch_transcribe.py and document
 HAL0022 transcription setup

- batch_transcribe.py: recursive multi-creator transcription runner that
  walks nested subdirectories, attributes creator from top-level folder name,
  writes batch_manifest.json with timing and per-creator results
- README.md: updated with batch mode docs, HAL0022 environment details,
  transcript output location (C:\Users\jlightner\chrysopedia\transcripts),
  scheduled task usage, and transfer instructions for ub01 ingestion
---
 whisper/README.md           | 137 ++++++++++++++--
 whisper/batch_transcribe.py | 319 ++++++++++++++++++++++++++++++++++++
 2 files changed, 446 insertions(+), 10 deletions(-)
 create mode 100644 whisper/batch_transcribe.py

diff --git a/whisper/README.md b/whisper/README.md
index 03a7179..40e36e3 100644
--- a/whisper/README.md
+++ b/whisper/README.md
@@ -18,12 +18,18 @@ sudo apt install ffmpeg
 
 # macOS
 brew install ffmpeg
+
+# Windows (via chocolatey or manual install)
+choco install ffmpeg
 ```
 
 ### Install Python dependencies
 
 ```bash
 pip install -r requirements.txt
+
+# For CUDA support, install torch with CUDA wheels:
+pip install torch --index-url https://download.pytorch.org/whl/cu126
 ```
 
 ## Usage
@@ -40,7 +46,29 @@ python transcribe.py --input "path/to/video.mp4" --output-dir ./transcripts
 python transcribe.py --input ./videos/ --output-dir ./transcripts
 ```
 
-### Options
+### Mass batch mode (recursive, multi-creator)
+
+For large content libraries with nested subdirectories per creator:
+
+```bash
+python batch_transcribe.py \
+  --content-root "A:\Education\Artist Streams & Content" \
+  --output-dir "C:\Users\jlightner\chrysopedia\transcripts" \
+  --python C:\Users\jlightner\.conda\envs\transcribe\python.exe
+
+# Dry run to preview without transcribing:
+python batch_transcribe.py --content-root ... --output-dir ... --dry-run
+```
+
+`batch_transcribe.py` recursively walks all subdirectories, discovers video
+files, and calls `transcribe.py` for each directory. The `creator_folder`
+field in the output JSON is set to the top-level subdirectory name (the
+artist/creator). Output directory structure mirrors the source hierarchy.
+
+A `batch_manifest.json` is written to the output root on completion with
+timing, per-creator results, and error details.
+
+### Options (transcribe.py)
 
 | Flag            | Default     | Description                                     |
 | --------------- | ----------- | ----------------------------------------------- |
@@ -51,9 +79,21 @@ python transcribe.py --input ./videos/ --output-dir ./transcripts
 | `--creator`     | (inferred)  | Override creator folder name in output JSON      |
 | `-v, --verbose` | off         | Enable debug logging                             |
 
+### Options (batch_transcribe.py)
+
+| Flag              | Default      | Description                                      |
+| ----------------- | ------------ | ------------------------------------------------ |
+| `--content-root`  | (required)   | Root directory with creator subdirectories        |
+| `--output-dir`    | (required)   | Root output directory for transcript JSONs        |
+| `--script`        | (auto)       | Path to transcribe.py (default: same directory)   |
+| `--python`        | (auto)       | Python interpreter to use                         |
+| `--model`         | `large-v3`   | Whisper model name                                |
+| `--device`        | `cuda`       | Compute device                                    |
+| `--dry-run`       | off          | Preview work plan without transcribing            |
+
 ## Output Format
 
-Each video produces a JSON file matching the Chrysopedia spec:
+Each video produces a JSON file matching the Chrysopedia pipeline spec:
 
 ```json
 {
@@ -74,29 +114,106 @@ Each video produces a JSON file matching the Chrysopedia spec:
 }
 ```
 
+This format is consumed directly by the Chrysopedia pipeline stage 2
+(transcript segmentation) via the `POST /api/v1/ingest` endpoint.
+
 ## Resumability
 
-The script automatically skips videos whose output JSON already exists. To
+Both scripts automatically skip videos whose output JSON already exists. To
 re-transcribe a file, delete its output JSON first.
 
+## Current Transcription Environment
+
+### Machine: HAL0022 (10.0.0.131)
+
+- **GPU:** NVIDIA GeForce RTX 4090 (24GB VRAM)
+- **OS:** Windows 11
+- **Python:** Conda env `transcribe` at `C:\Users\jlightner\.conda\envs\transcribe\python.exe`
+- **CUDA:** PyTorch with cu126 wheels
+
+### Content Source
+
+```
+A:\Education\Artist Streams & Content\
+├── au5/           (334 videos)
+├── Keota/         (193 videos)
+├── DJ Shortee/    (83 videos)
+├── KOAN Sound/    (68 videos)
+├── Teddy Killerz/ (62 videos)
+├── ... (42 creators, 1197 videos total across 146 directories)
+```
+
+### Transcript Output Location
+
+```
+C:\Users\jlightner\chrysopedia\transcripts\
+```
+
+Directory structure mirrors the source hierarchy. Each video produces a
+`<filename>.json` transcript file.
+
+**Transfer to ub01:** Transcripts need to be copied to
+`/vmPool/r/services/chrysopedia_data/transcripts/` on ub01 for pipeline
+ingestion. This can be done via SMB (`\\ub01\vmPool\services\chrysopedia_data\transcripts`)
+or via `scp`/`rsync` from a Linux machine with access to both.
+
+### Running the Batch Job
+
+The batch transcription runs as a Windows Scheduled Task to survive SSH
+disconnections:
+
+```powershell
+# The task is already created. To re-run:
+schtasks /run /tn "ChrysopediaTranscribe"
+
+# Check status:
+schtasks /query /tn "ChrysopediaTranscribe" /v /fo list | findstr /i "status result"
+
+# Monitor log:
+Get-Content 'C:\Users\jlightner\chrysopedia\transcription.log' -Tail 30
+
+# Or follow live:
+Get-Content 'C:\Users\jlightner\chrysopedia\transcription.log' -Tail 20 -Wait
+```
+
+### Scripts on HAL0022
+
+```
+C:\Users\jlightner\chrysopedia\
+├── transcribe.py          # Single-file/directory transcription
+├── batch_transcribe.py    # Recursive multi-creator batch runner
+├── run_transcription.bat  # Batch file invoked by scheduled task
+├── launch_transcription.py # Alternative launcher (subprocess)
+├── transcription.log      # Current batch run log output
+└── transcripts/           # Output directory
+    ├── batch_manifest.json
+    ├── au5/
+    ├── Break/
+    └── ...
+```
+
 ## Performance
 
 Whisper large-v3 on an RTX 4090 processes audio at roughly 10–20× real-time.
-A 2-hour video takes ~6–12 minutes. For 300 videos averaging 1.5 hours each,
-the initial transcription pass takes roughly 15–40 hours of GPU time.
+A 2-hour video takes ~6–12 minutes. For the full 1,197-video library, expect
+roughly 20–60 hours of GPU time depending on average video length.
 
 ## Directory Convention
 
 The script infers the `creator_folder` field from the parent directory of each
-video file. Organize videos like:
+video file (or the top-level creator folder in batch mode). Organize videos like:
 
 ```
-videos/
+content-root/
 ├── Skope/
-│   ├── Sound Design Masterclass pt1.mp4
-│   └── Sound Design Masterclass pt2.mp4
+│   ├── Youtube/
+│   │   ├── Sound Design Masterclass pt1.mp4
+│   │   └── Sound Design Masterclass pt2.mp4
+│   └── Patreon/
+│       └── Advanced Wavetables.mp4
 ├── Mr Bill/
-│   └── Glitch Techniques.mp4
+│   └── Youtube/
+│       └── Glitch Techniques.mp4
 ```
 
 Override with `--creator` when processing files outside this structure.
diff --git a/whisper/batch_transcribe.py b/whisper/batch_transcribe.py
new file mode 100644
index 0000000..6e536fa
--- /dev/null
+++ b/whisper/batch_transcribe.py
@@ -0,0 +1,319 @@
+#!/usr/bin/env python3
+"""
+Chrysopedia — Batch Transcription Runner
+
+Recursively iterates all creator subdirectories under a content root and runs
+transcribe.py against each leaf directory containing videos. Outputs are
+written to a parallel directory structure under --output-dir that mirrors
+the source hierarchy:
+
+    output-dir/
+    ├── au5/
+    │   ├── Patreon/
+    │   │   ├── video1.mp4.json
+    │   │   └── video2.mp4.json
+    │   └── Youtube/
+    │       └── ...
+    ├── Skope/
+    │   └── ...
+
+The --creator flag passed to transcribe.py is always the top-level folder
+name (the artist), regardless of subdirectory nesting depth.
+
+Resumable: transcribe.py already skips videos whose output JSON exists.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import logging
+import os
+import subprocess
+import sys
+import time
+from datetime import datetime, timezone
+from pathlib import Path
+
+LOG_FORMAT = "%(asctime)s [%(levelname)s] %(message)s"
+logging.basicConfig(format=LOG_FORMAT, level=logging.INFO)
+logger = logging.getLogger("chrysopedia.batch_transcribe")
+
+SUPPORTED_EXTENSIONS = {".mp4", ".mkv", ".avi", ".mov", ".webm", ".flv", ".wmv"}
+
+
+def find_video_dirs(content_root: Path) -> list[dict]:
+    """
+    Recursively find all directories containing video files.
+    Returns list of dicts with folder path, creator name, and video count.
+    """
+    results = []
+    for dirpath, dirnames, filenames in os.walk(content_root):
+        dirpath = Path(dirpath)
+        videos = [
+            f for f in filenames
+            if Path(f).suffix.lower() in SUPPORTED_EXTENSIONS
+        ]
+        if not videos:
+            continue
+
+        # Creator is always the top-level subdirectory under content_root
+        rel = dirpath.relative_to(content_root)
+        creator = rel.parts[0]
+
+        results.append({
+            "folder": dirpath,
+            "creator": creator,
+            "rel_path": rel,
+            "video_count": len(videos),
+        })
+
+    return sorted(results, key=lambda x: (x["creator"], str(x["rel_path"])))
+
+
+def count_existing_transcripts(output_dir: Path) -> int:
+    """Count existing transcript JSONs in an output folder."""
+    if not output_dir.exists():
+        return 0
+    return sum(1 for p in output_dir.iterdir() if p.suffix == ".json")
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(
+        description="Batch transcription runner for Chrysopedia"
+    )
+    parser.add_argument(
+        "--content-root",
+        required=True,
+        help="Root directory containing creator subdirectories with videos",
+    )
+    parser.add_argument(
+        "--output-dir",
+        required=True,
+        help="Root output directory for transcript JSONs",
+    )
+    parser.add_argument(
+        "--script",
+        default=None,
+        help="Path to transcribe.py (default: same directory as this script)",
+    )
+    parser.add_argument(
+        "--python",
+        default=sys.executable,
+        help="Python interpreter to use (default: current interpreter)",
+    )
+    parser.add_argument(
+        "--model",
+        default="large-v3",
+        help="Whisper model name (default: large-v3)",
+    )
+    parser.add_argument(
+        "--device",
+        default="cuda",
+        help="Compute device (default: cuda)",
+    )
+    parser.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="List what would be transcribed without running",
+    )
+    args = parser.parse_args()
+
+    content_root = Path(args.content_root)
+    output_root = Path(args.output_dir)
+    script_path = Path(args.script) if args.script else Path(__file__).parent / "transcribe.py"
+
+    if not content_root.is_dir():
+        logger.error("Content root does not exist: %s", content_root)
+        return 1
+
+    if not script_path.is_file():
+        logger.error("transcribe.py not found at: %s", script_path)
+        return 1
+
+    # Discover all directories with videos (recursive)
+    video_dirs = find_video_dirs(content_root)
+
+    if not video_dirs:
+        logger.warning("No video files found anywhere under %s", content_root)
+        return 0
+
+    # Build work plan with existing transcript counts
+    total_videos = 0
+    total_existing = 0
+    work_plan = []
+
+    for item in video_dirs:
+        # Output mirrors the relative source structure
+        out_dir = output_root / item["rel_path"]
+        n_existing = count_existing_transcripts(out_dir)
+        n_remaining = item["video_count"] - n_existing
+
+        total_videos += item["video_count"]
+        total_existing += n_existing
+
+        work_plan.append({
+            **item,
+            "output": out_dir,
+            "existing": n_existing,
+            "remaining": n_remaining,
+        })
+
+    # Aggregate by creator for summary
+    creator_stats = {}
+    for item in work_plan:
+        c = item["creator"]
+        if c not in creator_stats:
+            creator_stats[c] = {"videos": 0, "existing": 0, "remaining": 0, "dirs": 0}
+        creator_stats[c]["videos"] += item["video_count"]
+        creator_stats[c]["existing"] += item["existing"]
+        creator_stats[c]["remaining"] += item["remaining"]
+        creator_stats[c]["dirs"] += 1
+
+    logger.info("=" * 70)
+    logger.info("BATCH TRANSCRIPTION PLAN")
+    logger.info("=" * 70)
+    logger.info("Content root:  %s", content_root)
+    logger.info("Output root:   %s", output_root)
+    logger.info("Creators:      %d", len(creator_stats))
+    logger.info("Directories:   %d", len(work_plan))
+    logger.info("Total videos:  %d", total_videos)
+    logger.info("Already done:  %d", total_existing)
+    logger.info("Remaining:     %d", total_videos - total_existing)
+    logger.info("=" * 70)
+
+    for name in sorted(creator_stats.keys()):
+        s = creator_stats[name]
+        status = "DONE" if s["remaining"] == 0 else f"{s['remaining']} to do"
+        logger.info(
+            "  %-35s %4d videos (%d dirs), %4d done  [%s]",
+            name, s["videos"], s["dirs"], s["existing"], status,
+        )
+
+    logger.info("=" * 70)
+
+    if args.dry_run:
+        logger.info("DRY RUN — exiting without transcribing.")
+        return 0
+
+    # Execute
+    manifest = {
+        "started_at": datetime.now(timezone.utc).isoformat(),
+        "content_root": str(content_root),
+        "output_root": str(output_root),
+        "model": args.model,
+        "device": args.device,
+        "results": [],
+    }
+
+    total_processed = 0
+    total_skipped = 0
+    total_failed_dirs = 0
+    batch_start = time.time()
+
+    for i, item in enumerate(work_plan, 1):
+        if item["remaining"] == 0:
+            logger.info("[%d/%d] SKIP %s (all %d videos already transcribed)",
+                        i, len(work_plan), item["rel_path"], item["video_count"])
+            total_skipped += item["video_count"]
+            continue
+
+        logger.info("=" * 70)
+        logger.info("[%d/%d] TRANSCRIBING: %s  (creator: %s)",
+                    i, len(work_plan), item["rel_path"], item["creator"])
+        logger.info("  %d videos, %d remaining",
+                    item["video_count"], item["remaining"])
+        logger.info("=" * 70)
+
+        dir_start = time.time()
+
+        cmd = [
+            args.python,
+            str(script_path),
+            "--input", str(item["folder"]),
+            "--output-dir", str(item["output"]),
+            "--model", args.model,
+            "--device", args.device,
+            "--creator", item["creator"],
+        ]
+
+        try:
+            result = subprocess.run(
+                cmd,
+                capture_output=False,
+                text=True,
+                timeout=14400,  # 4-hour timeout per directory
+            )
+            dir_elapsed = time.time() - dir_start
+
+            n_after = count_existing_transcripts(item["output"])
+            n_new = n_after - item["existing"]
+
+            manifest["results"].append({
+                "creator": item["creator"],
+                "rel_path": str(item["rel_path"]),
+                "videos": item["video_count"],
+                "new_transcripts": n_new,
+                "total_transcripts": n_after,
+                "exit_code": result.returncode,
+                "elapsed_seconds": round(dir_elapsed, 1),
+            })
+
+            if result.returncode == 0:
+                total_processed += n_new
+                total_skipped += item["existing"]
+                logger.info("Completed %s: %d new transcripts in %.1f s",
+                            item["rel_path"], n_new, dir_elapsed)
+            else:
+                total_failed_dirs += 1
+                logger.error("FAILED %s (exit code %d) after %.1f s",
+                             item["rel_path"], result.returncode, dir_elapsed)
+
+        except subprocess.TimeoutExpired:
+            total_failed_dirs += 1
+            logger.error("TIMEOUT: %s exceeded 4-hour limit", item["rel_path"])
+            manifest["results"].append({
+                "creator": item["creator"],
+                "rel_path": str(item["rel_path"]),
+                "videos": item["video_count"],
+                "error": "timeout",
+            })
+        except Exception as exc:
+            total_failed_dirs += 1
+            logger.exception("ERROR processing %s: %s", item["rel_path"], exc)
+            manifest["results"].append({
+                "creator": item["creator"],
+                "rel_path": str(item["rel_path"]),
+                "videos": item["video_count"],
+                "error": str(exc),
+            })
+
+    batch_elapsed = time.time() - batch_start
+    manifest["completed_at"] = datetime.now(timezone.utc).isoformat()
+    manifest["elapsed_seconds"] = round(batch_elapsed, 1)
+    manifest["summary"] = {
+        "processed": total_processed,
+        "skipped": total_skipped,
+        "failed_dirs": total_failed_dirs,
+    }
+
+    # Write manifest
+    manifest_path = output_root / "batch_manifest.json"
+    output_root.mkdir(parents=True, exist_ok=True)
+    with open(manifest_path, "w", encoding="utf-8") as f:
+        json.dump(manifest, f, indent=2, ensure_ascii=False)
+
+    logger.info("=" * 70)
+    logger.info("BATCH COMPLETE")
+    logger.info("  Processed:    %d new transcripts", total_processed)
+    logger.info("  Skipped:      %d (already existed)", total_skipped)
+    logger.info("  Failed dirs:  %d", total_failed_dirs)
+    logger.info("  Elapsed:      %.1f s (%.1f hours)", batch_elapsed, batch_elapsed / 3600)
+    logger.info("  Manifest:     %s", manifest_path)
+    logger.info("=" * 70)
+
+    return 1 if total_failed_dirs > 0 else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

From 64ff263da289d31046464cf6fc256b99df23f4fc Mon Sep 17 00:00:00 2001
From: jlightner <jlightner@ub01.a.xpltd.co>
Date: Mon, 30 Mar 2026 14:27:02 -0500
Subject: [PATCH 8/8] docs: Rewrite README with information flow stages and
 updated architecture

Replaces outdated README with streamlined version covering all 8 services,
complete API endpoints, 6-stage information flow diagram, and current
project structure.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 README.md | 514 +++++++++++++++++++++++++++---------------------------
 1 file changed, 256 insertions(+), 258 deletions(-)

diff --git a/README.md b/README.md
index f0b4568..58d6e84 100644
--- a/README.md
+++ b/README.md
@@ -3,320 +3,318 @@
 > From *chrysopoeia* (alchemical transmutation of base material into gold) + *encyclopedia*.
 > Chrysopedia transmutes raw video content into refined, searchable production knowledge.
 
-A self-hosted knowledge extraction and retrieval system for electronic music production content. Transcribes video libraries with Whisper, extracts key moments and techniques with LLM analysis, and serves a search-first web UI for mid-session retrieval.
+A self-hosted knowledge extraction system for electronic music production content. Video libraries are transcribed with Whisper, analyzed through a multi-stage LLM pipeline, curated via an admin review workflow, and served through a search-first web UI designed for mid-session retrieval.
+
+---
+
+## Information Flow
+
+Content moves through six stages from raw video to searchable knowledge:
+
+```
+ ┌─────────────────────────────────────────────────────────────────────────┐
+ │  STAGE 1 · Transcription                            [Desktop / GPU]    │
+ │                                                                         │
+ │  Video files → Whisper large-v3 (CUDA) → JSON transcripts              │
+ │  Output: timestamped segments with speaker text                         │
+ └────────────────────────────────┬────────────────────────────────────────┘
+                                  │ JSON files (manual or folder watcher)
+                                  ▼
+ ┌─────────────────────────────────────────────────────────────────────────┐
+ │  STAGE 2 · Ingestion                                [API + Watcher]    │
+ │                                                                         │
+ │  POST /api/v1/ingest ← watcher auto-submits from /watch folder         │
+ │  • Validate JSON structure                                              │
+ │  • Compute content hash (SHA-256) for deduplication                     │
+ │  • Find-or-create Creator from folder name                              │
+ │  • Upsert SourceVideo (exact filename → content hash → fuzzy match)     │
+ │  • Bulk-insert TranscriptSegment rows                                   │
+ │  • Dispatch pipeline to Celery worker                                   │
+ └────────────────────────────────┬────────────────────────────────────────┘
+                                  │ Celery task: run_pipeline(video_id)
+                                  ▼
+ ┌─────────────────────────────────────────────────────────────────────────┐
+ │  STAGE 3 · LLM Extraction Pipeline                  [Celery Worker]    │
+ │                                                                         │
+ │  Four sequential LLM stages, each with its own prompt template:         │
+ │                                                                         │
+ │  3a. Segmentation — Split transcript into semantic topic boundaries     │
+ │      Model: chat (fast)         Prompt: stage2_segmentation.txt         │
+ │                                                                         │
+ │  3b. Extraction — Identify key moments (title, summary, timestamps)     │
+ │      Model: reasoning (think)   Prompt: stage3_extraction.txt           │
+ │                                                                         │
+ │  3c. Classification — Assign content types + extract plugin names       │
+ │      Model: chat (fast)         Prompt: stage4_classification.txt       │
+ │                                                                         │
+ │  3d. Synthesis — Compose technique pages from approved moments          │
+ │      Model: reasoning (think)   Prompt: stage5_synthesis.txt            │
+ │                                                                         │
+ │  Each stage emits PipelineEvent rows (tokens, duration, model, errors)  │
+ └────────────────────────────────┬────────────────────────────────────────┘
+                                  │ KeyMoment rows (review_status: pending)
+                                  ▼
+ ┌─────────────────────────────────────────────────────────────────────────┐
+ │  STAGE 4 · Review & Curation                        [Admin UI]         │
+ │                                                                         │
+ │  Admin reviews extracted KeyMoments before they become technique pages:  │
+ │  • Approve — moment proceeds to synthesis                               │
+ │  • Edit — correct title, summary, content type, plugins, then approve   │
+ │  • Reject — moment is excluded from knowledge base                      │
+ │  (When REVIEW_MODE=false, moments auto-approve and skip this stage)     │
+ └────────────────────────────────┬────────────────────────────────────────┘
+                                  │ Approved moments → Stage 3d synthesis
+                                  ▼
+ ┌─────────────────────────────────────────────────────────────────────────┐
+ │  STAGE 5 · Knowledge Base                           [Web UI]           │
+ │                                                                         │
+ │  TechniquePages — the primary output:                                   │
+ │  • Structured body sections, signal chains, plugin lists                │
+ │  • Linked to source KeyMoments with video timestamps                    │
+ │  • Cross-referenced via RelatedTechniqueLinks                           │
+ │  • Versioned (snapshots before each re-synthesis)                       │
+ │  • Organized by topic taxonomy (6 categories from canonical_tags.yaml)  │
+ └────────────────────────────────┬────────────────────────────────────────┘
+                                  │
+                                  ▼
+ ┌─────────────────────────────────────────────────────────────────────────┐
+ │  STAGE 6 · Search & Retrieval                       [Web UI]           │
+ │                                                                         │
+ │  • Semantic search: query → embedding → Qdrant vector similarity        │
+ │  • Keyword fallback: ILIKE search on title/summary (300ms timeout)      │
+ │  • Browse by topic hierarchy, creator, or content type                  │
+ │  • Typeahead search from home page (debounced, top 5 results)           │
+ └─────────────────────────────────────────────────────────────────────────┘
+```
 
 ---
 
 ## Architecture
 
 ```
-┌──────────────────────────────────────────────────────────────────┐
-│  Desktop (GPU workstation)                                       │
-│  ┌──────────────┐                                                │
-│  │ whisper/      │  Transcribes video → JSON (Whisper large-v3)  │
-│  │ transcribe.py │  Runs locally with CUDA, outputs to /data     │
-│  └──────┬───────┘                                                │
-│         │ JSON transcripts                                       │
-└─────────┼────────────────────────────────────────────────────────┘
-          │
-          ▼
-┌──────────────────────────────────────────────────────────────────┐
-│  Docker Compose (xpltd_chrysopedia) — Server (e.g. ub01)         │
-│                                                                  │
-│  ┌────────────────┐  ┌────────────────┐  ┌──────────────────┐   │
-│  │ chrysopedia-db │  │chrysopedia-redis│  │ chrysopedia-api  │   │
-│  │ PostgreSQL 16  │  │  Redis 7       │  │ FastAPI + Uvicorn│   │
-│  │ :5433→5432     │  │                │  │ :8000            │   │
-│  └────────────────┘  └────────────────┘  └────────┬─────────┘   │
-│                                                    │             │
-│  ┌──────────────────┐  ┌──────────────────────┐    │             │
-│  │ chrysopedia-web  │  │ chrysopedia-worker   │    │             │
-│  │ React + nginx    │  │ Celery (LLM pipeline)│    │             │
-│  │ :3000→80         │  │                      │    │             │
-│  └──────────────────┘  └──────────────────────┘    │             │
-│                                                    │             │
-│  Network: chrysopedia (172.24.0.0/24)              │             │
-└──────────────────────────────────────────────────────────────────┘
+┌──────────────────────────────────────────────────────────────────────────┐
+│  Desktop (GPU workstation — hal0022)                                     │
+│  whisper/transcribe.py → JSON transcripts → copy to /watch folder        │
+└────────────────────────────┬─────────────────────────────────────────────┘
+                             │
+                             ▼
+┌──────────────────────────────────────────────────────────────────────────┐
+│  Docker Compose: xpltd_chrysopedia (ub01)                                │
+│  Network: chrysopedia (172.32.0.0/24)                                    │
+│                                                                          │
+│  ┌────────────┐  ┌─────────────┐  ┌───────────────┐  ┌──────────────┐  │
+│  │  PostgreSQL │  │    Redis    │  │    Qdrant     │  │    Ollama    │  │
+│  │  :5433      │  │  broker +   │  │  vector DB    │  │  embeddings  │  │
+│  │  7 entities │  │  cache      │  │  semantic     │  │  nomic-embed │  │
+│  └─────┬───────┘  └──────┬──────┘  └───────┬───────┘  └──────┬───────┘  │
+│        │                 │                 │                 │           │
+│  ┌─────┴─────────────────┴─────────────────┴─────────────────┴────────┐  │
+│  │                         FastAPI (API)                              │  │
+│  │  Ingest · Pipeline control · Review · Search · CRUD · Reports     │  │
+│  └──────────────────────────────┬────────────────────────────────────┘  │
+│                                 │                                       │
+│  ┌──────────────┐  ┌────────────┴───┐  ┌──────────────────────────┐    │
+│  │   Watcher    │  │  Celery Worker │  │     Web UI (React)       │    │
+│  │  /watch →    │  │  LLM pipeline  │  │  nginx → :8096           │    │
+│  │  auto-ingest │  │  stages 2-5    │  │  search-first interface  │    │
+│  └──────────────┘  └────────────────┘  └──────────────────────────┘    │
+└──────────────────────────────────────────────────────────────────────────┘
 ```
 
 ### Services
 
-| Service              | Image / Build          | Port          | Purpose                                    |
-|----------------------|------------------------|---------------|--------------------------------------------|
-| `chrysopedia-db`     | `postgres:16-alpine`   | `5433 → 5432` | Primary data store (7 entity schema)       |
-| `chrysopedia-redis`  | `redis:7-alpine`       | —             | Celery broker / cache                      |
-| `chrysopedia-api`    | `docker/Dockerfile.api`| `8000`        | FastAPI REST API                           |
-| `chrysopedia-worker` | `docker/Dockerfile.api`| —             | Celery worker for LLM pipeline stages 2-5  |
-| `chrysopedia-web`    | `docker/Dockerfile.web`| `3000 → 80`  | React frontend (nginx)                     |
+| Service | Image | Port | Purpose |
+|---------|-------|------|---------|
+| `chrysopedia-db` | `postgres:16-alpine` | `5433 → 5432` | Primary data store |
+| `chrysopedia-redis` | `redis:7-alpine` | — | Celery broker + feature flag cache |
+| `chrysopedia-qdrant` | `qdrant/qdrant:v1.13.2` | — | Vector DB for semantic search |
+| `chrysopedia-ollama` | `ollama/ollama` | — | Embedding model server (nomic-embed-text) |
+| `chrysopedia-api` | `Dockerfile.api` | `8000` | FastAPI REST API |
+| `chrysopedia-worker` | `Dockerfile.api` | — | Celery worker (LLM pipeline) |
+| `chrysopedia-watcher` | `Dockerfile.api` | — | Folder monitor → auto-ingest |
+| `chrysopedia-web` | `Dockerfile.web` | `8096 → 80` | React frontend (nginx) |
 
-### Data Model (7 entities)
+### Data Model
 
-- **Creator** — artists/producers whose content is indexed
-- **SourceVideo** — original video files processed by the pipeline
-- **TranscriptSegment** — timestamped text segments from Whisper
-- **KeyMoment** — discrete insights extracted by LLM analysis
-- **TechniquePage** — synthesized knowledge pages (primary output)
-- **RelatedTechniqueLink** — cross-references between technique pages
-- **Tag** — hierarchical topic/genre taxonomy
-
----
-
-## Prerequisites
-
-- **Docker** ≥ 24.0 and **Docker Compose** ≥ 2.20
-- **Python 3.10+** (for the Whisper transcription script)
-- **ffmpeg** (for audio extraction)
-- **NVIDIA GPU + CUDA** (recommended for Whisper; CPU fallback available)
+| Entity | Purpose |
+|--------|---------|
+| **Creator** | Artists/producers whose content is indexed |
+| **SourceVideo** | Video files processed by the pipeline (with content hash dedup) |
+| **TranscriptSegment** | Timestamped text segments from Whisper |
+| **KeyMoment** | Discrete insights extracted by LLM analysis |
+| **TechniquePage** | Synthesized knowledge pages — the primary output |
+| **TechniquePageVersion** | Snapshots before re-synthesis overwrites |
+| **RelatedTechniqueLink** | Cross-references between technique pages |
+| **Tag** | Hierarchical topic taxonomy |
+| **ContentReport** | User-submitted content issues |
+| **PipelineEvent** | Structured pipeline execution logs (tokens, timing, errors) |
 
 ---
 
 ## Quick Start
 
-### 1. Clone and configure
+### Prerequisites
+
+- Docker ≥ 24.0 and Docker Compose ≥ 2.20
+- Python 3.10+ with NVIDIA GPU + CUDA (for Whisper transcription)
+
+### Setup
 
 ```bash
-git clone <repository-url>
-cd content-to-kb-automator
+# Clone and configure
+git clone git@github.com:xpltdco/chrysopedia.git
+cd chrysopedia
+cp .env.example .env    # edit with real values
 
-# Create environment file from template
-cp .env.example .env
-# Edit .env with your actual values (see Environment Variables below)
-```
-
-### 2. Start the Docker Compose stack
-
-```bash
+# Start the stack
 docker compose up -d
+
+# Run database migrations
+docker exec chrysopedia-api alembic upgrade head
+
+# Pull the embedding model (first time only)
+docker exec chrysopedia-ollama ollama pull nomic-embed-text
+
+# Verify
+curl http://localhost:8096/health
 ```
 
-This starts PostgreSQL, Redis, the API server, the Celery worker, and the web UI.
-
-### 3. Run database migrations
+### Transcribe videos
 
 ```bash
-# From inside the API container:
-docker compose exec chrysopedia-api alembic upgrade head
-
-# Or locally (requires Python venv with backend deps):
-alembic upgrade head
-```
-
-### 4. Verify the stack
-
-```bash
-# Health check (with DB connectivity)
-curl http://localhost:8000/health
-
-# API health (lightweight, no DB)
-curl http://localhost:8000/api/v1/health
-
-# Docker Compose status
-docker compose ps
-```
-
-### 5. Transcribe videos (desktop)
-
-```bash
-cd whisper
-pip install -r requirements.txt
+cd whisper && pip install -r requirements.txt
 
 # Single file
 python transcribe.py --input "path/to/video.mp4" --output-dir ./transcripts
 
-# Batch (all videos in a directory)
+# Batch
 python transcribe.py --input ./videos/ --output-dir ./transcripts
 ```
 
-See [`whisper/README.md`](whisper/README.md) for full transcription documentation.
+See [`whisper/README.md`](whisper/README.md) for full transcription docs.
 
 ---
 
 ## Environment Variables
 
-Create `.env` from `.env.example`. All variables have sensible defaults for local development.
+Copy `.env.example` to `.env`. Key groups:
 
-### Database
-
-| Variable           | Default        | Description                     |
-|--------------------|----------------|---------------------------------|
-| `POSTGRES_USER`    | `chrysopedia`  | PostgreSQL username             |
-| `POSTGRES_PASSWORD`| `changeme`     | PostgreSQL password             |
-| `POSTGRES_DB`      | `chrysopedia`  | Database name                   |
-| `DATABASE_URL`     | *(composed)*   | Full async connection string    |
-
-### Services
-
-| Variable        | Default                            | Description              |
-|-----------------|------------------------------------|--------------------------|
-| `REDIS_URL`     | `redis://chrysopedia-redis:6379/0` | Redis connection string  |
-
-### LLM Configuration
-
-| Variable            | Default                                   | Description                        |
-|---------------------|-------------------------------------------|------------------------------------|
-| `LLM_API_URL`       | `https://friend-openwebui.example.com/api`| Primary LLM endpoint (OpenAI-compatible) |
-| `LLM_API_KEY`       | `sk-changeme`                             | API key for primary LLM            |
-| `LLM_MODEL`         | `qwen2.5-72b`                             | Primary model name                 |
-| `LLM_FALLBACK_URL`  | `http://localhost:11434/v1`               | Fallback LLM endpoint (Ollama)     |
-| `LLM_FALLBACK_MODEL`| `qwen2.5:14b-q8_0`                       | Fallback model name                |
-
-### Embedding / Vector
-
-| Variable              | Default                       | Description              |
-|-----------------------|-------------------------------|--------------------------|
-| `EMBEDDING_API_URL`   | `http://localhost:11434/v1`   | Embedding endpoint       |
-| `EMBEDDING_MODEL`     | `nomic-embed-text`            | Embedding model name     |
-| `QDRANT_URL`          | `http://qdrant:6333`          | Qdrant vector DB URL     |
-| `QDRANT_COLLECTION`   | `chrysopedia`                 | Qdrant collection name   |
-
-### Application
-
-| Variable                 | Default                          | Description                    |
-|--------------------------|----------------------------------|--------------------------------|
-| `APP_ENV`                | `production`                     | Environment (`development` / `production`) |
-| `APP_LOG_LEVEL`          | `info`                           | Log level                      |
-| `APP_SECRET_KEY`         | `changeme-generate-a-real-secret`| Application secret key         |
-| `TRANSCRIPT_STORAGE_PATH`| `/data/transcripts`             | Transcript JSON storage path   |
-| `VIDEO_METADATA_PATH`    | `/data/video_meta`              | Video metadata storage path    |
-| `REVIEW_MODE`            | `true`                           | Enable human review workflow   |
-
----
-
-## Development Workflow
-
-### Local development (without Docker)
-
-```bash
-# Create virtual environment
-python -m venv .venv
-source .venv/bin/activate
-
-# Install backend dependencies
-pip install -r backend/requirements.txt
-
-# Start PostgreSQL and Redis (via Docker)
-docker compose up -d chrysopedia-db chrysopedia-redis
-
-# Run migrations
-alembic upgrade head
-
-# Start the API server with hot-reload
-cd backend && uvicorn main:app --reload --host 0.0.0.0 --port 8000
-```
-
-### Database migrations
-
-```bash
-# Create a new migration after model changes
-alembic revision --autogenerate -m "describe_change"
-
-# Apply all pending migrations
-alembic upgrade head
-
-# Rollback one migration
-alembic downgrade -1
-```
-
-### Project structure
-
-```
-content-to-kb-automator/
-├── backend/               # FastAPI application
-│   ├── main.py            # App entry point, middleware, routers
-│   ├── config.py          # pydantic-settings configuration
-│   ├── database.py        # SQLAlchemy async engine + session
-│   ├── models.py          # 7-entity ORM models
-│   ├── schemas.py         # Pydantic request/response schemas
-│   ├── routers/           # API route handlers
-│   │   ├── health.py      # /health (DB check)
-│   │   ├── creators.py    # /api/v1/creators
-│   │   └── videos.py      # /api/v1/videos
-│   └── requirements.txt   # Python dependencies
-├── whisper/               # Desktop transcription script
-│   ├── transcribe.py      # Whisper CLI tool
-│   ├── requirements.txt   # Whisper + ffmpeg deps
-│   └── README.md          # Transcription documentation
-├── docker/                # Dockerfiles
-│   ├── Dockerfile.api     # FastAPI + Celery image
-│   ├── Dockerfile.web     # React + nginx image
-│   └── nginx.conf         # nginx reverse proxy config
-├── alembic/               # Database migrations
-│   ├── env.py             # Migration environment
-│   └── versions/          # Migration scripts
-├── config/                # Configuration files
-│   └── canonical_tags.yaml # 6 topic categories + genre taxonomy
-├── prompts/               # LLM prompt templates (editable)
-├── frontend/              # React web UI (placeholder)
-├── tests/                 # Test fixtures and test suites
-│   └── fixtures/          # Sample data for testing
-├── docker-compose.yml     # Full stack definition
-├── alembic.ini            # Alembic configuration
-├── .env.example           # Environment variable template
-└── chrysopedia-spec.md    # Full project specification
-```
+| Group | Variables | Notes |
+|-------|-----------|-------|
+| **Database** | `POSTGRES_USER`, `POSTGRES_PASSWORD`, `POSTGRES_DB` | Default user: `chrysopedia` |
+| **LLM** | `LLM_API_URL`, `LLM_API_KEY`, `LLM_MODEL` | OpenAI-compatible endpoint |
+| **LLM Fallback** | `LLM_FALLBACK_URL`, `LLM_FALLBACK_MODEL` | Automatic failover |
+| **Per-Stage Models** | `LLM_STAGE{2-5}_MODEL`, `LLM_STAGE{2-5}_MODALITY` | `chat` for fast stages, `thinking` for reasoning |
+| **Embedding** | `EMBEDDING_API_URL`, `EMBEDDING_MODEL` | Ollama nomic-embed-text |
+| **Vector DB** | `QDRANT_URL`, `QDRANT_COLLECTION` | Container-internal |
+| **Features** | `REVIEW_MODE`, `DEBUG_MODE` | Review gate + LLM I/O capture |
+| **Storage** | `TRANSCRIPT_STORAGE_PATH`, `VIDEO_METADATA_PATH` | Container bind mounts |
 
 ---
 
 ## API Endpoints
 
-| Method | Path                        | Description                     |
-|--------|-----------------------------|---------------------------------|
-| GET    | `/health`                   | Health check with DB connectivity |
-| GET    | `/api/v1/health`            | Lightweight health (no DB)      |
-| GET    | `/api/v1/creators`          | List all creators               |
-| GET    | `/api/v1/creators/{slug}`   | Get creator by slug             |
-| GET    | `/api/v1/videos`            | List all source videos          |
+### Public
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/health` | Health check (DB connectivity) |
+| GET | `/api/v1/search?q=&scope=&limit=` | Semantic + keyword search |
+| GET | `/api/v1/techniques` | List technique pages |
+| GET | `/api/v1/techniques/{slug}` | Technique detail + key moments |
+| GET | `/api/v1/techniques/{slug}/versions` | Version history |
+| GET | `/api/v1/creators` | List creators (sort, genre filter) |
+| GET | `/api/v1/creators/{slug}` | Creator detail |
+| GET | `/api/v1/topics` | Topic hierarchy with counts |
+| GET | `/api/v1/videos` | List source videos |
+| POST | `/api/v1/reports` | Submit content report |
+
+### Admin
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/api/v1/review/queue` | Review queue (status filter) |
+| POST | `/api/v1/review/moments/{id}/approve` | Approve key moment |
+| POST | `/api/v1/review/moments/{id}/reject` | Reject key moment |
+| PUT | `/api/v1/review/moments/{id}` | Edit key moment |
+| POST | `/api/v1/admin/pipeline/trigger/{video_id}` | Trigger/retrigger pipeline |
+| GET | `/api/v1/admin/pipeline/events/{video_id}` | Pipeline event log |
+| GET | `/api/v1/admin/pipeline/token-summary/{video_id}` | Token usage by stage |
+| GET | `/api/v1/admin/pipeline/worker-status` | Celery worker status |
+| PUT | `/api/v1/admin/pipeline/debug-mode` | Toggle debug mode |
+
+### Ingest
+
+| Method | Path | Description |
+|--------|------|-------------|
+| POST | `/api/v1/ingest` | Upload Whisper JSON transcript |
 
 ---
 
-## XPLTD Conventions
+## Development
 
-This project follows XPLTD infrastructure conventions:
+```bash
+# Local backend (with Docker services)
+python -m venv .venv && source .venv/bin/activate
+pip install -r backend/requirements.txt
+docker compose up -d chrysopedia-db chrysopedia-redis
+alembic upgrade head
+cd backend && uvicorn main:app --reload --host 0.0.0.0 --port 8000
 
-- **Docker project name:** `xpltd_chrysopedia`
-- **Bind mounts:** persistent data stored under `/vmPool/r/services/`
-- **Network:** dedicated bridge `chrysopedia` (`172.32.0.0/24`)
-- **PostgreSQL host port:** `5433` (avoids conflict with system PostgreSQL on `5432`)
+# Database migrations
+alembic revision --autogenerate -m "describe_change"
+alembic upgrade head
+```
+
+### Project Structure
+
+```
+chrysopedia/
+├── backend/                 # FastAPI application
+│   ├── main.py              # Entry point, middleware, router mounting
+│   ├── config.py            # Pydantic Settings (all env vars)
+│   ├── models.py            # SQLAlchemy ORM models
+│   ├── schemas.py           # Pydantic request/response schemas
+│   ├── worker.py            # Celery app configuration
+│   ├── watcher.py           # Transcript folder watcher service
+│   ├── search_service.py    # Semantic search + keyword fallback
+│   ├── routers/             # API endpoint handlers
+│   ├── pipeline/            # LLM pipeline stages + clients
+│   │   ├── stages.py        # Stages 2-5 (Celery tasks)
+│   │   ├── llm_client.py    # OpenAI-compatible LLM client
+│   │   ├── embedding_client.py
+│   │   └── qdrant_client.py
+│   └── tests/
+├── frontend/                # React + TypeScript + Vite
+│   └── src/
+│       ├── pages/           # Home, Search, Technique, Creator, Topic, Admin
+│       ├── components/      # Shared UI components
+│       └── api/             # Typed API clients
+├── whisper/                 # Desktop transcription (Whisper large-v3)
+├── docker/                  # Dockerfiles + nginx config
+├── alembic/                 # Database migrations
+├── config/                  # canonical_tags.yaml (topic taxonomy)
+├── prompts/                 # LLM prompt templates (editable at runtime)
+├── docker-compose.yml
+└── .env.example
+```
 
 ---
 
 ## Deployment (ub01)
 
-The production stack runs on **ub01.a.xpltd.co**:
-
 ```bash
-# Clone (first time only — requires SSH agent forwarding)
-ssh -A ub01
+ssh ub01
 cd /vmPool/r/repos/xpltdco/chrysopedia
-git clone git@github.com:xpltdco/chrysopedia.git .
-
-# Create .env from template
-cp .env.example .env
-# Edit .env with production secrets
-
-# Build and start
-docker compose build
-docker compose up -d
-
-# Run migrations
-docker exec chrysopedia-api alembic upgrade head
-
-# Pull embedding model (first time only)
-docker exec chrysopedia-ollama ollama pull nomic-embed-text
+git pull && docker compose build && docker compose up -d
 ```
 
-### Service URLs
-| Service | URL |
-|---------|-----|
-| Web UI | http://ub01:8096 |
-| API Health | http://ub01:8096/health |
-| PostgreSQL | ub01:5433 |
+| Resource | Location |
+|----------|----------|
+| Web UI | `http://ub01:8096` |
+| API | `http://ub01:8096/health` |
+| PostgreSQL | `ub01:5433` |
 | Compose config | `/vmPool/r/compose/xpltd_chrysopedia/docker-compose.yml` |
+| Persistent data | `/vmPool/r/services/chrysopedia_*` |
 
-### Update Workflow
-```bash
-ssh -A ub01
-cd /vmPool/r/repos/xpltdco/chrysopedia
-git pull
-docker compose build && docker compose up -d
-```
+XPLTD conventions: `xpltd_chrysopedia` project name, dedicated bridge network (`172.32.0.0/24`), bind mounts under `/vmPool/r/services/`, PostgreSQL on port `5433`.