Add post-midterm course content and refactor topic card curation

AGENTS.md

@@ -10,29 +10,32 @@ Technical handoff for coding agents and contributors working on this repository.
 - No backend/runtime services required
 - Source dataset and generated card data are JSON files in repo
 
-## Current Snapshot (2026-02-27)
+## Current Snapshot (2026-03-21)
 
-- `topic_cards.json`: **28 total cards**
-- Default exam deck (`only exam topics`): **21 cards**
+- `topic_cards.json`: **174 total cards**
+- `deck_groups`: **6** (`week-1` through `week-6`)
+- Weeks covered in the dataset: **1-6**
+- Exam-topic cards (`exam_stats.total_hits > 0`): **136**
 - Duplicate normalized topic labels: **0**
-- Exam-topic key points: **198**
-- Exam-topic key points with optional details: **198/198**
-- Optional key-point detail blocks: **247**
+- Total key points across all cards: **935**
+- Optional key-point detail blocks: **256**
 
 Curation state:
 
-- All 21 exam-topic cards were curated using an evidence-driven pass over exam + lecture + notebook + trap data.
+- Weeks `4-6` and post-midterm/final assessment material are already imported into `data/study_db.json`.
+- Raw-material ingestion is now AI-first for `.pptx`, `.ipynb`, `.py` + `.txt`, and messy `.pdf` sources.
 - `key_points_to_remember` and `ai_examples` are intentionally **variable-length** by topic based on evidence coverage.
 - There is no fixed per-topic cap for key points/examples.
-- Optional key-point `details` are enabled and intentionally selectable in the UI (example/table/explanation/commands).
-- Exact duplicate key-point text and exact duplicate example code blocks across exam topics were removed.
+- Optional key-point `details` remain intentionally selectable in the UI (`example`, `table`, `explanation`, `commands`).
+- Exact duplicate key-point text and exact duplicate example code blocks were removed.
 - Example code blocks for exam topics and key-point detail code blocks were syntax-checked.
-- A parallel Gemini generation+audit pass plus manual review was used to improve optional detail coverage and quality.
+- Duplicate user-facing topic labels were cleaned up so cards are easier to scan in the explorer sidebar.
 
 ## App Behavior
 
-- Swipe workflow for keep/reject topic cards
-- Detail selection per card (key points, examples, snippets)
+- Topic Explorer workflow with a left week/topic sidebar and a main topic-detail pane
+- Item-first selection model: users select concrete key points, examples, and snippets inside each topic
+- Preview cards are derived only from selected renderable items; empty preview cards should not exist by design
 - 2-page A4 preview with draggable/resizable cards
 - Preview editing controls for card/item edit+delete with undo (`Undo Edit`, `Ctrl/Cmd+Z`)
 - Preview card lock/unlock control to freeze position/size while editing
@@ -44,13 +47,14 @@ Curation state:
 
 Storage keys:
 
-- `python_midterm_app_state_v1`
-- `python_midterm_splash_seen_v1`
+- `python_midterm_app_state_v4`
+- `python_midterm_splash_seen_v3`
 
 ## Core Files
 
 - `index.html`: app shell and major sections
 - `app/`: split frontend logic modules (loaded in order via deferred scripts)
+- `app/topic-selection.js`: selection normalization, useful-item filtering, and preview-eligibility projection
 - `scripts/smoke_ui_playwright.js`: browser smoke test (isolated Playwright install workflow)
 - `scripts/stress_layout_playwright.js`: exhaustive layout stress test workflow
 - `scripts/gemini_test_protocol.py`: complete automated UI QA protocol (hard gates + Gemini micro-audits)
@@ -64,6 +68,7 @@ Storage keys:
 - `topic_cards.json`: curated card dataset consumed by UI
 - `data/study_db.json`: canonical structured source database
 - `materials/`: raw lectures/notebooks/exam files
+- `design_inspo/stitch_exports/`: exported Stitch reference screens used to guide the explorer redesign
 
 Generation/processing scripts:
 
@@ -122,6 +127,14 @@ Useful flags:
 - `--allow-missing-sources`: bypass strict source-path existence checks
 - `--replace-existing`: replace an existing week entry
 
+Raw-material ingestion / import helpers:
+
+```bash
+python3 scripts/ingest_raw_materials.py
+python3 scripts/validate_extracted_material.py
+python3 scripts/import_extracted_materials.py
+```
+
 ## Curation Rules (Important)
 
 When editing `topic_cards.json`:
@@ -187,6 +200,7 @@ python3 scripts/check_file_lengths.py
 python3 scripts/maintenance_audit.py
 python3 -m unittest discover -s tests -v
 make smoke-ui
+make full-ui
 make stress-layout-ui
 make gemini-ui-protocol
 make gemini-benchmark
@@ -282,13 +296,17 @@ PY
 2. `Get Started` dismisses splash
 3. `Reset intro` reopens splash
 4. Refresh preserves progress
-5. Swipe counts and filters behave correctly
+5. Topic Explorer sidebar behaves correctly:
+   - only one week is expanded by default
+   - topic navigation changes the main pane correctly
+   - selected-item counts update without any keep/reject flow
 6. Preview drag/resize persists
 7. Preview edit/delete actions can be undone via button and `Ctrl/Cmd+Z`; modal text edits keep native in-field undo behavior
 8. `Print` generates and prints a PDF (not raw page print)
 9. PDF export/print both show custom support prompt only after successful save/print trigger (not before)
 10. Exported cheat sheet view has no wasted chrome: no edit/delete/resize controls and no oversized title bars.
