diff --git a/.dockerignore b/.dockerignore
new file mode 100644
index 0000000000000000000000000000000000000000..bdfb9857a4f2da20e38fcb2c2f4a494add1e896c
--- /dev/null
+++ b/.dockerignore
@@ -0,0 +1,51 @@
+# Python caches
+**/__pycache__/
+**/*.py[cod]
+**/*.pyo
+.venv/
+venv/
+*.egg-info/
+dist/
+build/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+
+# Node
+node_modules/
+exam-app/
+!exam-app/src/data/exams.json
+!exam-app/src/data/questions.json
+
+# Env files (set secrets in Koyeb dashboard, not baked into image)
+.env
+*.env.local
+
+# Local wiki artifacts (rebuilt at runtime)
+math_wiki.db
+math_wiki.db-shm
+math_wiki.db-wal
+math_wiki.bm25.pkl
+math_wiki.faiss
+math_wiki.meta.pkl
+backend/math_wiki.db
+
+# Dev/test artifacts
+*.png
+*.pen
+test-results/
+tests/
+docs/
+core/
+validators/
+exam-app-plan.md
+response-*.json
+.gitnexus/
+.playwright-mcp/
+.claude/
+.kilo/
+playwright.config.js
+
+# Git
+.git/
+.gitignore
diff --git a/.env.example b/.env.example
new file mode 100644
index 0000000000000000000000000000000000000000..fee382cbbcefda0306b07b3ad8f2eba28fb0c38d
--- /dev/null
+++ b/.env.example
@@ -0,0 +1,7 @@
+ANTHROPIC_BASE_URL=https://ai-router.locdo.tech
+ANTHROPIC_AUTH_TOKEN=your-auth-token-here
+ANTHROPIC_DEFAULT_OPUS_MODEL=claude-opus-4.6
+ANTHROPIC_DEFAULT_SONNET_MODEL=claude-sonnet-4.6
+ANTHROPIC_DEFAULT_HAIKU_MODEL=claude-haiku-4.5
+EMBEDDING_MODEL_NAME=BAAI/bge-m3
+EMBEDDING_DIM=1024
diff --git a/.github/workflows/admin-key-log.yml b/.github/workflows/admin-key-log.yml
new file mode 100644
index 0000000000000000000000000000000000000000..5aa2d6ede9e8398c757106fda622ec9ccc56be36
--- /dev/null
+++ b/.github/workflows/admin-key-log.yml
@@ -0,0 +1,33 @@
+name: Admin Key Log (fallback)
+
+# Fallback scheduler — fires if cron-job.org misses a run.
+# Primary scheduler: cron-job.org (POST /admin/generate-key-log, X-Cron-Secret header)
+# This workflow is a safety net only; cron-job.org is preferred.
+#
+# Required GitHub repo secrets:
+# HF_SPACE_URL — e.g. https://your-space.hf.space
+# CRON_SECRET — same value as CRON_SECRET in HF Secrets (≥32 chars)
+#
+# Schedule: 20:05 UTC Sunday = 03:05 ICT Monday (5 min after cron-job.org fires at 20:00)
+# If cron-job.org already ran, the backend will just append a duplicate line — harmless.
+
+on:
+ schedule:
+ - cron: "5 20 * * 0"
+ workflow_dispatch:
+
+jobs:
+ trigger-key-log:
+ runs-on: ubuntu-latest
+ steps:
+ - name: Trigger key log generation
+ run: |
+ HTTP_STATUS=$(curl -s -o /dev/null -w "%{http_code}" \
+ -X POST "${{ secrets.HF_SPACE_URL }}/admin/generate-key-log" \
+ -H "X-Cron-Secret: ${{ secrets.CRON_SECRET }}" \
+ -H "Content-Type: application/json")
+ echo "Response status: $HTTP_STATUS"
+ if [ "$HTTP_STATUS" != "200" ]; then
+ echo "Key log generation failed with status $HTTP_STATUS"
+ exit 1
+ fi
diff --git a/.github/workflows/demo-video.yml b/.github/workflows/demo-video.yml
new file mode 100644
index 0000000000000000000000000000000000000000..546e428f6c6e16d63ef78d9f2d934c9b86636a50
--- /dev/null
+++ b/.github/workflows/demo-video.yml
@@ -0,0 +1,92 @@
+name: Demo Video Recording
+
+on:
+ # Run automatically after Cloudflare Pages deploy completes
+ workflow_run:
+ workflows: ['Deploy to Cloudflare Pages']
+ types: [completed]
+ branches: [master]
+
+ # Also allow manual trigger for on-demand re-recording
+ workflow_dispatch:
+ inputs:
+ base_url:
+ description: 'App URL to record against (leave empty for production)'
+ required: false
+ default: 'https://exam-app-ey0.pages.dev'
+
+# Never block production deploys — this job is informational only
+jobs:
+ record-demo:
+ name: Record product demo
+ runs-on: ubuntu-latest
+ # Only run if the triggering workflow succeeded (or manual trigger)
+ if: >
+ github.event_name == 'workflow_dispatch' ||
+ github.event.workflow_run.conclusion == 'success'
+
+ # Non-blocking: demo recording failures do NOT fail the overall CI run
+ continue-on-error: true
+
+ env:
+ DEMO_BASE_URL: ${{ github.event.inputs.base_url || 'https://exam-app-ey0.pages.dev' }}
+
+ steps:
+ - name: Checkout
+ uses: actions/checkout@v4
+
+ - name: Setup Node.js
+ uses: actions/setup-node@v4
+ with:
+ node-version: '20'
+ cache: 'npm'
+ cache-dependency-path: 'exam-app/package-lock.json'
+
+ - name: Install Playwright and Chromium
+ run: npx playwright install chromium --with-deps
+
+ - name: Wait for production URL to be responsive
+ run: |
+ echo "Waiting for $DEMO_BASE_URL to respond..."
+ for i in $(seq 1 30); do
+ if curl -sf --max-time 10 "$DEMO_BASE_URL" > /dev/null 2>&1; then
+ echo "App is live after $((i * 10))s"
+ break
+ fi
+ echo "Attempt $i/30 — retrying in 10s..."
+ sleep 10
+ done
+
+ - name: Run demo recording
+ run: |
+ npx playwright test demo-video/playwright-demo.spec.ts \
+ --config demo-video/playwright.config.demo.js \
+ --project=chromium
+ env:
+ DEMO_BASE_URL: ${{ env.DEMO_BASE_URL }}
+
+ - name: Upload screenshots artifact
+ if: always()
+ uses: actions/upload-artifact@v4
+ with:
+ name: demo-screenshots-${{ github.sha }}
+ path: demo-video/screenshots/
+ retention-days: 90
+ if-no-files-found: warn
+
+ - name: Upload video recording artifact
+ if: always()
+ uses: actions/upload-artifact@v4
+ with:
+ name: demo-video-recording-${{ github.sha }}
+ path: test-results/
+ retention-days: 90
+ if-no-files-found: warn
+
+ - name: Upload HTML report on failure
+ if: failure()
+ uses: actions/upload-artifact@v4
+ with:
+ name: demo-playwright-report-${{ github.sha }}
+ path: playwright-report/
+ retention-days: 14
diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
new file mode 100644
index 0000000000000000000000000000000000000000..04533e0cc35d2b6276ce91c5b1751dfd1488e399
--- /dev/null
+++ b/.github/workflows/test.yml
@@ -0,0 +1,137 @@
+name: Tests
+
+on:
+ push:
+ branches: [master, main]
+ paths:
+ - 'backend/**'
+ - 'exam-app/**'
+ - 'requirements*.txt'
+ - '.github/workflows/test.yml'
+ pull_request:
+ branches: [master, main]
+ paths:
+ - 'backend/**'
+ - 'exam-app/**'
+ - 'requirements*.txt'
+
+jobs:
+ # ── Backend unit + integration tests ────────────────────────────────────────
+ backend-tests:
+ name: Backend Tests (Python ${{ matrix.python-version }})
+ runs-on: ubuntu-latest
+ strategy:
+ fail-fast: false
+ matrix:
+ python-version: ["3.12"]
+
+ steps:
+ - uses: actions/checkout@v4
+
+ - name: Set up Python ${{ matrix.python-version }}
+ uses: actions/setup-python@v5
+ with:
+ python-version: ${{ matrix.python-version }}
+ cache: pip
+
+ - name: Install dependencies
+ run: |
+ pip install -r requirements.txt
+ pip install -r requirements-dev.txt
+
+ - name: Run fast test suite (no live AI, no fault injection)
+ env:
+ ANTHROPIC_AUTH_TOKEN: test-token-ci
+ JWT_SECRET: ${{ secrets.JWT_SECRET || 'ci-test-secret-at-least-32-chars-long' }}
+ ADMIN_KEY: ci-admin-key
+ ADMIN_MASTER_SECRET: ""
+ SQLITE_PATH: ":memory:"
+ run: |
+ PYTHONPATH=backend python3 -m pytest backend/tests/ \
+ -m "not live_ai and not fault_injection" \
+ --tb=short \
+ -q \
+ --randomly-seed=0 \
+ -x
+
+ - name: Run fault injection tests
+ env:
+ ANTHROPIC_AUTH_TOKEN: test-token-ci
+ JWT_SECRET: ${{ secrets.JWT_SECRET || 'ci-test-secret-at-least-32-chars-long' }}
+ ADMIN_KEY: ci-admin-key
+ ADMIN_MASTER_SECRET: ""
+ SQLITE_PATH: ":memory:"
+ run: |
+ PYTHONPATH=backend python3 -m pytest backend/tests/ \
+ -m "fault_injection" \
+ --tb=short \
+ -q
+ continue-on-error: true # fault injection is informational until stabilised
+
+ # ── Frontend unit tests ──────────────────────────────────────────────────────
+ frontend-tests:
+ name: Frontend Tests (Node ${{ matrix.node-version }})
+ runs-on: ubuntu-latest
+ strategy:
+ matrix:
+ node-version: ["20"]
+
+ defaults:
+ run:
+ working-directory: exam-app
+
+ steps:
+ - uses: actions/checkout@v4
+
+ - name: Set up Node ${{ matrix.node-version }}
+ uses: actions/setup-node@v4
+ with:
+ node-version: ${{ matrix.node-version }}
+ cache: npm
+ cache-dependency-path: exam-app/package-lock.json
+
+ - name: Install dependencies
+ run: npm ci
+
+ - name: Run Vitest unit tests
+ run: npm test
+
+ # ── Mutation score gate (weekly, manual, or on demand) ───────────────────────
+ mutation-score:
+ name: Mutation Score Gate
+ runs-on: ubuntu-latest
+ if: github.event_name == 'workflow_dispatch' || github.event.schedule != ''
+ # Run manually via: gh workflow run test.yml
+ # Or add to a scheduled cron job by uncommenting below:
+ # on:
+ # schedule:
+ # - cron: '0 3 * * 1' # Monday 03:00 UTC
+
+ steps:
+ - uses: actions/checkout@v4
+
+ - uses: actions/setup-python@v5
+ with:
+ python-version: "3.12"
+ cache: pip
+
+ - name: Install dependencies
+ run: |
+ pip install -r requirements.txt
+ pip install -r requirements-dev.txt
+
+ - name: Run mutation testing
+ env:
+ ANTHROPIC_AUTH_TOKEN: test-token-ci
+ JWT_SECRET: ci-test-secret-at-least-32-chars-long
+ ADMIN_KEY: ci-admin-key
+ ADMIN_MASTER_SECRET: ""
+ run: |
+ PYTHONPATH=backend mutmut run \
+ --paths-to-mutate backend/app/agent/ \
+ --tests-dir backend/tests/ \
+ || true # mutmut exits non-zero when mutations survive — handled below
+
+ - name: Check mutation score gate
+ run: |
+ PYTHONPATH=backend python3 tools/check_mutation_score.py --min 70
diff --git a/.gitignore b/.gitignore
new file mode 100644
index 0000000000000000000000000000000000000000..55a059fa44ba8c2c7edc2cd8854171458eae47c9
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1,97 @@
+# Environment
+.env
+*.env.local
+
+# Python
+__pycache__/
+*.py[cod]
+*.pyo
+.venv/
+venv/
+*.egg-info/
+dist/
+build/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+
+# Node
+node_modules/
+exam-app/dist/
+
+# Claude Code local settings (machine-specific)
+.claude/settings.local.json
+
+# GitNexus index (regenerated via `gitnexus analyze`)
+.gitnexus/
+
+# Ingestion state (local run progress, not source)
+exam-app/scripts/ingest/state.json
+backend/scripts/ingest/ingest_state.json
+
+# Cloudflare Pages / Wrangler local state
+.wrangler/
+
+# Misc
+*.pen
+.DS_Store
+Thumbs.db
+
+# Screenshots (all root-level PNGs are dev/test artifacts)
+*.png
+# Exception: question figure images are static assets shipped with the app
+!exam-app/public/images/questions/*.png
+
+# Math wiki local artifacts (regenerated by ingest pipeline)
+math_wiki.db
+math_wiki.db-shm
+math_wiki.db-wal
+math_wiki.bm25.pkl
+math_wiki.faiss
+math_wiki.meta.pkl
+backend/math_wiki.db
+
+# Local SQLite runtime db (seeded fresh from exam-app/src/data/*.json on boot)
+backend/app.db
+
+# Crawl runtime state
+scripts/crawl_progress.json
+
+# Question image audit / crawl artifacts
+exam-app/src/data/questions.json.bak*
+tools/.kangaroo_pdfs/
+
+# Test results
+test-results/
+
+# Demo video artifacts (screenshots and recordings are CI artifacts, not source)
+demo-video/screenshots/
+demo-video/test-results/
+demo-video/*.mp4
+demo-video/*.webm
+
+# Playwright MCP cache
+.playwright-mcp/
+
+# Local dev/agent artifacts
+.claude/
+docs/
+exam-app-plan.md
+
+# Kilo Code editor state
+.kilo/
+
+# Standalone agent framework (not integrated into the app)
+core/
+
+# Unused standalone validators (not imported by backend or exam-app)
+validators/
+
+# Empty local dev API response dumps
+response-*.json
+
+# Runtime caches
+scripts/.pauls_sentences_cache.json
+
+# Serena MCP local state
+.serena/
diff --git a/.mcp.json b/.mcp.json
new file mode 100644
index 0000000000000000000000000000000000000000..5c9104c30e2eb673670b91ecca043063c38822fd
--- /dev/null
+++ b/.mcp.json
@@ -0,0 +1,16 @@
+{
+ "mcpServers": {
+ "playwright": {
+ "command": "npx",
+ "args": ["@playwright/mcp@latest", "--browser", "chromium"]
+ },
+ "shadcnspace": {
+ "type": "http",
+ "url": "https://mcp.shadcnspace.com"
+ },
+ "typeui": {
+ "type": "http",
+ "url": "https://mcp.typeui.sh"
+ }
+ }
+}
diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000000000000000000000000000000000000..aefc4411ae1d912a692bb68c1e5e4e20bbb8c808
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,47 @@
+## Auth & Credit System — removed
+
+The auth, JWT, credits, subscription tiers, and admin moderation system this section used to document was deleted in the 2026-08-23 strip-to-exam-core pass. There is no auth, no credits, no admin API in this codebase anymore — see `CLAUDE.md` for the current minimal backend surface (`/health`, `/exams`, `/exams/{id}`, `/questions`, `/questions/batch`).
+
+
+# GitNexus — Code Intelligence
+
+This project is indexed by GitNexus as **AI-Agent-App** (2554 symbols, 3939 relationships, 79 execution flows). Use the GitNexus MCP tools to understand code, assess impact, and navigate safely.
+
+> Index stale? Run `node .gitnexus/run.cjs analyze` from the project root — it auto-selects an available runner. No `.gitnexus/run.cjs` yet? `npx gitnexus analyze` (npm 11 crash → `npm i -g gitnexus`; #1939).
+
+## Always Do
+
+- **MUST run impact analysis before editing any symbol.** Before modifying a function, class, or method, run `impact({target: "symbolName", direction: "upstream"})` and report the blast radius (direct callers, affected processes, risk level) to the user.
+- **MUST run `detect_changes()` before committing** to verify your changes only affect expected symbols and execution flows. For regression review, compare against the default branch: `detect_changes({scope: "compare", base_ref: "main"})`.
+- **MUST warn the user** if impact analysis returns HIGH or CRITICAL risk before proceeding with edits.
+- When exploring unfamiliar code, use `query({query: "concept"})` to find execution flows instead of grepping. It returns process-grouped results ranked by relevance.
+- When you need full context on a specific symbol — callers, callees, which execution flows it participates in — use `context({name: "symbolName"})`.
+
+## Never Do
+
+- NEVER edit a function, class, or method without first running `impact` on it.
+- NEVER ignore HIGH or CRITICAL risk warnings from impact analysis.
+- NEVER rename symbols with find-and-replace — use `rename` which understands the call graph.
+- NEVER commit changes without running `detect_changes()` to check affected scope.
+
+## Resources
+
+| Resource | Use for |
+|----------|---------|
+| `gitnexus://repo/AI-Agent-App/context` | Codebase overview, check index freshness |
+| `gitnexus://repo/AI-Agent-App/clusters` | All functional areas |
+| `gitnexus://repo/AI-Agent-App/processes` | All execution flows |
+| `gitnexus://repo/AI-Agent-App/process/{name}` | Step-by-step execution trace |
+
+## CLI
+
+| Task | Read this skill file |
+|------|---------------------|
+| Understand architecture / "How does X work?" | `.claude/skills/gitnexus/gitnexus-exploring/SKILL.md` |
+| Blast radius / "What breaks if I change X?" | `.claude/skills/gitnexus/gitnexus-impact-analysis/SKILL.md` |
+| Trace bugs / "Why is X failing?" | `.claude/skills/gitnexus/gitnexus-debugging/SKILL.md` |
+| Rename / extract / split / refactor | `.claude/skills/gitnexus/gitnexus-refactoring/SKILL.md` |
+| Tools, resources, schema reference | `.claude/skills/gitnexus/gitnexus-guide/SKILL.md` |
+| Index, status, clean, wiki CLI commands | `.claude/skills/gitnexus/gitnexus-cli/SKILL.md` |
+
+
diff --git a/BAO_CAO_NGHIEN_CUU.md b/BAO_CAO_NGHIEN_CUU.md
new file mode 100644
index 0000000000000000000000000000000000000000..86ab7ae6b4a05eb4ae8225df52084189eae17c09
--- /dev/null
+++ b/BAO_CAO_NGHIEN_CUU.md
@@ -0,0 +1,706 @@
+# Zenith — Báo Cáo Sản Phẩm Toàn Diện
+
+**Dự án:** Zenith — Nền tảng luyện thi Toán thích ứng dành cho học sinh Việt Nam
+**Đối tượng đọc:** Lãnh đạo, quản lý sản phẩm — không yêu cầu kiến thức kỹ thuật
+**Ngày:** tháng 6 năm 2026
+**Phiên bản:** 2.0
+
+---
+
+## Tóm Tắt Điều Hành
+
+Zenith là ứng dụng luyện thi Toán dành cho học sinh từ lớp 9 đến lớp 12 tại Việt Nam, tập trung vào kỳ thi tuyển sinh lớp 10 và kỳ thi THPT Quốc gia. Điểm khác biệt cốt lõi là **hệ thống học thích ứng**: thay vì cho tất cả học sinh làm cùng một bộ đề, Zenith tự động phân tích điểm yếu của từng em và điều chỉnh nội dung luyện tập theo thời gian thực.
+
+Nền tảng bao gồm **24 tính năng chính** trải dài trên toàn bộ hành trình học tập — từ bài kiểm tra đầu vào, làm đề thi, phân tích kết quả, luyện tập thích ứng, đến ôn tập thông minh và theo dõi tiến độ dài hạn. Tất cả tính năng được hỗ trợ bởi AI (mô hình Claude của Anthropic) và được xây dựng dựa trên các phương pháp giáo dục đã được nghiên cứu khoa học kiểm chứng.
+
+**Kho đề thi:** 86 đề từ 47 nguồn thực (Bộ GD&ĐT, Sở GD&ĐT các tỉnh, AMC Mỹ, CEMC Canada, SEC Ireland, KICE Hàn Quốc), với 2.075+ câu hỏi được phân loại theo chủ đề và mức độ khó.
+
+---
+
+## Mục Lục
+
+1. [Hành Trình Học Sinh](#1-hành-trình-học-sinh)
+2. [Bước 1 — Đánh Giá Năng Lực Đầu Vào](#2-bước-1--đánh-giá-năng-lực-đầu-vào)
+3. [Bước 2 — Làm Bài Thi](#3-bước-2--làm-bài-thi)
+4. [Bước 3 — Phân Tích Kết Quả và Đề Xuất Trường](#4-bước-3--phân-tích-kết-quả-và-đề-xuất-trường)
+5. [Bước 4 — Kế Hoạch Học Tập Cá Nhân Hóa](#5-bước-4--kế-hoạch-học-tập-cá-nhân-hóa)
+6. [Bước 5 — Luyện Tập Thích Ứng Hàng Ngày](#6-bước-5--luyện-tập-thích-ứng-hàng-ngày)
+7. [Bước 6 — Ôn Tập Thông Minh (Spaced Repetition)](#7-bước-6--ôn-tập-thông-minh-spaced-repetition)
+8. [Bước 7 — Oracle: Gia Sư Toán AI](#8-bước-7--oracle-gia-sư-toán-ai)
+9. [Bước 8 — Theo Dõi Tiến Độ và Bản Đồ Khái Niệm](#9-bước-8--theo-dõi-tiến-độ-và-bản-đồ-khái-niệm)
+10. [Tính Năng Cộng Đồng và Gamification](#10-tính-năng-cộng-đồng-và-gamification)
+11. [Tài Khoản và Thống Kê Cá Nhân](#11-tài-khoản-và-thống-kê-cá-nhân)
+12. [Kho Đề Thi và Dữ Liệu](#12-kho-đề-thi-và-dữ-liệu)
+13. [Gói Dịch Vụ và Hệ Thống Tín Dụng AI](#13-gói-dịch-vụ-và-hệ-thống-tín-dụng-ai)
+14. [Cơ Sở Khoa Học](#14-cơ-sở-khoa-học)
+15. [Tài Liệu Tham Khảo](#15-tài-liệu-tham-khảo)
+
+---
+
+## 1. Hành Trình Học Sinh
+
+Dưới đây là toàn bộ luồng trải nghiệm của một học sinh trên Zenith:
+
+```
+Lần đầu vào app
+ │
+ ▼
+[Kiểm tra đầu vào] ──→ AI phân tích điểm yếu
+ │
+ ▼
+[Chọn đề thi] ──→ 86 đề từ THPT/thi lớp 10/quốc tế
+ │
+ ▼
+[Làm bài] ──→ Hẹn giờ, gợi ý AI, chống gian lận
+ │
+ ▼
+[Kết quả] ──→ Điểm số, biểu đồ, đề xuất trường, kế hoạch
+ │
+ ├──→ [Kế hoạch học tập 4 tuần] (AI tạo tự động)
+ │
+ ├──→ [Luyện tập thích ứng] (15 câu tập trung vào điểm yếu)
+ │
+ ├──→ [Ôn tập spaced repetition] (nhắc đúng lúc quên)
+ │
+ ├──→ [Oracle - hỏi đáp Toán AI] (giải thích + gợi ý)
+ │
+ └──→ [Tiến độ & Bản đồ khái niệm] (58 khái niệm Toán)
+```
+
+---
+
+## 2. Bước 1 — Đánh Giá Năng Lực Đầu Vào
+
+### 2.1 Bài Kiểm Tra Xếp Lớp (Placement Test)
+
+**Trang:** `/placement`
+
+Khi học sinh lần đầu đăng ký, Zenith mời làm **bài kiểm tra 10 câu** bao phủ 10 chủ đề Toán khác nhau (đại số, hàm số, hình học, xác suất, tổ hợp…). Mỗi câu được chọn ngẫu nhiên từ mức độ trung bình để tránh quá dễ hoặc quá khó.
+
+**Kết quả:** Hệ thống tính điểm ước lượng năng lực ban đầu của học sinh trên thang điểm chuẩn, sử dụng làm cơ sở cho tất cả đề xuất sau đó.
+
+### 2.2 Bài Kiểm Tra Chẩn Đoán (Diagnostic Test)
+
+**Trang:** `/diagnostic`
+
+Sau khi xếp lớp, học sinh có thể làm thêm **bài kiểm tra chẩn đoán 12 câu**, phân phối đều cho 6 chủ đề trọng tâm (Đại số, Hình học, Thống kê, Tổ hợp, Lượng giác, Hàm số — 2 câu mỗi chủ đề).
+
+**Kết quả:**
+Hệ thống tính **"trọng số điểm yếu"** cho từng chủ đề: chủ đề nào học sinh làm sai nhiều hơn sẽ nhận trọng số cao hơn, và sẽ xuất hiện nhiều hơn trong các buổi luyện tập thích ứng sau đó.
+
+**Tại sao cần bước này?**
+Nghiên cứu từ năm 2011 cho thấy các hệ thống gia sư thông minh có thể đạt hiệu quả tương đương gia sư một-một khi được cá nhân hóa đúng cách — nhưng điều kiện tiên quyết là hệ thống phải biết học sinh đang ở đâu trước khi bắt đầu dạy. Bước chẩn đoán là chìa khóa để mở tính năng này [1].
+
+---
+
+## 3. Bước 2 — Làm Bài Thi
+
+### 3.1 Chọn Đề Thi (ExamSelect)
+
+**Trang:** `/exams`
+
+Học sinh duyệt **86 đề thi** chia thành 3 danh mục:
+
+| Danh mục | Số đề | Đối tượng |
+|----------|-------|-----------|
+| Thi vào lớp 10 | 47 đề | Học sinh lớp 9 |
+| THPT Quốc gia | 29 đề | Học sinh lớp 10–12 |
+| Ứng dụng / Quốc tế | 10 đề | Nâng cao, AMC, CEMC |
+
+Giao diện cho phép **lọc theo lớp và gói đăng ký**. Học sinh chưa đăng ký được làm **1 đề thử miễn phí** (guest trial). Đề đã làm được đánh dấu để tránh trùng lặp.
+
+**Nguồn đề:** Bộ GD&ĐT, các Sở GD&ĐT (Hà Nội, TP.HCM, Cà Mau, Bình Dương…), AMC 8/AMC 10 (Mỹ), Gauss (Canada), Junior Math Challenge (Anh), Leaving Certificate (Ireland), CSAT (Hàn Quốc).
+
+> Toàn bộ câu hỏi đến từ nguồn thực do con người tạo ra. Zenith không dùng AI để tạo nội dung câu hỏi.
+
+### 3.2 Giao Diện Thi (TestInterface)
+
+**Trang:** `/test/:examId`
+
+**Tính năng trong phòng thi:**
+
+- **Bộ đếm giờ** — đếm ngược, tự nộp bài khi hết giờ
+- **Ngăn chuyển tab** — phát hiện và ghi lại số lần học sinh chuyển ra khỏi trang thi
+- **Bảng công thức** — kéo ra ngay trong khi thi, không cần mở tab khác
+- **Theo dõi thời gian từng câu** — ghi lại thời gian học sinh dừng ở mỗi câu
+- **Phím tắt bàn phím** — điều hướng nhanh không cần chuột
+- **Toàn màn hình** — chế độ không phân tâm
+- **Gợi ý AI (⚡1 Tia)** — học sinh có thể xin gợi ý cho câu đang làm (AI không đưa đáp án, chỉ hỏi ngược để dẫn dắt)
+- **Nền sao chuyển động** — hiệu ứng thị giác giúp tạo cảm giác tập trung, tương tự "vùng dòng chảy" (flow state)
+
+---
+
+## 4. Bước 3 — Phân Tích Kết Quả và Đề Xuất Trường
+
+**Trang:** `/results/:id`
+
+Ngay sau khi nộp bài, học sinh nhận được:
+
+### 4.1 Bảng Điểm và Phân Tích AI
+
+- **Điểm số** hiển thị với hoạt ảnh đếm lên (tạo cảm xúc tích cực)
+- **Biểu đồ radar** thể hiện hiệu suất theo 6–8 chủ đề Toán
+- **Phân tích AI streaming** — AI đọc toàn bộ bài làm và trả lời theo dòng (như gõ thư), nêu:
+ - Điểm mạnh cụ thể ("Em làm tốt phần Hàm số")
+ - Điểm yếu cần tập trung
+ - Các lỗi sai phổ biến trong bài vừa làm
+ - Đề xuất học tập cụ thể cho tuần tới
+
+### 4.2 Đề Xuất Trường Theo Tỉnh
+
+Dựa trên điểm số và tỉnh thành học sinh đã khai báo, AI đề xuất **3–5 trường phù hợp** với mức điểm chuẩn địa phương. Dữ liệu ngưỡng điểm được cập nhật theo thực tế tuyển sinh của từng tỉnh (4 cấp độ cạnh tranh: D1–D4, từ ít cạnh tranh đến Hà Nội/TP.HCM).
+
+### 4.3 Dự Đoán Điểm Thi Thực Tế
+
+Hệ thống sử dụng **bộ lọc Kalman** — một thuật toán đã được NASA dùng để theo dõi quỹ đạo tàu vũ trụ, được ứng dụng vào giáo dục để ước lượng điểm thi — tính ra khoảng điểm dự kiến với độ tin cậy thay đổi theo số lần học sinh đã thi. Học sinh thi càng nhiều, khoảng dự báo càng chính xác.
+
+### 4.4 Chia Sẻ và Thách Đấu
+
+- **Chia sẻ kết quả** — tạo hình ảnh đẹp để đăng mạng xã hội
+- **Thách đấu bạn bè** — gửi link, bạn bè vào làm cùng đề và so sánh điểm
+
+---
+
+## 5. Bước 4 — Kế Hoạch Học Tập Cá Nhân Hóa
+
+### 5.1 Kế Hoạch Phục Hồi (StudyPlan)
+
+**Trang:** `/study-plan/:resultId`
+
+Sau khi xem kết quả, học sinh bấm **"Tạo Kế Hoạch"** (5 Tia). AI đọc toàn bộ bài làm và tạo **kế hoạch phục hồi** chi tiết:
+
+- **3–4 vùng trọng tâm** cần cải thiện (sắp xếp theo mức độ ưu tiên)
+- **Mục tiêu checkpoint** cho từng vùng (ví dụ: "Trả lời đúng 3 câu liên tiếp về Hàm số")
+- **Liên kết trực tiếp** đến bộ câu hỏi luyện tập cho từng vùng
+- **Tiến độ checkbox** lưu trên máy, học sinh đánh dấu hoàn thành từng bước
+
+### 5.2 Kế Hoạch Thích Ứng (AdaptiveStudyPlan)
+
+**Trang:** `/adaptive-plan`
+
+Kế hoạch nâng cao, cập nhật liên tục theo tiến độ thực tế:
+
+- **Điểm dự kiến** ngày thi (hiển thị rõ "Đúng hướng ↗" hay "Cần tăng tốc ⚠")
+- **Số khái niệm đã vững** / tổng số khái niệm cần nắm
+- **Số ngày còn lại** đến ngày thi (học sinh khai báo ngày thi khi đăng ký)
+- **Danh sách khái niệm theo giai đoạn** — từ "Chưa học" (xám) đến "Thành thạo" (xanh lá)
+
+**Các giai đoạn thành thạo khái niệm:**
+
+| Màu | Giai đoạn | Ý nghĩa |
+|-----|-----------|---------|
+| Xám | Chưa học | Chưa gặp khái niệm này |
+| Xanh dương | Mới tiếp cận | Đã thấy nhưng chưa làm được |
+| Vàng cam | Đang học | Làm được một phần |
+| Vàng | Luyện tập | Làm được nhưng chưa ổn định |
+| Xanh lá nhạt | Vững | Làm được đáng tin cậy |
+| Xanh lá đậm | Thành thạo | Làm đúng nhất quán, kể cả câu khó |
+
+---
+
+## 6. Bước 5 — Luyện Tập Thích Ứng Hàng Ngày
+
+### 6.1 Luyện Tập Thích Ứng (AdaptivePractice)
+
+**Trang:** `/practice/adaptive`
+
+Đây là tính năng học tập cốt lõi của Zenith. Mỗi buổi luyện tập gồm **15 câu hỏi**, được chọn thông minh từ kho 2.075+ câu:
+
+**Cách hệ thống chọn câu hỏi:**
+
+1. Đọc toàn bộ lịch sử làm bài của học sinh (hoặc kết quả Diagnostic nếu chưa có lịch sử)
+2. Tính **"trọng số điểm yếu"** cho từng chủ đề — chủ đề nào sai nhiều hơn được ưu tiên hơn
+3. Chọn câu hỏi từ các chủ đề yếu nhiều hơn, xen kẽ chủ đề mạnh
+4. **Xáo trộn** thứ tự chủ đề để tránh học thuộc theo nhóm (kỹ thuật "interleaving" có căn cứ nghiên cứu)
+
+**Tại sao hiệu quả hơn học bình thường?**
+Nghiên cứu meta-phân tích (US Department of Education, 2010) cho thấy học thích ứng cho kết quả **tốt hơn đáng kể** so với học một-kích-thước-cho-tất-cả, đặc biệt khi học sinh có nền tảng không đồng đều [2].
+
+Thêm vào đó, kỹ thuật xen kẽ chủ đề (**interleaving**) — thay vì học hết Đại số rồi mới sang Hình học — được nghiên cứu tại các trường đại học Mỹ xác nhận cải thiện khả năng vận dụng kiến thức trong bài thi đến **43%** [3].
+
+### 6.2 Thử Thách Hàng Ngày (DailyChallenge)
+
+**Trang:** `/daily`
+
+Mỗi ngày, Zenith đưa ra **1 câu hỏi thử thách** được chọn từ kho đề. Học sinh trả lời và nhận phản hồi ngay lập tức.
+
+**Tính năng streak (chuỗi ngày):** Hệ thống theo dõi số ngày liên tiếp học sinh hoàn thành thử thách. Nếu bỏ lỡ một ngày, có thể dùng **Streak Freeze** (đóng băng chuỗi) để bảo toàn kỷ lục.
+
+**Tại sao quan trọng?**
+Kết quả nghiên cứu về gamification trong giáo dục (Hamari, Koivisto & Sarsa, 2014) cho thấy các cơ chế như streak và thách thức hàng ngày tăng tỷ lệ học sinh quay lại ứng dụng và duy trì thói quen học đều đặn [4].
+
+### 6.3 Tạo Đề Thi AI (GenerateExam)
+
+**Trang:** `/generate-exam`
+
+Học sinh (hoặc giáo viên) có thể yêu cầu AI tạo **đề thi mới hoàn toàn** theo yêu cầu:
+
+- Chọn chủ đề (1 hoặc nhiều trong số 15 chủ đề Toán)
+- Chọn số câu (10–50 câu)
+- Chọn mức độ khó (dễ / trung bình / khó / hỗn hợp)
+
+AI tạo câu hỏi trực tiếp theo luồng (streaming) — từng câu xuất hiện trên màn hình ngay khi AI tạo xong, không cần chờ toàn bộ.
+
+> **Lưu ý:** Đây là tính năng thực hành bổ sung. Câu hỏi do AI tạo được đánh dấu riêng và không được tính vào kho đề thi chính thức, vốn chỉ chứa câu hỏi từ nguồn thực.
+
+---
+
+## 7. Bước 6 — Ôn Tập Thông Minh (Spaced Repetition)
+
+**Trang:** `/review`
+
+### 7.1 Nguyên Lý Hoạt Động
+
+Đây là một trong những tính năng khoa học nhất của Zenith. Hệ thống dựa trên **"đường cong quên lãng" của Ebbinghaus** (1885): sau khi học xong, kiến thức bắt đầu phai dần theo thời gian, nhưng mỗi lần ôn tập lại đúng thời điểm sẽ kéo dài thêm độ bền của ký ức.
+
+**Cách Zenith hoạt động:**
+Mỗi câu hỏi học sinh đã làm được theo dõi riêng. Sau khi học sinh trả lời, hệ thống tính toán **ngày ôn tập tối ưu tiếp theo** dựa trên:
+
+- Học sinh nhớ bài này tốt đến đâu (đánh giá qua 3 mức: Đoán / Khá / Chắc)
+- Độ khó của câu hỏi đó
+- Khoảng thời gian đã trôi qua kể từ lần ôn gần nhất
+
+### 7.2 Thuật Toán FSRS
+
+Zenith sử dụng thuật toán **FSRS v5** — một trong những thuật toán lặp lại ngắt quãng hiện đại nhất, được xây dựng và kiểm chứng trên dữ liệu của hàng triệu người dùng ứng dụng học thẻ Anki trên toàn thế giới.
+
+**Bằng chứng đã kiểm chứng (3/3 phiếu bầu trong nghiên cứu phản biện độc lập):**
+
+> FSRS khi được **cá nhân hóa theo từng học sinh** dự đoán thời điểm quên chính xác hơn **39%** so với khi dùng thông số mặc định.
+
+*Nguồn: Kho dữ liệu open-source srs-benchmark — hơn 350 triệu lượt ôn tập từ 9.999 người dùng thực* [5]
+
+**Hàm ý:** Mỗi học sinh có tốc độ quên khác nhau. Một học sinh giỏi Hình học có thể ôn lại sau 14 ngày mà vẫn nhớ, trong khi học sinh khác cần ôn lại sau 3 ngày. FSRS tự điều chỉnh cho từng người.
+
+### 7.3 Giao Diện Ôn Tập
+
+- Hiển thị **câu hỏi đến hạn ôn** (chỉ những câu sắp quên, không ôn lại cái đã nhớ vững)
+- Học sinh chọn mức tự đánh giá: **Đoán** (sẽ ôn lại sớm) / **Khá** (ôn sau vài ngày) / **Chắc** (ôn sau vài tuần)
+- Thanh tiến độ cho thấy còn bao nhiêu câu trong ngày
+
+---
+
+## 8. Bước 7 — Oracle: Gia Sư Toán AI
+
+**Trang:** `/oracle`
+
+### 8.1 Oracle là gì?
+
+Oracle là trợ lý Toán AI tích hợp sâu nhất trong Zenith — không chỉ trả lời câu hỏi mà còn nhớ bối cảnh cuộc trò chuyện và điều chỉnh cách giải thích theo từng học sinh.
+
+### 8.2 Tính Năng
+
+**Đặt câu hỏi Toán tự do**
+Học sinh gõ câu hỏi bằng tiếng Việt hoặc tiếng Anh, kết hợp công thức toán học. AI trả lời theo dòng (streaming) với:
+- Giải thích từng bước
+- Công thức được render đẹp bằng LaTeX
+- Các trường hợp đặc biệt cần lưu ý
+
+**Chụp ảnh bài toán (OCR)**
+Học sinh chụp ảnh trang sách hoặc đề thi, tải lên — Oracle đọc công thức từ ảnh và giải thích.
+
+**Nhập liệu bằng giọng nói**
+Học sinh nói câu hỏi thay vì gõ — tiện lợi khi tay đang cầm bút.
+
+**Bảng ký hiệu Toán**
+Palette ký hiệu toán học (∑, √, π, ∫, α, β…) và chữ Hy Lạp — click để chèn vào câu hỏi.
+
+**Chuẩn hóa công thức tự động**
+Khi dán công thức từ nguồn bên ngoài (PDF, Word), Oracle tự động chuyển đổi về định dạng chuẩn LaTeX.
+
+**Lịch sử trò chuyện**
+Oracle nhớ những gì đã được giải thích trong buổi chat, tránh giải thích lại điều đã biết.
+
+**Lọc theo chủ đề**
+Học sinh có thể giới hạn Oracle chỉ trả lời về một chủ đề cụ thể (ví dụ: chỉ về Tích phân).
+
+### 8.3 Phương Pháp Sư Phạm
+
+Oracle được thiết kế theo **phương pháp Socrates**: thay vì đưa đáp án ngay, AI đặt câu hỏi dẫn dắt để học sinh tự tìm ra cách giải. Nghiên cứu giáo dục ghi nhận phương pháp này giúp học sinh hiểu sâu hơn và nhớ lâu hơn so với học vẹt.
+
+Khi học sinh bấm nút **Gợi ý (⚡1 Tia)** trong lúc làm bài, Oracle cũng sử dụng phong cách này — không cho đáp án, chỉ gợi mở hướng suy nghĩ.
+
+---
+
+## 9. Bước 8 — Theo Dõi Tiến Độ và Bản Đồ Khái Niệm
+
+### 9.1 Trang Tiến Độ (Progress)
+
+**Trang:** `/progress`
+
+Học sinh thấy **bức tranh toàn cảnh** về năng lực Toán của mình:
+
+**Điểm chuẩn theo tỉnh:**
+So sánh điểm trung bình của học sinh với **ngưỡng điển hình và ngưỡng top** của tỉnh đó. Ví dụ: Hà Nội cần ~8.0 điểm để vào trường tốt, trong khi Hà Giang chỉ cần ~5.0. Zenith hiển thị học sinh đang ở đâu so với mặt bằng tỉnh nhà (dữ liệu 63 tỉnh thành).
+
+**Biểu đồ theo chủ đề:**
+Điểm theo từng trong số 15 chủ đề Toán — Đại số, Hình học, Giải tích, Xác suất, Lượng giác, Dãy số, Số phức, Logarit…
+
+**Điểm thành thạo khái niệm (BKT):**
+Dựa trên thuật toán **Bayesian Knowledge Tracing** — một phương pháp khoa học từ năm 1994 được dùng trong các hệ thống gia sư thông minh hàng đầu thế giới (như Carnegie Learning). Zenith tính xác suất "học sinh thực sự biết khái niệm này" thay vì chỉ đếm số câu đúng/sai.
+
+### 9.2 Bản Đồ Khái Niệm (ConceptMap)
+
+**Trang:** `/concept-map`
+
+Đây là tính năng trực quan hóa độc đáo nhất của Zenith: **đồ thị tương tác gồm 58 nút khái niệm Toán**, được sắp xếp theo quan hệ điều kiện tiên quyết (khái niệm nào cần học trước khái niệm nào).
+
+**Cách đọc bản đồ:**
+
+| Màu nút | Ý nghĩa |
+|---------|---------|
+| Xám đậm | Chưa từng thử |
+| Đỏ | Đã thử nhưng còn yếu (< 40%) |
+| Vàng/cam | Đang tiến bộ (40–70%) |
+| Xanh lá | Đã vững (> 70%) |
+
+**Cách sử dụng:**
+Click vào bất kỳ nút nào để xem chi tiết khái niệm và bắt đầu luyện tập tập trung vào khái niệm đó. Các mũi tên cho thấy mối quan hệ học trước/sau (ví dụ: phải hiểu Phương trình bậc nhất trước khi học Hệ phương trình).
+
+**Cơ sở khoa học:**
+Nghiên cứu về bản đồ khái niệm trong giáo dục (Novak & Cañas, 2006) cho thấy học sinh sử dụng biểu diễn trực quan kiến thức hiểu bài sâu hơn và nhớ lâu hơn so với học theo danh sách tuyến tính [6].
+
+### 9.3 Phân Tích Lỗi Sai (ErrorAnalysis)
+
+**Trang:** `/error-analysis`
+
+Tổng hợp tất cả lỗi sai của học sinh qua tất cả bài thi, phân loại thành **5 nhóm lỗi**:
+
+| Loại lỗi | Ý nghĩa thực tế |
+|----------|----------------|
+| Sai dấu | Nhầm dấu cộng/trừ khi biến đổi |
+| Nhầm công thức | Áp dụng sai công thức |
+| Sai quy trình | Đúng hướng nhưng sai bước giữa |
+| Lỗ hổng khái niệm | Chưa hiểu bản chất |
+| Tính toán sai | Sai số học đơn thuần |
+
+Lỗi gần đây được tính trọng số cao hơn lỗi cũ (thuật toán giảm dần theo thời gian — "temporal decay"). Điều này giúp phân biệt lỗi học sinh đã khắc phục và lỗi vẫn còn tồn tại.
+
+**Biểu đồ radar:** Hiển thị phân phối lỗi theo chủ đề — một cái nhìn nhanh về "cần sửa gì, ở đâu".
+
+### 9.4 Sổ Lỗi Sai (Mistakes)
+
+**Trang:** `/mistakes`
+
+Danh sách toàn bộ câu hỏi học sinh đã làm sai, nhóm theo chủ đề. Với mỗi câu sai:
+
+- Xem lại câu hỏi và đáp án đúng
+- **Giải thích chi tiết (1 Tia)** — AI giải thích tại sao đáp án đó đúng, phân tích lỗi học sinh mắc phải
+- **Gắn nhãn lỗi** — học sinh tự phân loại lỗi (giúp tự nhận thức metacognitive)
+
+---
+
+## 10. Tính Năng Cộng Đồng và Gamification
+
+### 10.1 Lớp Học (ClassDashboard)
+
+**Trang:** `/class` *(đã xây dựng, chưa mở cho người dùng)*
+
+Giáo viên hoặc học sinh có thể tạo **lớp học ảo**:
+
+- **Giáo viên tạo lớp** → nhận mã lớp (ví dụ: `ABC123`)
+- **Học sinh tham gia** bằng cách nhập mã
+- **Giáo viên xem** kết quả bài thi của toàn lớp trong một bảng
+
+Tính năng này hỗ trợ giáo viên ra bài tập về nhà dưới dạng đề thi trên Zenith và theo dõi học sinh hoàn thành.
+
+### 10.2 Thách Đấu Bạn Bè (ChallengeLanding)
+
+**Trang:** `/challenge`
+
+Sau khi làm bài, học sinh bấm **"Thách đấu bạn"** → nhận link → gửi cho bạn. Bạn bè vào làm cùng đề đó và kết quả được so sánh trực tiếp.
+
+Tính năng này tạo **động lực xã hội** (social motivation) — một trong những yếu tố được nghiên cứu giáo dục xác nhận có tác động tích cực đến sự gắn kết học tập.
+
+### 10.3 Huy Hiệu Thành Tích (Badges)
+
+Zenith cấp huy hiệu khi học sinh đạt cột mốc:
+
+| Huy hiệu | Điều kiện |
+|----------|-----------|
+| Điểm hoàn hảo | Đạt 10 điểm trong 1 bài thi |
+| Chinh phục 10 đề | Hoàn thành 10 bài thi |
+| Tốc độ ánh sáng | Nộp bài trước khi hết 70% thời gian |
+| Tiến bộ vượt bậc | Cải thiện ≥ 2 điểm so với lần trước cùng đề |
+
+---
+
+## 11. Tài Khoản và Thống Kê Cá Nhân
+
+**Trang:** `/account`
+
+Trang tài khoản là **trung tâm điều khiển cá nhân** của học sinh, chia thành 4 tab:
+
+### Tab Tiến Độ
+
+- **Biểu đồ radar** thể hiện năng lực 8 chủ đề Toán
+- **Đường xu hướng điểm** qua các lần thi
+- **Số ngày streak** (chuỗi học liên tục)
+- **Chuỗi ngày kỷ lục** (personal best)
+- **Đếm ngược đến ngày thi**
+- **Cấp độ thành thạo** (từ Học Sinh mới đến Thần Đồng Toán học) với thanh tiến độ
+- **Loại học sinh** (learner archetype) — AI phân loại học sinh theo phong cách học (ví dụ: "Người chăm chỉ", "Người học theo hiểu biết", "Người học theo tốc độ")
+
+### Tab Phân Tích
+
+- **Điểm số theo trường mục tiêu** — so sánh với ngưỡng của trường học sinh muốn vào
+- **Thống kê đồng lứa** (peer stats) — AI so sánh ẩn danh với các học sinh cùng tỉnh, cùng lớp
+- **Nhận xét hàng tuần** — AI tổng kết tuần vừa qua và đưa ra lời khuyên
+- **Kế hoạch mô phỏng thi** — AI tạo lịch thi thử theo ngày thi thực tế
+- **Bối cảnh địa phương** — phân tích cạnh tranh tuyển sinh theo tỉnh
+
+### Tab AI & Tia
+
+- **Chiến lược thi** — AI đưa ra chiến lược làm bài dựa trên điểm yếu cụ thể
+- **Chương trình học tuần** — lịch học cụ thể từng ngày trong tuần
+- **Nhận xét điểm thi** — so sánh điểm thực tế với dự đoán, giải thích chênh lệch
+
+### Tab Cài Đặt
+
+- Đổi tên hiển thị
+- Cài đặt nhắc nhở học tập (thông báo trình duyệt)
+- Quản lý gói đăng ký
+- Lịch sử giao dịch Tia (AI credits)
+
+---
+
+## 12. Kho Đề Thi và Dữ Liệu
+
+### 12.1 Tổng Quan
+
+| Chỉ số | Giá trị |
+|--------|---------|
+| Tổng số đề | 86 đề |
+| Đề thi vào lớp 10 | 47 đề |
+| Đề THPT Quốc gia | 29 đề |
+| Đề ứng dụng / quốc tế | 10 đề |
+| Tổng số câu hỏi | 2.075+ câu |
+| Số chủ đề Toán được phân loại | 15 chủ đề |
+| Số khái niệm trong bản đồ | 58 khái niệm |
+| Phân loại câu hỏi | Dễ / Trung bình / Khó |
+
+### 12.2 Nguồn Đề Thi Trong Nước
+
+- Bộ Giáo dục và Đào tạo (đề THPT Quốc gia 2018–2023)
+- Sở GD&ĐT Hà Nội, TP.HCM, Bình Dương, Cà Mau và các tỉnh khác
+- Nguồn luyện thi uy tín: loigiaihay.com
+
+### 12.3 Nguồn Đề Thi Quốc Tế
+
+| Tổ chức | Quốc gia | Loại đề |
+|---------|---------|---------|
+| Mathematical Association of America (MAA) | Mỹ | AMC 8, AMC 10 |
+| Centre for Education in Mathematics and Computing (CEMC) | Canada | Gauss Grade 7/8 |
+| UK Mathematics Trust | Anh | Junior Math Challenge |
+| State Examinations Commission (SEC) | Ireland | Leaving Certificate |
+| Korea Institute for Curriculum and Evaluation (KICE) | Hàn Quốc | CSAT |
+
+### 12.4 Chính Sách Nội Dung
+
+Toàn bộ câu hỏi (nội dung + đáp án + các lựa chọn sai) đến từ nguồn thực do con người tạo ra. **AI không được phép tạo nội dung câu hỏi** — chính sách này được ghi cứng vào hệ thống để đảm bảo chất lượng và tính chính xác. Đây là điểm khác biệt quan trọng so với một số nền tảng luyện thi khác trên thị trường.
+
+---
+
+## 13. Gói Dịch Vụ và Hệ Thống Tín Dụng AI
+
+### 13.1 Gói Đăng Ký
+
+| Gói | Tên | Đề thi được dùng | Tính năng đặc biệt |
+|-----|-----|-----------------|-------------------|
+| Miễn phí | Cơ bản | 1 đề thử | Xem kết quả cơ bản |
+| Trả phí | Học sinh | Tất cả đề lớp 10 + THPT | AI phân tích, kế hoạch |
+| Trả phí | Toàn diện | Tất cả + đề quốc tế | Kế hoạch học 5 Tia, tất cả tính năng |
+
+Gói Học sinh và Toàn diện có lựa chọn **thanh toán tháng hoặc năm** (thanh toán năm rẻ hơn, hiển thị badge "Năm" trong Navbar).
+
+### 13.2 Hệ Thống Tia (AI Credits)
+
+Các tính năng AI tiêu thụ "Tia" (⚡) — đơn vị tín dụng AI. Điều này cho phép học sinh dùng miễn phí các tính năng cơ bản và chỉ trả tiền cho AI khi thực sự cần.
+
+| Tính năng AI | Chi phí |
+|-------------|---------|
+| Gợi ý câu hỏi (Socratic hint) | 1 Tia |
+| Giải thích đáp án | 1 Tia |
+| Phân tích kết quả bài thi | 3 Tia |
+| Kế hoạch học tập 4 tuần | 5 Tia |
+
+Tia có thể nhận miễn phí khi nâng cấp gói, hoặc mua thêm từ trang tài khoản.
+
+---
+
+## 14. Cơ Sở Khoa Học
+
+Zenith được xây dựng dựa trên 6 lĩnh vực nghiên cứu giáo dục có bằng chứng vững chắc. Tất cả các số liệu dưới đây đã được xác minh qua hệ thống kiểm tra phản biện độc lập (214 tác nhân AI, 50 nguồn học thuật, chỉ giữ lại tuyên bố được ≥2/3 tác nhân xác nhận).
+
+---
+
+### 14.1 Lặp Lại Ngắt Quãng — Chiến Lược Học Tập Hiệu Quả Nhất
+
+**Tính năng áp dụng:** Ôn Tập (ReviewSession), thuật toán FSRS
+
+**Bằng chứng đã kiểm chứng (3/3 phiếu bầu):**
+
+> Lặp lại ngắt quãng và luyện tập truy xuất (tự kiểm tra) là hai kỹ thuật học tập hiệu quả nhất, mỗi loại đạt **hiệu ứng d=0.85** — gấp hơn **2 lần hiệu quả trung bình** của các can thiệp giáo dục thông thường (d≈0.40) — trong phân tích tổng hợp năm 2021 của **242 nghiên cứu với 169.179 học sinh**.
+
+*Nguồn: Donoghue & Hattie (2021), Frontiers in Education, DOI: 10.3389/feduc.2021.581216* [A]
+
+*Xác nhận độc lập: Cepeda et al. (2006), Psychological Bulletin — tổng hợp 839 bài đánh giá từ 317 thí nghiệm trên 184 bài báo* [B]
+
+**Ý nghĩa thực tế:** Học nhồi nhét một lần ("học tủ") trước kỳ thi tạo cảm giác nhớ nhưng kiến thức phai rất nhanh. Ôn tập đúng thời điểm — ngay trước khi bộ nhớ phai — giúp kiến thức gắn chắc hơn mỗi lần ôn. Đây là lý do tính năng Ôn Tập của Zenith không cho học sinh ôn bừa bãi mà chỉ đưa ra câu hỏi **đúng khi sắp quên**.
+
+Một phát hiện quan trọng từ nghiên cứu (3/3 phiếu bầu): khoảng cách ôn tập tối ưu **phải điều chỉnh theo ngày thi** — kỳ thi còn xa thì khoảng cách ôn dài hơn, kỳ thi gần thì ôn dày hơn. Zenith sử dụng thông tin ngày thi (học sinh khai báo khi đăng ký) để điều chỉnh lịch ôn theo nguyên tắc này.
+
+---
+
+### 14.2 Tự Kiểm Tra — Nhớ Lâu Hơn Đọc Lại
+
+**Tính năng áp dụng:** Luyện Tập Thích Ứng, Thử Thách Hàng Ngày, Luyện Tập trong Kế Hoạch Học Tập
+
+**Bằng chứng đã kiểm chứng (2/3 phiếu bầu):**
+
+> Học sinh **tự kiểm tra** nhớ nhiều hơn học sinh **đọc lại bài**: sau 2 ngày, nhóm tự kiểm tra nhớ **68%** so với **54%** của nhóm đọc lại (hơn **26%**); sau 1 tuần, khoảng cách tăng lên: **56% so với 42%** (hơn **33%**).
+
+*Nguồn: Roediger & Karpicke (2006), Psychological Science, 17(3), 249–255 — thí nghiệm với 120 người tham gia* [C]
+
+**Ý nghĩa thực tế:** Học sinh thường có thói quen đọc lại bài hoặc xem lại lý thuyết. Nghiên cứu cho thấy việc **tự làm bài trắc nghiệm** (dù sai) hiệu quả hơn đọc lại gấp đôi về khả năng nhớ sau 1 tuần. Đây là lý do Zenith luôn đặt học sinh vào tình huống phải chọn đáp án — không phải chỉ đọc giải thích.
+
+---
+
+### 14.3 Gia Sư Thông Minh — Hiệu Quả Ngang Gia Sư Người Thật
+
+**Tính năng áp dụng:** Oracle, Gợi Ý Socrates, Giải Thích Đáp Án
+
+**Bằng chứng đã kiểm chứng (3/3 phiếu bầu — đồng thuận tuyệt đối về thư mục; 2/3 về chỉ số cụ thể):**
+
+> Hệ thống gia sư AI phản hồi từng bước giải đạt hiệu ứng **d=0.76** so với không có gia sư — gần bằng gia sư con người một-một (**d=0.79**). Hệ thống chỉ chấm đúng/sai mà không giải thích đạt **d=0.31** — kém hơn **2,5 lần**.
+
+*Nguồn: VanLehn (2011), Educational Psychologist, 46(4), 197–221 — phân tích 1.400+ trích dẫn, tiêu chuẩn ngành cho hiệu quả gia sư thông minh* [D]
+
+**Ý nghĩa thiết kế quan trọng:** Zenith thiết kế Oracle và tính năng Gợi Ý theo nguyên tắc "từng bước" — không chỉ đánh dấu sai/đúng mà giải thích tại sao, đặt câu hỏi dẫn dắt. Đây chính là điều kiện để đạt hiệu quả d=0.76 thay vì chỉ d=0.31.
+
+*Lưu ý trung thực: Tuyên bố "gia sư AI hiệu quả ngang hoàn toàn với gia sư người thật" và "hiệu ứng 2-sigma của Bloom" đều bị bác bỏ 0/3 phiếu — không nên trích dẫn các tuyên bố này.*
+
+---
+
+### 14.4 Gamification — Tăng Gắn Kết, Duy Trì Thói Quen Học
+
+**Tính năng áp dụng:** Streak hàng ngày, Thử Thách, Huy Hiệu, Điểm Thành Thạo
+
+**Bằng chứng đã kiểm chứng (2/3 phiếu bầu):**
+
+> Gamification (điểm streak, huy hiệu, thử thách) tạo hiệu ứng tổng thể **d=0.48** đối với kết quả học tập và hành vi. Tác động lên **tham gia học tập là d=0.60** (mạnh hơn), trong khi tác động trực tiếp lên điểm thi là **d=0.30** (nhỏ hơn).
+
+*Nguồn: Sailer & Homner (2020/2021), Frontiers in Psychology, PMC8037535 — phân tích 18 nghiên cứu thực nghiệm* [E]
+
+**Ý nghĩa thực tế:** Gamification không phải "phép màu" tăng điểm, nhưng nó **duy trì thói quen học đều đặn** — điều quan trọng hơn nhiều trong việc ôn thi dài hạn. Một học sinh học 30 phút mỗi ngày đều đặn trong 3 tháng sẽ vượt trội hơn học sinh học nhồi 10 tiếng trong 1 tuần trước thi.
+
+---
+
+### 14.5 Học Tập Thích Ứng — Đúng Người, Đúng Nội Dung
+
+**Tính năng áp dụng:** Luyện Tập Thích Ứng, Xáo Trộn Chủ Đề (Interleaving), Kế Hoạch Học Tập
+
+Thay vì dạy tất cả học sinh như nhau, hệ thống điều chỉnh nội dung theo năng lực từng người. Nghiên cứu tổng hợp của Bộ Giáo dục Mỹ (2010, phân tích 46 nghiên cứu độc lập) cho thấy học trực tuyến thích ứng tốt hơn đáng kể so với học lớp truyền thống [F].
+
+Kỹ thuật **xen kẽ chủ đề** (interleaving) — thay vì học hết Đại số rồi mới sang Hình học, Zenith xáo trộn câu hỏi từ nhiều chủ đề — được nghiên cứu tại Đại học California và Florida xác nhận cải thiện khả năng vận dụng trong kỳ thi [G].
+
+---
+
+### 14.6 Kiểm Tra Thích Ứng — Câu Hỏi Vừa Khớp Năng Lực
+
+**Tính năng áp dụng:** Luyện Tập Thích Ứng, BanditCAT + IRT
+
+Hệ thống chọn câu hỏi **vừa khớp với năng lực học sinh** — không quá dễ (nhàm chán) và không quá khó (nản lòng). Bài báo BanditCAT (PMLR 2024–2025) được xác minh bởi **3/3 tác nhân kiểm tra phản biện độc lập** trong nghiên cứu của chúng tôi [H].
+
+---
+
+### 14.7 Theo Dõi Kiến Thức — Biết Học Sinh Thực Sự Hiểu Gì
+
+**Tính năng áp dụng:** Bản Đồ Khái Niệm, Trang Tiến Độ, Kế Hoạch Thích Ứng
+
+Thuật toán BKT (Bayesian Knowledge Tracing, Corbett & Anderson 1994) ước lượng **xác suất thực sự học sinh đã hiểu khái niệm** — chính xác hơn và ít bị ảnh hưởng bởi đoán may so với chỉ đếm tỉ lệ đúng/sai đơn giản [I].
+
+---
+
+### Bảng Tổng Hợp Bằng Chứng
+
+| Cơ chế | Số liệu đã kiểm chứng | Tính năng Zenith |
+|--------|----------------------|-----------------|
+| Lặp lại ngắt quãng | d=0.85, 242 nghiên cứu, 169.179 học sinh | Ôn Tập (FSRS) |
+| Tự kiểm tra | +26% nhớ sau 2 ngày, +33% sau 1 tuần | Luyện Tập, Thử Thách Hàng Ngày |
+| Gia sư từng bước | d=0.76 (gần bằng gia sư người: d=0.79) | Oracle, Gợi Ý Socrates |
+| Gamification | d=0.48 tổng thể; d=0.60 gắn kết | Streak, Huy Hiệu, Thách Đấu |
+| Cá nhân hóa FSRS | −39% sai số khi cá nhân hóa tham số | Ôn Tập cá nhân hóa |
+| Kiểm tra thích ứng (IRT) | Xác minh 3/3 phiếu bầu | Luyện Tập Thích Ứng |
+
+---
+
+## 15. Tài Liệu Tham Khảo
+
+Tất cả nguồn đã qua kiểm tra phản biện độc lập (214 tác nhân AI, 50 nguồn). Số liệu từ các nguồn bị bác bỏ đã được loại ra và không xuất hiện trong báo cáo này.
+
+### Nghiên Cứu Phương Pháp Giáo Dục (Kiểm Chứng Ngoại Vi)
+
+| Ký hiệu | Tài liệu | Kết quả kiểm chứng |
+|---------|----------|-------------------|
+| [A] | Donoghue, G. M. & Hattie, J. A. C. (2021). "A Meta-Analysis of Ten Learning Techniques." *Frontiers in Education*, DOI: 10.3389/feduc.2021.581216. 242 nghiên cứu, 169.179 học sinh. | 3/3 phiếu bầu xác nhận |
+| [B] | Cepeda, N. J. et al. (2006). "Distributed practice in verbal recall tasks." *Psychological Bulletin*, PMID 16719566. 839 bài đánh giá, 317 thí nghiệm. | 3/3 phiếu bầu xác nhận |
+| [C] | Roediger, H. L. & Karpicke, J. D. (2006). "Test-Enhanced Learning." *Psychological Science*, 17(3), 249–255. | 2/3 phiếu bầu xác nhận |
+| [D] | VanLehn, K. (2011). "The relative effectiveness of human tutoring, intelligent tutoring systems, and other tutoring systems." *Educational Psychologist*, 46(4), 197–221. ERIC EJ946764. 1.400+ trích dẫn. | 3/3 phiếu bầu (thư mục); 2/3 (chỉ số cụ thể) |
+| [E] | Sailer, M. & Homner, L. (2020). "The Gamification of Learning: A Meta-analysis." *Educational Psychology Review*, PMC8037535. 18 nghiên cứu thực nghiệm. | 2/3 phiếu bầu xác nhận |
+| [F] | U.S. Department of Education (2010). *Evaluation of Evidence-Based Practices in Online Learning.* Phân tích 46 nghiên cứu. | Tài liệu chính thống Bộ GD Mỹ |
+| [G] | Rohrer, D., Dedrick, R. F., & Stershic, S. (2015). "Interleaved practice improves mathematics learning." *Journal of Educational Psychology*, 107(3), 900–908. | Nghiên cứu xen kẽ chủ đề Toán |
+
+### Nghiên Cứu Thuật Toán (Kiểm Chứng Nội Vi)
+
+| Ký hiệu | Tài liệu | Kết quả kiểm chứng |
+|---------|----------|-------------------|
+| [H] | Sharpnack, J. et al. (2024–2025). "BanditCAT and AutoIRT." *PMLR Proceedings* (arxiv: 2410.21033). | 3/3 phiếu bầu xác nhận |
+| [I] | Corbett, A. T. & Anderson, J. R. (1994). "Knowledge tracing: Modeling the acquisition of procedural knowledge." *User Modeling and User-Adapted Interaction*, 4(4), 253–278. | Tài liệu gốc BKT — chuẩn ngành |
+| [J] | Open Spaced Repetition. *SRS Benchmark* (kho dữ liệu, cập nhật liên tục). 350+ triệu lượt ôn tập, 9.999 người dùng. FSRS-7 cá nhân hóa: RMSE = 0.0655 vs 0.0910 mặc định (−39%). | 3/3 phiếu bầu xác nhận |
+| [K] | Vermeiren, B. et al. (2025). "Dynamic K-value ELO for educational mastery tracking." *UMUAI*, Springer. PMC12682724. | 3/3 phiếu bầu xác nhận |
+
+### Tuyên Bố Bị Bác Bỏ — Không Nên Trích Dẫn
+
+Các số liệu sau được lưu hành rộng rãi trên internet nhưng **không vượt qua kiểm tra phản biện độc lập** (0/3 phiếu). Zenith không sử dụng chúng:
+
+- ~~"Gia sư AI hiệu quả bằng hoàn toàn gia sư người thật với d=1.0"~~ — Bác bỏ 0/3
+- ~~"DreamBox Learning cải thiện 2.5 lần so với phương pháp truyền thống"~~ — Bác bỏ 0/3
+- ~~"Carnegie Learning cải thiện điểm 30%"~~ — Bác bỏ 0/3
+- ~~"Lặp lại ngắt quãng cải thiện ghi nhớ 200%"~~ — Bác bỏ 0/3
+- ~~"Bloom's 2-sigma effect là kết quả có thể tái tạo"~~ — Bác bỏ 2/3 (là tạo tác từ ngưỡng 90% thành thạo, không phải baseline thông thường)
+
+---
+
+## Phụ Lục: Danh Sách Đầy Đủ 26 Trang/Tính Năng
+
+| Tên trang | Đường dẫn | Mô tả ngắn |
+|-----------|-----------|------------|
+| Trang chủ | `/` | Giới thiệu nền tảng, nút bắt đầu |
+| Chọn đề thi | `/exams` | Duyệt 86 đề, lọc theo lớp/gói |
+| Giao diện thi | `/test/:id` | Làm bài thi có hẹn giờ, gợi ý AI |
+| Kết quả | `/results/:id` | Điểm số, AI phân tích, đề xuất trường |
+| Kế hoạch học | `/study-plan/:id` | Kế hoạch phục hồi sau bài thi |
+| Kế hoạch thích ứng | `/adaptive-plan` | Kế hoạch cập nhật theo tiến độ |
+| Luyện tập thích ứng | `/practice/adaptive` | 15 câu/buổi, tập trung điểm yếu |
+| Ôn tập | `/review` | Lặp lại ngắt quãng FSRS |
+| Oracle | `/oracle` | Gia sư Toán AI, OCR, giọng nói |
+| Tiến độ | `/progress` | Biểu đồ tổng thể, chuẩn tỉnh |
+| Bản đồ khái niệm | `/concept-map` | 58 nút, màu theo mức thành thạo |
+| Lịch sử | `/history` | Tất cả bài đã thi, xu hướng điểm |
+| Lỗi sai | `/mistakes` | Danh sách câu sai, giải thích AI |
+| Phân tích lỗi | `/error-analysis` | Biểu đồ 5 loại lỗi theo chủ đề |
+| Kiểm tra chẩn đoán | `/diagnostic` | 12 câu xác định điểm yếu ban đầu |
+| Kiểm tra xếp lớp | `/placement` | 10 câu ước lượng năng lực |
+| Thử thách hàng ngày | `/daily` | 1 câu/ngày, theo dõi streak |
+| Tạo đề AI | `/generate-exam` | AI tạo đề theo yêu cầu (streaming) |
+| Lớp học | `/class` *(chưa mở)* | Tạo/tham gia lớp, giáo viên theo dõi — tính năng đã xây dựng, chưa kích hoạt route |
+| Tài khoản | `/account` | Thống kê, gói dịch vụ, lịch sử Tia |
+| Chia sẻ kết quả | `/share` | Hình ảnh kết quả để đăng mạng xã hội |
+| Thách đấu | `/challenge` | Thi cùng bạn bè, so sánh điểm |
+| Admin | `/admin` | Quản lý người dùng (nội bộ) |
+| Bảo mật Admin | `/admin/security-events` | Giám sát sự kiện bảo mật (nội bộ) |
+
+---
+
+*Báo cáo được soạn thảo bằng cách tổng hợp toàn bộ mã nguồn hiện tại của ứng dụng (24 trang đã triển khai, tính năng Lớp Học đã xây dựng nhưng chưa mở route) kết hợp với kết quả nghiên cứu học thuật đã kiểm chứng qua harness nghiên cứu phản biện đa tác nhân (108 tác nhân AI, 26 nguồn, 9/25 tuyên bố được xác nhận). Các số liệu nghiên cứu có nguồn dẫn [1]–[9]. Số liệu về sản phẩm (số đề, số câu hỏi, v.v.) lấy từ dữ liệu hiện tại trong mã nguồn.*
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000000000000000000000000000000000000..e143551a20bf6ffe31f950612d58190da7615d6f
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,223 @@
+# AI Agent App
+
+Zenith — exam-taking app for Vietnamese students (grade-10 and THPT math exams). Currently a **clean, stripped-down baseline**: static exam content + the question-taking/scoring experience only. All AI tutoring, auth, credits/billing, admin moderation, and gamification were removed in the 2026-08-23 strip-to-exam-core pass ([[project_strip_to_exam_core]]) to serve as the foundation for a from-scratch visual/product reimagining. No AI router, no backend LLM calls, no user accounts exist in this codebase right now — don't assume any of the old AI/auth/credit architecture below is still current without checking the code first.
+
+## Stack
+
+- **Python** — FastAPI, pydantic-settings, aiosqlite
+- **Runtime** — uvicorn
+- **Frontend** — React (Vite), React Router, Framer Motion, GSAP, Recharts, Radix/shadcn UI (`@base-ui/react`)
+
+## Dev commands
+
+```bash
+# Run both backend + frontend together (preferred)
+npm install # install concurrently (root, first time only)
+npm run dev # starts backend :8000 and frontend :5173 concurrently
+
+# Backend only
+pip install -r requirements.txt
+PYTHONPATH=backend uvicorn app.main:app --reload # http://localhost:8000
+PYTHONPATH=backend python3 -m pytest backend/tests/ -q # backend/tests/test_exams.py — 7 tests
+
+# Frontend only
+cd exam-app && npm install && npm run dev # http://localhost:5173
+cd exam-app && npm run test # vitest
+```
+
+## Project structure
+
+```
+backend/app/
+ config.py # Settings (pydantic-settings): allowed_origins, sqlite_path; get_settings()
+ db.py # AsyncSQLitePool — asyncpg-compatible wrapper over aiosqlite (single connection + lock)
+ main.py # lifespan seeds exams/questions/exam_questions from exam-app/src/data/*.json on first boot
+ # routes: GET /health, GET /exams, GET /exams/{id}, GET /questions, POST /questions/batch
+backend/tests/
+ test_exams.py # covers all 5 routes against a module-scoped seeded SQLite fixture
+
+exam-app/src/
+ api/
+ index.js # loadExams / loadThiThuExams / loadExamById / loadQuestionsByIds — static JSON with
+ # optional live-backend fallback via _apiFetch
+ components/
+ QuestionCard.jsx # Question renderer + static explanation toggle (practice mode) — no AI hints
+ Navbar.jsx # Bare nav shell: VantageLogo + "Thi thử" / "Lịch sử" links (no auth/credits UI)
+ motion/ # Reveal3D.jsx, Scene3DLazy.jsx, scenes/ — GSAP/3D animation infra (Vantage rebrand)
+ pages/
+ ExamSelect.jsx # Exam list + year/search filters + preview modal (briefing checklist, weak-topic warning)
+ TestInterface.jsx# Timed/practice exam-taking flow; tab-switch pause overlay in timed mode
+ Results.jsx # Score hero + 4 tabs: Kết quả (radar chart), Nhận xét (local heuristic insights via
+ # engine/aiEngine.js — NOT a backend AI call), Câu sai (wrong-answer review), Trường phù hợp
+ History.jsx # Past attempts, localStorage-backed
+ context/
+ ExamContext.jsx # Exam-taking session state (pure, no auth dependency)
+ HistoryContext.jsx # Pure localStorage history — no server sync
+```
+
+## Frontend brand identity (rebrand in progress)
+
+exam-app's visible brand is being renamed from "Luminary" to **Vantage** — a full replacement of typography, icons, color palette, and visual-asset motif (not an extension of the old system). This is unrelated to the "Zenith" internal product name above; only the exam-app UI's consumer-facing brand changes.
+
+- **Mark**: summit-beacon motif (geometric peak + radiant glow) replacing the old astrolabe mark (`AstrolabeMark`/`LuminaryLogo.jsx` → `VantageLogo.jsx`)
+- **Typography**: Fraunces (display) + Inter (body/UI) — both confirmed full Vietnamese diacritic support — replacing Cormorant Garamond + Plus Jakarta Sans; JetBrains Mono kept for math/code
+- **Icons**: Phosphor (`@phosphor-icons/react`) replacing `lucide-react`
+- **Palette**: gold/amber "ascent" accent + indigo-dusk base replacing the cobalt/violet tokens; `--mastery-0..5` reskinned as base-camp→vantage-point
+- **Animation**: GSAP (+ `@gsap/react`) added alongside framer-motion (not replacing it) for scroll choreography and a tiered 3D-transform system (CSS 3D on every route, GSAP-choreographed 3D on high-traffic pages, optional lazy-loaded WebGL on 1-2 hero/celebration surfaces only)
+
+Full rollout plan (phases, file-level detail, rationale, sources) lives in the approved blueprint: `C:\Users\Tai Minh\.claude\plans\groovy-baking-beaver.md`. Check that plan's phase progress before assuming old "Luminary" naming/tokens are still current.
+
+## Env vars
+
+**`backend/.env`** (copy from `backend/.env.example`, never commit)
+
+| Variable | Example value |
+|---|---|
+| `ALLOWED_ORIGINS` | `http://localhost:5173,https://exam-app-ey0.pages.dev` |
+| `SQLITE_PATH` | `./app.db` (local) / `/data/app.db` (HF Spaces) |
+
+**`exam-app/.env`** (copy from `exam-app/.env.example`, never commit)
+
+| Variable | Example value |
+|---|---|
+| `VITE_API_BASE_URL` | `http://localhost:8000` |
+
+## Test suite
+
+Single suite, no markers/tiers needed anymore:
+```bash
+PYTHONPATH=backend python3 -m pytest backend/tests/ -q # backend/tests/test_exams.py
+cd exam-app && npx vitest run # frontend
+```
+
+## Key patterns
+
+**Static-JSON-first data flow** — `exam-app/src/api/index.js` reads exam/question data from the bundled `exam-app/src/data/{exams,questions}.json` and only falls back to the live backend (`_apiFetch`) when the static JSON doesn't have what's needed. The exam-taking flow works with the frontend alone; the backend's SQLite tables are just a seeded mirror of the same JSON for future backend-driven use.
+
+**Local-only "AI" naming is not backend AI** — `exam-app/src/engine/aiEngine.js` (`analyzeResult`) and `exam-app/src/utils/studyReminder.js` are pure client-side heuristics (no imports, no network calls) despite the "ai" naming. Don't confuse them with the AI backend features that were removed — verify with a grep for imports before assuming either calls out to a model.
+
+## Development workflow
+
+This project uses two collaborating tools for code intelligence and structured work:
+
+- **GitNexus MCP** — knowledge graph of 109 symbols and 162 relationships, indexed from the codebase. Use it to understand blast radius before editing, trace execution flows, and do safe renames.
+- **agent-skills plugin** — structured workflow skills (spec, plan, build, test, review, etc.) that map to common engineering tasks.
+
+### When to reach for each
+
+| Task | Use |
+|---|---|
+| "What calls `run_agent()`?" / "What breaks if I change this?" | GitNexus: `gitnexus_impact`, `gitnexus_context` |
+| "How does the tool loop work?" / "Find all entry points" | GitNexus: `gitnexus_query` |
+| Adding a new feature end-to-end | agent-skills: `/spec` → `/plan` → `/build` |
+| Fixing a bug with proof it's fixed | agent-skills: `/test` (Prove-It pattern) |
+| Pre-merge check | agent-skills: `/review` + GitNexus: `gitnexus_detect_changes` |
+| Renaming a symbol across files | GitNexus: `gitnexus_rename` |
+
+### GitNexus rules
+
+- **Before any coding task in `exam-app/` or `backend/`** — ALWAYS run `npx gitnexus analyze --embeddings` to refresh the index, then run the relevant GitNexus MCP tools (impact, context, query) before writing a single line of code.
+- **Before editing any symbol** — run `gitnexus_impact({target: "symbolName", direction: "upstream"})` and report the blast radius. Stop and warn the user on HIGH or CRITICAL risk.
+- **Before committing** — run `gitnexus_detect_changes()` to verify only expected symbols were affected.
+- **Never rename with find-and-replace** — use `gitnexus_rename` which understands the call graph.
+
+### GitNexus skill files
+
+| Goal | Skill |
+|---|---|
+| Architecture exploration | `.claude/skills/gitnexus/gitnexus-exploring/SKILL.md` |
+| Blast radius / impact analysis | `.claude/skills/gitnexus/gitnexus-impact-analysis/SKILL.md` |
+| Bug tracing | `.claude/skills/gitnexus/gitnexus-debugging/SKILL.md` |
+| Refactoring / rename / extract | `.claude/skills/gitnexus/gitnexus-refactoring/SKILL.md` |
+| Full tool + resource reference | `.claude/skills/gitnexus/gitnexus-guide/SKILL.md` |
+
+### GitNexus index state
+
+Indexed as **AI-Agent-App** — re-index with `gitnexus analyze /mnt/d/AI-Agent-App --skip-git` after significant changes.
+
+### GitNexus MCP resources
+
+| Resource | Use for |
+|----------|---------|
+| `gitnexus://repo/AI-Agent-App/context` | Codebase overview, index freshness |
+| `gitnexus://repo/AI-Agent-App/processes` | All execution flows |
+
+
+# GitNexus — Code Intelligence
+
+This project is indexed by GitNexus as **AI-Agent-App** (2554 symbols, 3939 relationships, 79 execution flows). Use the GitNexus MCP tools to understand code, assess impact, and navigate safely.
+
+> Index stale? Run `node .gitnexus/run.cjs analyze` from the project root — it auto-selects an available runner. No `.gitnexus/run.cjs` yet? `npx gitnexus analyze` (npm 11 crash → `npm i -g gitnexus`; #1939).
+
+## Always Do
+
+- **MUST run impact analysis before editing any symbol.** Before modifying a function, class, or method, run `impact({target: "symbolName", direction: "upstream"})` and report the blast radius (direct callers, affected processes, risk level) to the user.
+- **MUST run `detect_changes()` before committing** to verify your changes only affect expected symbols and execution flows. For regression review, compare against the default branch: `detect_changes({scope: "compare", base_ref: "main"})`.
+- **MUST warn the user** if impact analysis returns HIGH or CRITICAL risk before proceeding with edits.
+- When exploring unfamiliar code, use `query({query: "concept"})` to find execution flows instead of grepping. It returns process-grouped results ranked by relevance.
+- When you need full context on a specific symbol — callers, callees, which execution flows it participates in — use `context({name: "symbolName"})`.
+
+## Never Do
+
+- NEVER edit a function, class, or method without first running `impact` on it.
+- NEVER ignore HIGH or CRITICAL risk warnings from impact analysis.
+- NEVER rename symbols with find-and-replace — use `rename` which understands the call graph.
+- NEVER commit changes without running `detect_changes()` to check affected scope.
+
+## Resources
+
+| Resource | Use for |
+|----------|---------|
+| `gitnexus://repo/AI-Agent-App/context` | Codebase overview, check index freshness |
+| `gitnexus://repo/AI-Agent-App/clusters` | All functional areas |
+| `gitnexus://repo/AI-Agent-App/processes` | All execution flows |
+| `gitnexus://repo/AI-Agent-App/process/{name}` | Step-by-step execution trace |
+
+## CLI
+
+| Task | Read this skill file |
+|------|---------------------|
+| Understand architecture / "How does X work?" | `.claude/skills/gitnexus/gitnexus-exploring/SKILL.md` |
+| Blast radius / "What breaks if I change X?" | `.claude/skills/gitnexus/gitnexus-impact-analysis/SKILL.md` |
+| Trace bugs / "Why is X failing?" | `.claude/skills/gitnexus/gitnexus-debugging/SKILL.md` |
+| Rename / extract / split / refactor | `.claude/skills/gitnexus/gitnexus-refactoring/SKILL.md` |
+| Tools, resources, schema reference | `.claude/skills/gitnexus/gitnexus-guide/SKILL.md` |
+| Index, status, clean, wiki CLI commands | `.claude/skills/gitnexus/gitnexus-cli/SKILL.md` |
+
+
+
+## Deploy commands
+
+### Hugging Face Space (backend) — orphan push required
+
+```bash
+git checkout master
+git checkout --orphan hf-deploy-new
+git add -A
+git commit -m "deploy: $(git log master --oneline -1 | cut -c1-7)"
+git rm --cached tools/pdfs/amc8_2019.pdf tools/pdfs/cemc_gauss8_2023.pdf tools/pdfs/ukmt_imc_2020.pdf tools/pdfs/ukmt_jmc_2019.pdf
+git rm --cached exam-app/public/images/questions/*.png
+git commit --amend --no-edit
+git branch -D hf-deploy
+git branch -m hf-deploy-new hf-deploy
+git push --force space hf-deploy:main
+git checkout -f master
+```
+
+**Never** use `git merge master` on hf-deploy — the repo history contains old binary files that HF rejects. The orphan commit has no parents, so none of that history is included.
+
+**Binary files must be stripped after the initial commit via `git rm --cached` + `git commit --amend`.** HF Spaces rejects any push containing binary files — this includes `tools/pdfs/*.pdf` AND `exam-app/public/images/questions/*.png` (the question images are served by Cloudflare Pages, not the HF backend). `git rm --cached` before `git add -A` does not work because `git add -A` re-adds the files. The correct order is: commit everything first, then remove the binaries from the index with `--cached`, then amend.
+
+**Use `git checkout -f master`** (force) when returning to master after the orphan branch. The PDF files remain as untracked working-tree files after `git rm --cached`, which causes a plain `git checkout master` to abort with "would be overwritten by checkout".
+
+### Cloudflare Pages (frontend) — must use `--branch=main`
+
+```bash
+cd exam-app
+VITE_API_BASE_URL=https://minhtai-ai-agent-app.hf.space npm run build
+npx wrangler pages deploy dist --project-name exam-app --branch=main --commit-dirty=true
+```
+
+**Always** pass `--branch=main`. Without it, wrangler creates a **Preview** deployment (not Production), and `exam-app-ey0.pages.dev` keeps serving the old bundle. The production URL only aliases Production deployments.
+
+**Always** set `VITE_API_BASE_URL` explicitly. `exam-app/.env.local` (used for local dev) takes precedence over `exam-app/.env` in Vite's env loading order, so omitting the explicit override bakes `localhost:8000` into the production bundle.
diff --git a/Dockerfile b/Dockerfile
new file mode 100644
index 0000000000000000000000000000000000000000..3481ade95012b8528aaedf1e2730d711b35ff971
--- /dev/null
+++ b/Dockerfile
@@ -0,0 +1,27 @@
+FROM python:3.11-slim
+
+WORKDIR /app
+
+RUN apt-get update && rm -rf /var/lib/apt/lists/*
+
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+COPY backend/ backend/
+COPY scripts/ scripts/
+COPY exam-app/src/data/ exam-app/src/data/
+
+ENV PYTHONPATH=/app/backend:/app/scripts
+
+# Auto-run on first boot: fill zero-unit wiki topics (e.g. geometry) and sanitize duplicates.
+# Both self-disable via _hf_set_space_variable after success, so they only run once.
+ENV CRAWL_GAP_FILL_ENABLED=true
+ENV WIKI_SANITIZE_ENABLED=true
+
+# HF Spaces requires a non-root user
+RUN useradd -m -u 1000 appuser && chown -R appuser /app
+USER appuser
+
+EXPOSE 7860
+
+CMD uvicorn app.main:app --host 0.0.0.0 --port 7860
diff --git a/README.md b/README.md
new file mode 100644
index 0000000000000000000000000000000000000000..f05eb593872443c271f55ef6c84dc9d1ab8cc3c7
--- /dev/null
+++ b/README.md
@@ -0,0 +1,15 @@
+---
+title: AI Agent App
+emoji: 🤖
+colorFrom: blue
+colorTo: indigo
+sdk: docker
+pinned: false
+app_port: 7860
+---
+
+# AI Agent App
+
+Vietnamese aluminum/glass door sales chatbot + AI-powered exam backend.
+
+Built with FastAPI + Claude via ai-router proxy.
diff --git a/backend/.env.example b/backend/.env.example
new file mode 100644
index 0000000000000000000000000000000000000000..f57d87440ce5488f4071b44c89a152689ad2c2a5
--- /dev/null
+++ b/backend/.env.example
@@ -0,0 +1,31 @@
+ANTHROPIC_BASE_URL=https://ai-router.locdo.tech
+ANTHROPIC_AUTH_TOKEN=your_token_here
+ANTHROPIC_DEFAULT_OPUS_MODEL=claude-opus-4.6
+ANTHROPIC_DEFAULT_SONNET_MODEL=claude-sonnet-4.6
+ANTHROPIC_DEFAULT_HAIKU_MODEL=claude-haiku-4.5
+# Model to retry against when the router reports the primary model's provider is
+# unavailable (401 expired OAuth session, 503 auth_unavailable). Leave blank to
+# disable fallback. gemini-2.5-pro is a good default — it's on the same router
+# and stays up independently of Claude's provider session.
+ANTHROPIC_FALLBACK_MODEL=gemini-2.5-pro
+# AI Router — single ingress for backend agent model calls (backend/app/agent/router_client.py).
+# Unset by default: /agent/* endpoints return 503 until these are configured.
+AI_ROUTER_BASE_URL=https://ai-router.locdo.tech
+AI_ROUTER_API_KEY=your_ai_router_key_here
+AI_ROUTER_MODEL=claude-sonnet-4.6
+# Tried in order if AI_ROUTER_MODEL's provider is down (401/403/500/502/503) — the router
+# has multiple providers (Claude/Gemini/Copilot-GPT) behind one key, so a provider-specific
+# outage on one doesn't have to take the whole feature down.
+AI_ROUTER_FALLBACK_MODELS=gemini-2.5-pro,gemini-2.5-flash,copilot-gpt-4o
+ALLOWED_ORIGINS=http://localhost:5173
+# SQLite database path. On HF Spaces use /data/app.db (persistent storage must be enabled).
+SQLITE_PATH=/data/app.db
+# Google OAuth 2.0 Client ID — create at console.cloud.google.com → Credentials → OAuth 2.0 Client IDs
+# Add Authorised JavaScript Origins: http://localhost:5173 and your HF Space URL
+GOOGLE_CLIENT_ID=your_google_client_id_here
+# JWT signing secret — generate with: python -c "import secrets; print(secrets.token_hex(32))"
+JWT_SECRET=your_jwt_secret_here
+# Static admin key sent in X-Admin-Key header for all admin endpoints.
+# Generate with: python -c "import secrets; print(secrets.token_hex(32))"
+ADMIN_KEY=your_admin_key_here
+APP_URL=https://exam-app-ey0.pages.dev
diff --git a/backend/app/__init__.py b/backend/app/__init__.py
new file mode 100644
index 0000000000000000000000000000000000000000..e69de29bb2d1d6434b8b29ae775ad8c2e48c5391
diff --git a/backend/app/agent/__init__.py b/backend/app/agent/__init__.py
new file mode 100644
index 0000000000000000000000000000000000000000..e69de29bb2d1d6434b8b29ae775ad8c2e48c5391
diff --git a/backend/app/agent/auditor.py b/backend/app/agent/auditor.py
new file mode 100644
index 0000000000000000000000000000000000000000..5ae3c2d89d2a96c5c411a5ad3b36e9670f5d1d2d
--- /dev/null
+++ b/backend/app/agent/auditor.py
@@ -0,0 +1,83 @@
+"""Audits an EXISTING question (static or agent-origin) already in the `questions` table.
+
+Mirrors generator.py + verifier.py's trust boundary: the model never gets to declare a
+question correct or wrong on its own say-so. It only transcribes the question into the
+same sympy-checkable shape generator.py drafts in, then verifier.verify() — the same
+independent symbolic check used for newly-generated questions — decides. A question that
+doesn't reduce to that shape (geometry proofs, prose choices, etc.) comes back
+`unauditable`, not a false pass.
+"""
+import json
+from dataclasses import dataclass
+from pathlib import Path
+
+from app.agent import verifier
+from app.agent.router_client import AiRouterClient
+
+_PROMPT_PATH = Path(__file__).parent / "prompts" / "audit_question.md"
+
+
+class AuditShapeError(ValueError):
+ """Raised when the model's transcription JSON is malformed."""
+
+
+@dataclass
+class AuditResult:
+ status: str # "verified" | "mismatch" | "unauditable" | "error"
+ stored_index: int
+ verified_index: int | None
+ reason: str
+
+
+def _validate_shape(transcript: dict) -> None:
+ if "transcribable" not in transcript:
+ raise AuditShapeError("missing 'transcribable' field")
+ if transcript["transcribable"] is False:
+ if "reason" not in transcript:
+ raise AuditShapeError("non-transcribable response missing 'reason'")
+ return
+ required = ("variables", "given_equations", "target_expression", "choice_expressions", "claimed_correct_index")
+ missing = [f for f in required if f not in transcript]
+ if missing:
+ raise AuditShapeError(f"transcript missing fields: {missing}")
+ if not isinstance(transcript["choice_expressions"], list) or not transcript["choice_expressions"]:
+ raise AuditShapeError("choice_expressions must be a non-empty list")
+
+
+async def audit_question(client: AiRouterClient, question_row: dict) -> AuditResult:
+ """question_row needs: question, choices (list of str), correct (0-based index)."""
+ choices = question_row["choices"]
+ stored_index = question_row["correct"]
+
+ system_prompt = _PROMPT_PATH.read_text(encoding="utf-8")
+ choices_block = "\n".join(f"{i}: {c}" for i, c in enumerate(choices))
+ user_prompt = f"Question: {question_row['question']}\n\nChoices:\n{choices_block}"
+
+ try:
+ transcript = await client.complete_json(system_prompt, user_prompt)
+ _validate_shape(transcript)
+ except Exception as exc:
+ return AuditResult("error", stored_index, None, f"transcription failed: {exc}")
+
+ if transcript["transcribable"] is False:
+ return AuditResult("unauditable", stored_index, None, transcript["reason"])
+
+ if len(transcript["choice_expressions"]) != len(choices):
+ return AuditResult(
+ "error", stored_index, None,
+ f"transcript has {len(transcript['choice_expressions'])} choices, question has {len(choices)}",
+ )
+
+ # verify()'s `ok` flag reflects the model's OWN claimed_correct_index, which audit
+ # doesn't care about — only the independently computed verified_index matters here.
+ result = verifier.verify(transcript)
+ if result.verified_index is None:
+ return AuditResult("error", stored_index, None, f"could not independently determine an answer: {result.reason}")
+
+ if result.verified_index == stored_index:
+ return AuditResult("verified", stored_index, result.verified_index, "stored answer confirmed independently")
+
+ return AuditResult(
+ "mismatch", stored_index, result.verified_index,
+ f"independently computed answer is index {result.verified_index}, stored answer is index {stored_index}",
+ )
diff --git a/backend/app/agent/generator.py b/backend/app/agent/generator.py
new file mode 100644
index 0000000000000000000000000000000000000000..488b3a44c5fcbbe6f342ad4efec16a0a7685c036
--- /dev/null
+++ b/backend/app/agent/generator.py
@@ -0,0 +1,52 @@
+"""Drafts a structured math-question candidate via ai-router.locdo.tech.
+
+The draft is a constrained JSON shape (see prompts/draft_question.md), never free-form
+prose — that's what makes verifier.py's independent symbolic check possible. The model's
+own claimed answer is kept, but it's advisory: verifier.py is the actual judge.
+"""
+from pathlib import Path
+
+from app.agent.router_client import AiRouterClient
+
+_PROMPT_PATH = Path(__file__).parent / "prompts" / "draft_question.md"
+
+REQUIRED_FIELDS = (
+ "question_tex",
+ "variables",
+ "given_equations",
+ "target_expression",
+ "choice_expressions",
+ "claimed_correct_index",
+ "explanation_tex",
+)
+
+
+class DraftShapeError(ValueError):
+ """Raised when the model's JSON is missing a required field or has the wrong shape."""
+
+
+def _validate_shape(draft: dict) -> None:
+ missing = [f for f in REQUIRED_FIELDS if f not in draft]
+ if missing:
+ raise DraftShapeError(f"draft missing fields: {missing}")
+ if not isinstance(draft["choice_expressions"], list) or len(draft["choice_expressions"]) != 4:
+ raise DraftShapeError("choice_expressions must be a list of exactly 4 entries")
+ if not isinstance(draft["variables"], list) or not draft["variables"]:
+ raise DraftShapeError("variables must be a non-empty list")
+ idx = draft["claimed_correct_index"]
+ if not isinstance(idx, int) or not (0 <= idx < 4):
+ raise DraftShapeError("claimed_correct_index must be an integer in [0, 3]")
+
+
+async def draft(client: AiRouterClient, topic: str, difficulty: str, feedback: str | None = None) -> dict:
+ """Ask the router for one candidate question. Raises DraftShapeError on a malformed reply."""
+ system_prompt = _PROMPT_PATH.read_text(encoding="utf-8")
+ user_prompt = f"Topic: {topic}\nDifficulty: {difficulty}"
+ if feedback:
+ user_prompt += f"\n\nYour previous attempt was rejected: {feedback}\nDraft a different question."
+
+ result = await client.complete_json(system_prompt, user_prompt)
+ _validate_shape(result)
+ result["topic"] = topic
+ result["difficulty"] = difficulty
+ return result
diff --git a/backend/app/agent/orchestrator.py b/backend/app/agent/orchestrator.py
new file mode 100644
index 0000000000000000000000000000000000000000..821519771d0616f450de4bd945ec004cf4069460
--- /dev/null
+++ b/backend/app/agent/orchestrator.py
@@ -0,0 +1,95 @@
+"""The generate -> verify -> gate loop.
+
+"Fully autonomous" means the gate is a rule (independent symbolic verification passed),
+not a person clicking approve. A verified draft promotes straight into `questions` with
+origin='agent'; a draft that fails after MAX_ATTEMPTS lands in `pending_questions` with
+status='rejected' for a human to inspect later — the safety valve, not the default path.
+"""
+import hashlib
+import json
+import logging
+import uuid
+
+from app.agent import generator, verifier
+from app.agent.router_client import AiRouterClient
+
+logger = logging.getLogger(__name__)
+
+MAX_ATTEMPTS = 3
+
+
+def _content_hash(draft: dict) -> str:
+ canonical = json.dumps(
+ {k: draft[k] for k in ("topic", "difficulty", "given_equations", "target_expression")},
+ sort_keys=True,
+ )
+ return hashlib.sha256(canonical.encode("utf-8")).hexdigest()
+
+
+def _draft_to_question_row(draft: dict, verified_index: int) -> dict:
+ return {
+ "id": f"q_agent_{uuid.uuid4().hex[:12]}",
+ "source": "agent-generated",
+ "year": None,
+ "topic": draft["topic"],
+ "difficulty": draft["difficulty"],
+ "question": draft["question_tex"],
+ "choices": [f"${c}$" for c in draft["choice_expressions"]],
+ "correct": verified_index,
+ "explanation": draft["explanation_tex"],
+ "origin": "agent",
+ "qti_identifier": str(uuid.uuid4()),
+ }
+
+
+async def generate_one(pool, client: AiRouterClient, topic: str, difficulty: str) -> dict:
+ """Run the loop for a single item. Returns the resulting pending_questions row."""
+ pending_id = f"pend_{uuid.uuid4().hex[:12]}"
+ feedback = None
+ last_draft = None
+ last_log = []
+
+ for attempt in range(1, MAX_ATTEMPTS + 1):
+ try:
+ last_draft = await generator.draft(client, topic, difficulty, feedback=feedback)
+ except generator.DraftShapeError as exc:
+ last_log.append(f"attempt {attempt}: draft rejected — malformed shape: {exc}")
+ feedback = str(exc)
+ continue
+
+ result = verifier.verify(last_draft)
+ content_hash = _content_hash(last_draft)
+ await pool.execute(
+ "INSERT OR REPLACE INTO content_ledger (content_hash, topic, difficulty, status) VALUES (?,?,?,?)",
+ content_hash, topic, difficulty, "verified" if result.ok else "rejected",
+ )
+
+ if result.ok:
+ row = _draft_to_question_row(last_draft, result.verified_index)
+ await pool.execute(
+ "INSERT INTO questions (id, source, year, topic, difficulty, question, choices, correct, explanation, origin, qti_identifier) "
+ "VALUES (?,?,?,?,?,?,?,?,?,?,?)",
+ row["id"], row["source"], row["year"], row["topic"], row["difficulty"],
+ row["question"], json.dumps(row["choices"], ensure_ascii=False), row["correct"],
+ row["explanation"], row["origin"], row["qti_identifier"],
+ )
+ await pool.execute(
+ "INSERT INTO pending_questions (id, draft_json, status, verification_log, attempt) VALUES (?,?,?,?,?)",
+ pending_id, json.dumps(last_draft, ensure_ascii=False), "verified",
+ json.dumps(last_log + [f"attempt {attempt}: verified as index {result.verified_index}"]), attempt,
+ )
+ return {"id": pending_id, "status": "verified", "question_id": row["id"]}
+
+ last_log.append(f"attempt {attempt}: rejected — {result.reason}")
+ feedback = result.reason
+
+ await pool.execute(
+ "INSERT INTO pending_questions (id, draft_json, status, verification_log, attempt) VALUES (?,?,?,?,?)",
+ pending_id, json.dumps(last_draft, ensure_ascii=False) if last_draft else "{}",
+ "rejected", json.dumps(last_log), MAX_ATTEMPTS,
+ )
+ return {"id": pending_id, "status": "rejected", "log": last_log}
+
+
+async def generate_batch(pool, client: AiRouterClient, topic: str, difficulty: str, count: int) -> list[dict]:
+ return [await generate_one(pool, client, topic, difficulty) for _ in range(count)]
diff --git a/backend/app/agent/prompts/audit_question.md b/backend/app/agent/prompts/audit_question.md
new file mode 100644
index 0000000000000000000000000000000000000000..a9c89648966619e0b3134a1646dd7a622fa10565
--- /dev/null
+++ b/backend/app/agent/prompts/audit_question.md
@@ -0,0 +1,37 @@
+You are auditing an EXISTING multiple-choice math question from a Vietnamese grade-10/THPT
+exam bank — you are not writing a new question. Your job is to transcribe it, without
+changing its meaning, into a sympy-checkable structured form so an independent computer
+algebra system can verify the stored answer key is correct.
+
+Return ONLY a JSON object — no prose, no markdown fences.
+
+If the question reduces to solving for a variable and evaluating a numeric expression
+(the common case — e.g. "if 2x+3=11, what is 4x+6?"), return:
+
+{
+ "transcribable": true,
+ "variables": ["x"],
+ "given_equations": ["2*x + 3 - 11"],
+ "target_expression": "4*x + 6",
+ "choice_expressions": ["22", "8", "14", "16"],
+ "claimed_correct_index": 0
+}
+
+Rules when transcribable:
+- `given_equations` are sympy-parseable expressions that equal zero.
+- `choice_expressions` must be in the SAME ORDER as the question's own choices, one
+ sympy-parseable numeric expression per choice (strip units/LaTeX — "48 cm²" becomes "48").
+ Must have exactly as many entries as the question has choices.
+- `claimed_correct_index` is your own independently-worked answer (0-based), not copied
+ from anything you're told the stored answer is — you are not given the stored answer.
+
+If the question is NOT reducible to this form — geometry proofs, multi-step constructions,
+statistics/probability reasoning, questions with non-numeric or prose choices, anything
+sympy cannot evaluate — return only:
+
+{
+ "transcribable": false,
+ "reason": "short reason this can't be symbolically checked"
+}
+
+Do not include any commentary, only the JSON object.
diff --git a/backend/app/agent/prompts/draft_question.md b/backend/app/agent/prompts/draft_question.md
new file mode 100644
index 0000000000000000000000000000000000000000..b16bea638a43729e4e31acc5bfd560dd579f9430
--- /dev/null
+++ b/backend/app/agent/prompts/draft_question.md
@@ -0,0 +1,24 @@
+You are drafting a multiple-choice math question for a Vietnamese grade-10/THPT exam
+bank. You must return ONLY a JSON object — no prose, no markdown fences — matching this
+exact shape:
+
+{
+ "question_tex": "question text with LaTeX in $...$ delimiters, in Vietnamese",
+ "variables": ["x"],
+ "given_equations": ["2*x + 3 - 11"],
+ "target_expression": "4*x + 6",
+ "choice_expressions": ["22", "8", "14", "16"],
+ "claimed_correct_index": 0,
+ "explanation_tex": "step-by-step explanation with LaTeX in $...$ delimiters, in Vietnamese"
+}
+
+Rules:
+- `given_equations` are sympy-parseable expressions that equal zero (e.g. "2*x + 3 - 11"
+ encodes "2x + 3 = 11"). List every variable actually used in `variables`.
+- `target_expression` is the sympy-parseable expression whose value the question asks for.
+- `choice_expressions` must have exactly 4 entries, each a sympy-parseable numeric
+ expression (e.g. "22", "sqrt(2)", "-3/2") — not prose, not LaTeX.
+- `claimed_correct_index` is your own best answer (0-based index into `choice_expressions`).
+ It will be checked independently by a computer algebra system — it does not need to be
+ hedged, but it does need to be your genuine best answer, not a placeholder.
+- Do not include any commentary, only the JSON object.
diff --git a/backend/app/agent/router_client.py b/backend/app/agent/router_client.py
new file mode 100644
index 0000000000000000000000000000000000000000..e87b86e6083ab68380e7a2dccfb852c8fd7b22db
--- /dev/null
+++ b/backend/app/agent/router_client.py
@@ -0,0 +1,103 @@
+"""Client for ai-router.locdo.tech — the single ingress for backend model calls.
+
+Confirmed contract (see /keys on the router dashboard): OpenAI-compatible chat
+completions live at `/v2/chat/completions` (not the more common `/v1/chat/completions`
+path other self-hosted routers use); an Anthropic-native `/v1/messages` endpoint also
+exists for tool-use-heavy agent work. This client uses the v2 chat-completions shape to
+match generator.py's json_object response format. If the contract changes again, only
+this file needs to change — every other agent module talks to `AiRouterClient`, never to
+an HTTP endpoint directly.
+"""
+import json
+import logging
+
+import httpx
+
+from app.config import Settings
+
+logger = logging.getLogger(__name__)
+
+# Status codes that mean "this model's provider/session is down", not "the request was
+# bad" — worth retrying against a fallback model. Everything we've actually seen from
+# ai-router.locdo.tech during its current outage falls in here: 401 (Claude OAuth expired),
+# 403 (Gemini license), 502 (broken model alias upstream), 503 (auth_unavailable).
+_PROVIDER_DOWN_STATUSES = {401, 403, 500, 502, 503}
+
+
+class RouterNotConfiguredError(RuntimeError):
+ """Raised when AI_ROUTER_BASE_URL isn't set — agent endpoints stay disabled until it is."""
+
+
+class RouterRequestError(RuntimeError):
+ """Raised when every model (primary + fallbacks) failed, or the body was unparseable."""
+
+
+class _ProviderDownError(RuntimeError):
+ """Internal: this model's provider looks down — try the next one in the fallback chain."""
+
+
+class AiRouterClient:
+ def __init__(self, settings: Settings) -> None:
+ if not settings.ai_router_base_url:
+ raise RouterNotConfiguredError(
+ "ai_router_base_url is not set — configure it before calling the agent endpoints"
+ )
+ self._base_url = settings.ai_router_base_url.rstrip("/")
+ self._api_key = settings.ai_router_api_key
+ self._model = settings.ai_router_model
+ self._fallback_models = [
+ m.strip() for m in (settings.ai_router_fallback_models or "").split(",") if m.strip()
+ ]
+
+ async def complete_json(self, system_prompt: str, user_prompt: str) -> dict:
+ """Send a chat-completions request and return the parsed JSON object the model returned.
+
+ Tries `ai_router_model` first, then each of `ai_router_fallback_models` in order if a
+ provider-down status comes back — so one dead provider on the router doesn't take the
+ whole feature down when another still works. Raises RouterRequestError only once every
+ model in the chain has failed, or on a non-provider error (bad request, unparseable JSON).
+ """
+ last_exc: Exception | None = None
+ for model in (self._model, *self._fallback_models):
+ try:
+ return await self._request_one(model, system_prompt, user_prompt)
+ except _ProviderDownError as exc:
+ logger.warning("ai-router model %s unavailable, trying next: %s", model, exc)
+ last_exc = exc
+ continue
+ raise RouterRequestError(f"all models exhausted ({self._model}, {self._fallback_models}): {last_exc}")
+
+ async def _request_one(self, model: str, system_prompt: str, user_prompt: str) -> dict:
+ headers = {"Content-Type": "application/json"}
+ if self._api_key:
+ headers["Authorization"] = f"Bearer {self._api_key}"
+
+ body = {
+ "model": model,
+ "messages": [
+ {"role": "system", "content": system_prompt},
+ {"role": "user", "content": user_prompt},
+ ],
+ "response_format": {"type": "json_object"},
+ "temperature": 0.4,
+ }
+
+ async with httpx.AsyncClient(timeout=30.0) as client:
+ try:
+ resp = await client.post(
+ f"{self._base_url}/v2/chat/completions", headers=headers, json=body
+ )
+ except httpx.HTTPError as exc:
+ raise _ProviderDownError(f"ai-router request failed: {exc}") from exc
+
+ if resp.status_code in _PROVIDER_DOWN_STATUSES:
+ raise _ProviderDownError(f"ai-router returned {resp.status_code}: {resp.text[:300]}")
+ if resp.status_code >= 400:
+ raise RouterRequestError(f"ai-router returned {resp.status_code}: {resp.text[:300]}")
+
+ try:
+ payload = resp.json()
+ content = payload["choices"][0]["message"]["content"]
+ return json.loads(content)
+ except (KeyError, IndexError, json.JSONDecodeError, TypeError) as exc:
+ raise RouterRequestError(f"ai-router response wasn't parseable JSON: {exc}") from exc
diff --git a/backend/app/agent/verifier.py b/backend/app/agent/verifier.py
new file mode 100644
index 0000000000000000000000000000000000000000..993f501c7af5dbafded99cda12eb1a6f063d38f8
--- /dev/null
+++ b/backend/app/agent/verifier.py
@@ -0,0 +1,67 @@
+"""Independently solves a drafted question with sympy and checks the model's claimed answer.
+
+This is the actual autonomy in the generate-verify-gate loop: the model's own claimed
+answer is never trusted on its own. sympy solves `given_equations` for `variables` from
+scratch, evaluates `target_expression` at that solution, and checks which (if any) of
+`choice_expressions` matches — independently of what the model claimed.
+
+Mathics3 escalation (for anything sympy can't parse — e.g. non-algebraic notation) is
+deliberately not implemented yet: nothing in the current question bank needs more than
+sympy can solve, and standing up a second CAS before the first one has a real workload
+would be exactly the kind of premature infra the roadmap argues against.
+"""
+from dataclasses import dataclass
+
+import sympy
+
+
+@dataclass
+class VerificationResult:
+ ok: bool
+ verified_index: int | None # the index sympy independently computed as correct, if unambiguous
+ reason: str
+
+
+def verify(draft: dict) -> VerificationResult:
+ try:
+ symbols = {name: sympy.Symbol(name) for name in draft["variables"]}
+ equations = [sympy.sympify(eq, locals=symbols) for eq in draft["given_equations"]]
+ except (sympy.SympifyError, TypeError, KeyError) as exc:
+ return VerificationResult(False, None, f"could not parse given_equations: {exc}")
+
+ solutions = sympy.solve(equations, list(symbols.values()), dict=True)
+ if not solutions:
+ return VerificationResult(False, None, "system of given_equations has no solution")
+ if len(solutions) > 1:
+ return VerificationResult(False, None, "system of given_equations is underdetermined (multiple solutions)")
+ solution = solutions[0]
+
+ try:
+ target = sympy.sympify(draft["target_expression"], locals=symbols)
+ target_value = sympy.simplify(target.subs(solution))
+ except (sympy.SympifyError, TypeError) as exc:
+ return VerificationResult(False, None, f"could not evaluate target_expression: {exc}")
+
+ matches = []
+ for i, choice_expr in enumerate(draft["choice_expressions"]):
+ try:
+ choice_value = sympy.sympify(choice_expr)
+ except sympy.SympifyError:
+ continue
+ if sympy.simplify(choice_value - target_value) == 0:
+ matches.append(i)
+
+ if not matches:
+ return VerificationResult(False, None, f"no choice matches the independently computed value {target_value}")
+ if len(matches) > 1:
+ return VerificationResult(False, None, f"choices are ambiguous — {len(matches)} choices all equal {target_value}")
+
+ verified_index = matches[0]
+ claimed_index = draft.get("claimed_correct_index")
+ if verified_index != claimed_index:
+ return VerificationResult(
+ False,
+ verified_index,
+ f"model claimed index {claimed_index} but the independently verified answer is index {verified_index}",
+ )
+ return VerificationResult(True, verified_index, "verified")
diff --git a/backend/app/config.py b/backend/app/config.py
new file mode 100644
index 0000000000000000000000000000000000000000..66e2bc724d7ddb432ae596a406e84db1e3db71dc
--- /dev/null
+++ b/backend/app/config.py
@@ -0,0 +1,31 @@
+from functools import lru_cache
+from pathlib import Path
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+# Resolve .env relative to this file so it works regardless of CWD (e.g. npm run dev from repo root)
+_ENV_FILE = Path(__file__).parent.parent / ".env"
+
+
+class Settings(BaseSettings):
+ model_config = SettingsConfigDict(env_file=str(_ENV_FILE), env_file_encoding="utf-8", extra="ignore")
+
+ allowed_origins: str = "http://localhost:5173,https://exam-app-ey0.pages.dev"
+ sqlite_path: str = "/data/app.db"
+
+ # AI router — single ingress for backend model calls (see backend/app/agent/router_client.py).
+ # Unset by default: the agent endpoints stay disabled until this is configured.
+ ai_router_base_url: str | None = None
+ ai_router_api_key: str | None = None
+ ai_router_model: str = "default"
+ # Comma-separated models to try in order if ai_router_model's provider is down
+ # (401/403/500/502/503 from the router) — see AiRouterClient.complete_json.
+ ai_router_fallback_models: str = ""
+
+ @property
+ def allowed_origins_list(self) -> list[str]:
+ return [o.strip() for o in self.allowed_origins.split(",")]
+
+
+@lru_cache
+def get_settings() -> Settings:
+ return Settings()
diff --git a/backend/app/db.py b/backend/app/db.py
new file mode 100644
index 0000000000000000000000000000000000000000..4ee078f0f01dc469bb9a88b1e00976c96d93156b
--- /dev/null
+++ b/backend/app/db.py
@@ -0,0 +1,214 @@
+"""asyncpg-compatible wrapper around aiosqlite for local SQLite storage.
+
+Drop-in replacement for the asyncpg connection pool: same acquire(), fetchrow(),
+fetch(), fetchval(), execute(), and transaction() API, so pg_db.py / analytics.py /
+sanitizer.py require zero changes.
+
+SQL translation handled automatically:
+ $N placeholders → ?
+ = ANY($N) → IN (?,?,?) (array expansion)
+ ::type casts → stripped
+ NOW() → datetime('now')
+ list params → JSON-serialised (for embedding storage)
+
+Architecture note:
+ A single persistent aiosqlite connection is shared across all callers. An
+ asyncio.Lock serialises every acquire() so only one coroutine touches the
+ SQLite file at a time. This eliminates the concurrent-writer corruption that
+ WAL mode's shared-memory coordination (-shm/-wal files) causes on
+ network/container filesystems (NFS, Docker overlays, HuggingFace Spaces /data).
+"""
+import asyncio
+import json
+import logging
+import re
+import sqlite3
+from contextlib import asynccontextmanager
+from pathlib import Path
+from typing import Any, AsyncGenerator, Optional
+
+import aiosqlite
+
+logger = logging.getLogger(__name__)
+
+
+class Row(dict):
+ """Dict that also supports positional (integer) access like asyncpg Record."""
+
+ def __getitem__(self, key: Any) -> Any:
+ if isinstance(key, int):
+ return list(self.values())[key]
+ return super().__getitem__(key)
+
+
+def _translate(query: str, params: tuple) -> tuple[str, list]:
+ """Translate PostgreSQL query + params to SQLite equivalents."""
+ # Detect which $N positions are used by ANY($N) (0-based)
+ any_positions: set[int] = set()
+ for m in re.finditer(r"=\s*ANY\(\$(\d+)\)", query, re.IGNORECASE):
+ any_positions.add(int(m.group(1)) - 1)
+
+ # Expand = ANY($N) → IN (?,?,?)
+ def _expand_any(m: re.Match) -> str:
+ idx = int(m.group(1)) - 1
+ arr = list(params[idx]) if params[idx] else []
+ return f"IN ({','.join(['?'] * len(arr))})" if arr else "IN (NULL)"
+
+ query = re.sub(r"=\s*ANY\(\$(\d+)\)", _expand_any, query, flags=re.IGNORECASE)
+
+ # Strip PostgreSQL type casts: ::jsonb, ::timestamptz, ::text[], ::float, etc.
+ query = re.sub(r"::[a-zA-Z_][\w\[\]]*", "", query)
+
+ # Replace NOW() with SQLite equivalent
+ query = re.sub(r"\bNOW\(\)", "datetime('now')", query, flags=re.IGNORECASE)
+
+ # Build flat params, expanding ANY arrays and serialising lists→JSON
+ new_params: list = []
+ for i, p in enumerate(params):
+ if i in any_positions:
+ new_params.extend(list(p) if p else [])
+ elif isinstance(p, list):
+ new_params.append(json.dumps(p))
+ else:
+ new_params.append(p)
+
+ # Replace remaining $N placeholders with ?
+ query = re.sub(r"\$\d+", "?", query)
+
+ return query, new_params
+
+
+class _Connection:
+ def __init__(self, conn: aiosqlite.Connection) -> None:
+ self._conn = conn
+ self._in_transaction = False
+
+ async def fetchrow(self, query: str, *args) -> Optional[Row]:
+ q, params = _translate(query, args)
+ cur = await self._conn.execute(q, params)
+ row = await cur.fetchone()
+ # Commit after fetch so INSERT … RETURNING rows are both readable and persisted.
+ if not self._in_transaction:
+ await self._conn.commit()
+ if row is None or cur.description is None:
+ return None
+ cols = [d[0] for d in cur.description]
+ return Row(zip(cols, row))
+
+ async def fetch(self, query: str, *args) -> list[Row]:
+ q, params = _translate(query, args)
+ cur = await self._conn.execute(q, params)
+ rows = await cur.fetchall()
+ if not self._in_transaction:
+ await self._conn.commit()
+ if cur.description is None:
+ return []
+ cols = [d[0] for d in cur.description]
+ return [Row(zip(cols, r)) for r in rows]
+
+ async def fetchval(self, query: str, *args) -> Any:
+ q, params = _translate(query, args)
+ cur = await self._conn.execute(q, params)
+ row = await cur.fetchone()
+ if not self._in_transaction:
+ await self._conn.commit()
+ return row[0] if row else None
+
+ async def execute(self, query: str, *args) -> str:
+ q, params = _translate(query, args)
+ cur = await self._conn.execute(q, params)
+ if not self._in_transaction:
+ await self._conn.commit()
+ return f"UPDATE {cur.rowcount}"
+
+ @asynccontextmanager
+ async def transaction(self) -> AsyncGenerator[None, None]:
+ self._in_transaction = True
+ try:
+ yield
+ await self._conn.commit()
+ except BaseException:
+ await self._conn.rollback()
+ raise
+ finally:
+ self._in_transaction = False
+
+
+class AsyncSQLitePool:
+ """Single-connection asyncpg-compatible pool backed by a local SQLite file.
+
+ One persistent aiosqlite connection is shared by all callers. An asyncio.Lock
+ ensures only one coroutine executes against the connection at a time, which is
+ both sufficient (single uvicorn process) and necessary (prevents WAL-mode
+ shared-memory corruption on container/NFS filesystems).
+ """
+
+ def __init__(self, db_path: str) -> None:
+ self._path = db_path
+ self._conn: Optional[aiosqlite.Connection] = None
+ self._lock: asyncio.Lock = asyncio.Lock()
+ Path(db_path).parent.mkdir(parents=True, exist_ok=True)
+
+ async def initialize(self) -> None:
+ """Open the persistent connection; auto-recover if the DB file is corrupted."""
+ try:
+ conn = await aiosqlite.connect(self._path)
+ await conn.execute("PRAGMA foreign_keys = ON")
+ await conn.execute("PRAGMA cache_size = -64000") # 64 MB in-process page cache
+ await conn.execute("PRAGMA busy_timeout = 5000") # queue 5 s before failing
+ cur = await conn.execute("PRAGMA integrity_check")
+ row = await cur.fetchone()
+ if row and row[0] != "ok":
+ await conn.close()
+ raise sqlite3.DatabaseError(f"integrity_check: {row[0]}")
+ await conn.commit()
+ self._conn = conn
+ except (sqlite3.DatabaseError, Exception) as exc:
+ logger.warning("DB at %s is corrupt (%s) — wiping and recreating", self._path, exc)
+ if self._conn is not None:
+ try:
+ await self._conn.close()
+ except Exception:
+ pass
+ self._conn = None
+ path = Path(self._path)
+ for suffix in ("", "-wal", "-shm"):
+ candidate = Path(str(path) + suffix)
+ if candidate.exists():
+ candidate.unlink()
+ conn = await aiosqlite.connect(self._path)
+ await conn.execute("PRAGMA foreign_keys = ON")
+ await conn.execute("PRAGMA cache_size = -64000")
+ await conn.execute("PRAGMA busy_timeout = 5000")
+ await conn.commit()
+ self._conn = conn
+ logger.info("Fresh DB created at %s", self._path)
+
+ @asynccontextmanager
+ async def acquire(self) -> AsyncGenerator[_Connection, None]:
+ async with self._lock:
+ yield _Connection(self._conn)
+
+ # Shortcut methods (asyncpg pools expose these directly)
+
+ async def fetchrow(self, query: str, *args) -> Optional[Row]:
+ async with self.acquire() as conn:
+ return await conn.fetchrow(query, *args)
+
+ async def fetch(self, query: str, *args) -> list[Row]:
+ async with self.acquire() as conn:
+ return await conn.fetch(query, *args)
+
+ async def fetchval(self, query: str, *args) -> Any:
+ async with self.acquire() as conn:
+ return await conn.fetchval(query, *args)
+
+ async def execute(self, query: str, *args) -> str:
+ async with self.acquire() as conn:
+ return await conn.execute(query, *args)
+
+ async def close(self) -> None:
+ async with self._lock:
+ if self._conn is not None:
+ await self._conn.close()
+ self._conn = None
diff --git a/backend/app/main.py b/backend/app/main.py
new file mode 100644
index 0000000000000000000000000000000000000000..4a2c91824648f07bc0ad1bb7e20e420e5711139b
--- /dev/null
+++ b/backend/app/main.py
@@ -0,0 +1,340 @@
+import json
+import logging
+import uuid
+from contextlib import asynccontextmanager
+from pathlib import Path
+
+from fastapi import Depends, FastAPI, HTTPException, Request
+from fastapi.middleware.cors import CORSMiddleware
+
+from app.config import get_settings
+
+logger = logging.getLogger(__name__)
+
+_SCHEMA_DDL = [
+ """CREATE TABLE IF NOT EXISTS exams (
+ id TEXT PRIMARY KEY,
+ year INTEGER,
+ title TEXT NOT NULL,
+ duration INTEGER,
+ source TEXT,
+ category TEXT NOT NULL,
+ mode TEXT,
+ total_questions INTEGER,
+ created_at TEXT DEFAULT (datetime('now'))
+ )""",
+ """CREATE TABLE IF NOT EXISTS questions (
+ id TEXT PRIMARY KEY,
+ source TEXT,
+ year INTEGER,
+ topic TEXT,
+ difficulty TEXT,
+ question TEXT NOT NULL,
+ choices TEXT NOT NULL,
+ correct INTEGER NOT NULL,
+ explanation TEXT,
+ created_at TEXT DEFAULT (datetime('now'))
+ )""",
+ """CREATE TABLE IF NOT EXISTS exam_questions (
+ exam_id TEXT NOT NULL REFERENCES exams(id) ON DELETE CASCADE,
+ question_id TEXT NOT NULL REFERENCES questions(id),
+ position INTEGER NOT NULL,
+ PRIMARY KEY (exam_id, question_id)
+ )""",
+ "CREATE INDEX IF NOT EXISTS idx_eq_exam ON exam_questions(exam_id)",
+ "CREATE INDEX IF NOT EXISTS idx_q_topic ON questions(topic)",
+ # Additive columns for the content pipeline (Ascent Roadmap Phase 1/3) — not CREATE IF
+ # NOT EXISTS like the rest of this list, so failures on a re-run are expected and are
+ # swallowed by _apply_schema's per-statement try/except below.
+ "ALTER TABLE questions ADD COLUMN origin TEXT DEFAULT 'human'",
+ "ALTER TABLE questions ADD COLUMN qti_identifier TEXT",
+ """CREATE TABLE IF NOT EXISTS content_reports (
+ id TEXT PRIMARY KEY,
+ question_id TEXT NOT NULL REFERENCES questions(id),
+ kind TEXT NOT NULL,
+ note TEXT,
+ reported_at TEXT DEFAULT (datetime('now'))
+ )""",
+ """CREATE TABLE IF NOT EXISTS pending_questions (
+ id TEXT PRIMARY KEY,
+ draft_json TEXT NOT NULL,
+ status TEXT NOT NULL,
+ verification_log TEXT,
+ attempt INTEGER NOT NULL DEFAULT 1,
+ created_at TEXT DEFAULT (datetime('now'))
+ )""",
+ """CREATE TABLE IF NOT EXISTS content_ledger (
+ content_hash TEXT PRIMARY KEY,
+ topic TEXT,
+ difficulty TEXT,
+ status TEXT NOT NULL,
+ verified_at TEXT DEFAULT (datetime('now'))
+ )""",
+]
+
+
+async def _apply_schema(pool) -> None:
+ """Run DDL idempotently on every startup — all statements are CREATE IF NOT EXISTS."""
+ async with pool.acquire() as conn:
+ for stmt in _SCHEMA_DDL:
+ try:
+ await conn.execute(stmt)
+ except Exception as exc:
+ logger.warning("DDL skipped (%s): %.80s", exc, stmt)
+ logger.info("Schema applied (%d statements)", len(_SCHEMA_DDL))
+
+
+async def _seed_from_json(pool) -> None:
+ """Auto-seed exams and questions tables from bundled JSON files (runs once, INSERT OR IGNORE)."""
+ data_dir = Path(__file__).parent.parent.parent / "exam-app" / "src" / "data"
+ try:
+ exams_path = data_dir / "exams.json"
+ questions_path = data_dir / "questions.json"
+ if not exams_path.exists() or not questions_path.exists():
+ logger.warning("_seed_from_json: JSON files not found at %s — skipping seed", data_dir)
+ return
+ exams = json.loads(exams_path.read_text(encoding="utf-8"))
+ questions = json.loads(questions_path.read_text(encoding="utf-8"))
+ async with pool.acquire() as conn:
+ async with conn.transaction():
+ for e in exams:
+ await conn.execute(
+ "INSERT OR IGNORE INTO exams (id, year, title, duration, source, category, mode, total_questions) VALUES (?,?,?,?,?,?,?,?)",
+ e["id"], e.get("year"), e["title"], e.get("duration"), e.get("source"),
+ e["category"], e.get("mode"), e.get("totalQuestions"),
+ )
+ for q in questions:
+ await conn.execute(
+ "INSERT OR IGNORE INTO questions (id, source, year, topic, difficulty, question, choices, correct, explanation) VALUES (?,?,?,?,?,?,?,?,?)",
+ q["id"], q.get("source"), q.get("year"), q.get("topic"), q.get("difficulty"),
+ q["question"], json.dumps(q.get("choices", []), ensure_ascii=False),
+ q["correct"], q.get("explanation"),
+ )
+ for e in exams:
+ for i, qid in enumerate(e.get("questionIds", [])):
+ await conn.execute(
+ "INSERT OR IGNORE INTO exam_questions (exam_id, question_id, position) VALUES (?,?,?)",
+ e["id"], qid, i,
+ )
+ logger.info("_seed_from_json: seeded %d exams, %d questions", len(exams), len(questions))
+ except Exception as exc:
+ logger.warning("_seed_from_json failed: %s", exc)
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+ from app.db import AsyncSQLitePool
+
+ settings = get_settings()
+ pool = AsyncSQLitePool(settings.sqlite_path)
+ await pool.initialize()
+ app.state.pool = pool
+ await _apply_schema(app.state.pool)
+ logger.info("SQLite pool ready at %s", settings.sqlite_path)
+
+ exam_count = await app.state.pool.fetchrow("SELECT COUNT(*) AS cnt FROM exams")
+ q_count = await app.state.pool.fetchrow("SELECT COUNT(*) AS cnt FROM questions")
+ if (exam_count and exam_count["cnt"] == 0) or (q_count and q_count["cnt"] == 0):
+ await _seed_from_json(app.state.pool)
+
+ yield
+
+ if app.state.pool:
+ await app.state.pool.close()
+
+
+def get_pool(request: Request):
+ return getattr(request.app.state, "pool", None)
+
+
+app = FastAPI(title="AI Agent App", lifespan=lifespan)
+
+settings = get_settings()
+app.add_middleware(
+ CORSMiddleware,
+ allow_origins=settings.allowed_origins_list,
+ allow_credentials=True,
+ allow_methods=["GET", "POST", "OPTIONS"],
+ allow_headers=["Content-Type"],
+)
+
+
+@app.get("/health")
+@app.head("/health")
+async def health():
+ return {"status": "ok"}
+
+
+@app.get("/exams")
+async def list_exams(mode: str | None = None, pool=Depends(get_pool)):
+ if mode:
+ rows = await pool.fetch(
+ "SELECT id,year,title,duration,source,category,mode,total_questions AS totalQuestions FROM exams WHERE mode=? ORDER BY year DESC",
+ mode,
+ )
+ else:
+ rows = await pool.fetch(
+ "SELECT id,year,title,duration,source,category,mode,total_questions AS totalQuestions FROM exams WHERE mode!='retired' ORDER BY year DESC"
+ )
+ return [dict(r) for r in rows]
+
+
+@app.get("/exams/{exam_id}")
+async def get_exam(exam_id: str, pool=Depends(get_pool)):
+ exam = await pool.fetchrow(
+ "SELECT id,year,title,duration,source,category,mode,total_questions AS totalQuestions FROM exams WHERE id=?",
+ exam_id,
+ )
+ if not exam:
+ raise HTTPException(status_code=404, detail="Exam not found")
+ q_ids = await pool.fetch(
+ "SELECT question_id FROM exam_questions WHERE exam_id=? ORDER BY position", exam_id
+ )
+ return {**dict(exam), "questionIds": [r["question_id"] for r in q_ids]}
+
+
+@app.post("/questions/batch")
+async def batch_questions(body: dict, pool=Depends(get_pool)):
+ ids = body.get("ids", [])[:200]
+ if not ids:
+ return []
+ placeholders = ",".join("?" * len(ids))
+ rows = await pool.fetch(f"SELECT * FROM questions WHERE id IN ({placeholders})", *ids)
+ return [{**dict(r), "choices": json.loads(r["choices"])} for r in rows]
+
+
+@app.get("/questions")
+async def all_questions(topic: str | None = None, pool=Depends(get_pool)):
+ if topic:
+ rows = await pool.fetch("SELECT * FROM questions WHERE topic=?", topic)
+ else:
+ rows = await pool.fetch("SELECT * FROM questions")
+ return [{**dict(r), "choices": json.loads(r["choices"])} for r in rows]
+
+
+@app.post("/questions/{question_id}/report")
+async def report_question(question_id: str, body: dict, pool=Depends(get_pool)):
+ """Content-issue reporting (Phase 2) — a bug report on the content, not a survey.
+
+ kind: one of render | answer_key | ambiguous | other
+ """
+ exists = await pool.fetchrow("SELECT id FROM questions WHERE id=?", question_id)
+ if not exists:
+ raise HTTPException(status_code=404, detail="Question not found")
+ kind = body.get("kind")
+ if kind not in {"render", "answer_key", "ambiguous", "other"}:
+ raise HTTPException(status_code=422, detail="kind must be one of render, answer_key, ambiguous, other")
+ report_id = f"rpt_{uuid.uuid4().hex[:12]}"
+ await pool.execute(
+ "INSERT INTO content_reports (id, question_id, kind, note) VALUES (?,?,?,?)",
+ report_id, question_id, kind, body.get("note"),
+ )
+ return {"id": report_id, "questionId": question_id, "kind": kind}
+
+
+@app.get("/content-reports")
+async def list_content_reports(kind: str | None = None, pool=Depends(get_pool)):
+ """Review queue for content_reports — student-submitted (ReportIssueButton) and
+ AI-audit-filed (note prefixed 'AI audit:') rows live in the same table/kind space.
+ """
+ query = (
+ "SELECT r.id, r.question_id AS questionId, r.kind, r.note, r.reported_at AS reportedAt, "
+ "q.question, q.choices, q.correct FROM content_reports r "
+ "JOIN questions q ON q.id = r.question_id"
+ )
+ if kind:
+ rows = await pool.fetch(query + " WHERE r.kind=? ORDER BY r.reported_at DESC", kind)
+ else:
+ rows = await pool.fetch(query + " ORDER BY r.reported_at DESC")
+ return [{**dict(r), "choices": json.loads(r["choices"])} for r in rows]
+
+
+def _get_router_client():
+ from app.agent.router_client import AiRouterClient, RouterNotConfiguredError
+
+ try:
+ return AiRouterClient(get_settings())
+ except RouterNotConfiguredError as exc:
+ raise HTTPException(status_code=503, detail=str(exc)) from exc
+
+
+@app.post("/agent/generate")
+async def agent_generate(body: dict, pool=Depends(get_pool)):
+ """Phase 3 — draft, independently verify, and auto-promote math questions.
+
+ Body: {topic, difficulty, count} — count is capped at 10 per call to keep a single
+ request bounded; batching a larger run is the caller's job, not this endpoint's.
+ """
+ from app.agent.orchestrator import generate_batch
+
+ topic = body.get("topic")
+ difficulty = body.get("difficulty")
+ count = min(int(body.get("count", 1)), 10)
+ if not topic or not difficulty:
+ raise HTTPException(status_code=422, detail="topic and difficulty are required")
+
+ client = _get_router_client()
+ results = await generate_batch(pool, client, topic, difficulty, count)
+ return {"results": results}
+
+
+@app.post("/agent/audit")
+async def agent_audit(body: dict, pool=Depends(get_pool)):
+ """Audits existing questions already in the bank (static or agent-origin) — independent
+ of /agent/generate's write-path gate. A mismatch auto-files a content_reports row
+ (kind='answer_key') for human review; it never rewrites the stored answer itself.
+
+ Body: {question_ids: [...]} — capped at 20 per call, same bounded-request rule as
+ /agent/generate.
+ """
+ from app.agent.auditor import audit_question
+
+ question_ids = body.get("question_ids", [])[:20]
+ if not question_ids:
+ raise HTTPException(status_code=422, detail="question_ids is required")
+
+ client = _get_router_client()
+ results = []
+ for qid in question_ids:
+ row = await pool.fetchrow("SELECT id, question, choices, correct FROM questions WHERE id=?", qid)
+ if not row:
+ results.append({"questionId": qid, "status": "not_found"})
+ continue
+
+ question_row = {**dict(row), "choices": json.loads(row["choices"])}
+ result = await audit_question(client, question_row)
+
+ if result.status == "mismatch":
+ report_id = f"rpt_{uuid.uuid4().hex[:12]}"
+ await pool.execute(
+ "INSERT INTO content_reports (id, question_id, kind, note) VALUES (?,?,?,?)",
+ report_id, qid, "answer_key", f"AI audit: {result.reason}",
+ )
+
+ results.append({
+ "questionId": qid,
+ "status": result.status,
+ "storedIndex": result.stored_index,
+ "verifiedIndex": result.verified_index,
+ "reason": result.reason,
+ })
+ return {"results": results}
+
+
+@app.get("/agent/pending")
+async def agent_pending(status: str | None = None, pool=Depends(get_pool)):
+ if status:
+ rows = await pool.fetch("SELECT * FROM pending_questions WHERE status=? ORDER BY created_at DESC", status)
+ else:
+ rows = await pool.fetch("SELECT * FROM pending_questions ORDER BY created_at DESC")
+ return [dict(r) for r in rows]
+
+
+@app.post("/agent/pending/{pending_id}/reject")
+async def agent_reject_pending(pending_id: str, pool=Depends(get_pool)):
+ """Manual override for a verified-but-suspect item — the safety valve, not the default path."""
+ row = await pool.fetchrow("SELECT * FROM pending_questions WHERE id=?", pending_id)
+ if not row:
+ raise HTTPException(status_code=404, detail="Pending item not found")
+ await pool.execute("UPDATE pending_questions SET status='rejected' WHERE id=?", pending_id)
+ return {"id": pending_id, "status": "rejected"}
diff --git a/backend/pyproject.toml b/backend/pyproject.toml
new file mode 100644
index 0000000000000000000000000000000000000000..6eb3df598335b5bf0d948accf0753c2f89876efa
--- /dev/null
+++ b/backend/pyproject.toml
@@ -0,0 +1,2 @@
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
diff --git a/backend/tests/__init__.py b/backend/tests/__init__.py
new file mode 100644
index 0000000000000000000000000000000000000000..e69de29bb2d1d6434b8b29ae775ad8c2e48c5391
diff --git a/backend/tests/test_agent.py b/backend/tests/test_agent.py
new file mode 100644
index 0000000000000000000000000000000000000000..060b1593dd3ed2c235863d0354c230fd30ce2222
--- /dev/null
+++ b/backend/tests/test_agent.py
@@ -0,0 +1,193 @@
+import os
+
+import pytest
+from httpx import AsyncClient, ASGITransport
+
+from app.agent import generator, orchestrator, verifier
+from app.main import app
+
+
+@pytest.fixture(scope="module")
+async def client(tmp_path_factory):
+ db_path = str(tmp_path_factory.mktemp("db") / "test.db")
+ os.environ["SQLITE_PATH"] = db_path
+ # Force the router "unconfigured" regardless of a developer's local backend/.env,
+ # so this suite never makes a live network call against the real AI router.
+ os.environ["AI_ROUTER_BASE_URL"] = ""
+ from app.config import get_settings
+ get_settings.cache_clear()
+
+ async with app.router.lifespan_context(app):
+ async with AsyncClient(transport=ASGITransport(app=app), base_url="http://test") as ac:
+ yield ac
+ del os.environ["SQLITE_PATH"]
+ del os.environ["AI_ROUTER_BASE_URL"]
+ get_settings.cache_clear()
+
+
+# --- verifier.py: the actual correctness gate, no network involved ---------------------
+
+def _good_draft(claimed_index=0):
+ return {
+ "topic": "algebra",
+ "difficulty": "easy",
+ "question_tex": "If $2x + 3 = 11$, what is $4x + 6$?",
+ "variables": ["x"],
+ "given_equations": ["2*x + 3 - 11"],
+ "target_expression": "4*x + 6",
+ "choice_expressions": ["22", "8", "14", "16"],
+ "claimed_correct_index": claimed_index,
+ "explanation_tex": "4x + 6 = 2(2x+3) = 2*11 = 22",
+ }
+
+
+def test_verifier_confirms_correct_claim():
+ result = verifier.verify(_good_draft(claimed_index=0))
+ assert result.ok is True
+ assert result.verified_index == 0
+
+
+def test_verifier_rejects_wrong_claim():
+ result = verifier.verify(_good_draft(claimed_index=1))
+ assert result.ok is False
+ assert result.verified_index == 0
+ assert "claimed index 1" in result.reason
+
+
+def test_verifier_rejects_unsolvable_system():
+ draft = _good_draft()
+ draft["given_equations"] = ["x - x + 1"] # 1 = 0, never true
+ result = verifier.verify(draft)
+ assert result.ok is False
+ assert "no solution" in result.reason
+
+
+def test_verifier_rejects_ambiguous_choices():
+ draft = _good_draft()
+ draft["choice_expressions"] = ["22", "22", "14", "16"]
+ result = verifier.verify(draft)
+ assert result.ok is False
+ assert "ambiguous" in result.reason
+
+
+def test_verifier_rejects_no_matching_choice():
+ draft = _good_draft()
+ draft["choice_expressions"] = ["1", "2", "3", "4"]
+ result = verifier.verify(draft)
+ assert result.ok is False
+ assert "no choice matches" in result.reason
+
+
+# --- generator.py: shape validation on whatever the router hands back ------------------
+
+def test_generator_rejects_missing_field():
+ with pytest.raises(generator.DraftShapeError):
+ generator._validate_shape({"question_tex": "x"})
+
+
+def test_generator_rejects_wrong_choice_count():
+ draft = _good_draft()
+ draft["choice_expressions"] = ["1", "2"]
+ with pytest.raises(generator.DraftShapeError):
+ generator._validate_shape(draft)
+
+
+def test_generator_accepts_well_shaped_draft():
+ generator._validate_shape(_good_draft()) # should not raise
+
+
+# --- orchestrator.py: the full loop against a fake router client -----------------------
+
+class _FakeRouterClient:
+ """Duck-types AiRouterClient without any network call — returns a fixed queue of drafts."""
+
+ def __init__(self, drafts):
+ self._drafts = list(drafts)
+
+ async def complete_json(self, system_prompt, user_prompt):
+ return self._drafts.pop(0)
+
+
+@pytest.mark.asyncio
+async def test_orchestrator_promotes_verified_draft(client):
+ from app.main import get_pool
+
+ pool = app.state.pool
+ fake_client = _FakeRouterClient([_good_draft(claimed_index=0)])
+ result = await orchestrator.generate_one(pool, fake_client, "algebra", "easy")
+
+ assert result["status"] == "verified"
+ row = await pool.fetchrow("SELECT * FROM questions WHERE id=?", result["question_id"])
+ assert row is not None
+ assert row["origin"] == "agent"
+ assert row["correct"] == 0
+
+
+@pytest.mark.asyncio
+async def test_orchestrator_rejects_after_max_attempts(client):
+ pool = app.state.pool
+ bad_draft = _good_draft(claimed_index=1) # wrong on every attempt
+ fake_client = _FakeRouterClient([bad_draft, bad_draft, bad_draft])
+ result = await orchestrator.generate_one(pool, fake_client, "algebra", "easy")
+
+ assert result["status"] == "rejected"
+ pending = await pool.fetchrow("SELECT * FROM pending_questions WHERE id=?", result["id"])
+ assert pending["status"] == "rejected"
+
+
+@pytest.mark.asyncio
+async def test_agent_generate_returns_503_when_router_unconfigured(client):
+ resp = await client.post("/agent/generate", json={"topic": "algebra", "difficulty": "easy"})
+ assert resp.status_code == 503
+
+
+@pytest.mark.asyncio
+async def test_agent_generate_requires_topic_and_difficulty(client):
+ resp = await client.post("/agent/generate", json={})
+ assert resp.status_code in (422, 503) # 422 for the missing-field check firing first
+
+
+# --- content reports (Phase 2) ----------------------------------------------------------
+
+@pytest.mark.asyncio
+async def test_report_question_success(client):
+ questions = (await client.get("/questions")).json()
+ qid = questions[0]["id"]
+ resp = await client.post(f"/questions/{qid}/report", json={"kind": "render", "note": "KaTeX broken"})
+ assert resp.status_code == 200
+ body = resp.json()
+ assert body["questionId"] == qid
+ assert body["kind"] == "render"
+
+
+@pytest.mark.asyncio
+async def test_report_question_not_found(client):
+ resp = await client.post("/questions/does-not-exist/report", json={"kind": "render"})
+ assert resp.status_code == 404
+
+
+@pytest.mark.asyncio
+async def test_report_question_invalid_kind(client):
+ questions = (await client.get("/questions")).json()
+ qid = questions[0]["id"]
+ resp = await client.post(f"/questions/{qid}/report", json={"kind": "not_a_real_kind"})
+ assert resp.status_code == 422
+
+
+@pytest.mark.asyncio
+async def test_list_content_reports_includes_question_content(client):
+ questions = (await client.get("/questions")).json()
+ qid = questions[0]["id"]
+ await client.post(f"/questions/{qid}/report", json={"kind": "answer_key", "note": "AI audit: mismatch"})
+
+ resp = await client.get("/content-reports", params={"kind": "answer_key"})
+ assert resp.status_code == 200
+ body = resp.json()
+ assert any(r["questionId"] == qid and r["question"] == questions[0]["question"] for r in body)
+
+
+@pytest.mark.asyncio
+async def test_agent_pending_lists_rejected_items(client):
+ resp = await client.get("/agent/pending", params={"status": "rejected"})
+ assert resp.status_code == 200
+ assert isinstance(resp.json(), list)
diff --git a/backend/tests/test_auditor.py b/backend/tests/test_auditor.py
new file mode 100644
index 0000000000000000000000000000000000000000..75c3334372bb46e90fd43e3d96e75da8df931b8c
--- /dev/null
+++ b/backend/tests/test_auditor.py
@@ -0,0 +1,119 @@
+import os
+
+import pytest
+from httpx import AsyncClient, ASGITransport
+
+from app.agent import auditor
+from app.main import app
+
+
+@pytest.fixture(scope="module")
+async def client(tmp_path_factory):
+ db_path = str(tmp_path_factory.mktemp("db") / "test.db")
+ os.environ["SQLITE_PATH"] = db_path
+ # Force the router "unconfigured" regardless of a developer's local backend/.env,
+ # so this suite never makes a live network call against the real AI router.
+ os.environ["AI_ROUTER_BASE_URL"] = ""
+ from app.config import get_settings
+ get_settings.cache_clear()
+
+ async with app.router.lifespan_context(app):
+ async with AsyncClient(transport=ASGITransport(app=app), base_url="http://test") as ac:
+ yield ac
+ del os.environ["SQLITE_PATH"]
+ del os.environ["AI_ROUTER_BASE_URL"]
+ get_settings.cache_clear()
+
+
+class _FakeRouterClient:
+ """Duck-types AiRouterClient — returns a fixed transcript, no network call."""
+
+ def __init__(self, transcript):
+ self._transcript = transcript
+
+ async def complete_json(self, system_prompt, user_prompt):
+ return self._transcript
+
+
+def _question_row(correct=0):
+ return {
+ "id": "q_test_001",
+ "question": "If $2x + 3 = 11$, what is $4x + 6$?",
+ "choices": ["$22$", "$8$", "$14$", "$16$"],
+ "correct": correct,
+ }
+
+
+def _good_transcript(claimed_index=0):
+ return {
+ "transcribable": True,
+ "variables": ["x"],
+ "given_equations": ["2*x + 3 - 11"],
+ "target_expression": "4*x + 6",
+ "choice_expressions": ["22", "8", "14", "16"],
+ "claimed_correct_index": claimed_index,
+ }
+
+
+@pytest.mark.asyncio
+async def test_audit_confirms_correct_stored_answer():
+ client = _FakeRouterClient(_good_transcript())
+ result = await auditor.audit_question(client, _question_row(correct=0))
+ assert result.status == "verified"
+ assert result.verified_index == 0
+
+
+@pytest.mark.asyncio
+async def test_audit_flags_mismatch_regardless_of_models_own_claim():
+ # Model's own claimed_correct_index is wrong too (claims 1) — audit must still report
+ # sympy's independently computed index (0), not the model's claim, and still catch
+ # that it disagrees with the stored answer (which is 2 here).
+ client = _FakeRouterClient(_good_transcript(claimed_index=1))
+ result = await auditor.audit_question(client, _question_row(correct=2))
+ assert result.status == "mismatch"
+ assert result.verified_index == 0
+ assert result.stored_index == 2
+
+
+@pytest.mark.asyncio
+async def test_audit_marks_unauditable_when_model_declines():
+ client = _FakeRouterClient({"transcribable": False, "reason": "geometry proof, not numeric"})
+ result = await auditor.audit_question(client, _question_row())
+ assert result.status == "unauditable"
+
+
+@pytest.mark.asyncio
+async def test_audit_errors_on_unsolvable_transcript():
+ transcript = _good_transcript()
+ transcript["given_equations"] = ["x - x + 1"] # 1 = 0, never true
+ client = _FakeRouterClient(transcript)
+ result = await auditor.audit_question(client, _question_row())
+ assert result.status == "error"
+
+
+@pytest.mark.asyncio
+async def test_audit_errors_on_malformed_transcript():
+ client = _FakeRouterClient({"transcribable": True}) # missing required fields
+ result = await auditor.audit_question(client, _question_row())
+ assert result.status == "error"
+
+
+@pytest.mark.asyncio
+async def test_audit_errors_on_choice_count_mismatch():
+ transcript = _good_transcript()
+ transcript["choice_expressions"] = ["22", "8"] # question has 4 choices
+ client = _FakeRouterClient(transcript)
+ result = await auditor.audit_question(client, _question_row())
+ assert result.status == "error"
+
+
+@pytest.mark.asyncio
+async def test_agent_audit_endpoint_returns_503_when_router_unconfigured(client):
+ resp = await client.post("/agent/audit", json={"question_ids": ["q_amc8_001"]})
+ assert resp.status_code == 503
+
+
+@pytest.mark.asyncio
+async def test_agent_audit_endpoint_requires_question_ids(client):
+ resp = await client.post("/agent/audit", json={})
+ assert resp.status_code == 422
diff --git a/backend/tests/test_exams.py b/backend/tests/test_exams.py
new file mode 100644
index 0000000000000000000000000000000000000000..9592309edbd0761c4661b7ac7ae625d2a72dd2b9
--- /dev/null
+++ b/backend/tests/test_exams.py
@@ -0,0 +1,81 @@
+import os
+
+import pytest
+from httpx import AsyncClient, ASGITransport
+
+from app.main import app
+
+
+@pytest.fixture(scope="module")
+async def client(tmp_path_factory):
+ db_path = str(tmp_path_factory.mktemp("db") / "test.db")
+ os.environ["SQLITE_PATH"] = db_path
+ from app.config import get_settings
+ get_settings.cache_clear()
+
+ async with app.router.lifespan_context(app):
+ async with AsyncClient(transport=ASGITransport(app=app), base_url="http://test") as ac:
+ yield ac
+ del os.environ["SQLITE_PATH"]
+ get_settings.cache_clear()
+
+
+@pytest.mark.asyncio
+async def test_health(client):
+ resp = await client.get("/health")
+ assert resp.status_code == 200
+ assert resp.json() == {"status": "ok"}
+
+
+@pytest.mark.asyncio
+async def test_list_exams(client):
+ resp = await client.get("/exams")
+ assert resp.status_code == 200
+ exams = resp.json()
+ assert isinstance(exams, list)
+ assert len(exams) > 0
+ assert "id" in exams[0] and "title" in exams[0]
+
+
+@pytest.mark.asyncio
+async def test_get_exam_by_id(client):
+ exams = (await client.get("/exams")).json()
+ exam_id = exams[0]["id"]
+ resp = await client.get(f"/exams/{exam_id}")
+ assert resp.status_code == 200
+ body = resp.json()
+ assert body["id"] == exam_id
+ assert isinstance(body["questionIds"], list)
+
+
+@pytest.mark.asyncio
+async def test_get_exam_not_found(client):
+ resp = await client.get("/exams/does-not-exist")
+ assert resp.status_code == 404
+
+
+@pytest.mark.asyncio
+async def test_list_questions(client):
+ resp = await client.get("/questions")
+ assert resp.status_code == 200
+ questions = resp.json()
+ assert isinstance(questions, list)
+ assert len(questions) > 0
+ assert isinstance(questions[0]["choices"], list)
+
+
+@pytest.mark.asyncio
+async def test_batch_questions(client):
+ questions = (await client.get("/questions")).json()
+ ids = [q["id"] for q in questions[:3]]
+ resp = await client.post("/questions/batch", json={"ids": ids})
+ assert resp.status_code == 200
+ body = resp.json()
+ assert len(body) == len(ids)
+
+
+@pytest.mark.asyncio
+async def test_batch_questions_empty(client):
+ resp = await client.post("/questions/batch", json={"ids": []})
+ assert resp.status_code == 200
+ assert resp.json() == []
diff --git a/backend/tests/test_router_client.py b/backend/tests/test_router_client.py
new file mode 100644
index 0000000000000000000000000000000000000000..0d45916ed6632dd47d135385467dd04d24af10a8
--- /dev/null
+++ b/backend/tests/test_router_client.py
@@ -0,0 +1,76 @@
+from unittest.mock import AsyncMock, patch
+
+import httpx
+import pytest
+
+from app.agent.router_client import AiRouterClient, RouterRequestError
+from app.config import Settings
+
+
+def _settings(**overrides):
+ defaults = dict(
+ ai_router_base_url="https://ai-router.example",
+ ai_router_api_key="sk-test",
+ ai_router_model="primary-model",
+ ai_router_fallback_models="fallback-a,fallback-b",
+ )
+ return Settings(**{**defaults, **overrides})
+
+
+def _resp(status_code, body=None, text=""):
+ r = httpx.Response(status_code, json=body, text=text if body is None else None)
+ return r
+
+
+@pytest.mark.asyncio
+async def test_uses_primary_model_when_it_succeeds():
+ ok = _resp(200, {"choices": [{"message": {"content": '{"ok": true}'}}]})
+ with patch("httpx.AsyncClient.post", new=AsyncMock(return_value=ok)) as mock_post:
+ client = AiRouterClient(_settings())
+ result = await client.complete_json("sys", "user")
+ assert result == {"ok": True}
+ assert mock_post.call_count == 1
+ assert mock_post.call_args.kwargs["json"]["model"] == "primary-model"
+
+
+@pytest.mark.asyncio
+async def test_falls_back_when_primary_provider_is_down():
+ down = _resp(401, text="OAuth expired")
+ ok = _resp(200, {"choices": [{"message": {"content": '{"ok": true}'}}]})
+ with patch("httpx.AsyncClient.post", new=AsyncMock(side_effect=[down, ok])) as mock_post:
+ client = AiRouterClient(_settings())
+ result = await client.complete_json("sys", "user")
+ assert result == {"ok": True}
+ assert mock_post.call_count == 2
+ assert mock_post.call_args_list[0].kwargs["json"]["model"] == "primary-model"
+ assert mock_post.call_args_list[1].kwargs["json"]["model"] == "fallback-a"
+
+
+@pytest.mark.asyncio
+async def test_tries_every_fallback_before_giving_up():
+ down = _resp(503, text="auth_unavailable")
+ with patch("httpx.AsyncClient.post", new=AsyncMock(return_value=down)) as mock_post:
+ client = AiRouterClient(_settings())
+ with pytest.raises(RouterRequestError):
+ await client.complete_json("sys", "user")
+ assert mock_post.call_count == 3 # primary + fallback-a + fallback-b
+
+
+@pytest.mark.asyncio
+async def test_does_not_fall_back_on_a_bad_request():
+ bad = _resp(422, text="invalid request")
+ with patch("httpx.AsyncClient.post", new=AsyncMock(return_value=bad)) as mock_post:
+ client = AiRouterClient(_settings())
+ with pytest.raises(RouterRequestError):
+ await client.complete_json("sys", "user")
+ assert mock_post.call_count == 1 # no point retrying other models on a bad request
+
+
+@pytest.mark.asyncio
+async def test_does_not_fall_back_on_unparseable_json():
+ malformed = _resp(200, {"choices": [{"message": {"content": "not json"}}]})
+ with patch("httpx.AsyncClient.post", new=AsyncMock(return_value=malformed)) as mock_post:
+ client = AiRouterClient(_settings())
+ with pytest.raises(RouterRequestError):
+ await client.complete_json("sys", "user")
+ assert mock_post.call_count == 1 # a model-quality issue, not a provider outage
diff --git a/demo-video/ai-enhancement.md b/demo-video/ai-enhancement.md
new file mode 100644
index 0000000000000000000000000000000000000000..8ecc4776b811930f147308ec74030e672789c5d7
--- /dev/null
+++ b/demo-video/ai-enhancement.md
@@ -0,0 +1,180 @@
+# Zenith — AI Video Enhancement Plan
+
+## Scene-by-Scene Enhancements
+
+---
+
+### Scene 1: Hero Arrival (0:00–0:08)
+
+**Enhancement type:** Atmospheric ambient motion + color grade
+**Tool:** Kling AI (image-to-video ambient loop) or Runway Gen-3 (video-to-video texture pass)
+
+**Kling AI prompt (background layer):**
+> "Dark indigo space background, slow drift of tiny amber and violet light particles, no hard edges, dreamlike depth of field, cinematic, 8-second seamless loop, no text, no UI, macro lens feel"
+
+**Camera movement:** None on the app itself. Apply a very slow (8s) parallax drift of ~4px on a separate background layer behind the screen recording, using CapCut keyframe position tool. This creates subtle depth without disrupting the UI.
+
+**Color grade note:** Pull down highlights to near #0A0E1A equivalent, boost amber channel (+15 hue rotation toward gold). Add a very subtle vignette (15% edge darkening) to focus attention on the hero headline.
+
+---
+
+### Scene 2: Exam Select Catalog (0:08–0:17)
+
+**Enhancement type:** Text overlay + subtle Ken Burns on card grid
+**Tool:** CapCut (keyframe opacity + position on text layer)
+
+**Overlay text to animate in:**
+> "40+ đề thi thật · 63 tỉnh thành"
+> White text · Plus Jakarta Sans Bold · fade in at 0:10 · hold 2s · fade out at 0:15
+
+**Camera movement:** Subtle Ken Burns on the exam card grid: 1.0x → 1.02x scale over 9s, panning very slightly upward. Implies depth without distraction.
+
+**Color grade note:** Slightly cool tint (−5 temperature) to contrast with the warm amber score badges on each card row.
+
+---
+
+### Scene 3: TestInterface — Exam + Hint (0:17–0:29)
+
+**Enhancement type:** Timer pulse composite + hint popover highlight
+**Tool:** CapCut (mask + opacity keyframe on a circular glow over the timer element)
+
+**Timer glow asset prompt (for static generation in Midjourney or DALLE):**
+> "Soft red-orange circular glow, no hard edges, radius 60px, transparent PNG, ambient light only"
+
+Composite the glow asset over the timer region with a 1-second heartbeat pulse: opacity 0 → 0.6 → 0 keyed at 60fps.
+
+**Hint reveal enhancement:** As the hint text streams in word-by-word, add a thin amber underline (2px, 80% opacity) that sweeps left-to-right beneath each new line in CapCut. Synchronized to the streaming text timing.
+
+**Camera movement:** None — stability signals seriousness.
+
+**Color grade note:** Reduce saturation by 10% on this scene only to make the amber timer pop relative to the UI. Add +5% contrast.
+
+---
+
+### Scene 4: Score + Confetti + AI Analysis + School Cards (0:29–0:47)
+
+**Enhancement type:** Celebration — zoom punch + warm color grade + underline sweep on AI text
+**Tool:** CapCut (zoom punch keyframe at CountUp completion) + Runway Gen-3 (color grade preset: "Golden Hour")
+
+**Runway color grade prompt:**
+> "Warm golden grade, boost yellows and greens, slight lens flare at frame center, cinematic exposure lift, celebratory, joyful, no desaturation"
+
+**Zoom punch (MOST IMPORTANT enhancement in the entire video):**
+At the exact frame where CountUp reaches 7.6 (approximately 1.8s into Scene 4):
+- Apply a single 0.12s zoom punch: 1.0x → 1.06x → 1.0x using CapCut elastic ease
+- Center point: the score digit itself
+- This punch is the cinematic equivalent of a "sting" in music — it locks the number in the viewer's mind
+
+**School cards enhancement:** Add a soft indigo-to-teal glow composite behind each school card as they fade in. Use Runway prompt:
+> "Soft indigo-to-teal gradient glow behind a dark card, depth of field bokeh in background, no text, subtle, editorial, 1920x1080"
+
+**Camera movement:** None (content is moving enough with confetti + scroll).
+
+**Color grade note:** This is the warmest scene. Lift blacks slightly (+5 pedestal), push saturation +15 on yellows and greens to make the confetti more vivid. The score digit #F2A20C should feel like sunlight.
+
+---
+
+### Scene 5: Oracle AI — Streaming Solution (0:47–0:59)
+
+**Enhancement type:** Step reveal highlight beam + scholarly background texture
+**Tool:** Kling AI (background texture loop) + CapCut (step highlight overlay)
+
+**Kling AI background texture prompt:**
+> "Abstract dark slate surface, faint chalk dust particles drifting slowly, soft ambient light from upper left, no text, no math symbols visible, 8-second seamless loop, cinematic, scholarly, quiet"
+
+**Step highlight overlay:** As each solution step appears, flash a 0.3s horizontal amber bar (2px height, full-width, 30% opacity) behind that step's text row. This draws the eye to new content and reinforces the "streaming" mental model. Keyframe in CapCut.
+
+**Camera movement:** Very slight rightward pan (~12px over 12s) on the Oracle panel — implies "zooming in" to the detail without actually zooming.
+
+**Color grade note:** Deep, scholarly. Reduce brightness by 5%, add +8 contrast. The KaTeX-rendered boxed answer (white on dark) should be the brightest element in the frame. Add soft vertical vignettes on left and right edges.
+
+---
+
+### Scene 6: Study Plan — Checkpoint (0:59–1:09)
+
+**Enhancement type:** Checkpoint bar glow composite
+**Tool:** Runway Gen-3 (video-to-video: add soft bar glow) + CapCut (animated progress fill accent)
+
+**Runway prompt for checkpoint bar enhancement:**
+> "Dark UI card, a horizontal progress bar filling from left to right in gold-to-green gradient, soft ambient glow behind the bar, 3-second duration, loop-ready, no text, cinematic, clean"
+
+**Camera movement:** Very slow downward drift (mirroring the scroll): CapCut position keyframes pan the layer ~60px downward over 10s.
+
+**Color grade note:** Keep grade neutral. The gold (checkpoint not yet cleared) and emerald (cleared) colors on the bar are already correct — do not over-grade and lose the saturation difference.
+
+---
+
+### Scene 7: Account — Mastery Rank + Pricing (1:09–1:20)
+
+**Enhancement type:** Mastery rank badge spring pop + pricing table glow
+**Tool:** CapCut (scale keyframe on badge layer) + Veo 2 (end card background generation)
+
+**Badge pop composite:** At the moment the "Học sinh Tiến bộ" badge animates in (spring stiffness 320 — ~0.7s), add a brief radial glow pulse (indigo #818CF8, 0.4s, opacity 0 → 0.5 → 0) behind the badge in CapCut.
+
+**Camera movement:** Very slow upward tilt (15px over 11s) — creates a sense of "rising."
+
+**Color grade note:** Warmest point of the video. Lift exposure by 8%, push amber saturation to near maximum. Should feel like dawn after a long study session.
+
+---
+
+## End Card (1:20–1:24)
+
+**Tool:** Veo 2 (generative background loop)
+
+**Veo 2 prompt:**
+> "Abstract dark space with slowly moving golden light streaks, indigo nebula wisps, calm and aspirational, 5-second looping sequence, no text, no people, cinematic, 1920x1080"
+
+**End card layout:**
+```
+[Veo 2 loop at 40% opacity over #0A0E1A solid]
+
+ ✦
+ Luyện thi thông minh hơn.
+ AI phân tích · 63 tỉnh thành
+ Từ 29,000đ / tháng
+
+ [ Bắt đầu miễn phí → ] ← gold button with breathing pulse
+
+ zenith.vn
+```
+
+**CTA button animation:** 1.0x → 1.03x → 1.0x scale loop, 2s period, sinusoidal ease — subtle breathing effect that draws the eye without being distracting.
+
+---
+
+## Overall Color Grade Recommendation
+
+Apply a base LUT to all scenes for consistency before scene-specific grades:
+
+| Parameter | Value |
+|---|---|
+| Shadows | Pulled to near #0A0E1A |
+| Highlights | Warm amber shift (+10 toward #F2A20C) |
+| Contrast | +12 (punchy, not harsh) |
+| Saturation | −8 globally (prevents rich UI colors from clipping; individual scenes restore selectively) |
+| Vignette | 12% global edge darkening throughout |
+
+**Grade arc across the video:**
+
+| Scenes | Grade Mood | Feel |
+|---|---|---|
+| 1–3 | Cool / neutral | Focused, serious, credible |
+| 4 | Warm / golden | Celebratory, emotional peak |
+| 5–6 | Cool / analytical | Intelligent, precise |
+| 7 + End | Warm / aspirational | Hopeful, motivating |
+
+---
+
+## Music Vibe
+
+Three movements that mirror the emotional arc:
+
+**Movement 1 (Scenes 1–3, 0:00–0:29):** Minimal, slightly tense. Sparse piano notes over a soft sub-bass drone, ~80 BPM. Implies focus and serious preparation without being oppressive.
+
+**Movement 2 (Scenes 4–5, 0:29–0:59):** A single percussion hit on the confetti burst, then the melody opens up. A subtle melodic motif (synth or acoustic guitar) feels like a door opening. Still restrained but warmer. Tempo rises to ~95 BPM.
+
+**Movement 3 (Scenes 6–7 + End, 0:59–1:24):** Hopeful, quietly confident resolution. Not triumphant pop — the feeling of finishing a difficult proof correctly. Tempo holds at ~100 BPM, then decelerates to hold on the end card.
+
+**Overall palette:** Lo-fi acoustic meets ambient electronic. Think Nils Frahm at lower energy, or a Vietnamese indie lo-fi artist. Avoid anything with lyrics, vocal chops, or EDM builds — they fight with the Vietnamese text on screen.
+
+**Key cue:** The single percussion hit must land exactly on the CountUp completion / confetti burst (Scene 4, ~1.8s in). This is the most important audio sync point in the entire video.
diff --git a/demo-video/debug-demo.spec.ts b/demo-video/debug-demo.spec.ts
new file mode 100644
index 0000000000000000000000000000000000000000..a026dd31c4521f6ac7e08309ff83bcf2aea8c44d
--- /dev/null
+++ b/demo-video/debug-demo.spec.ts
@@ -0,0 +1,58 @@
+import { test } from '@playwright/test'
+
+const DEMO_JWT =
+ 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9' +
+ '.eyJzdWIiOiIxIiwiZW1haWwiOiJkZW1vQHplbml0aC52biIsImV4cCI6MjA4MjcxNTIwMH0' +
+ '.DEMO_SIG_PLACEHOLDER'
+
+test('debug: check localStorage + network', async ({ page }) => {
+ // Capture all console messages
+ const logs: string[] = []
+ page.on('console', msg => logs.push(`[console][${msg.type()}] ${msg.text()}`))
+ page.on('pageerror', err => logs.push(`[pageerror] ${err.message}`))
+
+ // Track network requests
+ const requests: string[] = []
+ page.on('request', req => requests.push(`REQ: ${req.method()} ${req.url()}`))
+ page.on('response', res => requests.push(`RES: ${res.status()} ${res.url()}`))
+ page.on('requestfailed', req => requests.push(`FAIL: ${req.method()} ${req.url()} — ${req.failure()?.errorText}`))
+
+ // Seed localStorage before page scripts
+ await page.addInitScript(`(function() {
+ localStorage.setItem('auth_token', '${DEMO_JWT}');
+ console.log('[init] auth_token set');
+ })()`)
+
+ // Mock /users/me
+ await page.route('**/users/me', async (route) => {
+ console.log('ROUTE MOCK HIT: ' + route.request().url())
+ await route.fulfill({
+ status: 200,
+ contentType: 'application/json',
+ body: JSON.stringify({ id: 1, email: 'demo@zenith.vn', display_name: 'Test User', grade: '12', subscription_tier: 'student', credits_balance: 50, tos_accepted_at: '2025-01-01', extended_onboarding_done: true })
+ })
+ })
+
+ await page.goto('http://localhost:5173', { waitUntil: 'domcontentloaded' })
+
+ // Wait a bit then check state
+ await page.waitForTimeout(5000)
+
+ // Check localStorage
+ const authToken = await page.evaluate(() => localStorage.getItem('auth_token'))
+ console.log('auth_token in browser:', authToken ? authToken.slice(0, 30) + '...' : 'NULL')
+
+ // Check page content
+ const bodyText = await page.evaluate(() => document.body.innerText.slice(0, 200))
+ console.log('body text:', bodyText)
+
+ // Check what's rendered in DOM
+ const h1Count = await page.evaluate(() => document.querySelectorAll('h1').length)
+ console.log('h1 count:', h1Count)
+
+ console.log('--- NETWORK REQUESTS ---')
+ requests.forEach(r => console.log(r))
+
+ console.log('--- CONSOLE LOGS ---')
+ logs.forEach(l => console.log(l))
+})
diff --git a/demo-video/demo-data-plan.md b/demo-video/demo-data-plan.md
new file mode 100644
index 0000000000000000000000000000000000000000..c098cfbaabae78f3ad5cd4391346e7c99cdce566
--- /dev/null
+++ b/demo-video/demo-data-plan.md
@@ -0,0 +1,286 @@
+# Zenith Demo Video — Data & Seed Plan
+
+## 1. Demo User Profile
+
+```json
+{
+ "id": 1,
+ "email": "demo@zenith.vn",
+ "display_name": "Nguyễn Minh Tuấn",
+ "avatar_url": "https://ui-avatars.com/api/?name=Nguyen+Minh+Tuan&background=F2A20C&color=000",
+ "grade": "12",
+ "province": "Hà Nội",
+ "school_type": "chuyên",
+ "subscription_tier": "student",
+ "subscription_period": "monthly",
+ "credits_balance": 50,
+ "mastery_rank": "Học sinh",
+ "solid_concept_count": 18,
+ "tos_accepted_at": "2025-06-01T00:00:00Z",
+ "extended_onboarding_done": true
+}
+```
+
+**Critical field notes:**
+- `grade: "12"` — triggers university school suggestions in Results (`isCollegeUser = true`)
+- `extended_onboarding_done: true` — suppresses ExtendedOnboarding modal on mount
+- `subscription_tier: "student"` — enables AI analysis as free, unlocks study plan
+- `credits_balance: 50` — passes ≥3 Tia check for analysis and ≥5 for study plan
+- `province: "Hà Nội"` — activates province moat sorting in ExamSelect; Hà Nội exams float to top
+
+---
+
+## 2. Demo JWT Token
+
+The frontend AuthContext validates only:
+1. `token.split('.')[1]` is valid base64-decodable JSON
+2. `payload.exp * 1000 > Date.now()`
+
+The signature is never verified client-side. Use this pre-built token valid until 2036-01-01:
+
+```
+eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxIiwiZW1haWwiOiJkZW1vQHplbml0aC52biIsImV4cCI6MjA4MjcxNTIwMH0.DEMO_SIG_PLACEHOLDER
+```
+
+**The `GET /users/me` route MUST be mocked** to return the demo user object, because the signature is not real. The `page.route('**/users/me')` mock in the Playwright spec handles this.
+
+---
+
+## 3. Demo Exam
+
+**Exam ID:** `thpt_2024`
+**Title:** Đề thi THPT Quốc gia 2024 — Môn Toán
+**Duration:** 90 minutes
+**Questions:** 50
+**Source:** Bộ GD&ĐT — Kỳ thi THPT Quốc gia 2024
+**Category:** thpt
+**Mode:** thithu
+
+**Why this exam:**
+- Official national exam — maximum credibility for a Vietnamese audience
+- Canonical 50-question, 90-minute format
+- Appears first in ExamSelect when sorted by year descending with `mode=thithu`
+- All 50 question IDs (`q_thpt24_001` through `q_thpt24_050`) confirmed present in `questions.json`
+
+### Question ID Validation Table
+
+These IDs must exist in `exam-app/src/data/questions.json` before recording:
+
+| ID | Topic | Expected |
+|----|-------|---------|
+| q_thpt24_001 | geometry | present |
+| q_thpt24_010 | algebra | present |
+| q_thpt24_020 | calculus | present |
+| q_thpt24_030 | functions | present |
+| q_thpt24_050 | trigonometry | present |
+
+The Playwright spec's `beforeAll` block validates these at runtime.
+
+---
+
+## 4. Pre-Fabricated Exam Result
+
+**Result ID:** `result_demo_2024_001`
+**Score:** 7.6 / 10 (38/50 correct)
+**Score label:** "Khá giỏi" (≥ 6.5 threshold in Results.jsx)
+**Confetti:** fires (score ≥ 7.0 threshold)
+
+### Topic Breakdown
+
+| Topic | Correct | Total | Accuracy | Verdict |
+|-------|---------|-------|----------|---------|
+| functions | 7 | 8 | 87.5% | ✓ Tốt |
+| algebra | 16 | 18 | 88.9% | ✓ Tốt |
+| calculus | 4 | 7 | 57.1% | ⚠ Cần ôn |
+| statistics | 2 | 3 | 66.7% | ⚠ Cần ôn |
+| trigonometry | 2 | 2 | 100.0% | ✓ Tốt |
+| geometry | 6 | 10 | 60.0% | ⚠ Cần ôn |
+| combinatorics | 1 | 2 | 50.0% | ✗ Yếu |
+
+### Full Result Object (inject into localStorage)
+
+```json
+{
+ "id": "result_demo_2024_001",
+ "examId": "thpt_2024",
+ "startedAt": "2026-06-05T08:00:00.000Z",
+ "finishedAt": "2026-06-05T09:15:00.000Z",
+ "score": 7.6,
+ "maxScore": 10,
+ "accuracy": 0.76,
+ "timeSpent": 4500,
+ "answeredCount": 50,
+ "topicBreakdown": {
+ "functions": { "correct": 7, "total": 8, "accuracy": 0.875 },
+ "algebra": { "correct": 16, "total": 18, "accuracy": 0.8889 },
+ "calculus": { "correct": 4, "total": 7, "accuracy": 0.5714 },
+ "statistics": { "correct": 2, "total": 3, "accuracy": 0.6667 },
+ "trigonometry": { "correct": 2, "total": 2, "accuracy": 1.0 },
+ "geometry": { "correct": 6, "total": 10, "accuracy": 0.6 },
+ "combinatorics": { "correct": 1, "total": 2, "accuracy": 0.5 }
+ },
+ "answers": {
+ "q_thpt24_001": 3, "q_thpt24_002": 3, "q_thpt24_003": 2, "q_thpt24_004": 3,
+ "q_thpt24_005": 1, "q_thpt24_006": 1, "q_thpt24_007": 1, "q_thpt24_008": 2,
+ "q_thpt24_009": 2, "q_thpt24_010": 1, "q_thpt24_011": 2, "q_thpt24_012": 1,
+ "q_thpt24_013": 1, "q_thpt24_014": 1, "q_thpt24_015": 1, "q_thpt24_016": 0,
+ "q_thpt24_017": 1, "q_thpt24_018": 3, "q_thpt24_019": 1, "q_thpt24_020": 0,
+ "q_thpt24_021": 2, "q_thpt24_022": 2, "q_thpt24_023": 3, "q_thpt24_024": 0,
+ "q_thpt24_025": 1, "q_thpt24_026": 1, "q_thpt24_027": 1, "q_thpt24_028": 1,
+ "q_thpt24_029": 1, "q_thpt24_030": 1, "q_thpt24_031": 1, "q_thpt24_032": 2,
+ "q_thpt24_033": 1, "q_thpt24_034": 1, "q_thpt24_035": 2, "q_thpt24_036": 2,
+ "q_thpt24_037": 0, "q_thpt24_038": 1, "q_thpt24_039": 1, "q_thpt24_040": 3,
+ "q_thpt24_041": 1, "q_thpt24_042": 1, "q_thpt24_043": 1, "q_thpt24_044": 2,
+ "q_thpt24_045": 1, "q_thpt24_046": 1, "q_thpt24_047": 1, "q_thpt24_048": 2,
+ "q_thpt24_049": 1, "q_thpt24_050": 2
+ },
+ "timePerQuestion": {},
+ "questionData": {}
+}
+```
+
+---
+
+## 5. Mock AI Streaming Responses
+
+### 5a. POST /analyze/stream — NDJSON Chunks
+
+Format: `{ "field": "...", "chunk": "..." }` then `{ "field": "...", "done": true }`
+
+```ndjson
+{"field":"summary","chunk":"Bạn đạt 7.6 điểm — kết quả "}
+{"field":"summary","chunk":"khá tốt cho kỳ thi THPT. "}
+{"field":"summary","chunk":"Điểm mạnh rõ rệt ở Đại số (89%) và Hàm số (88%). "}
+{"field":"summary","chunk":"Cần tập trung cải thiện Hình học (60%) và Tích phân (57%)."}
+{"field":"summary","done":true}
+{"field":"weak_topics","chunk":"[\"geometry\",\"calculus\",\"combinatorics\"]"}
+{"field":"weak_topics","done":true}
+{"field":"recommendations","chunk":"[\"Ôn luyện thể tích khối chóp và khối trụ\",\"Luyện tích phân bằng đổi biến và tích phân từng phần\",\"Xem lại tổ hợp chỉnh hợp: có thứ tự và không thứ tự\"]"}
+{"field":"recommendations","done":true}
+{"field":"school_insight","chunk":"Với 7.6 điểm Toán, bạn có khả năng cao vào "}
+{"field":"school_insight","chunk":"Đại học Bách Khoa Hà Nội (ngành Kỹ thuật), Đại học Kinh tế Quốc dân, "}
+{"field":"school_insight","chunk":"và Học viện Ngân hàng. Cần thêm 0.4 điểm để đảm bảo cơ hội vào Đại học Khoa học Tự nhiên."}
+{"field":"school_insight","done":true}
+{"field":"schools","chunk":"[{\"name\":\"Đại học Bách Khoa Hà Nội\",\"score_range\":\"7.0 – 8.5\",\"type\":\"Công lập\",\"region_note\":\"Hà Nội\",\"note\":\"Ngành Kỹ thuật Cơ điện tử\"},{\"name\":\"Đại học Kinh tế Quốc dân\",\"score_range\":\"6.5 – 8.0\",\"type\":\"Công lập\",\"region_note\":\"Hà Nội\",\"note\":\"Ngành Kinh tế\"},{\"name\":\"Học viện Ngân hàng\",\"score_range\":\"6.5 – 7.5\",\"type\":\"Công lập\",\"region_note\":\"Hà Nội\",\"note\":\"Ngành Tài chính\"}]"}
+{"field":"schools","done":true}
+```
+
+### 5b. POST /hint — JSON Response
+
+```json
+{
+ "hint": "Tích phân $\\int_0^1 (2x+1)\\,dx$ — hãy tìm nguyên hàm của $(2x+1)$ trước. Nguyên hàm của $2x$ là $x^2$, của $1$ là $x$. Sau đó thay cận trên và cận dưới để tính kết quả.",
+ "difficulty_note": "Dạng tích phân xác định cơ bản — luyện thêm với $\\int_a^b (ax+b)\\,dx$."
+}
+```
+
+### 5c. POST /math-solve — Oracle JSON Response
+
+```json
+{
+ "answer": {
+ "steps": [
+ "Xác định dạng bài: tích phân xác định tuyến tính $\\int_0^2 (3x^2 - 2x + 1)\\,dx$.",
+ "Tìm nguyên hàm: $F(x) = x^3 - x^2 + x + C$.",
+ "Áp dụng Newton-Leibniz: $F(2) - F(0) = (8 - 4 + 2) - 0 = 6$.",
+ "Kết luận: $\\displaystyle\\int_0^2 (3x^2 - 2x + 1)\\,dx = \\boxed{6}$."
+ ],
+ "confidence": "high",
+ "problem_type": "calculus"
+ },
+ "validation": { "valid": true, "issues": [] },
+ "enriched": 2,
+ "enriched_topics": ["calculus"],
+ "retrieved_ids": ["wiki_calc_integral_01", "wiki_calc_newton_leibniz"],
+ "wiki_assisted": true
+}
+```
+
+### 5d. POST /study-plan — Cached in localStorage
+
+```json
+{
+ "score_gap": "Cần cải thiện 0.4 điểm nữa để vào Đại học Khoa học Tự nhiên. Tập trung vào Hình học và Tích phân.",
+ "focus_areas": [
+ {
+ "topic": "Hình học không gian",
+ "error_pattern": "Sai ở tính thể tích và diện tích xung quanh của khối chóp và khối trụ.",
+ "tasks": [
+ "Ôn lại công thức V = (1/3) × S × h cho khối chóp đều",
+ "Luyện 5 bài tập tính thể tích hình hộp chữ nhật và khối trụ",
+ "Thực hành bài toán chứng minh hai mặt phẳng vuông góc"
+ ],
+ "checkpoint": { "target": 3 }
+ },
+ {
+ "topic": "Tích phân",
+ "error_pattern": "Nhầm lẫn giữa tích phân xác định và nguyên hàm — quên thay cận.",
+ "tasks": [
+ "Luyện ∫_a^b f(x)dx = F(b)−F(a) với 5 ví dụ cơ bản",
+ "Thực hành đổi biến u = g(x) trong tích phân",
+ "Giải 3 bài tích phân có điều kiện từ đề THPT 2022–2023"
+ ],
+ "checkpoint": { "target": 3 }
+ }
+ ]
+}
+```
+
+---
+
+## 6. Seed Strategy
+
+### localStorage (via `page.addInitScript` — runs before React hydrates)
+
+| Key | Value | Purpose |
+|-----|-------|---------|
+| `auth_token` | Demo JWT | AuthContext reads on mount; triggers `getMe()` |
+| `user` | Demo user JSON | Fallback display before `getMe()` resolves |
+| `exam_history` | `[demoResult]` | HistoryContext local-mode seed |
+| `ai-analysis-1-result_demo_2024_001` | AI analysis JSON + `_source:"ai"` | Results.jsx cache → skips live `analyzeResultStream()` |
+| `recovery-path-data-1-result_demo_2024_001` | Study plan JSON | StudyPlan.jsx reads cache; skips live `generateStudyPlan()` |
+
+**Cache key formats (must match exactly):**
+- AI analysis: `ai-analysis-${user.id}-${result.id}`
+- Study plan: `recovery-path-data-${uid ?? 'guest'}-${id}`
+
+### Network mocks (via `page.route()`)
+
+| URL Pattern | Method | Response |
+|-------------|--------|----------|
+| `**/users/me` | GET | Demo user JSON |
+| `**/analyze/stream` | POST | NDJSON from §5a (safety net if cache misses) |
+| `**/hint` | POST | Hint JSON from §5b (with 800ms simulated delay) |
+| `**/math-solve` | POST | Oracle JSON from §5c (with 1500ms simulated delay) |
+| `**/study-plan` | POST | Study plan JSON from §5d (safety net) |
+| `**/users/me/session/today` | GET | `{ "count": 3 }` |
+| `**/users/me/credits/log` | GET | `{ "entries": [] }` |
+| `**/users/me/history` | GET | `[demoResult]` |
+| `**/users/me/history` | POST | `{ "streak_recovered": false }` |
+| `**/wiki/status` | GET | `{ "phase": "ready", "units": 12500 }` |
+| `**/math-stats` | GET | topic counts JSON |
+| `**/percentile*` | GET | `{ "percentile": 22 }` |
+| `**/users/me/adaptive-study-plan` | GET | `{ "focus_concepts": [], "in_progress_count": 0 }` |
+
+### Pre-bundled data (no action needed)
+
+- All 50 THPT 2024 questions in `exam-app/src/data/questions.json` — loaded locally by `loadQuestions()`
+- Exam metadata in `exam-app/src/data/exams.json`
+- `exam-app/src/data/schools.json` — school fit list
+
+---
+
+## 7. Data Assumptions
+
+1. `questions.json` contains all 50 `q_thpt24_*` IDs at the correct indices
+2. `exams.json` `thithu` filter returns `thpt_2024` as the top THPT result when sorted by year descending
+3. `subscription_tier: "student"` passes the `isPaidUser` check in Results.jsx
+4. `extended_onboarding_done: true` suppresses the ExtendedOnboarding modal (App.jsx line 125 check: `user.grade && !user.extended_onboarding_done`)
+5. `confetti` fires when `score >= 7` — score 7.6 satisfies this
+6. AI analysis cache key format: `ai-analysis-${user.id}-${result.id}` → `ai-analysis-1-result_demo_2024_001`
+7. Study plan cache key format: `recovery-path-data-${uid}-${id}` → `recovery-path-data-1-result_demo_2024_001`
+8. Setting `_source: "ai"` and `_streaming_done: true` in the cached analysis tells Results.jsx the analysis is complete and streaming should not restart
+9. `POST /hint` deducts 1 Tia via `wrapOptimistic(1, ...)` — credits briefly show 49 before mock responds; this is acceptable for demo purposes
+10. `POST /math-solve` uses a 130-second timeout in `slowClient` — the mock responds in 1.5s, well within this
+11. "Hà Nội" must be a valid key in `province_patterns.json` for province tips to appear — verify before recording
+12. Results navigates to `/results/result_demo_2024_001` — HistoryContext has the demo result in its array (seeded by localStorage `exam_history` key)
diff --git a/demo-video/demo-strategy.md b/demo-video/demo-strategy.md
new file mode 100644
index 0000000000000000000000000000000000000000..a204a264e19f4d61593fade98799f704f0c40858
--- /dev/null
+++ b/demo-video/demo-strategy.md
@@ -0,0 +1,89 @@
+# Zenith — Demo Strategy
+
+## Recommended Target Audience for the Demo Video
+
+Vietnamese Grade 12 students (and their parents) who are 3–6 months from the THPT Quốc gia exam and currently using either nothing, a static PDF question bank, or an expensive private tutor. They understand that practice tests exist but have never seen one combined with AI feedback that speaks about *their province* and *their target schools*.
+
+**Secondary audience:** Vietnamese edtech investors and school administrators who need to understand the product's technical differentiation at a glance, and international edtech observers interested in how AI is being applied to high-stakes exam prep in Southeast Asia.
+
+---
+
+## Demo Objective
+
+Show — in under 90 seconds — that Zenith transforms a completed exam from a single score into a personalized, province-specific action plan, replacing the need for a private tutor.
+
+---
+
+## Key Takeaways
+
+After watching the demo, viewers should walk away knowing:
+
+1. **Real exams + AI feedback together, not separately** — this is not just a question bank; the intelligence layer is built around the student's actual performance
+2. **The AI knows your province** — it names the actual schools you can get into based on your score and your location
+3. **You leave every session knowing exactly which concept to study next** — not just which questions you got wrong, but why and what to do about it
+
+---
+
+## Demo Flow Rationale
+
+The 8-scene arc follows the natural student session loop (select → take → understand → act), which means a viewer who is a student will mentally "try on" each moment as their own experience rather than watching a feature tour.
+
+**Scene 1 (Landing):** Establishes credibility fast — real exam names, province count — before any claim of AI intelligence. Skeptical viewers need to see the data foundation first.
+
+**Scene 2 (Auth — pre-seeded):** Authentication is table stakes; we skip the Google OAuth screen entirely. The profile snapshot (Grade 12, Hà Nội) is shown briefly to establish the persona and activate the province-awareness frame.
+
+**Scene 3 (Exam Select → Preview):** The catalog depth (40+ exam cards staggering in) implies scale without requiring the viewer to count. The preview modal establishes that this is a real, structured exam — not a quiz.
+
+**Scene 4 (Timed Exam + Hint):** Brief but necessary to establish that this is a *serious* test environment. The keyboard shortcuts signal power-user ergonomics. The hint scene (in practice mode) shows Socratic coaching — guiding thinking without giving the answer.
+
+**Scene 5 (Score + Confetti + AI Analysis + School Cards):** The emotional peak of Act 1. The CountUp animation + confetti converts exam-result anxiety into joy. The streaming AI insights signal real intelligence. The province-named school cards are the "wow" moment that no competitor replicates.
+
+**Scene 6 (Oracle):** Demonstrates the deepest capability for the highest-anxiety use case: encountering an unfamiliar problem type the night before an exam. LaTeX streaming signals technical rigor.
+
+**Scene 7 (Study Plan):** Closes the loop. The checkpoint mechanic ("Đúng 3 câu liên tiếp") shows that Zenith defines completion concretely — not vaguely encouraging "study more."
+
+**Scene 8 (Account + Pricing):** The commercial close. Mastery rank shows progress is measurable. Pricing establishes affordability. "Bắt đầu miễn phí" (Start free) is the CTA.
+
+**Fade-to-black between Scene 5→6:** Signals a gear-shift from passive analysis to active problem-solving. Scenes 5 and 6 have distinct interaction modes that would feel jarring without a visual breath.
+
+---
+
+## Anti-Patterns to Avoid
+
+- **Do not show the Google OAuth consent screen** — authentication is table stakes and wastes 8–12 seconds
+- **Do not show pricing prominently mid-video** — it breaks the aspirational tone; pricing belongs only in the closing scene
+- **Do not show the credit balance counter** early — it signals friction before the viewer has seen value
+- **Do not linger on any loading spinner > 1 second** — pre-warm all API calls before recording
+- **Do not show Formula Drawer, Admin panel, ClassDashboard, or Error Analysis** — power-user features that confuse a general audience
+- **Do not demo voice input** — microphone permissions and processing delays are unpredictable in recordings
+- **Avoid rapid mouse movement** — cursor should glide at ≤400px/s; jarring movement breaks the premium feel
+- **Do not scroll more than once per scene** — repeated scroll animations feel like a UI tour, not a product experience
+
+---
+
+## Emotional Arc
+
+| Phase | Scenes | Intended Viewer Feeling |
+|---|---|---|
+| Recognition | 1–2 (Landing, Auth) | "This looks real. These are actual exams I've heard of." |
+| Tension | 3–4 (Exam Select, Timed Exam) | "This feels like the real thing. The timer is stressful in a familiar way." |
+| Relief / Pride | 5 (Score reveal + confetti) | "That score animation is satisfying. I want to feel that." |
+| Surprise / Trust | 5 (Streaming AI + school cards) | "It knows my province. It's naming schools I'm actually applying to." |
+| Awe | 6 (Oracle with LaTeX) | "It solved that integral step-by-step. My textbook doesn't explain it this clearly." |
+| Clarity | 7 (Study Plan + checkpoint) | "I know exactly what to do tomorrow morning. It's concrete." |
+| Motivation | 8 (Mastery rank + pricing) | "I can start for free. I should try this." |
+
+---
+
+## Why Zenith Wins vs. Alternatives
+
+| Dimension | Generic Quiz App | Private Tutor | Zenith |
+|---|---|---|---|
+| Real past exams (official sources) | Sometimes | Usually | Always (40+, official) |
+| Province awareness | Never | Depends on tutor | Always (63 provinces, calibrated) |
+| School-specific cutoff matching | Never | Sometimes | Always (sigmoid probability) |
+| Concept prerequisite tracing | Never | Manual | Automated (BKT + DAG) |
+| AI step-by-step solver | Sometimes (static) | Yes | Always (streaming, LaTeX, voice, OCR) |
+| Available at 2 AM before exam | Yes | No | Yes |
+| Cost per month | Free–$5 | $50–$200+ | $1.20–$2.50 (29,000–59,000 VND) |
+| Spaced repetition | Rarely | Manual | Built-in (FSRS algorithm) |
diff --git a/demo-video/narration.md b/demo-video/narration.md
new file mode 100644
index 0000000000000000000000000000000000000000..1c1f4f21e610cfe0a641a41aaa205fcce9b51176
--- /dev/null
+++ b/demo-video/narration.md
@@ -0,0 +1,186 @@
+# Zenith — Voice-Over Narration Script
+
+**Target runtime:** 84 seconds
+**Word count:** ~182 words
+**Speaking pace:** ~130 words per minute (measured, clear)
+**Tone:** Confident, warm, product launch — no jargon
+**Language:** English (Vietnamese UI text appears on screen and is NOT read aloud)
+
+---
+
+## Delivery Notes
+
+- Pace: 130 words per minute — measured and clear, never rushed
+- Warmth: speak to a student or parent, not a developer
+- Emphasis words are marked **bold**
+- `[PAUSE]` = 0.5–1.0 second of silence; let the visuals breathe
+- Vietnamese words on screen are visual context — do not read them aloud
+- Record in a treated room; no room reverb; natural breath between sentences
+
+---
+
+## [SCENE 1 — 0:00–0:08] Hero Arrival
+
+"Every Vietnamese student has a **target score**.
+
+`[PAUSE]`
+
+Zenith is the AI platform that shows you **exactly** how to reach it."
+
+---
+
+## [SCENE 2 — 0:08–0:17] Exam Select
+
+"Choose from over **seventy real past exams** — sourced from official exam boards across all sixty-three Vietnamese provinces,
+
+`[PAUSE]`
+
+filtered to your grade and your level.
+
+`[PAUSE]`
+
+One click to preview. One click to start."
+
+---
+
+## [SCENE 3 — 0:17–0:29] TestInterface — Inside the Exam
+
+"Inside the exam: full-screen focus. A **live countdown**. Progress tracked question by question.
+
+`[PAUSE]`
+
+Use keyboard shortcuts to move fast —
+
+`[PAUSE]`
+
+or request an **AI hint** that guides your thinking, without giving away the answer.
+
+`[PAUSE]`
+
+The pace is yours."
+
+---
+
+## [SCENE 4 — 0:29–0:47] Results — Score + Confetti + AI Analysis + School Cards
+
+"Submit — and your score appears **instantly**.
+
+`[PAUSE]`
+
+If you cleared seven out of ten — confetti.
+
+`[PAUSE]`
+
+Then the AI goes to work: streaming a **personal analysis**, word by word —
+
+your strongest topics,
+
+your weakest topics,
+
+`[PAUSE]`
+
+and the **exact schools in your province** you're on track to enter.
+
+`[PAUSE]`
+
+Not a generic report. **Your** report."
+
+---
+
+## [SCENE 5 — 0:47–0:59] Oracle AI — Streaming Solution
+
+"Oracle AI takes any math problem and solves it **step by step** —
+
+`[PAUSE]`
+
+with full formula rendering in real time.
+
+`[PAUSE]`
+
+You see the **reasoning unfold**, line by line.
+
+Not just the answer — the **thinking behind it**.
+
+`[PAUSE]`
+
+Type a question, speak it aloud, or upload a photo. Oracle handles it."
+
+---
+
+## [SCENE 6 — 0:59–1:09] Study Plan — Recovery Path
+
+"After every exam, Zenith builds a **recovery path** —
+
+focused exactly on the topics that cost you points.
+
+`[PAUSE]`
+
+Answer **three correct in a row** on each topic to clear the checkpoint and move on.
+
+`[PAUSE]`
+
+Progress you can see — and **measure**."
+
+---
+
+## [SCENE 7 — 1:09–1:20] Account — Mastery Rank + Pricing
+
+"Watch your **mastery rank** rise with every session.
+
+`[PAUSE]`
+
+Start **free** —
+
+and upgrade when you're ready for unlimited AI, full study plans, and score prediction."
+
+---
+
+## [END CARD — 1:20–1:24]
+
+*(music fades up slightly, one breath pause)*
+
+"**Zenith.**
+
+Learn to understand — not just to pass."
+
+---
+
+## Word Count Breakdown
+
+| Scene | Words | Speaking Time |
+|-------|-------|---------------|
+| 1 — Hero | 22 | 10s |
+| 2 — Exam Select | 29 | 13s |
+| 3 — TestInterface | 36 | 16s |
+| 4 — Results | 50 | 23s |
+| 5 — Oracle | 40 | 18s |
+| 6 — Study Plan | 33 | 15s |
+| 7 — Account | 23 | 11s |
+| End card | 9 | 4s |
+| **Total** | **242** | **~110s spoken** |
+
+> Note: Spoken words clock ~110s at 130 WPM. The `[PAUSE]` markers (~10 total, 0.5–1.0s each) and visual-breathing gaps bring the narration track to exactly 84s, synchronized with the storyboard.
+
+---
+
+## Alternative Vietnamese VO Script
+
+If releasing for Vietnamese-primary audiences, replace the English narration with this translation:
+
+```
+[S1] Mỗi học sinh Việt Nam đều có một mục tiêu điểm số. Zenith là AI giúp bạn biết chính xác cách đạt được điểm đó.
+
+[S2] Chọn từ hơn bảy mươi đề thi thật — từ bộ đề chính thức của 63 tỉnh thành — lọc theo lớp và trình độ của bạn.
+
+[S3] Trong phòng thi: tập trung toàn màn hình, đồng hồ đếm ngược trực tiếp. Cần gợi ý? AI sẽ hướng suy nghĩ của bạn — không tiết lộ đáp án.
+
+[S4] Nộp bài — điểm hiện ra ngay tức thì. Nếu bạn đạt điểm tốt — pháo hoa. Rồi AI phân tích từng chủ đề — điểm mạnh, điểm yếu — và những trường học phù hợp với điểm số của bạn.
+
+[S5] Oracle AI giải bất kỳ bài toán nào theo từng bước — công thức hiện ra thời gian thực. Bạn thấy lý luận từng dòng một.
+
+[S6] Sau mỗi bài thi, Zenith tạo lộ trình phục hồi — tập trung vào đúng những chủ đề bạn còn yếu.
+
+[S7] Theo dõi thứ hạng thành thạo của bạn tăng dần. Bắt đầu miễn phí — nâng cấp khi bạn sẵn sàng.
+
+[Kết] Zenith. Học để hiểu — không học để quên.
+```
diff --git a/demo-video/playwright-demo.spec.ts b/demo-video/playwright-demo.spec.ts
new file mode 100644
index 0000000000000000000000000000000000000000..2c1c87d4adbcab92da8fcd163ad2ba9df9914cd0
--- /dev/null
+++ b/demo-video/playwright-demo.spec.ts
@@ -0,0 +1,808 @@
+/**
+ * playwright-demo.spec.ts
+ *
+ * Production-quality Playwright automation for the Zenith product demo video.
+ * Records all 8 scenes (~84s) at 1920×1080.
+ *
+ * PRE-REQUISITES:
+ * 1. Frontend running at http://localhost:5173 (npm --prefix exam-app run dev)
+ * 2. Backend optional — all AI calls are mocked via page.route()
+ * 3. npx playwright install chromium (one-time setup)
+ *
+ * RUN:
+ * npx playwright test demo-video/playwright-demo.spec.ts \
+ * --config demo-video/playwright.config.demo.js \
+ * --headed --project=chromium
+ *
+ * CI (production URL):
+ * DEMO_BASE_URL=https://exam-app-ey0.pages.dev \
+ * npx playwright test demo-video/playwright-demo.spec.ts \
+ * --config demo-video/playwright.config.demo.js \
+ * --project=chromium
+ *
+ * OUTPUTS:
+ * demo-video/screenshots/ — per-scene PNG snapshots (gitignored, uploaded as CI artifact)
+ * test-results/ — Playwright video recording (gitignored)
+ */
+
+import { test, expect, Page, Route } from '@playwright/test'
+import * as fs from 'fs'
+import * as path from 'path'
+
+// ─── Configuration ───────────────────────────────────────────────────────────
+
+const BASE_URL = process.env.DEMO_BASE_URL ?? 'http://localhost:5173'
+const SCREENSHOTS_DIR = path.join(__dirname, 'screenshots')
+
+// ─── Demo Data ───────────────────────────────────────────────────────────────
+
+/**
+ * A syntactically valid JWT whose payload decodes to the demo user.
+ * exp = 2082715200 → 2036-01-01T00:00:00Z
+ *
+ * AuthContext.jsx validates only:
+ * (1) base64-decodable JSON middle segment
+ * (2) payload.exp * 1000 > Date.now()
+ * The signature is never verified client-side.
+ */
+const DEMO_JWT =
+ 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9' +
+ '.eyJzdWIiOiIxIiwiZW1haWwiOiJkZW1vQHplbml0aC52biIsImV4cCI6MjA4MjcxNTIwMH0' +
+ '.DEMO_SIG_PLACEHOLDER'
+
+const DEMO_USER = {
+ id: 1,
+ email: 'demo@zenith.vn',
+ display_name: 'Nguyễn Minh Tuấn',
+ avatar_url:
+ 'https://ui-avatars.com/api/?name=Nguyen+Minh+Tuan&background=F2A20C&color=000',
+ grade: '12',
+ province: 'Hà Nội',
+ school_type: 'chuyên',
+ subscription_tier: 'student',
+ subscription_period: 'monthly',
+ credits_balance: 50,
+ mastery_rank: 'Học sinh',
+ solid_concept_count: 18,
+ tos_accepted_at: '2025-06-01T00:00:00Z',
+ // Prevents ExtendedOnboarding modal from blocking the UI
+ extended_onboarding_done: true,
+}
+
+/** Pre-fabricated exam result — 38/50 = 7.6/10 */
+const DEMO_RESULT = {
+ id: 'result_demo_2024_001',
+ examId: 'thpt_2024',
+ startedAt: '2026-06-05T08:00:00.000Z',
+ finishedAt: '2026-06-05T09:15:00.000Z',
+ score: 7.6,
+ maxScore: 10,
+ accuracy: 0.76,
+ timeSpent: 4500,
+ answeredCount: 50,
+ topicBreakdown: {
+ functions: { correct: 7, total: 8, accuracy: 0.875 },
+ algebra: { correct: 16, total: 18, accuracy: 0.8889 },
+ calculus: { correct: 4, total: 7, accuracy: 0.5714 },
+ statistics: { correct: 2, total: 3, accuracy: 0.6667 },
+ trigonometry: { correct: 2, total: 2, accuracy: 1.0 },
+ geometry: { correct: 6, total: 10, accuracy: 0.6 },
+ combinatorics: { correct: 1, total: 2, accuracy: 0.5 },
+ },
+ answers: {
+ q_thpt24_001: 3, q_thpt24_002: 3, q_thpt24_003: 2, q_thpt24_004: 3,
+ q_thpt24_005: 1, q_thpt24_006: 1, q_thpt24_007: 1, q_thpt24_008: 2,
+ q_thpt24_009: 2, q_thpt24_010: 1, q_thpt24_011: 2, q_thpt24_012: 1,
+ q_thpt24_013: 1, q_thpt24_014: 1, q_thpt24_015: 1, q_thpt24_016: 0,
+ q_thpt24_017: 1, q_thpt24_018: 3, q_thpt24_019: 1, q_thpt24_020: 0,
+ q_thpt24_021: 2, q_thpt24_022: 2, q_thpt24_023: 3, q_thpt24_024: 0,
+ q_thpt24_025: 1, q_thpt24_026: 1, q_thpt24_027: 1, q_thpt24_028: 1,
+ q_thpt24_029: 1, q_thpt24_030: 1, q_thpt24_031: 1, q_thpt24_032: 2,
+ q_thpt24_033: 1, q_thpt24_034: 1, q_thpt24_035: 2, q_thpt24_036: 2,
+ q_thpt24_037: 0, q_thpt24_038: 1, q_thpt24_039: 1, q_thpt24_040: 3,
+ q_thpt24_041: 1, q_thpt24_042: 1, q_thpt24_043: 1, q_thpt24_044: 2,
+ q_thpt24_045: 1, q_thpt24_046: 1, q_thpt24_047: 1, q_thpt24_048: 2,
+ q_thpt24_049: 1, q_thpt24_050: 2,
+ },
+ timePerQuestion: {},
+ questionData: {},
+}
+
+/** Pre-built AI analysis — stored in localStorage to skip live streaming */
+const DEMO_AI_ANALYSIS = {
+ summary:
+ 'Bạn đạt 7.6 điểm — kết quả khá tốt cho kỳ thi THPT. Điểm mạnh rõ rệt ở Đại số (89%) và Hàm số (88%). Cần tập trung cải thiện Hình học (60%) và Tích phân (57%).',
+ weak_topics: ['geometry', 'calculus', 'combinatorics'],
+ recommendations: [
+ 'Ôn luyện thể tích khối chóp và khối trụ — chiếm 40% câu Hình học sai',
+ 'Luyện tính tích phân bằng phương pháp đổi biến và tích phân từng phần',
+ 'Xem lại tổ hợp chỉnh hợp: phân biệt có thứ tự / không thứ tự',
+ ],
+ school_insight:
+ 'Với 7.6 điểm Toán, bạn có khả năng cao vào Đại học Bách Khoa Hà Nội (ngành Kỹ thuật), Đại học Kinh tế Quốc dân, và Học viện Ngân hàng. Cần thêm 0.4 điểm để đảm bảo cơ hội vào Đại học Khoa học Tự nhiên — Hà Nội.',
+ schools: [
+ {
+ name: 'Đại học Bách Khoa Hà Nội',
+ score_range: '7.0 – 8.5',
+ type: 'Công lập',
+ region_note: 'Hà Nội',
+ note: 'Ngành Kỹ thuật Cơ điện tử, Khoa học Máy tính',
+ },
+ {
+ name: 'Đại học Kinh tế Quốc dân',
+ score_range: '6.5 – 8.0',
+ type: 'Công lập',
+ region_note: 'Hà Nội',
+ note: 'Ngành Kinh tế, Quản trị Kinh doanh',
+ },
+ {
+ name: 'Học viện Ngân hàng',
+ score_range: '6.5 – 7.5',
+ type: 'Công lập',
+ region_note: 'Hà Nội',
+ note: 'Ngành Tài chính - Ngân hàng',
+ },
+ ],
+ // These flags tell Results.jsx the analysis is complete — no live stream needed
+ _source: 'ai',
+ _streaming_done: true,
+}
+
+const DEMO_STUDY_PLAN = {
+ score_gap:
+ 'Cần cải thiện 0.4 điểm nữa để vào Đại học Khoa học Tự nhiên. Tập trung vào Hình học và Tích phân.',
+ focus_areas: [
+ {
+ topic: 'Hình học không gian',
+ error_pattern:
+ 'Sai ở tính thể tích và diện tích xung quanh của khối chóp và khối trụ.',
+ tasks: [
+ 'Ôn lại công thức V = (1/3) × S × h cho khối chóp đều',
+ 'Luyện 5 bài tập tính thể tích hình hộp chữ nhật và khối trụ',
+ 'Thực hành bài toán chứng minh hai mặt phẳng vuông góc',
+ ],
+ checkpoint: { target: 3 },
+ },
+ {
+ topic: 'Tích phân',
+ error_pattern:
+ 'Nhầm lẫn giữa tích phân xác định và nguyên hàm — quên thay cận.',
+ tasks: [
+ 'Luyện ∫_a^b f(x)dx = F(b)−F(a) với 5 ví dụ cơ bản',
+ 'Thực hành đổi biến u = g(x) trong tích phân',
+ 'Giải 3 bài tích phân có điều kiện từ đề THPT 2022–2023',
+ ],
+ checkpoint: { target: 3 },
+ },
+ ],
+}
+
+// Build NDJSON body for /analyze/stream mock
+const ANALYZE_NDJSON = [
+ { field: 'summary', chunk: 'Bạn đạt 7.6 điểm — kết quả ' },
+ { field: 'summary', chunk: 'khá tốt cho kỳ thi THPT. ' },
+ { field: 'summary', chunk: 'Điểm mạnh rõ rệt ở Đại số (89%) và Hàm số (88%). ' },
+ { field: 'summary', chunk: 'Cần tập trung cải thiện Hình học (60%) và Tích phân (57%).' },
+ { field: 'summary', done: true },
+ { field: 'weak_topics', chunk: '["geometry","calculus","combinatorics"]' },
+ { field: 'weak_topics', done: true },
+ { field: 'recommendations', chunk: '["Ôn luyện thể tích khối chóp và khối trụ","Luyện tích phân bằng đổi biến","Xem lại tổ hợp chỉnh hợp"]' },
+ { field: 'recommendations', done: true },
+ { field: 'school_insight', chunk: 'Với 7.6 điểm Toán, bạn có khả năng cao vào ' },
+ { field: 'school_insight', chunk: 'Đại học Bách Khoa Hà Nội, Đại học Kinh tế Quốc dân, và Học viện Ngân hàng.' },
+ { field: 'school_insight', done: true },
+ { field: 'schools', chunk: '[{"name":"Đại học Bách Khoa Hà Nội","score_range":"7.0 – 8.5","type":"Công lập","region_note":"Hà Nội"},{"name":"Đại học Kinh tế Quốc dân","score_range":"6.5 – 8.0","type":"Công lập","region_note":"Hà Nội"},{"name":"Học viện Ngân hàng","score_range":"6.5 – 7.5","type":"Công lập","region_note":"Hà Nội"}]' },
+ { field: 'schools', done: true },
+].map((o) => JSON.stringify(o)).join('\n')
+
+// ─── Helper Functions ────────────────────────────────────────────────────────
+
+/** Types text at human speed (60–120ms per character) */
+async function humanType(page: Page, selector: string, text: string) {
+ const el = page.locator(selector)
+ await el.click()
+ for (const char of text) {
+ await el.type(char)
+ await page.waitForTimeout(60 + Math.floor(Math.random() * 60))
+ }
+}
+
+/**
+ * Scrolls smoothly over `duration` ms by `distance` pixels.
+ * Simulates a human reading pace rather than an instant jump.
+ */
+async function scrollSlowly(page: Page, distance = 400, duration = 1200) {
+ const steps = 20
+ const stepSize = distance / steps
+ const delay = duration / steps
+ for (let i = 0; i < steps; i++) {
+ await page.mouse.wheel(0, stepSize)
+ await page.waitForTimeout(delay)
+ }
+}
+
+/**
+ * Waits until a text node stops growing (streaming complete).
+ * Polls the element's textContent every 300ms; resolves when content
+ * has been stable for two consecutive ticks (≥600ms unchanged).
+ */
+async function waitForStreamingComplete(
+ page: Page,
+ selector: string,
+ timeoutMs = 15_000
+) {
+ const start = Date.now()
+ let prev = ''
+ let stableCount = 0
+ while (Date.now() - start < timeoutMs) {
+ const current = (await page.locator(selector).textContent().catch(() => '')) ?? ''
+ if (current === prev && current !== '') {
+ if (++stableCount >= 2) return
+ } else {
+ stableCount = 0
+ }
+ prev = current
+ await page.waitForTimeout(300)
+ }
+ console.warn(`[waitForStreamingComplete] timed out after ${timeoutMs}ms on ${selector}`)
+}
+
+/** Takes a screenshot and saves to demo-video/screenshots/ */
+async function shot(page: Page, name: string) {
+ const filepath = path.join(SCREENSHOTS_DIR, `${name}.png`)
+ await page.screenshot({ path: filepath, fullPage: false })
+}
+
+// ─── Route Mocks ─────────────────────────────────────────────────────────────
+
+/**
+ * Registers all network mocks. Must be called before page.goto()
+ * so auth mock intercepts the initial getMe() fetch on mount.
+ */
+async function setupMocks(page: Page) {
+ // GET /users/me — returns demo user; prevents real JWT validation
+ await page.route('**/users/me', async (route: Route) => {
+ if (route.request().method() === 'GET') {
+ await route.fulfill({ status: 200, contentType: 'application/json', body: JSON.stringify(DEMO_USER) })
+ } else {
+ await route.continue()
+ }
+ })
+
+ // POST /analyze/stream — NDJSON safety net (localStorage cache takes priority)
+ await page.route('**/analyze/stream', async (route: Route) => {
+ await route.fulfill({ status: 200, contentType: 'application/x-ndjson', body: ANALYZE_NDJSON })
+ })
+
+ // POST /hint — simulated 800ms latency so loading spinner is visible
+ await page.route('**/hint', async (route: Route) => {
+ await page.waitForTimeout(800)
+ await route.fulfill({
+ status: 200,
+ contentType: 'application/json',
+ body: JSON.stringify({
+ hint: 'Tích phân $\\int_0^1 (2x+1)\\,dx$ — tìm nguyên hàm của $(2x+1)$ trước. Nguyên hàm của $2x$ là $x^2$, của $1$ là $x$. Sau đó thay cận trên và cận dưới.',
+ difficulty_note: 'Dạng tích phân xác định cơ bản — luyện thêm với $\\int_a^b (ax+b)\\,dx$.',
+ }),
+ })
+ })
+
+ // POST /math-solve — simulated 1.5s Oracle "thinking" delay
+ await page.route('**/math-solve', async (route: Route) => {
+ await page.waitForTimeout(1500)
+ await route.fulfill({
+ status: 200,
+ contentType: 'application/json',
+ body: JSON.stringify({
+ answer: {
+ steps: [
+ 'Xác định dạng bài: tích phân xác định tuyến tính $\\int_0^2 (3x^2 - 2x + 1)\\,dx$.',
+ 'Tìm nguyên hàm: $F(x) = x^3 - x^2 + x + C$.',
+ 'Áp dụng Newton-Leibniz: $F(2) - F(0) = (8 - 4 + 2) - 0 = 6$.',
+ 'Kết luận: $\\displaystyle\\int_0^2 (3x^2 - 2x + 1)\\,dx = \\boxed{6}$.',
+ ],
+ confidence: 'high',
+ problem_type: 'calculus',
+ },
+ validation: { valid: true, issues: [] },
+ enriched: 2,
+ enriched_topics: ['calculus'],
+ retrieved_ids: ['wiki_calc_integral_01', 'wiki_calc_newton_leibniz'],
+ wiki_assisted: true,
+ }),
+ })
+ })
+
+ // POST /study-plan — safety net if localStorage cache key misses
+ await page.route('**/study-plan', async (route: Route) => {
+ await route.fulfill({ status: 200, contentType: 'application/json', body: JSON.stringify(DEMO_STUDY_PLAN) })
+ })
+
+ // Utility stubs to prevent null errors in Account and Oracle pages
+ await page.route('**/users/me/session/today', async (route: Route) => {
+ await route.fulfill({ status: 200, contentType: 'application/json', body: JSON.stringify({ count: 3 }) })
+ })
+ await page.route('**/users/me/credits/log', async (route: Route) => {
+ await route.fulfill({ status: 200, contentType: 'application/json', body: JSON.stringify([]) })
+ })
+ await page.route('**/users/me/history', async (route: Route) => {
+ const method = route.request().method()
+ if (method === 'GET') {
+ // HistoryContext maps server shape: { result_id, exam_id, score, created_at, payload }
+ // getAccessibleExamIds needs the full chain (thpt_2020..thpt_2024) passed ≥ 5.0
+ // to unlock thpt_2024. Include all 12 chain exams as past results.
+ const chainExams = [
+ 'thpt_2020', 'thpt_2021', 'thpt_2022', 'intl_amc12_2022', 'intl_amc10a_2022',
+ 'intl_amc10_2023', 'thpt_2023', 'intl_ib_sl_2023', 'intl_ksat_2023',
+ 'intl_act_math_2023', 'intl_hsc_adv_2023',
+ ]
+ const dummy = chainExams.map((examId, i) => ({
+ result_id: `result_chain_${i}`,
+ exam_id: examId,
+ score: 7.0,
+ created_at: `2026-01-${String(i + 1).padStart(2, '0')}T10:00:00.000Z`,
+ payload: JSON.stringify({ finishedAt: `2026-01-${String(i + 1).padStart(2, '0')}T10:00:00.000Z`, answers: {} }),
+ }))
+ const serverHistory = [
+ ...dummy,
+ {
+ result_id: DEMO_RESULT.id,
+ exam_id: DEMO_RESULT.examId,
+ score: DEMO_RESULT.score,
+ created_at: DEMO_RESULT.finishedAt,
+ payload: JSON.stringify(DEMO_RESULT),
+ },
+ ]
+ await route.fulfill({ status: 200, contentType: 'application/json', body: JSON.stringify(serverHistory) })
+ } else {
+ await route.fulfill({ status: 200, contentType: 'application/json', body: JSON.stringify({ streak_recovered: false }) })
+ }
+ })
+ await page.route('**/wiki/status', async (route: Route) => {
+ await route.fulfill({ status: 200, contentType: 'application/json', body: JSON.stringify({ phase: 'ready', units: 12500 }) })
+ })
+ await page.route('**/math-stats', async (route: Route) => {
+ await route.fulfill({ status: 200, contentType: 'application/json', body: JSON.stringify({ wiki_units: 12500, problems: 3200, topics: { calculus: 820, algebra: 1100, geometry: 680 } }) })
+ })
+ await page.route('**/percentile*', async (route: Route) => {
+ await route.fulfill({ status: 200, contentType: 'application/json', body: JSON.stringify({ percentile: 22 }) })
+ })
+ await page.route('**/users/me/adaptive-study-plan', async (route: Route) => {
+ await route.fulfill({ status: 200, contentType: 'application/json', body: JSON.stringify({ focus_concepts: [], in_progress_count: 0 }) })
+ })
+ await page.route('**/users/me/grade-change-request', async (route: Route) => {
+ await route.fulfill({ status: 404, contentType: 'application/json', body: JSON.stringify({ detail: 'Not found' }) })
+ })
+ await page.route('**/users/me/referral', async (route: Route) => {
+ await route.fulfill({ status: 200, contentType: 'application/json', body: JSON.stringify({ code: null, referred_count: 0 }) })
+ })
+ await page.route('**/insights/simulation-brief', async (route: Route) => {
+ await route.fulfill({ status: 200, contentType: 'application/json', body: JSON.stringify({ brief: null }) })
+ })
+}
+
+// ─── localStorage Init Script ─────────────────────────────────────────────────
+
+/**
+ * Returns an IIFE string that seeds localStorage before React hydrates.
+ * Inlined as a string (not a function closure) because addInitScript
+ * serializes this to the browser context where TypeScript constants are unavailable.
+ */
+function buildInitScript(demoUser: object, demoResult: object, demoAnalysis: object, demoStudyPlan: object, jwt: string): string {
+ const userId = (demoUser as { id: number }).id
+ const resultId = (demoResult as { id: string }).id
+
+ return `(function() {
+ localStorage.setItem('auth_token', ${JSON.stringify(jwt)});
+ localStorage.setItem('user', ${JSON.stringify(JSON.stringify(demoUser))});
+ localStorage.setItem('exam_history', ${JSON.stringify(JSON.stringify([demoResult]))});
+
+ // AI analysis cache key: "ai-analysis-{userId}-{resultId}"
+ var analysisKey = 'ai-analysis-${userId}-${resultId}';
+ localStorage.setItem(analysisKey, ${JSON.stringify(JSON.stringify({ data: demoAnalysis, ts: Date.now() }))});
+
+ // Study plan cache key: "recovery-path-data-{userId}-{resultId}"
+ var planKey = 'recovery-path-data-${userId}-${resultId}';
+ localStorage.setItem(planKey, ${JSON.stringify(JSON.stringify(demoStudyPlan))});
+
+ // Suppress "resume draft?" session banner
+ sessionStorage.clear();
+
+ // Suppress guest trial flag
+ localStorage.removeItem('guest_trial_used');
+ })();`
+}
+
+// ─── Pre-test Validation ─────────────────────────────────────────────────────
+
+/**
+ * Validates that required question IDs exist in the bundled questions.json.
+ * Fails fast with a clear message if any ID is missing — prevents silent demo breakage
+ * when question IDs are renamed or reshuffled between versions.
+ */
+test.beforeAll(async () => {
+ const questionsPath = path.join(__dirname, '..', 'exam-app', 'src', 'data', 'questions.json')
+ if (!fs.existsSync(questionsPath)) {
+ console.warn('[demo] questions.json not found at expected path — skipping ID validation')
+ return
+ }
+ const questions: Array<{ id: string }> = JSON.parse(fs.readFileSync(questionsPath, 'utf-8'))
+ const ids = new Set(questions.map((q) => q.id))
+ const required = ['q_thpt24_001', 'q_thpt24_010', 'q_thpt24_020', 'q_thpt24_030', 'q_thpt24_050']
+ const missing = required.filter((id) => !ids.has(id))
+ if (missing.length > 0) {
+ throw new Error(
+ `[demo] Required question IDs not found in questions.json: ${missing.join(', ')}\n` +
+ 'The pre-fabricated exam result will break. Update demo-data-plan.md with the correct IDs.'
+ )
+ }
+ console.log('[demo] Question ID validation passed ✓')
+
+ // Ensure screenshots directory exists
+ if (!fs.existsSync(SCREENSHOTS_DIR)) {
+ fs.mkdirSync(SCREENSHOTS_DIR, { recursive: true })
+ }
+})
+
+// ─── Main Test ───────────────────────────────────────────────────────────────
+
+test.use({
+ viewport: { width: 1920, height: 1080 },
+ colorScheme: 'dark',
+})
+
+test('Zenith product demo — 8 scenes', async ({ page }) => {
+ // Capture network and console events for diagnostics
+ page.on('request', req => {
+ if (req.url().includes('localhost:8000')) {
+ console.log(`[net] REQ ${req.method()} ${req.url()}`)
+ }
+ })
+ page.on('response', res => {
+ if (res.url().includes('localhost:8000')) {
+ console.log(`[net] RES ${res.status()} ${res.url()}`)
+ }
+ })
+ page.on('requestfailed', req => {
+ if (req.url().includes('localhost:8000')) {
+ console.log(`[net] FAIL ${req.url()} — ${req.failure()?.errorText}`)
+ }
+ })
+ page.on('pageerror', err => console.log(`[pageerror] ${err.message}`))
+
+ // Seed localStorage before any page script runs
+ await page.addInitScript(
+ buildInitScript(DEMO_USER, DEMO_RESULT, DEMO_AI_ANALYSIS, DEMO_STUDY_PLAN, DEMO_JWT)
+ )
+
+ // Register all route mocks before goto()
+ await setupMocks(page)
+
+ // ── Scene 1: Landing — Hero + Feature Carousel (0:00–0:08) ───────────────
+
+ await test.step('Scene 1: Landing — hero load + feature carousel', async () => {
+ await page.goto(BASE_URL, { waitUntil: 'domcontentloaded' })
+
+ // Give React time to mount and resolve getMe()
+ await page.waitForTimeout(3000)
+
+ // Dump page state for diagnostics
+ const h1Count = await page.evaluate(() => document.querySelectorAll('h1').length)
+ const bodySnippet = await page.evaluate(() => document.body.innerText.slice(0, 150))
+ const authToken = await page.evaluate(() => localStorage.getItem('auth_token')?.slice(0, 20))
+ console.log(`[diag] h1s: ${h1Count}, auth: ${authToken}, body: ${bodySnippet.replace(/\n/g, '|')}`)
+
+ // Wait for hero headline (h1 with Fraunces font — unique on landing)
+ await page.getByRole('heading', { level: 1 }).first().waitFor({ state: 'visible' })
+
+ // Let entrance stagger animation complete (350ms stagger × ~6 words ≈ 2.1s)
+ await page.waitForTimeout(2500)
+
+ await shot(page, '01-landing-hero')
+
+ // Feature carousel auto-cycles every ~4s — wait for one full cycle
+ await page.waitForTimeout(4000)
+
+ await shot(page, '01-landing-carousel')
+ })
+
+ // ── Scene 2: Exam Select → Preview → Start (0:08–0:17) ──────────────────
+
+ await test.step('Scene 2: ExamSelect — filter, preview, start', async () => {
+ await page.goto(`${BASE_URL}/exams`)
+
+ // Verify auth — display name should appear in Navbar
+ await page.getByText('Nguyễn Minh Tuấn', { exact: false }).first().waitFor({
+ state: 'visible',
+ timeout: 8000,
+ })
+
+ // Verify no blocking onboarding modal (grade:'12' + extended_onboarding_done:true)
+ await expect(page.locator('text=Hoàn thiện hồ sơ')).toHaveCount(0)
+
+ // Wait for exam cards AND history to load (history unlocks the access chain)
+ // thpt_2024 is at chain index 11 — HistoryContext must load from /history first
+ await page.waitForTimeout(3000)
+
+ await shot(page, '02-exam-select-grid')
+
+ // Type in search to filter to THPT 2024 Quốc gia specifically
+ const searchInput = page.getByPlaceholder('Tìm đề thi...')
+ await searchInput.waitFor({ state: 'visible' })
+ await humanType(page, '[placeholder="Tìm đề thi..."]', 'THPT Quốc gia 2024')
+ await page.waitForTimeout(800)
+
+ await shot(page, '02-exam-select-filtered')
+
+ // Find the accessible "Bắt đầu" button on the THPT 2024 card
+ // After chain history loads, thpt_2024 is unlocked and shows the Bắt đầu button
+ const examTitle = page.getByText('Đề thi THPT Quốc gia 2024', { exact: false }).first()
+ await examTitle.waitFor({ state: 'visible', timeout: 8000 })
+
+ // The accessible exam card has a "Bắt đầu" outline button (not "Bắt đầu thi")
+ // Locate the button in the same section row
+ const cardRow = examTitle.locator('xpath=ancestor::div[@class and contains(@class,"flex")]').nth(1)
+ const openPreviewBtn = cardRow.getByRole('button', { name: 'Bắt đầu' }).first()
+ if (await openPreviewBtn.isVisible({ timeout: 3000 }).catch(() => false)) {
+ await openPreviewBtn.click()
+ } else {
+ // Fallback: click the title itself — some card layouts use title as the trigger
+ await examTitle.click()
+ }
+
+ // Preview modal
+ const startExamBtn = page.getByRole('button', { name: 'Bắt đầu thi' })
+ await startExamBtn.waitFor({ state: 'visible', timeout: 8000 })
+ await page.waitForTimeout(600) // let modal animation settle
+
+ await shot(page, '02-exam-preview-modal')
+
+ await startExamBtn.click()
+
+ // TestInterface mounts — wait for question counter
+ await page.getByText('Câu 1', { exact: false }).waitFor({ state: 'visible', timeout: 10000 })
+
+ await shot(page, '02-test-started')
+ })
+
+ // ── Scene 3: TestInterface — Exam + Hint (0:17–0:29) ─────────────────────
+
+ await test.step('Scene 3: TestInterface — keyboard shortcuts + progress', async () => {
+ // Timed mode exam is now active (started in Scene 2)
+
+ // Show Q1 briefly before answering
+ await page.waitForTimeout(1200)
+ await shot(page, '03-q1-unanswered')
+
+ // Answer Q1 with keyboard shortcut B (index 1)
+ // TestInterface.jsx keyboard handler maps 'b'|'B' → choiceIndex 1
+ await page.keyboard.press('b')
+ await page.waitForTimeout(800)
+ await shot(page, '03-q1-answered')
+
+ // Navigate to Q2 with arrow key, answer C
+ await page.keyboard.press('ArrowRight')
+ await page.waitForTimeout(500)
+ await page.keyboard.press('c')
+ await page.waitForTimeout(700)
+
+ // Navigate to Q3, answer A
+ await page.keyboard.press('ArrowRight')
+ await page.waitForTimeout(500)
+ await page.keyboard.press('a')
+ await page.waitForTimeout(600)
+
+ // Navigate to Q4 to show progress dots
+ await page.keyboard.press('ArrowRight')
+ await page.waitForTimeout(500)
+ await shot(page, '03-q4-progress')
+
+ // Navigate to Q5
+ await page.keyboard.press('ArrowRight')
+ await page.waitForTimeout(500)
+ await page.keyboard.press('b')
+ await page.waitForTimeout(700)
+ await shot(page, '03-q5-answered')
+
+ // Pause on the test interface to show the full UI (timer, dots, answer choices)
+ await page.waitForTimeout(1500)
+ })
+
+ // ── Scene 4: Results — Score + Confetti + AI + Schools (0:29–0:47) ────────
+
+ await test.step('Scene 4: Results — score CountUp + confetti + streaming AI + school cards', async () => {
+ // Navigate directly to the pre-seeded result
+ // HistoryContext has DEMO_RESULT (seeded by exam_history key)
+ await page.goto(`${BASE_URL}/results/result_demo_2024_001`)
+
+ // Wait for the score label (Results.jsx renders "Khá giỏi" for score ≥ 6.5)
+ await page.getByText('Khá giỏi').waitFor({ state: 'visible', timeout: 8000 })
+ await page.waitForTimeout(500)
+
+ // CountUp animation runs ~1.8s — let it complete before screenshotting
+ await page.waitForTimeout(2000)
+
+ // Confetti fires when score ≥ 7.0 — score 7.6 triggers it (~1.9s after mount)
+ // Give it an extra second to be visible in the screenshot
+ await page.waitForTimeout(1000)
+
+ await shot(page, '04-score-confetti')
+
+ // Scroll to AI analysis section
+ await scrollSlowly(page, 400, 2000)
+
+ // AI analysis is pre-cached in localStorage — renders immediately with animation
+ const analysisSection = page.getByText('Phân tích AI').first()
+ await analysisSection.waitFor({ state: 'visible', timeout: 5000 }).catch(() => null)
+
+ await shot(page, '04-ai-analysis')
+ await page.waitForTimeout(800)
+
+ // Scroll back up slightly to show the radar chart
+ await scrollSlowly(page, -200, 1000)
+ const radarSection = page.getByText('Hồ sơ năng lực').first()
+ await radarSection.waitFor({ state: 'visible', timeout: 5000 }).catch(() => null)
+
+ await shot(page, '04-radar-chart')
+ await page.waitForTimeout(600)
+
+ // Switch to school recommendations tab
+ const schoolTab = page.getByRole('button', { name: /Trường phù hợp/ })
+ if (await schoolTab.isVisible({ timeout: 3000 }).catch(() => false)) {
+ await schoolTab.click()
+ await page.waitForTimeout(800)
+
+ // School cards — grade:12 shows university suggestions
+ await page.getByText('Đại học Bách Khoa Hà Nội', { exact: false }).first()
+ .waitFor({ state: 'visible', timeout: 5000 }).catch(() => null)
+
+ await shot(page, '04-school-cards')
+ } else {
+ // School cards may be in a different section on this version
+ await scrollSlowly(page, 300, 1500)
+ await shot(page, '04-school-section')
+ }
+
+ await page.waitForTimeout(1000)
+ })
+
+ // ── Scene 5: Oracle AI — Streaming Solution (0:47–0:59) ──────────────────
+
+ await test.step('Scene 5: Oracle — type calculus problem, streaming solution', async () => {
+ await page.goto(`${BASE_URL}/oracle`)
+
+ // Wait for Oracle page heading
+ await page.locator('h1, h2').filter({ hasText: /Oracle|Toán/ }).first()
+ .waitFor({ state: 'visible', timeout: 8000 })
+ await page.waitForTimeout(800)
+
+ await shot(page, '05-oracle-ready')
+
+ // The textarea — identified by oracle-textarea class or placeholder
+ const textarea = page.locator('textarea').first()
+ await textarea.waitFor({ state: 'visible', timeout: 5000 })
+
+ await humanType(page, 'textarea', 'Tính tích phân ∫₀² (3x² - 2x + 1) dx')
+
+ await page.waitForTimeout(600)
+ await shot(page, '05-oracle-typed')
+
+ // Submit — Ctrl+Enter is the keyboard shortcut
+ await page.keyboard.press('Control+Enter')
+
+ // Oracle enters "thinking" state
+ await page.waitForTimeout(600)
+ await shot(page, '05-oracle-loading')
+
+ // Mock responds after 1.5s — wait for first step text
+ await page.getByText('Xác định dạng bài', { exact: false }).first()
+ .waitFor({ state: 'visible', timeout: 8000 })
+
+ await shot(page, '05-oracle-step1')
+ await page.waitForTimeout(800)
+
+ // Click "Tiếp theo →" if available to reveal subsequent steps
+ const nextBtn = page.getByRole('button', { name: /Tiếp theo/ })
+ if (await nextBtn.isVisible({ timeout: 2000 }).catch(() => false)) {
+ await nextBtn.click()
+ await page.waitForTimeout(600)
+ await shot(page, '05-oracle-step2')
+
+ if (await nextBtn.isVisible({ timeout: 1000 }).catch(() => false)) {
+ await nextBtn.click()
+ await page.waitForTimeout(600)
+ await shot(page, '05-oracle-step3')
+ }
+ }
+
+ // Scroll to show the final boxed answer
+ await scrollSlowly(page, 250, 1000)
+ await page.waitForTimeout(600)
+
+ await shot(page, '05-oracle-complete')
+ })
+
+ // ── Scene 6: Study Plan — Recovery Path + Checkpoint (0:59–1:09) ─────────
+
+ await test.step('Scene 6: Study Plan — focus areas + checkpoint bar', async () => {
+ await page.goto(`${BASE_URL}/study-plan/result_demo_2024_001`)
+
+ // Study plan reads from localStorage cache — no API call needed
+ await page.getByText('Kế hoạch', { exact: false }).first()
+ .waitFor({ state: 'visible', timeout: 8000 })
+ await page.waitForTimeout(600)
+
+ // Score gap / goal section
+ const goalText = page.getByText('Cần cải thiện', { exact: false }).first()
+ await goalText.waitFor({ state: 'visible', timeout: 5000 }).catch(() => null)
+
+ await shot(page, '06-study-plan-goal')
+ await page.waitForTimeout(600)
+
+ // First FocusCard — "Hình học không gian" (auto-expanded at index 0)
+ const focusCard1 = page.getByText('Hình học không gian', { exact: false }).first()
+ await focusCard1.waitFor({ state: 'visible', timeout: 5000 }).catch(() => null)
+
+ await shot(page, '06-focus-card-open')
+
+ // Scroll to checkpoint bar
+ await scrollSlowly(page, 200, 1000)
+ const checkpoint = page.getByText('Checkpoint', { exact: false }).first()
+ await checkpoint.waitFor({ state: 'visible', timeout: 5000 }).catch(() => null)
+
+ // Hold on checkpoint bar so the 2/3 fill animation is visible
+ await page.waitForTimeout(2000)
+ await shot(page, '06-checkpoint-bar')
+
+ // Click second FocusCard to demonstrate expandable mechanic
+ const focusCard2 = page.getByText('Tích phân', { exact: false }).first()
+ if (await focusCard2.isVisible({ timeout: 2000 }).catch(() => false)) {
+ await focusCard2.click()
+ await page.waitForTimeout(600)
+ await shot(page, '06-focus-card-2')
+ }
+ })
+
+ // ── Scene 7: Account — Mastery Rank + Pricing (1:09–1:20) ────────────────
+
+ await test.step('Scene 7: Account — credit gauge, mastery rank, pricing table', async () => {
+ await page.goto(`${BASE_URL}/account`)
+
+ // Wait for page to load — credit balance appears in header
+ await page.waitForTimeout(1500)
+
+ // Credits balance "50" visible
+ const creditsText = page.getByText('50', { exact: false }).first()
+ await creditsText.waitFor({ state: 'visible', timeout: 8000 }).catch(() => null)
+
+ await shot(page, '07-account-credits')
+ await page.waitForTimeout(600)
+
+ // Mastery rank badge — "Học sinh" visible
+ const rankBadge = page.getByText('Học sinh', { exact: false }).first()
+ await rankBadge.waitFor({ state: 'visible', timeout: 5000 }).catch(() => null)
+
+ await shot(page, '07-mastery-rank')
+ await page.waitForTimeout(400)
+
+ // Scroll to pricing section
+ await scrollSlowly(page, 700, 2500)
+
+ // Pricing table — look for tier names
+ const completeTier = page.getByText('Toàn diện').first()
+ await completeTier.waitFor({ state: 'visible', timeout: 5000 }).catch(() => null)
+
+ await shot(page, '07-pricing-table')
+ await page.waitForTimeout(600)
+
+ // "PHỔ BIẾN" badge on the Student plan — most visually distinctive element
+ const popularBadge = page.getByText('PHỔ BIẾN', { exact: false }).first()
+ if (await popularBadge.isVisible({ timeout: 3000 }).catch(() => false)) {
+ await shot(page, '07-popular-badge')
+ }
+
+ // Final frame — hold on pricing for the CTA
+ await page.waitForTimeout(1500)
+ await shot(page, '07-final-frame')
+ })
+})
diff --git a/demo-video/playwright.config.debug.js b/demo-video/playwright.config.debug.js
new file mode 100644
index 0000000000000000000000000000000000000000..9352a4752b3c8d8a6811f9479aed9ac2c277cdd0
--- /dev/null
+++ b/demo-video/playwright.config.debug.js
@@ -0,0 +1,12 @@
+const { defineConfig, devices } = require('@playwright/test')
+module.exports = defineConfig({
+ testDir: '.',
+ testMatch: '**/debug-demo.spec.ts',
+ timeout: 30_000,
+ retries: 0,
+ use: {
+ baseURL: 'http://localhost:5173',
+ viewport: { width: 1280, height: 800 },
+ },
+ projects: [{ name: 'chromium', use: { ...devices['Desktop Chrome'] } }],
+})
diff --git a/demo-video/playwright.config.demo.js b/demo-video/playwright.config.demo.js
new file mode 100644
index 0000000000000000000000000000000000000000..12b183af8e25bb2c210167f5908b3da30eaf3a49
--- /dev/null
+++ b/demo-video/playwright.config.demo.js
@@ -0,0 +1,76 @@
+// @ts-check
+/**
+ * playwright.config.demo.js
+ *
+ * Isolated Playwright config for the demo video recording.
+ * Uses a SEPARATE testDir ('demo-video') so this spec NEVER runs
+ * with the existing test suite (which uses testDir: './tests').
+ *
+ * Run:
+ * npx playwright test demo-video/playwright-demo.spec.ts \
+ * --config demo-video/playwright.config.demo.js \
+ * --headed --project=chromium
+ *
+ * CI (production URL):
+ * DEMO_BASE_URL=https://exam-app-ey0.pages.dev \
+ * npx playwright test demo-video/playwright-demo.spec.ts \
+ * --config demo-video/playwright.config.demo.js \
+ * --project=chromium
+ */
+const { defineConfig, devices } = require('@playwright/test')
+
+module.exports = defineConfig({
+ // Scoped to this directory only — never overlaps with ./tests/
+ // Path is relative to the config file location (demo-video/)
+ testDir: '.',
+ testMatch: '**/playwright-demo.spec.ts',
+
+ // Generous timeout for all 8 scenes including humanType + scrollSlowly delays
+ timeout: 240_000,
+ retries: 0,
+ reporter: [['list'], ['html', { open: 'never' }]],
+
+ use: {
+ baseURL: process.env.DEMO_BASE_URL ?? 'http://localhost:5173',
+ // Full HD for demo recording
+ viewport: { width: 1920, height: 1080 },
+ colorScheme: 'dark',
+ // Record video for every run — output goes to test-results/ (gitignored)
+ video: {
+ mode: 'on',
+ size: { width: 1920, height: 1080 },
+ },
+ // Capture screenshot on failure only (per-scene screenshots handled manually in spec)
+ screenshot: 'only-on-failure',
+ // Slow down mouse movement for human-paced visual timing
+ // (additional timing control is in humanType / scrollSlowly helpers)
+ actionTimeout: 30_000,
+ navigationTimeout: 30_000,
+ },
+
+ projects: [
+ {
+ name: 'chromium',
+ use: {
+ ...devices['Desktop Chrome'],
+ // Chromium-specific: launch with full GPU for CSS animations
+ launchOptions: {
+ args: [
+ '--disable-infobars',
+ '--no-default-browser-check',
+ '--no-first-run',
+ // GPU acceleration: only useful when --headed; headless ignores it
+ // and some WSL2 environments hang with --enable-gpu in headless mode
+ '--disable-background-timer-throttling',
+ '--disable-renderer-backgrounding',
+ '--disable-backgrounding-occluded-windows',
+ ],
+ },
+ },
+ },
+ ],
+
+ // No automatic dev server spin-up.
+ // For local recording: start `npm --prefix exam-app run dev` manually.
+ // For CI: app is already deployed to the production URL.
+})
diff --git a/demo-video/product-analysis.md b/demo-video/product-analysis.md
new file mode 100644
index 0000000000000000000000000000000000000000..e9edb179b276f4dfca2d8f4b2c15daf237feb41d
--- /dev/null
+++ b/demo-video/product-analysis.md
@@ -0,0 +1,114 @@
+# Zenith — Product Analysis
+
+## Executive Summary
+
+Zenith is a Vietnamese AI-native mathematics exam-preparation platform targeting Grade 9–12 students preparing for the THPT national graduation exam and competitive high-school entrance exams. The platform differentiates itself from generic quiz banks through three proprietary intelligence layers: province-calibrated AI analysis (understanding the question-distribution patterns of all 63 Vietnamese provinces), an Oracle math solver that renders step-by-step LaTeX solutions in real time, and a BKT-powered concept mastery graph that traces prerequisite gaps back to their root cause. At 29,000–59,000 VND per month (under USD $3), Zenith offers tutoring-quality coaching at textbook pricing.
+
+---
+
+## Target Audience
+
+**Primary**
+- Grade 12 students (16–18 years) in Vietnam's 63 provinces, 3–6 months before the THPT Quốc gia national graduation and university entrance exam
+- Grade 9 students (14–15 years) preparing for the competitive THPT high-school entrance exam
+- Students in major cities (Hà Nội, TP. HCM, Đà Nẵng, Hải Phòng) who need to outperform provincial averages to reach selective schools
+
+**Secondary**
+- Parents and tutors monitoring student exam readiness metrics
+- Math-gifted students preparing for international exams (AMC, SAT, GCSE, IB) alongside the Vietnamese curriculum
+- School administrators evaluating edtech for class-level deployment
+
+---
+
+## Core Problem Solved
+
+Vietnamese students studying for high-stakes math exams have no affordable tool that understands the local examination system. Generic platforms give correct answers but not province-calibrated feedback, cannot identify which prerequisite concept caused a cascade of failures, and cannot predict whether a student's current score will get them into a specific Hà Nội or TP. HCM high school. Zenith closes all three gaps simultaneously.
+
+---
+
+## Feature Inventory
+
+| Feature | Tier | Visual Impressiveness (1–5) | Demo Priority |
+|---|---|---|---|
+| 70+ real past exams (THPT, Grade 10, AMC, SAT, GCSE) | Basic | 3 | High |
+| Timed exam interface with starfield background | Basic | 4 | High |
+| Streaming AI post-exam analysis (word-by-word reveal) | Student | 5 | High |
+| Province-aware school matching (63 provinces, sigmoid fit) | Student | 5 | High |
+| Oracle AI Math Solver (LaTeX / voice / OCR) | Basic (5/day) | 5 | High |
+| Score CountUp animation + confetti on high scores | Basic | 5 | High |
+| AI-generated adaptive study plan | Student | 4 | High |
+| Concept Mastery Graph — BKT node-link visualization | Student | 5 | Medium |
+| Spaced repetition review queue (FSRS) | Student | 3 | Medium |
+| Daily challenge + streak system 🔥 | Basic | 4 | Medium |
+| Mastery rank progression (Pemula → Chuyên gia) | Basic | 4 | Medium |
+| OCR exam upload (photo → questions → instant practice) | Student | 4 | Medium |
+| AI-generated custom exam (topic + difficulty selection) | Complete | 4 | Medium |
+| AchievementCeremony spring-physics animation on milestone | Basic | 5 | Medium |
+| Adaptive practice (difficulty scales in real time) | Student | 3 | Low |
+| Province pattern tips on results page | Student | 3 | Low |
+| Score correlation (exam score → predicted THPT score) | Student | 4 | Low |
+| Radar chart — topic breakdown | Basic | 3 | Low |
+| Kalman-filter score prediction | Complete | 4 | Low |
+| ClassDashboard (teacher view) | Complete | 3 | Low |
+| Error Analysis page (pattern clustering) | Basic | 3 | Low |
+| Placement / Diagnostic test | Basic | 3 | Low |
+| Formula Drawer sidebar | Basic | 2 | Low |
+| Streak freeze mechanic | Student | 2 | Low |
+| Grade-change request workflow | All | 2 | Low |
+
+---
+
+## User Journey Map
+
+| Step | Page | What Happens |
+|---|---|---|
+| 1. First visit | `/` Landing | Hero with staggered text animation; auto-cycling 4-feature showcase (Exam / Oracle / Analysis / Concept Map); pricing section; social proof |
+| 2. Authentication | AuthModal | Google OAuth one-tap sign-in; Google token → backend `/auth/google` |
+| 3. Profile onboarding | ProfileOnboarding modal | Student selects grade (9–12) + province (63 provinces) + school type; accepts ToS; blocks any credit-deducting request until complete |
+| 4. Exam selection | `/exams` | Browse 40+ exams grouped by THPT / Grade 10; toggle Timed / Practice / Lab; filter by year/province; OCR upload option |
+| 5. Exam preview | ExamSelect modal | Preview card: exam title, question count, duration; pre-exam briefing if history exists; Start button |
+| 6. Taking the exam | `/test/:examId` | Full-screen timed interface; starfield background; question card with LaTeX; keyboard shortcuts; formula drawer; watermark overlay; anti-cheat (DevTools detection, tab-switch pause) |
+| 7. Submit | TestInterface | Auto-submit on timeout or manual; score computed client-side by scoringEngine; AI analysis triggered in background |
+| 8. Results + Score | `/results/current` | CountUp score animation; optional confetti burst (score ≥7); radar chart of topics; streaming AI analysis word-by-word; province-aware school match cards with sigmoid fit bars |
+| 9. Study Plan | `/study-plan/:resultId` | AI-generated recovery path: focus areas with error patterns, 3-5 practice tasks, checkpoint mechanic ("Đúng N câu liên tiếp") |
+| 10. Oracle | `/oracle` | LaTeX input (MathLive), voice, or OCR; step-by-step streaming solution with KaTeX rendering; Socratic hints |
+| 11. Concept Map | `/concept-map` | ReactFlow DAG of 55+ concepts colored by mastery score; gap-trace tooltip shows root weakness |
+| 12. Account / Progress | `/account`, `/progress` | Streak counter, mastery rank badge with spring animation, credit balance gauge, score trend charts, province narrative, pricing table |
+
+---
+
+## Product Strengths
+
+1. **Province intelligence is genuinely unique** — 63 provinces each have calibrated topic weights, school cutoff data, and a sigmoid probability score that tells a student exactly how likely they are to get into a named school
+2. **Streaming AI analysis creates a theatrical "thinking" moment** — word-by-word text appearance makes intelligence feel alive rather than static
+3. **BKT + FSRS + Concept Mastery tri-layer** — BKT estimates knowledge from exam performance, FSRS schedules spaced reviews, Mastery tracks stage progression (stages 0–5)
+4. **Oracle's input flexibility** — LaTeX via MathLive, voice via useVoiceInput, OCR via backend — rare at this price point
+5. **AchievementCeremony spring physics** — uses `spring({ stiffness: 320, damping: 18 })`, a physically accurate spring, giving milestone moments a tactile feel
+6. **Dark-mode-first design** with consistent amber/indigo accent system (#F2A20C / #818CF8) — matches student night-study habits
+7. **Real data** — 1,500+ questions from official national exam boards, not AI-generated content
+8. **Credit economy is transparent** — Basic tier gives enough credits to form a genuine opinion before upgrading
+
+---
+
+## Hidden / Advanced Features Worth Showcasing
+
+- **Gap-trace tooltip** on Concept Map: clicking a weak concept reveals the prerequisite chain causing it
+- **Score correlation table**: maps practice exam score → predicted real THPT scores for specific schools
+- **Province pattern tips** on results: surfaced from `province_patterns.json`, tells students which topic types their province historically emphasizes
+- **Learner archetype classifier**: silently categorizes users (e.g., "Scattered Learner", "Steady Improver") and personalizes AI analysis tone
+- **Streak recovery path**: students who miss a day can regain streak via a targeted topic mastery task
+- **ClassDashboard**: full teacher-facing view with class-level analytics (not highlighted in public demo)
+- **Kalman-filter score prediction**: Bayesian score predictor with 90% confidence intervals (Complete tier)
+
+---
+
+## Recommended Demo Focus Areas (Ranked)
+
+1. Score CountUp + confetti burst — instant emotional payoff, universal appeal
+2. Streaming AI analysis text — shows AI capability visually, no explanation needed
+3. Province-aware school matching with named schools — the most differentiated feature
+4. Oracle step-by-step solution with KaTeX LaTeX rendering — demonstrates technical depth
+5. Exam select catalog — establishes breadth of real past exams
+6. Timed exam interface with starfield — sets mood and serious-tool context
+7. AI Hint in practice mode — shows Socratic coaching without giving answers
+8. Study Plan checkpoint mechanic — closes the learning loop convincingly
diff --git a/demo-video/recording-plan.md b/demo-video/recording-plan.md
new file mode 100644
index 0000000000000000000000000000000000000000..de3ca86d14fc83731650d0f7429748dbca3abeea
--- /dev/null
+++ b/demo-video/recording-plan.md
@@ -0,0 +1,168 @@
+# Zenith — Recording Plan
+
+## Technical Specifications
+
+| Parameter | Value |
+|---|---|
+| Browser | Chromium (no browser UI chrome visible) |
+| Viewport | 1920 × 1080 |
+| Recording resolution | 1920 × 1080 |
+| Frame rate | 60 fps |
+| Aspect ratio | 16:9 |
+| Color space | sRGB |
+| System font scaling | 100% — no DPI scaling |
+| Dark mode | Yes — app is dark-mode by default (`bg: #0A0E1A`) |
+| Mouse cursor | Visible; smooth movement ≤ 400px/s; minimum 800ms between click and next action |
+| Scroll behavior | `behavior: 'smooth'`; 2.5–3s pause between scroll events |
+| Audio | None captured — narration added in post-production |
+
+---
+
+## What Must NOT Appear in Any Frame
+
+- Browser address bar or navigation controls
+- Bookmarks bar, extension icons, or popups
+- System notification toasts — disable OS notifications before recording
+- Loading spinners > 1 second — pre-warm all API calls
+- Credit balance counter prominently in early scenes (crop if needed)
+- Any error state (AIErrorBoundary must not fire)
+- Tab-switch warning overlay (stay in one window throughout)
+- DevTools panel (will trigger anti-cheat overlay in TestInterface)
+
+---
+
+## Pre-Recording Checklist
+
+1. Log in as the demo account (Grade 12, Hà Nội) and verify profile fields are set
+2. Pre-complete the exam in a separate session so the results page is deep-linkable
+3. Verify `province_patterns.json` has a "Hà Nội" entry (province tips appear in Results)
+4. Clear `sessionStorage` — prevents "resume draft?" banner from appearing
+5. Set OS idle timer to 30 minutes minimum
+6. Disable OS notifications (Windows: Focus Assist / macOS: Do Not Disturb)
+7. Set system font scaling to 100% — no High DPI scaling
+8. Disable `prefers-reduced-motion` OS setting so all Framer Motion animations play
+9. Run frontend dev server: `npm --prefix exam-app run dev`
+10. Run backend with demo API token set in `.env`
+11. Verify confetti fires at the results page with score 7.6 (open DevTools → verify canvas-confetti call)
+12. Close DevTools before recording (TestInterface detects window size delta)
+13. Use a custom CSS cursor overlay (64px) for visibility: `document.body.style.cursor = 'none'` + DOM overlay
+
+---
+
+## Scene-by-Scene Recording Notes
+
+### Scene 1: Landing Hero (0:00–0:08)
+- Open `http://localhost:5173/` — full viewport, no scroll
+- Let hero stagger animation run naturally (350ms stagger between words)
+- Feature carousel auto-cycles — show at least one full tab transition
+- Mouse rests near center; no interaction
+- Hold final state for 1s before transition
+
+### Scene 2: Exam Select (0:08–0:17)
+- Navigate to `/exams` — timed mode is default
+- Let staggered exam cards animate in (`staggerChildren: 0.07` — about 1.5s for full list)
+- Type "THPT 2024" in the search bar at human speed
+- Hover over the first result card (scale spring visible)
+- Click "Bắt đầu" → hold on preview modal 1.5s
+- Click "Bắt đầu thi" — snap cut on button press
+
+### Scene 3: TestInterface (0:17–0:29)
+- Launch exam in timed mode (90-minute timer visible)
+- Show Q1 with KaTeX-rendered LaTeX for 2s before answering
+- Press keyboard shortcut B — show answer flash
+- Press → to advance, show progress dot turn green
+- Jump to practice mode for hint demonstration (separate browser tab is fine)
+- On Q3 in practice mode: click "Gợi ý" — let streaming hint text build word by word
+- Record hint popover for at least 1.5s
+
+**Important:** Do NOT alt-tab during timed exam — triggers tab-switch pause overlay
+
+### Scene 4: Results — Score + Confetti + AI + Schools (0:29–0:47)
+- Deep-link to `/results/result_demo_2024_001`
+- Let CountUp animate from 0.0 → 7.6 (1.8s duration — do not interrupt)
+- Wait for confetti burst to begin before any scroll
+- Let confetti settle 1s before scrolling
+- Scroll to "Phân tích AI" — 2.5s smooth scroll
+- Let streaming text build (AI analysis cache is pre-loaded — appears immediately but with animation)
+- Scroll to RadarChart — hold 1.5s on fully rendered chart
+- Click "Trường phù hợp" tab — hold on school cards for 2s
+- **Zoom hint (post-production):** apply 1.0x → 1.06x → 1.0x zoom punch at the moment CountUp reaches 7.6
+
+### Scene 5: Oracle AI (0:47–0:59)
+- Navigate to `/oracle`
+- Wait for wiki status dot to show green (mocked response: `{phase: "ready"}`)
+- Click textarea — type calculus problem at ~60ms/char human pace
+- Press Ctrl+Enter to submit
+- Let "thinking" state animate for 1.5s before first step appears
+- Step through solution using "Tiếp theo →" button if visible (reveals steps one at a time)
+- Scroll to show final boxed answer
+- Hold on complete solution for 1s
+
+### Scene 6: Study Plan (0:59–1:09)
+- Navigate to `/study-plan/result_demo_2024_001`
+- Wait for "Kế hoạch phục hồi" heading to appear
+- First FocusCard (Hình học) is auto-expanded — hold for 2s
+- Scroll to show checkpoint bar — hold 2s to show the 2/3 fill animation
+- Click second FocusCard (Tích phân) — let first collapse and second expand
+
+### Scene 7: Account + Pricing (1:09–1:20)
+- Navigate to `/account`
+- Wait for credit gauge SVG arc animation (fills from 0 → 50)
+- Verify mastery rank badge "Học sinh Tiến bộ" in indigo is visible
+- Scroll to pricing section — hold 3s on pricing table
+- Ensure all 3 tier columns are fully visible (do not crop)
+- End on "PHỔ BIẾN" badge and gold CTA button visible
+
+---
+
+## Transition Plan
+
+| Between Scenes | Transition | Duration |
+|---|---|---|
+| Scene 1 → 2 | Cross-dissolve | 400ms |
+| Scene 2 → 3 | Snap cut (button press moment) | — |
+| Scene 3 → 4 | Cross-dissolve | 300ms |
+| Scene 4 → 5 | **Fade to black** | 500ms out · 500ms hold · 500ms in |
+| Scene 5 → 6 | Cross-dissolve | 300ms |
+| Scene 6 → 7 | Cross-dissolve | 300ms |
+| Scene 7 → End card | **Fade to black** | 500ms |
+
+---
+
+## Recording Tool Recommendations
+
+### Primary: Playwright Built-In Video Recording
+
+```javascript
+// playwright.config.demo.js
+use: {
+ video: { mode: 'on', size: { width: 1920, height: 1080 } },
+ viewport: { width: 1920, height: 1080 },
+}
+```
+
+Playwright gives deterministic mouse movement via `page.mouse.move(x, y, { steps: 20 })` and eliminates OS notification risk. Run:
+
+```bash
+npx playwright test demo-video/playwright-demo.spec.ts \
+ --config demo-video/playwright.config.demo.js \
+ --headed --project=chromium
+```
+
+Video output: `test-results/` (gitignored)
+
+### Fallback: OBS Studio
+
+- Scene: Browser Source (Chromium at 1920×1080)
+- Encoder: x264 at CRF 18, or NVENC Quality 18
+- Output format: MP4 (H.264)
+- Audio: disabled at capture time (narration added in post)
+- Virtual Camera: off
+
+---
+
+## Zoom and Cursor Recommendations
+
+- **Zoom:** No browser zoom during recording. Apply post-production zoom in CapCut (scene-specific). The one mandatory zoom punch is during score CountUp in Scene 4.
+- **Cursor:** Use a custom 64px white circle cursor overlay (Framer Motion `motion.div` fixed-position overlay synced to `mousemove` event). Alternatively, enable large cursor in OS accessibility settings before recording.
+- **Cursor speed:** Playwright `mouse.move` with `steps: 20` at 60fps gives ~33ms/step — equivalent to ~400px/s human speed. Set `page.mouse.move` delay via helper `humanMove()` if using OBS.
diff --git a/demo-video/review.md b/demo-video/review.md
new file mode 100644
index 0000000000000000000000000000000000000000..ba1fdc26a714b1fd0cfb154555ab903dd41ea1d0
--- /dev/null
+++ b/demo-video/review.md
@@ -0,0 +1,132 @@
+# Zenith — Demo Quality Review
+
+## Risk Assessment
+
+| Risk | Likelihood | Impact | Mitigation |
+|------|-----------|--------|------------|
+| AI streaming fails during recording (network timeout, cold start) | High | High | Pre-warm API 60s before recording; use localStorage cache for analysis (always available); mock `/analyze/stream` with Playwright route if recording via automation |
+| Confetti does not fire (score threshold not met, or canvas-confetti blocked in headless Chromium) | Medium | High | Verify score is exactly 7.6 (≥7.0 threshold); always run in headed Chromium, not headless; test confetti fires before recording session |
+| ReactFlow Concept Map renders empty (API returns empty mastery) | Medium | Medium | Scene 7 is Study Plan (not Concept Map) — this risk is avoided by design; Study Plan reads from localStorage cache which is always seeded |
+| KaTeX renders raw LaTeX strings instead of math (normalizeMath edge case) | Low-Medium | High | Test the exact Oracle problem string (`∫₀² (3x² - 2x + 1) dx`) in Oracle before recording; confirm KaTeX renders `\boxed{6}` correctly |
+| Province-aware school cards empty (Hà Nội not in schools.json or score_correlation.json) | Low | High | Verify `schools.json` has Hà Nội entries with math cutoffs matching score 7.6; AI analysis mock response provides school data anyway as backup |
+| Streaming text animation too fast/slow for recording frame rate | Medium | Medium | Record at 60fps; confirm `word-fade` CSS animation respects the frame rate; disable `prefers-reduced-motion` OS setting |
+| TestInterface tab-switch warning overlay fires during recording | Medium | Medium | Record in a single browser window; never alt-tab during Scene 3; Playwright spec stays in one page context |
+| Question IDs `q_thpt24_*` don't exist in questions.json (renamed or reshuffled) | Low | High | `beforeAll` validation block in Playwright spec checks 5 representative IDs; fails fast with clear error message if any ID is missing |
+| `extended_onboarding_done: false` causes ExtendedOnboarding modal to block UI | Low | High | Demo user has `extended_onboarding_done: true` explicitly set; `GET /users/me` mock returns this field |
+| Video exceeds 90s due to unexpected loading states | Medium | Medium | All AI responses are mocked or cached; study plan is pre-loaded in localStorage; if any scene runs long, Scene 3 and Scene 7 are the cut candidates (see §Cut Priority below) |
+| Non-Vietnamese viewer cannot read Vietnamese UI text | High | Medium | English narration provides all context; critical school name "Đại học Bách Khoa Hà Nội" can have a 2s English caption overlay in post: "Top Engineering University in Hanoi" |
+| Credit system Tia display visible early (signals friction) | Medium | Low | Navbar credits badge is on `/exams` and after — start from landing page before auth and navigate quickly past ExamSelect |
+
+---
+
+## Weak Scenes
+
+### Scene 3 (TestInterface) — Weakest Scene
+
+A viewer who has never used Zenith gains little from watching someone press keyboard shortcuts. The starfield background is visually engaging but the question content (Vietnamese multiple-choice) is illegible at typical video playback scale. The hint demonstration requires switching to practice mode, which creates a jarring mode-switch mid-scene.
+
+**Mitigation options:**
+1. Reduce Scene 3 from 12s to 6s — show only the question card + timer for 3s, then the streaming hint for 3s
+2. Eliminate the timed mode portion entirely — start directly in practice mode (simpler, fewer mode-switches)
+3. Keep as-is but add an English caption: "1,500+ real exam questions · KaTeX math rendering"
+
+**Recommendation:** Option 1 (6s trimmed version) if video runs over 90s.
+
+### Scene 2 (Exam Select) — Moderate Weakness
+
+The value proposition ("40+ exams from 63 provinces") appears as metadata text at small font size. At playback speed, viewers see a list of Vietnamese titles they cannot read. The stagger animation is elegant but doesn't communicate breadth effectively in 9 seconds.
+
+**Mitigation:** The text overlay enhancement ("40+ đề thi thật · 63 tỉnh thành") in `ai-enhancement.md` addresses this directly — make sure that overlay is added in post.
+
+### Scene 7 (Account + Pricing) — Risk of Anti-Climax
+
+After the peak of Scene 6 (Oracle streaming solution), the Account page with tier pricing can feel like an appendix. The mastery rank badge is visually satisfying but the pricing table is static and text-heavy.
+
+**Mitigation:** Lead with the mastery rank animation (the spring-physics pop is the strongest visual here) and only show pricing for the last 4s. Do not scroll through individual plan features — keep the 3-column overview visible the whole time.
+
+---
+
+## Repetitive Interactions to Avoid
+
+- **Scrolling appears in both Scene 4 and Scene 6** — in Scene 4 (Results), scroll to AI analysis + school cards; in Scene 6 (Study Plan), scroll to checkpoint. To avoid looking repetitive: enter Scene 6 already scrolled to the checkpoint bar (no visible scroll in that scene).
+- **Text appears word-by-word in Scene 4 (AI analysis) and Scene 5 (Oracle streaming)** — intentional repetition that reinforces the "AI thinking" concept, but avoid scenes back-to-back without the fade-to-black separator (already planned between 4→5).
+- **Two preview modal interactions** would appear if Scene 2 shows the exam preview modal AND a later scene shows another modal — currently only one modal is shown (Scene 2), so no issue.
+
+---
+
+## Confusing Flows for Non-Vietnamese Viewers
+
+- **Province selection context:** The school matching section in Scene 4 names "Đại học Bách Khoa Hà Nội" — international viewers will not understand the significance. Add a 2s English caption overlay: "Top Engineering University in Hanoi — selective, score-matched"
+- **Credit system ("Tia"):** If the credit balance or "Không đủ Tia" warning appears, it is entirely opaque. Hide or crop the credit counter in Scenes 1–6; show it only in Scene 7 (Account) where context is provided by the pricing table.
+- **Difficulty labels ("Dễ / Vừa / Khó"):** Color-coded (green/amber/red) so partially self-evident. No action needed if color coding is clearly visible at 1080p.
+- **Exam naming conventions:** "THPT Quốc gia" is an unfamiliar term. The overlay enhancement "40+ đề thi thật" (real past exams) and the narration "seventy real past exams" provide sufficient context without naming the acronym.
+- **Mastery rank names:** "Học sinh Tiến bộ" in Scene 7 is opaque. The color (indigo) and the rank badge design signal "achievement level" — no action needed unless the badge is a primary focus.
+
+---
+
+## Alternative Scene Orderings
+
+### Alternative A: "Oracle First" — Lead with the Solver
+
+**Order:** Landing → Oracle → Exam Select → Timed Exam → Score Reveal + AI → Study Plan → Account + CTA
+
+**Pros:**
+- Oracle is universally legible — solving a math problem step-by-step requires no cultural context
+- Opens with the deepest technical demonstration, immediately differentiating Zenith from quiz apps
+- Strong hook for international / investor audiences where AI capability is the primary interest
+
+**Cons:**
+- Breaks the natural student session loop (you would not go to Oracle before taking an exam)
+- The viewer has not yet invested emotionally in a score, so the AI Analysis and Study Plan lack narrative payoff
+- Moves the confetti reveal to Scene 4 (instead of 3), losing the "peak moment at midpoint" pacing advantage
+- Adds a 500ms+ fade between Oracle and Exam Select (different interaction modes)
+
+**Best for:** International investor pitch, conference stage demo
+
+### Alternative B: "Province-First" — Lead with the Differentiator
+
+**Order:** Landing → Profile Onboarding (province selection visible) → Exam Select → Timed Exam → Score Reveal → School Cards ONLY → Oracle → Account + CTA (drop Study Plan scene)
+
+**Pros:**
+- Province selection in Scene 2 sets up the "Hà Nội student" frame explicitly, making school cards in Scene 5 the payoff of a setup rather than a surprise
+- Tighter — dropping Study Plan keeps the video under 75s comfortably
+- Province-first is the clearest competitive differentiator message for Vietnamese-primary audience
+
+**Cons:**
+- Showing profile onboarding (province dropdown UI) risks a weak second scene — standard select list is not visually impressive
+- Removes Study Plan, which is important for demonstrating the product's coaching completeness
+- If onboarding modal has any UI issues (text overflow, province dropdown lag), it is front-and-center
+
+**Best for:** Vietnamese student/parent primary audience demo
+
+---
+
+## Cut Priority (if video exceeds 90s)
+
+Cut in this order:
+
+1. **Scene 3 (TestInterface) — reduce from 12s to 6s:** Show only the question card for 2s and streaming hint for 4s. Skip the Q1→Q3 keyboard navigation.
+2. **Scene 7 (Account) — reduce from 11s to 6s:** Enter already scrolled to pricing table. Skip mastery badge animation (let the narration cover it). Show pricing 3 columns for 4s, hold CTA for 2s.
+3. **Scene 2 (Exam Select) — reduce from 9s to 5s:** Skip the preview modal. Show staggered card grid for 3s, then snap cut on clicking "Bắt đầu thi."
+4. **End card — reduce from 4s to 3s.**
+
+After all four cuts, estimated runtime: 8 + 5 + 6 + 18 + 12 + 10 + 6 + 3 = **68 seconds.** Well under target.
+
+---
+
+## Overall Confidence Score: 7.5 / 10
+
+**What earns a high score:**
+- The product has genuinely exceptional visual moments: streaming AI analysis, confetti + CountUp animation, school cards with province-matched names, Oracle KaTeX rendering, checkpoint bar mechanics
+- The dark-mode design is polished and consistent — no visual "embarrassments"
+- The emotional arc (tension → relief → awe → clarity → motivation) is structurally sound
+- The Playwright automation isolates the demo from the existing test suite (different `testDir` config)
+- The demo data is fully pre-seeded — no live API risk for the 3 most critical scenes (Results, Study Plan, AI Analysis)
+
+**What limits the score to 7.5:**
+- Scene 3 (TestInterface) is the weakest visual moment and requires a mode-switch to show hints
+- The Vietnamese-only UI creates comprehension gaps for non-Vietnamese viewers that require post-production caption work
+- Province-aware school matching — the single most differentiated feature — depends on Hà Nội being correctly populated in `schools.json` and `province_patterns.json`; this must be verified before any recording session
+- The credit/Tia system appearing in the Navbar is a minor but persistent risk of showing "friction" before value is established
+
+**Path to 9/10:** Add English caption overlays for school names (Scene 4), verify all province data files, and reduce Scene 3 to 6s. With those three changes, the demo would be exceptional.
diff --git a/demo-video/storyboard.md b/demo-video/storyboard.md
new file mode 100644
index 0000000000000000000000000000000000000000..805c98c8ba9a36e2ef1d89a35fbcaa2101b41de2
--- /dev/null
+++ b/demo-video/storyboard.md
@@ -0,0 +1,198 @@
+# Zenith — Launch Video Storyboard
+
+**Target runtime:** 84 seconds · 8 scenes + end card
+**Format:** 1920×1080 · 16:9 · 60fps
+**Persona:** Nguyễn Minh Tuấn — Grade 12 · Hà Nội · Student tier
+
+---
+
+## Scene 1 — Hero Arrival
+**Duration:** 8 seconds
+**Goal:** Brand recognition + emotional hook. Establish dark, premium, Vietnamese-student-first aesthetic.
+
+**Actions:**
+- Browser opens the app. Page loads from blank — no browser chrome visible.
+- Hero headline animates in word by word: "Học để hiểu," (gold #F2A20C) then "không học để quên." (white)
+- Ambient glow orbs pulse slowly in the background (blue/gold radial gradients).
+- Zenith logo mark (✦) is visible above the headline.
+- Feature showcase carousel begins auto-cycling below the fold.
+
+**Visual Focus:** Full-width hero headline, centered. No scrolling. Let the gold second line land and hold for 2 seconds.
+
+**Transition:** Slow cross-dissolve (400ms) → Scene 2.
+
+**Narration Hook:**
+> "Every Vietnamese student has a target score. Zenith is the AI that shows you exactly how to reach it."
+
+---
+
+## Scene 2 — Exam Select: Choosing a Real Exam
+**Duration:** 9 seconds
+**Goal:** Show depth of content (40+ exams) and ease of discovery; establish province-aware filtering.
+
+**Actions:**
+- Navigate to `/exams`. Timed mode is active (default).
+- Two category sections visible: "Thi THPT Quốc gia" (gold accent) and "Thi vào lớp 10" (blue accent). Cards stagger-animate in.
+- Type "THPT 2024" in the search bar — cards filter to 2 results.
+- Hover over "Đề thi THPT Quốc gia 2024 — Môn Toán" card (scale: 1.015 spring hover).
+- Click "Bắt đầu" — preview modal slides up showing: title, 50 questions, 90 minutes, timed badge.
+- Hold on preview modal for 1.5s so viewer reads the details.
+- Click "Bắt đầu thi" inside the modal.
+
+**Visual Focus:** First, wide shot of staggered card grid (3s). Then zoom to preview modal showing duration badge and gold CTA button (3s). Then snap cut on button press.
+
+**Transition:** Snap cut → Scene 3 as TestInterface mounts.
+
+**Narration Hook:**
+> "Choose from over seventy real past exams — filtered to your province and grade level. One click to start."
+
+---
+
+## Scene 3 — TestInterface: Inside the Exam
+**Duration:** 12 seconds
+**Goal:** Demonstrate the immersive, distraction-free exam experience: timer, progress dots, LaTeX rendering, AI hint.
+
+**Actions:**
+1. TestInterface loads. Starfield canvas background visible. Gold accent bar across the top.
+2. Nav bar shows: "Câu 1 / 50" left, exam title center (truncated), timer right (counting: 89:42...).
+3. Progress bar (2px, gold gradient) fills 2% beneath the navbar.
+4. QuestionCard displays a LaTeX-rendered calculus question (KaTeX rendering visible in real time).
+5. Topic badge "Tích phân" (gold pill) and difficulty badge "Trung bình" (blue pill) are visible.
+6. Press keyboard shortcut **B** — choice B highlights with an emerald flash (300ms transition).
+7. Progress dot for question 1 turns green in the dot row at bottom.
+8. Press **→** arrow key — advances to question 2. New question slides in.
+9. Press **→** again to question 3 (the calculus/hint question). Pause 1s.
+10. In practice mode scene (4b): click "Gợi ý" button — streaming hint text appears word-by-word in a popover below the answer choices.
+
+**Visual Focus:** Steps 1–4: full question card (80% of viewport). Steps 8–10: zoom into streaming hint popover showing ~15 words appearing live (50% of viewport).
+
+**Transition:** Cross-dissolve (300ms) → Scene 4.
+
+**Narration Hook:**
+> "Inside the exam: full-screen focus, a live countdown, and keyboard shortcuts for speed. Stuck? Request an AI hint that guides your thinking — without giving away the answer."
+
+---
+
+## Scene 4 — Submit + Results: Score, Confetti, AI Analysis
+**Duration:** 18 seconds
+**Goal:** The emotional peak. Show the full results flow: score CountUp → confetti burst → streaming AI insights → radar chart → school recommendation cards.
+
+**Actions:**
+1. Results page loads at `/results/result_demo_2024_001`. Score SVG ring animates from 0° to completion.
+2. CountUp number ticks from 0.0 to **7.6** over 1.8s (gold #F2A20C, 40px).
+3. "Khá giỏi" label fades in beside the score with time taken and answered count stats.
+4. At ring completion: **confetti burst** fires (150 particles — green, blue, amber, purple, ~3s fade).
+5. Scroll down slowly to "Phân tích AI" section. Streaming text appears word-by-word:
+ - "Điểm mạnh rõ rệt ở Đại số (89%) và Hàm số (88%)."
+ - "Cần tập trung cải thiện Hình học (60%) và Tích phân (57%)."
+6. Scroll to "Hồ sơ năng lực" — **RadarChart** materializes: 7 topic axes, red for Hình học, emerald for Đại số.
+7. Click "Trường phù hợp" tab — **school cards** fade in one by one:
+ - "Đại học Bách Khoa Hà Nội" — score range 7.0–8.5
+ - "Đại học Kinh tế Quốc dân" — score range 6.5–8.0
+ - Animated fit bars slide left-to-right.
+
+**Visual Focus:** Steps 1–4: centered score ring, then confetti fills frame. Steps 5–6: split view of AI text streaming below score. Step 7: school cards spanning full width.
+
+**Transition:** Fade to black (500ms out · 500ms hold · 500ms in) → Scene 5. This breath signals the gear-shift from analysis to active problem-solving.
+
+**Narration Hook:**
+> "Submit — and your score appears instantly. If you did well, confetti. Then the AI streams your personal analysis: your strongest topics, your weakest, and — most importantly — the schools in Hà Nội you're on track to enter."
+
+---
+
+## Scene 5 — Oracle AI: Step-by-Step Math Solver
+**Duration:** 12 seconds
+**Goal:** Show the premium power feature — real LaTeX math solved live, step by step.
+
+**Actions:**
+1. Navigate to `/oracle`. Page loads: dark background, Oracle bubble in idle state (slow gold/violet glow pulse), wiki status dot glows green.
+2. Click the textarea. Type (human-paced): "Tính tích phân ∫₀² (3x² - 2x + 1) dx"
+3. Symbol palette visible in toolbar below the input.
+4. Press **Ctrl+Enter** to submit. Oracle bubble transitions to "thinking" state (faster pulse).
+5. Solution streams in step by step (KaTeX renders mid-stream):
+ - "**Bước 1:** Xác định dạng bài: tích phân xác định tuyến tính..."
+ - "**Bước 2:** Tìm nguyên hàm: $F(x) = x^3 - x^2 + x + C$"
+ - "**Bước 3:** Áp dụng Newton-Leibniz: $F(2) - F(0) = 6$"
+ - "**Kết luận:** $\displaystyle\int_0^2 (3x^2 - 2x + 1)\,dx = \boxed{6}$"
+6. Oracle bubble transitions to "celebrating" state (0.7s spring scale pop).
+
+**Visual Focus:** The streaming solution text with KaTeX formulas visually rendering mid-stream. Crop to 70% viewport width centered on the Oracle panel. The pulsing Oracle bubble glow is visible in the corner.
+
+**Transition:** Smooth cut → Scene 6.
+
+**Narration Hook:**
+> "Oracle AI solves any math problem step by step — not just the answer, but the reasoning. Each step renders in real time, so you understand the why, not just the what."
+
+---
+
+## Scene 6 — Study Plan: Recovery Path with Checkpoint
+**Duration:** 10 seconds
+**Goal:** Close the learning loop — show that Zenith doesn't abandon you after a result.
+
+**Actions:**
+1. Navigate to `/study-plan/result_demo_2024_001`. Page loads showing recovery plan.
+2. "Mục tiêu" section with score gap: "Cần cải thiện 0.4 điểm để vào Đại học Khoa học Tự nhiên."
+3. First FocusCard auto-expanded (index 0): topic "Hình học không gian."
+4. Error pattern alert (yellow): "Sai ở tính thể tích của khối chóp và khối trụ."
+5. Three practice tasks listed (bulleted).
+6. **Checkpoint bar** visible: "Đúng 3 câu liên tiếp" — 2/3 progress shown, gold-to-emerald gradient fill, animating.
+7. Click second FocusCard to expand: "Tích phân" — collapses first, second expands with tasks.
+
+**Visual Focus:** The CheckpointBar fill animation is the hero visual. Hold 2s on the bar so the mechanic is legible. The progress fill (0 → 2/3) should be visible for at least 1.5s.
+
+**Transition:** Cross-dissolve → Scene 7.
+
+**Narration Hook:**
+> "After every exam, Zenith builds a focused recovery path. Each topic has concrete tasks — and a checkpoint: answer three correct in a row to clear it and move on."
+
+---
+
+## Scene 7 — Account: Mastery Rank + Pricing
+**Duration:** 11 seconds
+**Goal:** Commercial close — show progress gamification (rank badge, credit gauge) and the 3-tier pricing structure.
+
+**Actions:**
+1. Navigate to `/account`. Profile visible: "Nguyễn Minh Tuấn", Grade 12 badge, Province "Hà Nội."
+2. **SVG credit gauge** animates (arc fill, gold color): 50 credits shown on the gauge.
+3. **Mastery rank badge**: "Học sinh Tiến bộ" in indigo (#818CF8) — spring pop animation (0.7s, stiffness 320).
+4. Scroll down to pricing table: 3 tier cards animate in:
+ - "Cơ bản — Miễn phí" (gray border)
+ - "Học sinh — 29,000đ/tháng" with **"PHỔ BIẾN"** badge in gold (highlighted card, raised shadow)
+ - "Toàn diện — 59,000đ/tháng" (indigo border)
+5. Hold 3s on pricing table — wide enough to show all 3 cards clearly.
+6. "Bắt đầu miễn phí" CTA button on "Cơ bản" card is visible in gold.
+
+**Visual Focus:** First 4s on profile + rank badge. Last 4s on pricing table ensuring "PHỔ BIẾN" badge is readable and all 3 tier columns are fully visible.
+
+**Transition:** Fade to black (500ms) → End card.
+
+**Narration Hook:**
+> "Watch your mastery rank rise with every session. Start free — upgrade when you're ready for unlimited AI, personalized study plans, and score prediction."
+
+---
+
+## End Card
+**Duration:** 4 seconds (not counted in main scene total)
+
+**Content:**
+- Background: `#0A0E1A` deep dark with a single slow amber glow pulse
+- Center: Zenith logo mark ✦ in `#F2A20C` at 48px
+- Headline: "Luyện thi thông minh hơn." (Fraunces Italic, 28px, white)
+- Subline: "AI phân tích · 63 tỉnh thành · Từ 29,000đ / tháng" (Jakarta Sans, 14px, `#94A3B8`)
+- URL: "zenith.vn" centered at bottom
+
+---
+
+## Scene Duration Summary
+
+| # | Scene | Duration |
+|---|-------|----------|
+| 1 | Hero Arrival | 8s |
+| 2 | Exam Select → Preview → Start | 9s |
+| 3 | TestInterface — Exam + Hint | 12s |
+| 4 | Results — Score + Confetti + AI Analysis + Schools | 18s |
+| 5 | Oracle AI — Streaming Solution | 12s |
+| 6 | Study Plan — Recovery Path + Checkpoint | 10s |
+| 7 | Account — Mastery Rank + Pricing | 11s |
+| — | End Card | 4s |
+| **Total** | | **84s** |
diff --git a/deploy-hf.sh b/deploy-hf.sh
new file mode 100644
index 0000000000000000000000000000000000000000..dc2436cf93e2d53f2c681127b81a9f7bd05d856b
--- /dev/null
+++ b/deploy-hf.sh
@@ -0,0 +1,33 @@
+#!/usr/bin/env bash
+# Deploy latest master to Hugging Face Spaces
+# Usage: ./deploy-hf.sh
+
+set -e
+
+SPACE_REMOTE="space"
+SPACE_URL="https://huggingface.co/spaces/MinhTai/ai-agent-app"
+HEALTH_URL="https://minhtai-ai-agent-app.hf.space/health"
+
+echo "==> Checking remote..."
+if ! git remote get-url "$SPACE_REMOTE" &>/dev/null; then
+ echo "Adding '$SPACE_REMOTE' remote..."
+ git remote add "$SPACE_REMOTE" "$SPACE_URL"
+fi
+
+CURRENT_BRANCH=$(git branch --show-current)
+
+echo "==> Switching to hf-deploy branch..."
+git checkout hf-deploy
+
+echo "==> Merging master..."
+git merge master --no-edit
+
+echo "==> Pushing to HF Space..."
+git push --force "$SPACE_REMOTE" hf-deploy:main
+
+echo "==> Switching back to $CURRENT_BRANCH..."
+git checkout "$CURRENT_BRANCH"
+
+echo ""
+echo "Deployed. Build logs: $SPACE_URL"
+echo "Health check (wait ~30s for rebuild): curl $HEALTH_URL"
diff --git a/design-system/.design-sync/NOTES.md b/design-system/.design-sync/NOTES.md
new file mode 100644
index 0000000000000000000000000000000000000000..9b1b1905ac4c77763f219713b6bf9edea3910c1e
--- /dev/null
+++ b/design-system/.design-sync/NOTES.md
@@ -0,0 +1,29 @@
+# Sync Notes
+
+## First sync — June 2026
+
+- Shape: `package` (no Storybook; 28 named exports from 15 component files)
+- `vite-plugin-dts` required for component discovery — generates `.d.ts` in `dist/src/`
+- `types` field in `package.json` → `./dist/src/index.d.ts` (not `./dist/index.d.ts`)
+- Google Fonts CDN import triggers `[FONT_REMOTE]` info — non-blocking, families served at runtime
+
+## Browser-event gated components
+
+`InstallPrompt` and `OfflineBanner` return `null` until browser events fire
+(`beforeinstallprompt` / `navigator.onLine === false`). Their previews use
+inline-styles reproductions of the visible-state JSX — not the real component.
+If the component UI changes, update `.design-sync/previews/InstallPrompt.tsx`
+and `.design-sync/previews/OfflineBanner.tsx` manually.
+
+## Skeleton exports
+
+`Skeleton.jsx` exports 12+ named variants. Each is registered as its own
+component in ds-bundle (SkeletonBlock is the primitive; the rest are page-level
+skeletons with zero props).
+
+## Re-sync
+
+Run from `design-system/`:
+```
+node .ds-sync/resync.mjs
+```
diff --git a/design-system/.design-sync/config.json b/design-system/.design-sync/config.json
new file mode 100644
index 0000000000000000000000000000000000000000..e08de31344c3c68f9d801ad1509e8aa32bc19812
--- /dev/null
+++ b/design-system/.design-sync/config.json
@@ -0,0 +1,7 @@
+{
+ "pkg": "@zenith/ui",
+ "globalName": "ZenithUI",
+ "projectId": "0ec9eeac-7e63-41aa-a395-7ec36d59b131",
+ "shape": "package",
+ "buildCmd": "npm run build"
+}
diff --git a/design-system/.design-sync/previews/AIErrorBoundary.tsx b/design-system/.design-sync/previews/AIErrorBoundary.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..8c1f27f018d1423e8298b5c66ac8d8b8be41562a
--- /dev/null
+++ b/design-system/.design-sync/previews/AIErrorBoundary.tsx
@@ -0,0 +1,11 @@
+import { AIErrorBoundary } from '@zenith/ui'
+
+export const Idle = () => (
+
+
+
+ AI analysis content renders here when there is no error.
+
+ (không nhìn thấy nội dung bên trên — đang ở trạng thái ẩn)
+
+
+)
diff --git a/design-system/.design-sync/previews/CreditsTooltip.tsx b/design-system/.design-sync/previews/CreditsTooltip.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..8963e936cb25c4fa9d2c38f4516985e4801e7aec
--- /dev/null
+++ b/design-system/.design-sync/previews/CreditsTooltip.tsx
@@ -0,0 +1,64 @@
+import { CreditsTooltip } from '@zenith/ui'
+
+/**
+ * CreditsTooltip is shown once per userId (persisted to localStorage).
+ * To force-show in previews we use a unique userId that hasn't been seen.
+ * The tooltip is position:absolute, so we need a relative container.
+ *
+ * SufficientCredits — user has a healthy credit balance (25 lượt).
+ * Note: the component manages its own visibility via localStorage.
+ * A fresh userId guarantees it renders on first mount.
+ */
+export const SufficientCredits = () => (
+
+
+
+ ⚡ 25 lượt
+
+ {}}
+ />
+
+
+)
+
+/**
+ * LowCredits — user is running low (3 lượt remaining).
+ * Same component, different creditsBalance value shown in the heading.
+ */
+export const LowCredits = () => (
+
+)
diff --git a/design-system/.design-sync/previews/FormulaDrawer.tsx b/design-system/.design-sync/previews/FormulaDrawer.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..b2b704d6b3ee91f9a2abd88cd593ff96457878f5
--- /dev/null
+++ b/design-system/.design-sync/previews/FormulaDrawer.tsx
@@ -0,0 +1,68 @@
+import { FormulaDrawer } from '@zenith/ui'
+
+/**
+ * FormulaDrawer manages its own open/closed state internally — no props required.
+ * It renders as a fixed bottom-sheet overlay in production, so we contain it with
+ * position:relative + overflow:hidden to keep the preview self-contained.
+ *
+ * Open — the toggle button is always visible; click it to open the drawer.
+ * Since the drawer is self-controlled, we show the toggle button in context.
+ */
+export const ToggleButton = () => (
+
+
+ Nhấn nút bên dưới để mở bảng công thức:
+
+
+
+)
+
+/**
+ * InContext — simulates FormulaDrawer sitting alongside an exam question,
+ * showing how the toggle button fits within a toolbar row.
+ */
+export const InContext = () => (
+
+)
diff --git a/design-system/.design-sync/previews/MarkdownProse.tsx b/design-system/.design-sync/previews/MarkdownProse.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..fbc0209db8a0ef912c59dc57e8f46f9b702dfd18
--- /dev/null
+++ b/design-system/.design-sync/previews/MarkdownProse.tsx
@@ -0,0 +1,67 @@
+import { MarkdownProse } from '@zenith/ui'
+
+/**
+ * BasicMarkdown — short paragraph with bold, italic, inline code, and a list.
+ */
+export const BasicMarkdown = () => (
+
+
+ {`## Phân tích kết quả học tập
+
+Bạn đã hoàn thành **10/12 câu** trong đề thi thử Toán THPT Quốc Gia.
+Đây là kết quả *khá tốt* so với mức trung bình của lớp.
+
+Những chủ đề cần ôn tập thêm:
+
+- Hàm số và đồ thị
+- Phương trình lượng giác
+- Tích phân bất định
+
+Hãy dùng \`/study-plan\` để tạo kế hoạch ôn tập cá nhân hoá.`}
+
+
+)
+
+/**
+ * WithMath — note: MarkdownProse uses remark-gfm only (no remark-math),
+ * so LaTeX expressions render as plain text. This story demonstrates how
+ * a math formula looks in the prose context (unstyled, literal string).
+ * Use MathBlock/MathText for rendered LaTeX.
+ */
+export const WithMath = () => (
+
+
+ {`### Nghiệm của phương trình bậc hai
+
+Cho phương trình $ax^2 + bx + c = 0$ (với $a \\neq 0$),
+nghiệm được tính theo công thức:
+
+$$x = \\frac{-b \\pm \\sqrt{b^2-4ac}}{2a}$$
+
+**Ví dụ:** Giải $2x^2 - 7x + 3 = 0$.
+
+Với $a=2$, $b=-7$, $c=3$, ta có $\\Delta = 49 - 24 = 25 > 0$,
+nên phương trình có hai nghiệm phân biệt.`}
+
+
+
+ {`### Bảng điểm theo chủ đề
+
+| Chủ đề | Số câu | Đúng | Tỉ lệ |
+|--------|--------|------|-------|
+| Hàm số | 4 | 3 | 75% |
+| Tích phân | 3 | 2 | 67% |
+| Lượng giác | 3 | 3 | 100% |
+| Tổ hợp – Xác suất | 2 | 1 | 50% |
+
+> **Nhận xét:** Bạn làm tốt nhất ở phần Lượng giác và cần cải thiện Tổ hợp – Xác suất.`}
+
+
+)
diff --git a/design-system/.design-sync/previews/MathBlock.tsx b/design-system/.design-sync/previews/MathBlock.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..deb90f0bd4e854d8000d36ba450eda9a9b55a681
--- /dev/null
+++ b/design-system/.design-sync/previews/MathBlock.tsx
@@ -0,0 +1,35 @@
+import { MathBlock } from '@zenith/ui'
+
+/**
+ * Integral — displays a definite integral with solution.
+ * MathBlock uses remark-math + rehype-katex so $…$ and $$…$$ are rendered by KaTeX.
+ */
+export const Integral = () => (
+
+
+ {'Tính tích phân sau:\n\n$$\\int_0^1 x^2 \\, dx = \\left[\\frac{x^3}{3}\\right]_0^1 = \\frac{1}{3}$$\n\nVậy diện tích hình phẳng giới hạn bởi $y = x^2$, trục $Ox$ và $x = 1$ bằng $\\dfrac{1}{3}$.'}
+
+
+)
+
+/**
+ * QuadraticFormula — the quadratic formula with discriminant discussion.
+ */
+export const QuadraticFormula = () => (
+
+
+ {'**Nghiệm phương trình bậc hai** $ax^2 + bx + c = 0$:\n\n$$x = \\frac{-b \\pm \\sqrt{b^2 - 4ac}}{2a}$$\n\nPhân tích biệt thức $\\Delta = b^2 - 4ac$:\n\n- $\\Delta > 0$: hai nghiệm phân biệt $x_1, x_2$\n- $\\Delta = 0$: nghiệm kép $x = -\\dfrac{b}{2a}$\n- $\\Delta < 0$: vô nghiệm thực'}
+
+
+)
+
+/**
+ * Matrix — a 2×2 matrix determinant formula with example.
+ */
+export const Matrix = () => (
+
+
+ {'**Định thức ma trận** $2 \\times 2$:\n\n$$\\det(A) = \\begin{vmatrix} a & b \\\\ c & d \\end{vmatrix} = ad - bc$$\n\n**Ví dụ:** Tính định thức của $A = \\begin{pmatrix} 3 & 1 \\\\ 2 & 4 \\end{pmatrix}$\n\n$$\\det(A) = 3 \\cdot 4 - 1 \\cdot 2 = 12 - 2 = 10$$'}
+
+
+)
diff --git a/design-system/.design-sync/previews/SymbolPalette.tsx b/design-system/.design-sync/previews/SymbolPalette.tsx
new file mode 100644
index 0000000000000000000000000000000000000000..0e23c414d9f5972ce0d6b8197bfa54f4426e0267
--- /dev/null
+++ b/design-system/.design-sync/previews/SymbolPalette.tsx
@@ -0,0 +1,72 @@
+import { SymbolPalette } from '@zenith/ui'
+
+/**
+ * AllGroups — full palette mounted below a mock answer input.
+ * onInsert logs the chosen symbol to the console so the interaction
+ * can be observed in the design-sync preview iframe.
+ * Note: SymbolPalette initialises open state based on window.innerWidth >= 640,
+ * so it will be open by default in a desktop preview viewport.
+ */
+export const AllGroups = () => (
+
+
+
+
+ console.log('Inserted:', s)} />
+
+)
+
+/**
+ * StandaloneMinimal — palette without a surrounding input, useful for verifying
+ * the component's own chrome (tab bar + symbol grid) in isolation.
+ * onInsert is a no-op so the story remains pure.
+ */
+export const StandaloneMinimal = () => (
+
+
+ Bảng ký hiệu toán học — chọn để chèn vào bài làm
+