# Requirements

## R001 — Whisper Transcription Pipeline
**Status:** validated
**Description:** Desktop Python script that accepts video files (MP4/MKV), extracts audio via ffmpeg, runs Whisper large-v3 on RTX 4090, and outputs timestamped transcript JSON with segment-level timestamps and word-level timing. Must be resumable.
**Validation:** Script processes a sample video and produces valid JSON with timestamped segments.
**Primary Owner:** M001/S01

## R002 — Transcript Ingestion API
**Status:** validated
**Description:** FastAPI endpoint that accepts transcript JSON uploads, creates/updates Creator and Source Video records, and stores transcript data in PostgreSQL. Handles new creator detection from folder names.
**Validation:** POST transcript JSON → 200 OK, records created in DB, file stored on filesystem.
**Primary Owner:** M001/S02

## R003 — LLM-Powered Extraction Pipeline (Stages 2-5)
**Status:** validated
**Description:** Background worker pipeline: transcript segmentation → key moment extraction → classification/tagging → technique page synthesis. Uses OpenAI-compatible API with primary (DGX Sparks Qwen) and fallback (local Ollama) endpoints. Pipeline must be resumable per-video per-stage.
**Validation:** End-to-end: transcript JSON in → technique pages with key moments, tags, and cross-references out.
**Primary Owner:** M001/S03

## R004 — Review Queue UI
**Status:** validated
**Description:** Admin interface for reviewing extracted key moments: approve, edit+approve, split, merge, reject. Organized by source video for contextual review. Includes mode toggle (review vs auto-publish).
**Validation:** Admin can review, edit, and approve/reject moments; mode toggle controls whether new moments require review.
**Primary Owner:** M001/S04

## R005 — Search-First Web UI
**Status:** validated
**Description:** Landing page with prominent search bar, live typeahead (results after 2-3 chars), scope toggle (All/Topics/Creators), and two navigation cards (Topics, Creators). Recently added section. Search powered by Qdrant semantic search with keyword fallback.
**Validation:** User types query → results appear within 500ms, grouped by type, with clickable navigation.
**Primary Owner:** M001/S05

## R006 — Technique Page Display
**Status:** validated
**Description:** Core content unit: header (tags, title, creator, meta), study guide prose (organized by sub-aspects with signal chain blocks and quotes), key moments index (timestamped list), related techniques, plugins referenced. Amber banner for livestream-sourced content.
**Validation:** Technique page renders with all sections populated from synthesized data.
**Primary Owner:** M001/S05

## R007 — Creators Browse Page
**Status:** validated
**Description:** Filterable creator list with genre filter pills, type-to-narrow, sort options (randomized default, alphabetical, view count). Each row: name, genre tags, technique count, video count, view count. Links to creator detail page.
**Validation:** Page loads with randomized order, genre filtering works, clicking row navigates to creator detail.
**Primary Owner:** M001/S05

## R008 — Topics Browse Page
**Status:** validated
**Description:** Two-level topic hierarchy (7 top-level categories → sub-topics). Filter input, genre filter pills. Each sub-topic shows technique count and creator count. Clicking sub-topic loads a dedicated page with creator-grouped techniques and breadcrumbs.
**Validation:** Hierarchy renders, filtering works, sub-topics have dedicated pages at /topics/:category/:subtopic with backend filtering and creator grouping. Verified: M010/S01.
**Primary Owner:** M001/S05

## R009 — Qdrant Vector Search Integration
**Status:** validated
**Description:** Embed key moment summaries, technique page content, and transcript segments in Qdrant using configurable embedding model (nomic-embed-text default). Power semantic search with metadata filtering.
**Validation:** Semantic search returns relevant results for natural language queries; embeddings update when content changes.
**Primary Owner:** M001/S03

## R010 — Docker Compose Deployment
**Status:** validated
**Description:** Single docker-compose.yml packaging API, web UI, PostgreSQL, and worker services. Follows XPLTD conventions: bind mounts at /vmPool/r/services/, compose at /vmPool/r/compose/chrysopedia/, xpltd_chrysopedia project name, dedicated Docker network.
**Validation:** `docker compose up -d` brings up all services; data persists across restarts.
**Primary Owner:** M001/S01

## R011 — Canonical Tag System
**Status:** validated
**Description:** Editable canonical tag list (config file) with aliases. Pipeline references tags during classification. New tags can be proposed by LLM and queued for admin approval or auto-added within existing categories.
**Validation:** Tag list is editable; pipeline uses canonical tags consistently; alias normalization works.
**Primary Owner:** M001/S03

## R012 — Incremental Content Addition
**Status:** validated
**Description:** System handles ongoing content: new videos processed through pipeline, new creators auto-detected, existing technique pages updated when new moments are added for same creator+topic.
**Validation:** Adding a new video for an existing creator updates their technique pages; new creator folder creates new Creator record.
**Primary Owner:** M001/S03