-11. Gemini protocol report (`data/test_reports/gemini_ui_test_report.json`) is green and has no fail checks.
+11. Preview contains only topics with selected content; no empty fallback cards render.
+12. Gemini protocol report (`data/test_reports/gemini_ui_test_report.json`) is green and has no fail checks.
 
 ## Contributor Notes
 

DESIGN.md

@@ -0,0 +1,5 @@
+# Design Spec Pointer
+
+The canonical design-system spec for this project lives in `design_inspo/DESIGN.md`.
+
+This root file exists as a stable entry point for contributors and agents. Update the canonical file first, then only expand this pointer if the repo later needs a distinct root-level summary.

Makefile

@@ -1,4 +1,8 @@
-.PHONY: check-js check-py check-lines test smoke-ui stress-layout-ui export-canvas-guard-ui gemini-ui-protocol gemini-benchmark gemini-prompt-experiments gemini-health quality-dashboard maintenance-audit leave-better leave-better-ui validate
+.PHONY: check-js check-py check-lines test setup-playwright smoke-ui full-ui stress-layout-ui export-canvas-guard-ui gemini-ui-protocol gemini-benchmark gemini-prompt-experiments gemini-health quality-dashboard maintenance-audit leave-better leave-better-ui validate
+
+PW_TMP := /tmp/pwtmp
+PW_NODE_PATH := $(PW_TMP)/node_modules
+PW_CLI := $(PW_NODE_PATH)/.bin/playwright
 
 check-js:
 	node --check app/state-and-init.js
@@ -18,11 +22,12 @@ check-js:
 	node --check app/main.js
 	node --check scripts/export_canvas_guard_playwright.js
 	node --check scripts/smoke_ui_playwright.js
+	node --check scripts/full_ui_playwright.js
 	node --check scripts/stress_layout_playwright.js
 
 check-py:
 	python3 -m py_compile build_topic_cards.py generate_ai_sections.py generate_key_points_and_recommendations.py enrich_key_point_details.py
-	python3 -m py_compile scripts/add_week_material.py scripts/migrate_study_database.py scripts/gemini_test_protocol.py scripts/maintenance_audit.py scripts/gemini_capability_benchmark.py scripts/gemini_prompt_experiments.py scripts/gemini_model_health.py scripts/quality_dashboard.py
+	python3 -m py_compile scripts/add_week_material.py scripts/migrate_study_database.py scripts/gemini_test_protocol.py scripts/maintenance_audit.py scripts/gemini_capability_benchmark.py scripts/gemini_prompt_experiments.py scripts/gemini_model_health.py scripts/quality_dashboard.py scripts/validate_extracted_material.py
 	python3 -m py_compile $$(find pipelines -name '*.py' -type f)
 
 check-lines:
@@ -31,26 +36,25 @@ check-lines:
 test:
 	python3 -m unittest discover -s tests -v
 
-smoke-ui:
-	mkdir -p /tmp/pwtmp
-	npm install --prefix /tmp/pwtmp playwright --silent
-	/tmp/pwtmp/node_modules/.bin/playwright install chromium
-	NODE_PATH=/tmp/pwtmp/node_modules node scripts/smoke_ui_playwright.js
+setup-playwright:
+	mkdir -p $(PW_TMP)
+	npm install --prefix $(PW_TMP) playwright
+	$(PW_CLI) install chromium
+
+smoke-ui: setup-playwright
+	NODE_PATH=$(PW_NODE_PATH) node scripts/smoke_ui_playwright.js
+
+full-ui: setup-playwright
+	NODE_PATH=$(PW_NODE_PATH) node scripts/full_ui_playwright.js
 
-stress-layout-ui:
-	mkdir -p /tmp/pwtmp
-	npm install --prefix /tmp/pwtmp playwright --silent
-	/tmp/pwtmp/node_modules/.bin/playwright install chromium
-	NODE_PATH=/tmp/pwtmp/node_modules node scripts/stress_layout_playwright.js
+stress-layout-ui: setup-playwright
+	NODE_PATH=$(PW_NODE_PATH) node scripts/stress_layout_playwright.js
 
-export-canvas-guard-ui:
-	mkdir -p /tmp/pwtmp
-	npm install --prefix /tmp/pwtmp playwright --silent
-	/tmp/pwtmp/node_modules/.bin/playwright install chromium
-	NODE_PATH=/tmp/pwtmp/node_modules node scripts/export_canvas_guard_playwright.js
+export-canvas-guard-ui: setup-playwright
+	NODE_PATH=$(PW_NODE_PATH) node scripts/export_canvas_guard_playwright.js
 
 gemini-ui-protocol:
-	python3 scripts/gemini_test_protocol.py --canvas-cmd "make export-canvas-guard-ui"
+	python3 scripts/gemini_test_protocol.py --canvas-cmd "make export-canvas-guard-ui" --full-cmd "make full-ui"
 
 gemini-benchmark:
 	python3 scripts/gemini_capability_benchmark.py
@@ -69,6 +73,6 @@ maintenance-audit:
 
 leave-better: validate
 
-leave-better-ui: validate smoke-ui stress-layout-ui maintenance-audit
+leave-better-ui: validate full-ui smoke-ui stress-layout-ui maintenance-audit
 
 validate: check-js check-py check-lines test maintenance-audit