## R013 — Prompt Template System
**Status:** validated
**Description:** Extraction prompts (stages 2-5) stored as editable configuration files, not hardcoded. Admin can edit prompts and re-run extraction on specific or all videos for calibration.
**Validation:** Prompt files are editable; re-processing a video with updated prompts produces different output.
**Primary Owner:** M001/S03

## R014 — Creator Equity
**Status:** validated
**Description:** No creator is privileged in the UI. Default sort on Creators page is randomized on every page load. All creators get equal visual weight.
**Validation:** Refreshing Creators page shows different order each time; no creator gets larger/bolder display.
**Primary Owner:** M001/S05

## R015 — 30-Second Retrieval Target
**Status:** active
**Description:** A producer mid-session can find a specific technique in under 30 seconds from Alt+Tab to reading the key insight.
**Validation:** Timed test: Alt+Tab → search → read technique → under 30 seconds.
**Primary Owner:** M001/S05

## R016 — Card Hover Animations & Staggered Entrance
**Status:** validated
**Description:** All technique/content cards animate on hover (scale + shadow transition). Card grids use staggered fade-in-up entrance animations on page load.
**Validation:** Cards visually respond to hover with smooth 200ms transition. Grid cards appear sequentially on page load.
**Primary Owner:** M011/S01

## R017 — Featured Technique Visual Redesign
**Status:** validated
**Description:** Featured Technique section on homepage has a visually distinct treatment (gradient border, glow, or full-bleed) that differentiates it from ordinary cards.
**Validation:** Featured technique is visually prominent and clearly distinct from regular technique cards.
**Primary Owner:** M011/S01

## R018 — Random Technique Discovery
**Status:** validated
**Description:** A "Random Technique" button exists that navigates to a randomly selected technique page.
**Validation:** Clicking the button loads a different technique each time.
**Primary Owner:** M011/S01

## R019 — Topics Page Default-Collapsed
**Status:** validated
**Description:** Topics page loads with all categories collapsed, showing only category cards. Clicking a category expands its sub-topics with a smooth slide animation.
**Validation:** Page loads collapsed. Click expands with animation. Click again collapses.
**Primary Owner:** M011/S02

## R020 — Global Search in Navigation
**Status:** validated
**Description:** A compact search input in the navigation bar is available on all pages except the homepage. Cmd+K (or /) keyboard shortcut focuses it from any page.
**Validation:** Search bar visible in nav on Topics, Creators, Technique, About pages. Cmd+K focuses it.
**Primary Owner:** M011/S03

## R021 — Mobile Hamburger Menu
**Status:** validated
**Description:** Navigation uses a hamburger menu on viewports below 768px with generous touch targets (44×44px minimum).
**Validation:** Mobile viewport shows hamburger icon. Tapping reveals nav items. Touch targets meet minimum size.
**Primary Owner:** M011/S03

## R022 — Heading Hierarchy Fix
**Status:** validated
**Description:** Every page has exactly one H1 element. Heading levels are sequential (no skips from H1 to H3).
**Validation:** DOM inspection confirms single H1 per page and sequential heading levels.
**Primary Owner:** M011/S04

## R023 — Skip-to-Content Link
**Status:** validated
**Description:** A visually hidden skip link is the first focusable element on every page, visible on keyboard focus.
**Validation:** Tab from page load shows "Skip to content" link. Clicking it jumps to main content area.
**Primary Owner:** M011/S04

## R024 — Text Contrast AA Compliance
**Status:** validated
**Description:** All text meets WCAG AA contrast ratios (4.5:1 for normal text, 3:1 for large text) against the dark background.
**Validation:** Secondary text color passes 4.5:1 contrast check against page background.
**Primary Owner:** M011/S04

## R025 — Page-Specific Document Titles
**Status:** validated
**Description:** Each route sets a descriptive document title (e.g., "Bass — Sound Design — Chrysopedia", "COPYCATT — Chrysopedia").
**Validation:** Browser tab shows distinct title per page. Navigating between pages updates the title.
**Primary Owner:** M011/S04

## R026 — Creator Stats Topic-Colored Pills
**Status:** validated
**Description:** Creator detail page stats line rendered as topic-colored pill badges instead of run-on text.
**Validation:** Stats show as visually distinct colored pills grouped by topic category.
**Primary Owner:** M011/S02

## R027 — Tag Overflow Limit on Cards
**Status:** validated
**Description:** Technique cards show a maximum of 4 tags, with a "+N more" indicator for additional tags.
**Validation:** Cards with >4 tags show exactly 4 plus a "+N more" badge.
**Primary Owner:** M011/S02

## R028 — Empty Subtopic Handling
**Status:** validated
**Description:** Sub-topics with 0 techniques either hidden by default or display a "Coming soon" badge.
**Validation:** Empty subtopics are visually distinguished or hidden. No dead-end clicks.
**Primary Owner:** M011/S02

## Denied / Out of Scope

## R029 — Beginner Learning Paths
**Status:** out-of-scope
**Description:** Curated beginner learning paths with skill-level tags and "New to Production?" section.
**Validation:** n/a
**Notes:** Denied — audience knows what they're looking for. Assessment F01.

## R030 — YouTube Deep Links on Key Moments
**Status:** out-of-scope
**Description:** Key moment timestamps link to source YouTube videos at the correct time.
**Validation:** n/a
**Notes:** Denied — no video URLs in data model / don't want to link out. Assessment F02.

## R031 — Hide Admin Dropdown
**Status:** out-of-scope
**Description:** Admin dropdown hidden from public visitors behind auth or flag.
**Validation:** n/a
**Notes:** Denied — fine as-is. Assessment F03.

## R032 — CTA Label Changes
**Status:** out-of-scope
**Description:** Change "Start Exploring" to more descriptive CTA text.
**Validation:** n/a
**Notes:** Denied — skipped. Assessment F15.

## R033 — Creator Last Updated Date
**Status:** validated
**Description:** Each creator shows when their latest technique page was added. Visible on Creators browse page and subtly on homepage recently-added cards.
**Validation:** Creators browse page shows "Last updated: Apr 2/3" per creator. Homepage recently-added cards show subtle date stamps. Both verified live on ub01:8096 via browser assertions.
**Primary Owner:** M015/S02

## R034 — Homepage Stats Scorecard
**Status:** validated
**Description:** Homepage displays a visual metrics block showing article count, creator count in a scorecard/metric style that communicates volume and credibility without being literal or boastful.
**Validation:** GET /api/v1/stats returns {technique_count:21, creator_count:7}. Homepage scorecard displays "21 ARTICLES" and "7 CREATORS" in cyan-on-dark design. Verified via curl and browser screenshot on ub01:8096.
**Primary Owner:** M015/S03

## R035 — Popular Search Terms Display
**Status:** validated
**Description:** Show real search terms users are using in real-time. Backend logs all search queries to PostgreSQL, caches popular queries in Redis, and exposes a trending endpoint. Frontend displays these on the homepage.
**Validation:** Backend: search_log table with real rows, GET /search/popular returns cached top-N (5-min Redis TTL). Frontend: Trending Searches homepage section with clickable pill links. End-to-end verified on ub01:8096.
**Primary Owner:** M015/S01
**Supporting Slices:** M015/S04

## R036 — Admin Dropdown Hover on Desktop
**Status:** validated
**Description:** Admin navigation dropdown opens on mouse hover at desktop viewport widths (≥768px). On mobile/touch, remains click/tap to expand.
**Validation:** AdminDropdown.tsx implements matchMedia(min-width:769px) guard with 150ms leave delay. Mobile retains tap-to-toggle. Frontend build passes with zero errors.
**Primary Owner:** M015/S05

## R037 — Landing Page Visual Consistency
**Status:** active
**Description:** Homepage has consistent max-width tracks, spacing, border-radius, and no CSS bugs (duplicate .btn rule, border-image killing border-radius). Stats scorecard has animated count-up. Section headings use unified treatment.
**Validation:** Visual comparison at 1280px and 375px shows consistent alignment, spacing, and card radius. No jagged center column. Featured card has rounded corners.
**Primary Owner:** M016/S01
**Supporting Slices:** M016/S06

## R038 — Pipeline Admin UI Fixes
**Status:** active
**Description:** Pipeline admin page: most-recent run collapse toggle works without flicker, mobile job cards don't show vertical text, stage direction chevrons visible, status filter uses button group (not text input), creator dropdown populates without 422 error.
**Validation:** Collapse toggle on most-recent run works. 375px shows truncated creator names. Chevrons between stages. Filter buttons right-aligned. Creator dropdown populated.
**Primary Owner:** M016/S02

## R039 — Brand Minimum (Favicon, OG Tags, Logo)
**Status:** active
**Description:** Site has a favicon, OG meta tags for social sharing previews, and an inline SVG logo next to "Chrysopedia" in the header.
**Validation:** Browser tab shows favicon. Sharing URL produces preview card with title/description/image. Logo visible in header.
**Primary Owner:** M016/S03

## R040 — Table of Contents Modernization
**Status:** active
**Description:** Technique page ToC uses clean indentation (no numbered counters), left accent bar, "On this page" heading, hover background states, IntersectionObserver-based active section highlighting, and sticky positioning in sidebar.
**Validation:** Navigate to a 4+ section technique page. ToC highlights current section on scroll. Sticky in sidebar. No numbering. Hover states work.
**Primary Owner:** M016/S04

## R041 — Sticky Reading Header
**Status:** active
**Description:** Thin sticky bar appears when user scrolls past the article title on technique pages. Shows article title (truncated) + current section name. Slides in/out with CSS transition. Works on mobile.
**Validation:** Scroll past title on a long technique page — reading header appears with correct section tracking. Works at 375px.
**Primary Owner:** M016/S05
