From 2cbbfe00c3cb903bf4556f558b03bcf83757239c Mon Sep 17 00:00:00 2001
From: Daniel <daniel@danvics.com>
Date: Sat, 4 Apr 2026 22:48:26 +0200
Subject: [PATCH] Tag filtering, multi-category, bug fixes, image validation,
 docs
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Fix tag filtering (sa_text import shadowing caused UnboundLocalError)
- Add TagBrowser component with per-section search
- Multi-category selection (OR within categories, AND with tags)
- AI image validation: has_figure field in extraction prompt
- Skip known branding images by MD5 hash + dimension filters
- Fix quiz timer auto-submit (wrong useEffect dependency)
- Fix QuizResponse schema: section_id nullable
- Fix Question.quiz_id → source_quiz_id attribute name
- Fix SQL injection in quizzes.py vector search
- Add PDF processing progress steps via Redis
- Add delete user from admin panel
- Admin page: no spinner flash on data refresh
- Upload progress: axios 1.x e.progress, remove manual Content-Type
- Duplicate model error: 409 with clear message
- Backend startup: retry DDL migration on lock timeout
- Replace all silent except:pass with warning logs
- Comprehensive multi-page documentation (docs/)

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 README.md                                 |  379 ++++++--
 backend/app/database.py                   |    2 +-
 backend/app/main.py                       |   52 +-
 backend/app/models/ai_model_config.py     |    7 +-
 backend/app/routers/admin.py              |   44 +-
 backend/app/routers/attempts.py           |   26 +-
 backend/app/routers/auth.py               |   52 +-
 backend/app/routers/contact.py            |    8 +-
 backend/app/routers/documents.py          |   16 +
 backend/app/routers/questions.py          |   62 +-
 backend/app/routers/quizzes.py            |   10 +-
 backend/app/routers/tags.py               |   67 ++
 backend/app/schemas/auth.py               |    2 +
 backend/app/schemas/quiz.py               |    4 +-
 backend/app/services/ai_service.py        |   12 +-
 backend/app/services/extraction_modes.py  |   89 ++
 backend/app/services/pdf_service.py       |   23 +-
 backend/app/services/vector_service.py    |   15 +-
 backend/app/tasks/pdf_tasks.py            |   29 +
 backend/app/tasks/quiz_tasks.py           |  187 +++-
 docker-compose.yml                        |    2 +
 docs/README.md                            |   19 +
 docs/api-reference.md                     | 1051 +++++++++++++++++++++
 docs/architecture.md                      |  533 +++++++++++
 docs/deployment.md                        |  446 +++++++++
 docs/frontend.md                          |  341 +++++++
 docs/services.md                          |  394 ++++++++
 frontend/Dockerfile                       |    8 +-
 frontend/docker-entrypoint.sh             |   10 +
 frontend/index.html                       |    9 +
 frontend/nginx.conf                       |   10 +
 frontend/package-lock.json                |  464 ++++++++-
 frontend/package.json                     |    4 +-
 frontend/public/config.js                 |    2 +
 frontend/public/icon.svg                  |    4 +
 frontend/public/manifest.json             |   19 +
 frontend/public/sw.js                     |   12 +
 frontend/src/components/Navbar.jsx        |   16 +-
 frontend/src/components/TeachChat.jsx     |   21 +-
 frontend/src/context/AuthContext.jsx      |    4 +-
 frontend/src/pages/AdminPage.jsx          |   43 +-
 frontend/src/pages/DashboardPage.jsx      |   57 +-
 frontend/src/pages/DocumentDetailPage.jsx |   32 +-
 frontend/src/pages/LandingPage.jsx        |  254 ++++-
 frontend/src/pages/LoginPage.jsx          |   34 +-
 frontend/src/pages/QuestionBankPage.jsx   |  293 ++++--
 frontend/src/pages/QuizPage.jsx           |   43 +-
 frontend/src/pages/QuizzesPage.jsx        |  130 ++-
 frontend/src/pages/RegisterPage.jsx       |   34 +-
 frontend/src/pages/ResultsPage.jsx        |   37 +-
 frontend/src/pages/UploadPage.jsx         |   61 +-
 51 files changed, 5088 insertions(+), 385 deletions(-)
 create mode 100644 backend/app/routers/tags.py
 create mode 100644 docs/README.md
 create mode 100644 docs/api-reference.md
 create mode 100644 docs/architecture.md
 create mode 100644 docs/deployment.md
 create mode 100644 docs/frontend.md
 create mode 100644 docs/services.md
 create mode 100644 frontend/docker-entrypoint.sh
 create mode 100644 frontend/public/config.js
 create mode 100644 frontend/public/icon.svg
 create mode 100644 frontend/public/manifest.json
 create mode 100644 frontend/public/sw.js

diff --git a/README.md b/README.md
index 3c27db3..ee3e121 100644
--- a/README.md
+++ b/README.md
@@ -1,32 +1,47 @@
-# PedQuiz
+# PedsHub
 
-AI-powered pediatric knowledge quiz platform. Upload PDF study materials, automatically extract MCQ questions with AI, and take quizzes with text-to-speech support and semantic search.
+AI-powered pediatric learning platform. Upload PDF study materials, automatically extract or generate MCQ questions with AI, study with an AI tutor, and track your progress. Installable as a PWA.
 
 ## Features
 
 - **PDF → Quiz**: Upload PREP PDFs, AI extracts questions, answers, and explanations
-- **Quiz Modes**: Study (instant feedback) and Exam (timed, scored)
+- **Generative Mode**: AI reads plain text/textbook chapters and creates MCQ questions from scratch
+- **Quiz Modes**: Study (instant feedback with AI tutor) and Exam (timed, scored)
+- **AI Tutor (TeachChat)**: Ask follow-up questions mid-study — AI knows the current question, correct answer, and related content. Renders markdown tables, code, and follow-up suggestion chips.
+- **Tag Classification**: AI classifies questions with subjects, diseases, and keywords — filter your question bank by any combination of tags
+- **Multi-Category Filtering**: Filter questions by question category, tags, or quiz source — combine multiple filters for precise study sets
 - **Text-to-Speech**: OpenAI TTS, AWS Polly, ElevenLabs, Google Cloud — voice selection per quiz
 - **Semantic Search**: pgvector embeddings — finds questions by meaning, not just keywords
-- **Embedding Model**: Configurable via Admin UI or env — supports any LiteLLM proxy model or AWS Bedrock
-- **Job Cancellation**: Cancel running extractions from the web UI
+- **Question Bank**: All questions searchable, filterable by category and tags, with inline study mode
+- **Image Validation**: AI `has_figure` gating — only links extracted images to questions the AI flagged as having a figure, preventing mismatched images
+- **Performance Tracking**: Per-quiz attempt history with line charts, score trends, delete individual attempts
+- **PDF Processing Progress**: Step-by-step progress reporting for PDF uploads and quiz extraction — see each stage in real time
+- **Concurrent Quiz Protection**: Redis session locks prevent the same quiz from being resumed on multiple devices simultaneously
+- **Landing Page**: Integrated with the app — Sign In / Register open as modal overlays, shared Navbar
+- **PWA**: Installable on mobile/desktop (no caching — avoids stale JS issues)
+- **Bot Protection**: Cloudflare Turnstile on registration and contact forms
 - **Email Verification**: Required before first login; password reset via email
-- **Role system**: Admin / Moderator / User
+- **Role System**: Admin / Moderator / User with optional rate-limit exemption (unthrottle)
+- **Admin User Management**: Delete users, change roles, toggle unthrottle — all from the admin dashboard
 - **Nextcloud Integration**: Browse and import PDFs from your Nextcloud
-- **Themes**: Default and Warm Brown
+- **Themes**: Default (blue) and Warm/Literary (brown, serif fonts)
+- **Multi-worker**: 4 uvicorn workers with Redis singleton lock for scheduler
 
 ## Stack
 
 | Layer | Tech |
 |---|---|
-| Frontend | React + React Router, plain CSS, Nginx |
+| Frontend | React 18 + React Router 6, plain CSS, Nginx, PWA (network-only service worker) |
 | Backend | FastAPI, SQLAlchemy, PostgreSQL 16 + pgvector |
-| AI/LLM | LiteLLM proxy (Claude, Gemini, GPT, and more) |
-| Embeddings | Configurable — any LiteLLM proxy model or direct AWS Bedrock (1024-dim, set via Admin UI or env) |
+| AI/LLM | LiteLLM proxy (Claude, Gemini, GPT, Bedrock, and more) |
+| Embeddings | Configurable — any LiteLLM proxy model or direct AWS Bedrock (1024-dim) |
 | Document vectors | ChromaDB |
 | TTS | OpenAI (direct), AWS Polly, ElevenLabs, Google Cloud TTS |
-| Queue | Celery + Redis |
+| Queue | Celery + Redis (4 fork workers) |
 | Email | SMTP (smtp2go or any SMTP server) |
+| Bot protection | Cloudflare Turnstile (runtime-configurable, no rebuild needed) |
+
+For detailed architecture documentation, see [docs/architecture.md](docs/architecture.md).
 
 ## Quick Start
 
@@ -44,7 +59,7 @@ Frontend available at `http://localhost:8081`. The first registered user becomes
 
 ## Environment Variables
 
-Create `backend/.env`:
+### Backend (`backend/.env`)
 
 ```env
 # Database
@@ -61,7 +76,7 @@ LITELLM_API_BASE=https://your-litellm-proxy.com   # leave empty for direct OpenA
 
 # Embedding model — use the model name exactly as your proxy lists it (no prefix needed)
 # Can also be changed live via Admin → More settings without redeploying
-LITELLM_EMBEDDING_MODEL=ge-gemini-embedding-001
+LITELLM_EMBEDDING_MODEL=gemini-embedding-001
 
 # OpenAI (for TTS — calls api.openai.com directly, not the proxy)
 OPENAI_API_KEY=<openai-api-key>
@@ -86,6 +101,12 @@ MAIL_PASSWORD=<smtp2go-password>
 MAIL_FROM=noreply@yourdomain.com
 MAIL_STARTTLS=true
 
+# Bot protection — Cloudflare Turnstile (backend secret)
+TURNSTILE_SECRET_KEY=<cloudflare-turnstile-secret-key>
+
+# Contact form admin notifications
+ADMIN_EMAIL=admin@yourdomain.com
+
 # App
 APP_URL=https://your-domain.com
 UPLOAD_DIR=/app/uploads
@@ -93,9 +114,163 @@ MAX_UPLOAD_SIZE=524288000
 CHROMA_PERSIST_DIR=/app/chroma_data
 ```
 
+### Frontend (`frontend/.env`)
+
+```env
+# Bot protection — Cloudflare Turnstile (public site key)
+TURNSTILE_SITE_KEY=<cloudflare-turnstile-site-key>
+```
+
+The frontend env file is **not** baked into the Docker image at build time. Instead, `docker-entrypoint.sh` generates a `/config.js` file from the env vars when the container **starts**. This means:
+
+- Change keys by editing `frontend/.env` and restarting the container (no rebuild)
+- Switch captcha providers by updating the entrypoint script and the widget component
+- Remove bot protection by clearing the key (empty = disabled)
+
+## Cloudflare Turnstile (Bot Protection)
+
+### How it works
+
+Turnstile protects the **registration** and **contact** forms from bot submissions. It does NOT require Cloudflare DNS/proxy — it works standalone on any domain.
+
+**Flow:**
+
+```
+1. Page loads → Turnstile JS loads from challenges.cloudflare.com
+2. Widget renders (invisible or interactive depending on risk score)
+3. User completes challenge → widget calls onVerify(token)
+4. Frontend stores token in state → Sign Up button becomes enabled
+5. User submits form → token sent as `turnstile_token` in POST body
+6. Backend receives token → POSTs to Cloudflare's siteverify API:
+     POST https://challenges.cloudflare.com/turnstile/v0/siteverify
+     Body: { secret: TURNSTILE_SECRET_KEY, response: turnstile_token }
+7. Cloudflare returns { success: true/false }
+8. If false → 400 "Bot verification failed"
+9. If true → registration proceeds normally
+```
+
+**Where Turnstile is active:**
+- Register form (modal overlay on landing page)
+- Register form (standalone `/register` page)
+- Contact form (landing page)
+
+**Where it is NOT active (by design):**
+- Login — protected by IP-based rate limiting (10 attempts / 15 min) instead
+
+### Setup
+
+1. Go to https://dash.cloudflare.com → Turnstile → Add widget
+2. Add your domain(s), choose "Managed" widget type
+3. Copy the Site Key and Secret Key
+
+```bash
+# frontend/.env
+TURNSTILE_SITE_KEY=0x4AAAAAAA...
+
+# backend/.env
+TURNSTILE_SECRET_KEY=0x4AAAAAAA...
+
+# Restart (no rebuild needed)
+docker compose restart frontend backend
+```
+
+### Testing
+
+Cloudflare provides test keys for development:
+
+| Purpose | Site Key | Secret Key |
+|---|---|---|
+| Always passes | `1x00000000000000000000AA` | `1x0000000000000000000000000000000AA` |
+| Always blocks | `2x00000000000000000000AB` | `2x0000000000000000000000000000000AB` |
+
+### Disabling
+
+Set both keys to empty strings (or remove them), restart. The widget won't render and the backend skips verification.
+
+### Runtime Config Architecture
+
+```
+docker-compose.yml
+  └─ frontend service: env_file: ./frontend/.env
+
+Container startup (docker-entrypoint.sh):
+  └─ Reads $TURNSTILE_SITE_KEY from environment
+  └─ Writes /usr/share/nginx/html/config.js:
+       window.__APP_CONFIG__ = { TURNSTILE_SITE_KEY: "0x4AAA..." };
+
+Browser loads index.html:
+  └─ <script src="/config.js"> → sets window.__APP_CONFIG__
+  └─ <script type="module" src="/src/main.jsx"> → React app starts
+  └─ Components read: window.__APP_CONFIG__?.TURNSTILE_SITE_KEY
+```
+
+This avoids Vite's `import.meta.env.VITE_*` which bakes values into the JS bundle at build time.
+
+## Extraction Modes
+
+| Mode | Use Case | How It Works |
+|---|---|---|
+| **Standard** | PREP PDFs with inline answers | Finds "Correct Answer: X" / "Preferred Response: X" after each question |
+| **Two-Step** | PREP 2013-style (separate answer key) | Phase 1: extract questions, Phase 2: extract answer key, Phase 3: match |
+| **Questions Only** | No answers available | Extracts Q + options, sets answer to "PENDING" for manual fill |
+| **AI + Regex** | Non-standard answer formats | AI analyses format, generates regex, applies it for fast extraction |
+| **AI Decides** | Unknown format | AI samples start + end of document, picks the best strategy |
+| **Generate** | Textbook chapters, study notes | AI reads the text and **creates** MCQ questions (correct answer from text, distractors from AI knowledge) |
+
+The extraction model is selected per-job from the dropdown on the document detail page. Models are configured in Admin → AI Models with task `extraction`.
+
+## Tag Classification
+
+PedsHub can automatically classify questions with structured tags using AI. Tags are organized into three types:
+
+| Tag Type | Examples | Purpose |
+|---|---|---|
+| **Subject** | Cardiology, Infectious Disease, Neonatology | Medical specialty / rotation |
+| **Disease** | Kawasaki Disease, Pneumonia, Type 1 Diabetes | Specific condition mentioned |
+| **Keyword** | fever workup, antibiotic resistance, fluid management | Clinical concept / topic |
+
+**How it works:**
+
+1. Admin triggers classification from the admin dashboard (or via the `/api/admin/classify` endpoint)
+2. A Celery background task (`classify_questions`) finds all untagged questions
+3. Questions are sent to the AI in batches of 10 — the AI returns subjects, diseases, and keywords for each
+4. Tags are stored in `question_tags` with case-insensitive deduplication and linked via `question_tag_links`
+5. Users can filter the question bank by any combination of tags in the Question Bank page
+
+The classification model is configured in Admin → AI Models with task `keyword`.
+
+## AI Tutor (TeachChat)
+
+The study-mode AI tutor opens as a slide-in drawer. It:
+
+- Knows the current question, correct answer, and explanation
+- Pulls related questions from the question bank via semantic similarity (pgvector)
+- Supports model selection (dropdown when multiple teach models configured)
+- Renders full markdown including GFM tables (via `remark-gfm` + `rehype-raw`)
+- Generates follow-up suggestion chips after each response
+- Uses `litellm.acompletion()` (async) so it doesn't block other requests
+
+Models for teach are configured in Admin → AI Models with task `teach`.
+
+## Rate Limiting
+
+| Endpoint | Limit | Scope |
+|---|---|---|
+| Login | 10 attempts / 15 min | Per IP (Redis) |
+| TeachChat | 30 calls / 10 min | Per user (Redis) |
+| TTS | 20 calls / 5 min | Per user (Redis) |
+
+Admins, moderators, and users marked as "unthrottled" are exempt. Rate limiting degrades gracefully if Redis is unavailable (allows requests through).
+
+## PWA (Progressive Web App)
+
+The app is installable on mobile and desktop. The service worker is **network-only** (no caching) — it exists solely to satisfy the PWA installability requirement. This avoids stale cached JS causing blank screens or module-not-found errors after deployments.
+
+Files: `frontend/public/manifest.json`, `frontend/public/sw.js`, `frontend/public/icon.svg`
+
 ## Rebuild & Restart
 
-Frontend and backend are built into Docker images — code changes require a `build` before they take effect. `.env` changes only need a `restart`.
+Frontend and backend are built into Docker images — code changes require a `build` before they take effect. Environment variable changes only need a `restart`.
 
 ```bash
 # Rebuild and restart everything
@@ -104,10 +279,9 @@ docker compose build && docker compose up -d
 # Rebuild a single service
 docker compose build backend && docker compose up -d backend
 docker compose build frontend && docker compose up -d frontend
-docker compose build celery  && docker compose up -d celery
 
-# Restart without rebuilding (for .env changes only)
-docker compose restart backend
+# Restart without rebuilding (for .env changes, including Turnstile keys)
+docker compose restart frontend backend
 
 # View logs
 docker compose logs backend --tail=50
@@ -120,35 +294,25 @@ Accessible at `/admin` for admin users. Three tabs:
 
 ### AI Models
 - **Search models** from your LiteLLM proxy — click any result to pre-fill the add form
-- Configure models per task: `extraction` (PDF → questions), `tts` (voices), `general`
+- Configure models per task: `extraction` (PDF → questions), `teach` (AI tutor), `keyword` (tag classification), `tts` (voices)
+- Same model can be added to multiple tasks (e.g. `bedrock-claude-haiku-4.5` for both extraction and teach)
 - Set a default model per task; enable/disable individual models
 - Extraction models from the proxy don't need an `openai/` prefix — the backend adds it automatically
 
 ### Users
 - Create users directly (email auto-verified)
 - Change user roles: admin / moderator / user
+- Unthrottle users (exempt from rate limits)
+- **Delete users** — removes the user and all associated data (documents, quizzes, attempts)
 
 ### More Settings
 - **Public Registration** — enable/disable new user sign-ups
-- **AWS Polly** — global enable/disable toggle for all Polly voices (individual voices still manageable in AI Models tab)
+- **AWS Polly** — global enable/disable toggle for all Polly voices
+- **Classify Questions** — trigger AI tag classification for all untagged questions (runs as background task)
 - **Embedding Model** — set the model used for semantic search vectors:
   - Type a model name and click **Save**, or click **Search LiteLLM** to browse proxy models
   - Click **Test** to verify the model works and returns the correct dimensions (must be 1024)
   - Setting is stored in Redis and takes effect immediately — no restart needed
-  - Priority: Admin UI setting → `LITELLM_EMBEDDING_MODEL` env → direct AWS Bedrock fallback
-  - Model name should match exactly what your proxy lists (no prefix required)
-
-#### Switching embedding models
-
-To switch to a different embedding model:
-1. Go to Admin → More → click **Search LiteLLM**, find your model, click **Select**
-2. Click **Test** to confirm it returns 1024 dimensions
-3. Run `docker compose exec backend python manage.py reembed` to regenerate all existing question embeddings with the new model
-
-To revert to AWS Bedrock (when available):
-- Set model to the Bedrock model ID as configured on your proxy, or
-- Clear the Redis key to fall back to env: `docker compose exec redis redis-cli DEL settings:embedding_model`
-- Then set `LITELLM_EMBEDDING_MODEL=` to empty in `.env` to use direct Bedrock
 
 ## CLI Management
 
@@ -158,115 +322,116 @@ docker compose exec backend python manage.py reset-password admin@example.com Ne
 docker compose exec backend python manage.py list-users
 
 # ── Quiz extraction ───────────────────────────────────────────────────────────
-# 1. Find document and section IDs
 docker compose exec backend python manage.py list-sections
-
-# 2a. Extract in background (monitor via navbar jobs badge)
 docker compose exec backend python manage.py extract 6 --bg
 docker compose exec backend python manage.py extract 6 --bg --title "PREP 2012 Full" --mode timed
 
-# 2b. Extract inline (blocking, live output in terminal)
-docker compose exec backend python manage.py extract 6
-
-# 3. Check job status
-docker compose exec backend python manage.py jobs
-docker compose exec backend python manage.py jobs --user admin@example.com
-
-# CLI extract options:
-#   --title "My Quiz"       Custom quiz title
-#   --mode  timed|learning  Quiz mode (default: timed)
-#   --user  email           Owner of the quiz (default: first admin)
-#   --bg                    Run in background via Celery
-
 # ── Embeddings ───────────────────────────────────────────────────────────────
-# Regenerate all question embeddings (run after switching embedding model)
 docker compose exec backend python manage.py reembed
 ```
 
-### How extraction works
-
-1. **Upload PDF** via the web UI — text is extracted and stored
-2. **Create a section** on the document page (define page range)
-3. **Extract quiz** from the web UI or CLI:
-   - Large sections are split into 50-page chunks automatically
-   - Progress shown live in the web UI; running jobs can be cancelled from the Extraction Jobs page
-   - Supports multiple extraction modes: standard, two-step (separate answer key), questions-only, regex, AI-decides
-4. Questions land in the **Question Bank** and can be assigned to categories
-
 ## Architecture
 
 ```
 Browser
   │
   ▼
-Nginx (frontend + API proxy)
-  ├─► React SPA (static)
-  └─► FastAPI backend
-        ├─ PostgreSQL (pgvector)   ← users, quizzes, questions + 1024-dim embeddings
-        ├─ ChromaDB                ← document page chunks for semantic search
-        ├─ Redis                   ← Celery queue + runtime settings (embedding model, toggles)
-        ├─ Celery workers          ← background PDF processing, emails
-        ├─ LiteLLM proxy           ← Claude/Gemini/GPT for extraction; embedding models
-        ├─ AWS Bedrock             ← Polly TTS; embedding fallback
-        └─ OpenAI                  ← TTS (direct, not via proxy)
+Caddy/Nginx (HTTPS termination)
+  │
+  ▼
+Nginx (frontend container — serves React SPA + proxies /api to backend)
+  ├─► React SPA (static files + runtime config.js)
+  └─► FastAPI backend (4 uvicorn workers)
+        ├─ PostgreSQL 16 + pgvector   ← users, quizzes, questions + 1024-dim embeddings
+        ├─ ChromaDB                   ← document page chunks for RAG context
+        ├─ Redis                      ← Celery queue, rate limits, settings, quiz progress, singleton lock
+        ├─ Celery workers (x4)        ← background PDF processing, quiz extraction, tag classification, emails
+        ├─ LiteLLM proxy              ← Claude/Gemini/GPT for extraction + teach + classification; embedding models
+        ├─ AWS Bedrock                ← Polly TTS; embedding fallback
+        ├─ OpenAI                     ← TTS (direct, not via proxy)
+        └─ Cloudflare Turnstile       ← bot verification for registration + contact
 ```
 
-### Embeddings
+For deep architecture documentation (database schema, request flow, background tasks, vector search, auth, and more), see [docs/architecture.md](docs/architecture.md).
 
-Question embeddings are 1024-dimensional vectors stored in PostgreSQL via pgvector with an HNSW index for fast cosine similarity search. The embedding model is called **directly via the LiteLLM proxy HTTP API** (not the Python library) so the `dimensions=1024` parameter is forwarded correctly.
+### Multi-Worker Setup
 
-Priority chain:
-1. Model set in Admin UI (stored in Redis `settings:embedding_model`)
-2. `LITELLM_EMBEDDING_MODEL` env var
-3. Direct AWS Bedrock (`amazon.titan-embed-text-v2:0`) — automatic fallback if AWS credentials are present
+The backend runs 4 uvicorn workers. A Redis SETNX lock (`startup:singleton_lock`, TTL 300s) ensures only one worker starts the APScheduler and backfill thread. Stale `idle in transaction` DB connections are killed at startup to prevent DDL migration hangs.
 
-### Search
+### Landing Page
 
-Quiz search uses hybrid retrieval:
-1. **Semantic** — embed the query, cosine similarity via pgvector HNSW index
-2. **Keyword** — PostgreSQL `ILIKE` on question text and options
-3. Results merged — semantic matches ranked first by score, keyword-only matches appended
+The landing page at `/home` uses the shared `Navbar` component. When not logged in:
+- Navbar shows Sign In / Register buttons
+- Clicking either opens a **modal overlay** (no page navigation) with tabbed Sign In / Register forms
+- Hero CTA buttons also open the modal
+- Standalone `/login` and `/register` pages still exist for direct links, email verification redirects, and bookmarks
 
-### TTS Providers
+### Security
 
-| Provider | Model ID format | Key needed |
-|---|---|---|
-| OpenAI | `tts-1:alloy`, `tts-1:nova`, `tts-1:echo`, `tts-1:shimmer`, `tts-1:onyx`, `tts-1:fable`, `tts-1-hd:*` | `OPENAI_API_KEY` (calls api.openai.com directly) |
-| AWS Polly | `polly/Joanna`, `polly/Matthew`, `polly/Amy`, `polly/Brian` | `AWS_ACCESS_KEY_ID` + `polly:SynthesizeSpeech` IAM permission |
-| ElevenLabs | `elevenlabs/<voice-id>` | `ELEVENLABS_API_KEY` |
-| Google Cloud | `google/<voice-name>` e.g. `google/en-US-Wavenet-D` | `GOOGLE_TTS_API_KEY` |
-
-AWS Polly can be globally disabled/enabled via Admin → More settings without removing the individual voice configs.
+- **SQL injection**: pgvector queries use parameterized bind variables (`CAST(:vec AS vector)`)
+- **API key exposure**: LiteLLM/TTS model search uses POST body, not URL query params
+- **Rate limiting**: Redis INCR + TTL keys on login, teach, and TTS endpoints
+- **Bot protection**: Cloudflare Turnstile on registration and contact forms
+- **CSP headers**: Configured in nginx.conf for fonts, Turnstile, and self
 
 ## Project Structure
 
 ```
 ├── backend/
 │   ├── app/
-│   │   ├── main.py            # App startup, seeding, pgvector setup
+│   │   ├── main.py            # App startup, DB migrations, Redis singleton lock
 │   │   ├── config.py          # Settings (pydantic-settings, reads .env)
 │   │   ├── models/            # SQLAlchemy ORM models
-│   │   ├── routers/           # FastAPI route handlers
+│   │   ├── routers/
+│   │   │   ├── auth.py        # Login, register (with Turnstile), verify email, password reset
+│   │   │   ├── quizzes.py     # Quiz CRUD, async extraction jobs
+│   │   │   ├── attempts.py    # Quiz attempts, progress save/resume, history, stats
+│   │   │   ├── teach.py       # AI tutor chat (async, with follow-up suggestions)
+│   │   │   ├── admin.py       # Model management, user roles, settings, classification trigger
+│   │   │   ├── tags.py        # Tag listing and filtering endpoints
+│   │   │   ├── contact.py     # Contact form (with Turnstile)
+│   │   │   └── ...
 │   │   ├── services/
-│   │   │   ├── ai_service.py            # LLM extraction + TTS routing
+│   │   │   ├── ai_service.py            # LLM calls + _proxy_model() routing
+│   │   │   ├── extraction_modes.py      # 6 extraction strategies (standard → generate)
 │   │   │   ├── embedding_service.py     # pgvector embeddings (httpx → proxy)
 │   │   │   ├── vector_service.py        # ChromaDB document page chunks
-│   │   │   ├── quiz_service.py          # Quiz creation pipeline
 │   │   │   └── email_service.py         # Email templates + sending
 │   │   ├── tasks/
-│   │   │   ├── quiz_tasks.py            # Celery: PDF extraction with cancellation support
-│   │   │   └── pdf_tasks.py             # Celery: PDF text extraction
+│   │   │   ├── quiz_tasks.py            # Celery: quiz extraction, tag classification, re-embed
+│   │   │   └── pdf_tasks.py             # Celery: PDF text extraction + vectorization
 │   │   └── utils/
-│   ├── manage.py              # CLI: reset-password, list-users, reembed
-│   ├── requirements.txt
+│   │       └── auth.py                  # JWT, password hashing, rate limiting
+│   ├── manage.py              # CLI: reset-password, list-users, reembed, extract
 │   └── Dockerfile
 ├── frontend/
 │   ├── src/
-│   │   ├── pages/             # All page components
-│   │   ├── components/        # Navbar (with jobs badge), shared UI
-│   │   └── context/           # AuthContext, ThemeContext
-│   ├── nginx.conf
+│   │   ├── pages/
+│   │   │   ├── LandingPage.jsx          # Landing + contact form + auth modal + Turnstile
+│   │   │   ├── DashboardPage.jsx        # Stats, performance chart, attempt history with delete
+│   │   │   ├── QuizzesPage.jsx          # Quiz grid, search, past attempts with delete
+│   │   │   ├── QuizPage.jsx             # Quiz taking (study/exam), TTS, progress save
+│   │   │   ├── ResultsPage.jsx          # Score card, answer review, delete attempt
+│   │   │   ├── DocumentDetailPage.jsx   # Sections, extraction mode picker, model selector
+│   │   │   ├── RegisterPage.jsx         # Standalone register (with Turnstile)
+│   │   │   └── ...
+│   │   ├── components/
+│   │   │   ├── Navbar.jsx               # Shared navbar (auth-aware, optional modal callbacks)
+│   │   │   ├── TeachChat.jsx            # AI tutor drawer (markdown, tables, suggestions)
+│   │   │   └── ...
+│   │   └── context/                     # AuthContext, ThemeContext
+│   ├── public/
+│   │   ├── manifest.json                # PWA manifest
+│   │   ├── sw.js                        # Service worker (network-only, no cache)
+│   │   ├── icon.svg                     # App icon
+│   │   └── config.js                    # Dev fallback (overwritten by entrypoint in prod)
+│   ├── nginx.conf                       # API proxy + CSP headers
+│   ├── docker-entrypoint.sh             # Generates /config.js from env vars at runtime
 │   └── Dockerfile
+├── docs/
+│   └── architecture.md                  # Deep architecture documentation
+├── frontend/.env                        # Frontend runtime config (Turnstile site key)
+├── backend/.env                         # Backend config (all secrets)
 └── docker-compose.yml
 ```
 
@@ -277,3 +442,13 @@ AWS Polly can be globally disabled/enabled via Admin → More settings without r
 - Uploads live in the `uploads_data` volume — includes extracted question images
 - Redis data persists in `redis_data` volume — holds runtime settings and job state
 - Set `APP_URL` to your public domain so email verification and password reset links work
+- Frontend env vars (like Turnstile site key) are injected at container startup, not build time — change and restart, no rebuild needed
+
+## TTS Providers
+
+| Provider | Model ID format | Key needed |
+|---|---|---|
+| OpenAI | `tts-1:alloy`, `tts-1:nova`, `tts-1-hd:*` | `OPENAI_API_KEY` |
+| AWS Polly | `polly/Joanna`, `polly/Matthew`, `polly/Amy` | `AWS_ACCESS_KEY_ID` + IAM `polly:SynthesizeSpeech` |
+| ElevenLabs | `elevenlabs/<voice-id>` | `ELEVENLABS_API_KEY` |
+| Google Cloud | `google/<voice-name>` | `GOOGLE_TTS_API_KEY` |
diff --git a/backend/app/database.py b/backend/app/database.py
index aecff97..ba03de3 100644
--- a/backend/app/database.py
+++ b/backend/app/database.py
@@ -3,7 +3,7 @@ from sqlalchemy.orm import sessionmaker, declarative_base
 
 from app.config import settings
 
-engine = create_engine(settings.DATABASE_URL, pool_pre_ping=True)
+engine = create_engine(settings.DATABASE_URL, pool_pre_ping=True, pool_recycle=300)
 
 SessionLocal = sessionmaker(autocommit=False, autoflush=False, bind=engine)
 Base = declarative_base()
diff --git a/backend/app/main.py b/backend/app/main.py
index daff60f..73ad032 100644
--- a/backend/app/main.py
+++ b/backend/app/main.py
@@ -7,7 +7,7 @@ from fastapi.staticfiles import StaticFiles
 
 from app.config import settings
 from app.database import engine, Base, SessionLocal
-from app.routers import auth, documents, quizzes, attempts, admin, tts, nextcloud, categories, questions, question_categories, favorites, teach, contact
+from app.routers import auth, documents, quizzes, attempts, admin, tts, nextcloud, categories, questions, question_categories, favorites, teach, contact, tags
 from app.utils.auth import get_password_hash
 from app.utils.scheduler import start_scheduler, stop_scheduler
 
@@ -145,11 +145,24 @@ def setup_pgvector():
         """))
         conn.commit()
 
+    # Retry schema migration up to 3 times — Celery tasks may hold locks briefly
+    for attempt in range(3):
+        try:
+            with engine.connect() as conn:
+                conn.execute(text("SET lock_timeout = '15s'"))
+                conn.execute(text("CREATE EXTENSION IF NOT EXISTS vector"))
+                conn.execute(text("ALTER TABLE questions ADD COLUMN IF NOT EXISTS embedding vector(1024)"))
+                conn.commit()
+                break
+        except Exception as e:
+            if attempt < 2 and "lock" in str(e).lower():
+                import logging; logging.getLogger(__name__).warning(f"Schema migration lock timeout (attempt {attempt+1}/3), retrying in 5s...")
+                import time; time.sleep(5)
+                continue
+            raise
+
     with engine.connect() as conn:
-        # Fail fast instead of hanging if a lock can't be acquired within 10s.
-        conn.execute(text("SET lock_timeout = '10s'"))
-        conn.execute(text("CREATE EXTENSION IF NOT EXISTS vector"))
-        conn.execute(text("ALTER TABLE questions ADD COLUMN IF NOT EXISTS embedding vector(1024)"))
+        conn.execute(text("SET lock_timeout = '15s'"))
         conn.execute(text("""
             CREATE INDEX IF NOT EXISTS questions_embedding_hnsw
             ON questions USING hnsw (embedding vector_cosine_ops)
@@ -190,8 +203,9 @@ def setup_pgvector():
         try:
             conn.execute(text("ALTER TABLE quizzes DROP CONSTRAINT IF EXISTS quizzes_section_id_fkey"))
             conn.execute(text("ALTER TABLE quizzes ADD CONSTRAINT quizzes_section_id_fkey FOREIGN KEY (section_id) REFERENCES sections(id) ON DELETE SET NULL"))
-        except Exception:
-            pass  # constraint may already be correct
+        except Exception as e:
+            import logging
+            logging.getLogger(__name__).debug(f"FK constraint migration (may already exist): {e}")
 
         # Soft delete + publish control for quizzes
         conn.execute(text("ALTER TABLE quizzes ADD COLUMN IF NOT EXISTS deleted_at TIMESTAMP"))
@@ -242,6 +256,25 @@ def setup_pgvector():
                 created_at TIMESTAMP DEFAULT NOW()
             )
         """))
+        # AI question tags (subjects, diseases, keywords)
+        conn.execute(text("""
+            CREATE TABLE IF NOT EXISTS question_tags (
+                id SERIAL PRIMARY KEY,
+                name VARCHAR(200) NOT NULL,
+                type VARCHAR(50) NOT NULL,
+                created_at TIMESTAMP DEFAULT NOW()
+            )
+        """))
+        conn.execute(text("""
+            CREATE UNIQUE INDEX IF NOT EXISTS uq_tag_name_type ON question_tags(LOWER(name), type)
+        """))
+        conn.execute(text("""
+            CREATE TABLE IF NOT EXISTS question_tag_links (
+                question_id INTEGER REFERENCES questions(id) ON DELETE CASCADE,
+                tag_id INTEGER REFERENCES question_tags(id) ON DELETE CASCADE,
+                PRIMARY KEY (question_id, tag_id)
+            )
+        """))
         conn.commit()
 
 
@@ -265,8 +298,8 @@ def backfill_embeddings():
                 try:
                     if embedding_service.embed_question(q):
                         ok += 1
-                except Exception:
-                    pass
+                except Exception as e:
+                    log.warning(f"Embedding failed for question {q.id}: {e}")
             db.commit()
             log.info(f"Backfill complete: {ok}/{len(missing)} embedded")
         except Exception as e:
@@ -346,6 +379,7 @@ app.include_router(question_categories.router, prefix="/api/question-categories"
 app.include_router(favorites.router, prefix="/api/favorites", tags=["favorites"])
 app.include_router(teach.router, prefix="/api/teach", tags=["teach"])
 app.include_router(contact.router, prefix="/api/contact", tags=["contact"])
+app.include_router(tags.router, prefix="/api/tags", tags=["tags"])
 
 
 @app.get("/api/health")
diff --git a/backend/app/models/ai_model_config.py b/backend/app/models/ai_model_config.py
index beaa87c..ac27330 100644
--- a/backend/app/models/ai_model_config.py
+++ b/backend/app/models/ai_model_config.py
@@ -1,16 +1,19 @@
 from datetime import datetime
 
-from sqlalchemy import Column, Integer, String, Boolean, DateTime
+from sqlalchemy import Column, Integer, String, Boolean, DateTime, UniqueConstraint
 
 from app.database import Base
 
 
 class AIModelConfig(Base):
     __tablename__ = "ai_model_configs"
+    __table_args__ = (
+        UniqueConstraint("model_id", "task", name="uq_model_id_task"),
+    )
 
     id = Column(Integer, primary_key=True, index=True)
     name = Column(String, nullable=False)  # display name
-    model_id = Column(String, nullable=False, unique=True)  # litellm model id e.g. gpt-4o-mini
+    model_id = Column(String, nullable=False)  # litellm model id e.g. gpt-4o-mini
     task = Column(String, nullable=False)  # extraction, tts, general
     api_key = Column(String, nullable=True)  # override api key, if null uses default
     is_active = Column(Boolean, default=True)
diff --git a/backend/app/routers/admin.py b/backend/app/routers/admin.py
index fb269b7..0e1d0b0 100644
--- a/backend/app/routers/admin.py
+++ b/backend/app/routers/admin.py
@@ -63,6 +63,26 @@ def set_user_unthrottle(
     return user
 
 
+@router.delete("/users/{user_id}", status_code=204)
+def delete_user(
+    user_id: int,
+    db: Session = Depends(get_db),
+    admin: User = Depends(require_admin),
+):
+    """Delete a user and all their data (attempts, favorites, settings)."""
+    user = db.query(User).filter(User.id == user_id).first()
+    if not user:
+        raise HTTPException(status_code=404, detail="User not found")
+    if user.id == admin.id:
+        raise HTTPException(status_code=400, detail="Cannot delete yourself")
+    # Nullify non-cascading FKs before delete
+    from sqlalchemy import text
+    db.execute(text("UPDATE question_categories SET user_id = NULL WHERE user_id = :uid"), {"uid": user_id})
+    db.execute(text("UPDATE quiz_categories SET user_id = NULL WHERE user_id = :uid"), {"uid": user_id})
+    db.delete(user)
+    db.commit()
+
+
 @router.post("/users", response_model=UserResponse)
 def create_user(
     user_data: UserCreate,
@@ -167,8 +187,8 @@ def create_model(
     db: Session = Depends(get_db),
     admin: User = Depends(require_admin),
 ):
-    if data.task not in ("extraction", "tts", "general", "teach"):
-        raise HTTPException(status_code=400, detail="Task must be extraction, tts, general, or teach")
+    if data.task not in ("extraction", "tts", "teach", "keyword"):
+        raise HTTPException(status_code=400, detail="Task must be extraction, tts, teach, or keyword")
 
     if data.is_default:
         db.query(AIModelConfig).filter(
@@ -176,9 +196,25 @@ def create_model(
             AIModelConfig.is_default == True,
         ).update({"is_default": False})
 
-    model = AIModelConfig(**data.model_dump())
+    # Auto-set as default if this is the first model for the task
+    existing = db.query(AIModelConfig).filter(
+        AIModelConfig.task == data.task, AIModelConfig.is_active == True,
+    ).count()
+    if existing == 0:
+        data_dict = data.model_dump()
+        data_dict["is_default"] = True
+    else:
+        data_dict = data.model_dump()
+
+    model = AIModelConfig(**data_dict)
     db.add(model)
-    db.commit()
+    try:
+        db.commit()
+    except Exception as e:
+        db.rollback()
+        if "uq_model_task" in str(e).lower() or "unique" in str(e).lower():
+            raise HTTPException(status_code=409, detail=f"Model '{data.model_id}' already exists for task '{data.task}'")
+        raise HTTPException(status_code=500, detail=str(e))
     db.refresh(model)
     return model
 
diff --git a/backend/app/routers/attempts.py b/backend/app/routers/attempts.py
index 4e29e38..d56d7aa 100644
--- a/backend/app/routers/attempts.py
+++ b/backend/app/routers/attempts.py
@@ -1,6 +1,6 @@
 from datetime import datetime
 
-from fastapi import APIRouter, Depends, HTTPException
+from fastapi import APIRouter, Depends, HTTPException, Request
 from pydantic import BaseModel
 from sqlalchemy.orm import Session
 from sqlalchemy import func
@@ -200,14 +200,23 @@ class ProgressSave(BaseModel):
 @router.post("/progress")
 def save_progress(
     data: ProgressSave,
+    request: Request = None,
     current_user: User = Depends(get_current_user),
 ):
     """Save in-progress quiz answers to Redis (survives logout/browser change).
-    Each attempt gets its own saved progress (key includes attempt_id)."""
+    Each attempt gets its own saved progress (key includes attempt_id).
+    Also refreshes the active session lock to prevent concurrent resume on another device."""
     try:
         import redis as redis_lib, json as _json
         from app.config import settings
         r = redis_lib.from_url(settings.REDIS_URL, decode_responses=True)
+
+        # Session lock: identify this device by a session_id header
+        session_id = request.headers.get("x-quiz-session", "") if request else ""
+        lock_key = f"quiz_active:{current_user.id}:{data.attempt_id}"
+        if session_id:
+            r.setex(lock_key, 30, session_id)  # 30s TTL, refreshed every save
+
         key = f"quiz_progress:{current_user.id}:{data.attempt_id}"
         r.setex(key, 7 * 24 * 3600, _json.dumps({  # 7 days
             "quiz_id": data.quiz_id,
@@ -228,12 +237,13 @@ def save_progress(
 @router.get("/progress")
 def get_progress(
     quiz_id: int,
+    request: Request = None,
     db: Session = Depends(get_db),
     current_user: User = Depends(get_current_user),
 ):
     """Retrieve in-progress quiz answers from Redis.
     Finds the latest incomplete attempt for this quiz, then checks Redis.
-    Clears stale data if the saved attempt has already been submitted.
+    Rejects if another device is actively using this attempt.
     Auto-submits timed quizzes if timer has expired."""
     try:
         import redis as redis_lib, json as _json
@@ -251,6 +261,16 @@ def get_progress(
         if not attempt:
             return None
 
+        # Check if another device is actively using this attempt
+        session_id = request.headers.get("x-quiz-session", "") if request else ""
+        lock_key = f"quiz_active:{current_user.id}:{attempt.id}"
+        active_session = r.get(lock_key)
+        if active_session and session_id and active_session != session_id:
+            raise HTTPException(
+                status_code=409,
+                detail="This quiz is active on another device. It will become available when the other session ends or times out (~30 seconds)."
+            )
+
         key = f"quiz_progress:{current_user.id}:{attempt.id}"
         data = r.get(key)
         if not data:
diff --git a/backend/app/routers/auth.py b/backend/app/routers/auth.py
index ef3a767..af6c793 100644
--- a/backend/app/routers/auth.py
+++ b/backend/app/routers/auth.py
@@ -33,8 +33,8 @@ def _check_login_rate_limit(client_ip: str):
             raise HTTPException(status_code=429, detail="Too many login attempts. Try again in 15 minutes.")
     except HTTPException:
         raise
-    except Exception:
-        pass  # Redis unavailable — degrade gracefully, don't block login
+    except Exception as e:
+        import logging; logging.getLogger(__name__).warning(f"Redis rate limit unavailable (failing open): {e}")
 
 
 # Rate limit: max 3 reset requests per email per hour
@@ -59,8 +59,35 @@ def _check_reset_rate_limit(db: Session, email: str):
         )
 
 
+async def _verify_turnstile(token: str) -> bool:
+    """Verify Cloudflare Turnstile token. Returns True if valid or if not configured."""
+    from app.config import settings as cfg
+    secret = cfg.TURNSTILE_SECRET_KEY
+    if not secret:
+        return True
+    try:
+        import httpx
+        resp = httpx.post(
+            "https://challenges.cloudflare.com/turnstile/v0/siteverify",
+            data={"secret": secret, "response": token},
+            timeout=10,
+        )
+        return resp.json().get("success", False)
+    except Exception as e:
+        import logging; logging.getLogger(__name__).warning(f"Turnstile verification failed (failing open): {e}")
+        return True
+
+
 @router.post("/register")
 async def register(user_data: UserCreate, background_tasks: BackgroundTasks, db: Session = Depends(get_db)):
+    # Verify Turnstile if configured
+    from app.config import settings as cfg
+    if cfg.TURNSTILE_SECRET_KEY:
+        if not user_data.turnstile_token:
+            raise HTTPException(status_code=400, detail="Bot verification required")
+        if not await _verify_turnstile(user_data.turnstile_token):
+            raise HTTPException(status_code=400, detail="Bot verification failed — please try again")
+
     # Check if registration is enabled (unless this is the first user - always allow admin creation)
     is_first_user = db.query(User).count() == 0
     if not is_first_user:
@@ -74,8 +101,8 @@ async def register(user_data: UserCreate, background_tasks: BackgroundTasks, db:
                 raise HTTPException(status_code=403, detail="Registration is currently disabled by administrator")
         except HTTPException:
             raise
-        except Exception:
-            pass  # Redis unavailable — allow registration (fail open)
+        except Exception as e:
+            import logging; logging.getLogger(__name__).warning(f"Redis registration check failed (failing open): {e}")
 
     if len(user_data.password) < 8:
         raise HTTPException(status_code=400, detail="Password must be at least 8 characters")
@@ -116,7 +143,15 @@ async def register(user_data: UserCreate, background_tasks: BackgroundTasks, db:
 
 
 @router.post("/login", response_model=Token)
-def login(login_data: LoginRequest, db: Session = Depends(get_db), request: Request = None):
+async def login(login_data: LoginRequest, db: Session = Depends(get_db), request: Request = None):
+    # Verify Turnstile if configured
+    from app.config import settings as cfg
+    if cfg.TURNSTILE_SECRET_KEY:
+        if not login_data.turnstile_token:
+            raise HTTPException(status_code=400, detail="Bot verification required")
+        if not await _verify_turnstile(login_data.turnstile_token):
+            raise HTTPException(status_code=400, detail="Bot verification failed — please try again")
+
     if request:
         client_ip = request.client.host if request.client else "unknown"
         _check_login_rate_limit(client_ip)
@@ -232,7 +267,8 @@ def get_user_settings(current_user: User = Depends(get_current_user)):
         r = redis_lib.from_url(cfg.REDIS_URL, decode_responses=True)
         data = r.get(f"user_settings:{current_user.id}")
         return json.loads(data) if data else {}
-    except Exception:
+    except Exception as e:
+        import logging; logging.getLogger(__name__).warning(f"Failed to load user settings: {e}")
         return {}
 
 
@@ -247,8 +283,8 @@ def save_user_settings(
         from app.config import settings as cfg
         r = redis_lib.from_url(cfg.REDIS_URL, decode_responses=True)
         r.set(f"user_settings:{current_user.id}", json.dumps(settings_data))
-    except Exception:
-        pass
+    except Exception as e:
+        import logging; logging.getLogger(__name__).warning(f"Failed to save user settings: {e}")
     return {"saved": True}
 
 
diff --git a/backend/app/routers/contact.py b/backend/app/routers/contact.py
index 85a4069..b16d27b 100644
--- a/backend/app/routers/contact.py
+++ b/backend/app/routers/contact.py
@@ -66,14 +66,14 @@ async def submit_contact(req: ContactRequest, db: Session = Depends(get_db)):
     db.commit()
 
     # Email admin
-    _email_admin(name, req.email, req.type, message)
+    await _email_admin(name, req.email, req.type, message)
 
     return {"success": True}
 
 
-def _email_admin(name: str, email: str, type_: str, message: str):
+async def _email_admin(name: str, email: str, type_: str, message: str):
     try:
-        from app.services.email_service import send_email
+        from app.services.email_service import _send
         label = "Moderator Application" if type_ == "moderator" else "Contact Form Question"
         body = (
             f"<h2>New {label} — PedsHub</h2>"
@@ -85,7 +85,7 @@ def _email_admin(name: str, email: str, type_: str, message: str):
         )
         admin_email = getattr(settings, "ADMIN_EMAIL", None) or getattr(settings, "SMTP_FROM", None)
         if admin_email:
-            send_email(to=admin_email, subject=f"[PedsHub] {label} from {name}", html=body)
+            await _send(admin_email, f"[PedsHub] {label} from {name}", body)
     except Exception as e:
         log.warning(f"Failed to email admin about contact submission: {e}")
 
diff --git a/backend/app/routers/documents.py b/backend/app/routers/documents.py
index fffeef9..34546cd 100644
--- a/backend/app/routers/documents.py
+++ b/backend/app/routers/documents.py
@@ -125,6 +125,22 @@ def get_document_status(
     )
 
 
+@router.get("/{document_id}/processing-steps")
+def get_processing_steps(
+    document_id: int,
+    db: Session = Depends(get_db),
+    current_user: User = Depends(get_current_user),
+):
+    """Poll PDF processing progress steps from Redis."""
+    _get_doc_or_404(document_id, current_user, db)
+    import json as _json
+    import redis
+    r = redis.from_url(settings.REDIS_URL, decode_responses=True)
+    raw = r.lrange(f"pdf:steps:{document_id}", 0, -1)
+    steps = [_json.loads(s) for s in raw] if raw else []
+    return {"steps": steps}
+
+
 @router.post("/{document_id}/sections", response_model=SectionResponse)
 def create_section(
     document_id: int,
diff --git a/backend/app/routers/questions.py b/backend/app/routers/questions.py
index edfec93..f365a93 100644
--- a/backend/app/routers/questions.py
+++ b/backend/app/routers/questions.py
@@ -1,7 +1,7 @@
 """Question bank — view, search, categorise, and create quizzes from individual questions."""
 from fastapi import APIRouter, Depends, HTTPException, Query
 from pydantic import BaseModel
-from sqlalchemy import cast, String, or_
+from sqlalchemy import cast, String, or_, text as sa_text
 from sqlalchemy.orm import Session
 
 from app.database import get_db
@@ -40,16 +40,22 @@ def get_bank_ids(
     q: str | None = Query(None),
     quiz_id: int | None = Query(None),
     category_id: int | None = Query(None),
+    category_ids: str | None = Query(None, description="Comma-separated category IDs (OR filter)"),
     uncategorized: bool = Query(False),
     favorites_only: bool = Query(False),
+    tag_ids: str | None = Query(None, description="Comma-separated tag IDs (AND filter)"),
     db: Session = Depends(get_db),
     current_user: User = Depends(get_current_user),
 ):
     """Return just IDs for all matching questions (for server-side select-all)."""
     query = db.query(Question.id)
     if quiz_id:
-        query = query.filter(Question.quiz_id == quiz_id)
-    if category_id is not None:
+        query = query.filter(Question.source_quiz_id == quiz_id)
+    if category_ids:
+        cat_id_list = [int(c.strip()) for c in category_ids.split(",") if c.strip().isdigit()]
+        if cat_id_list:
+            query = query.filter(Question.question_category_id.in_(cat_id_list))
+    elif category_id is not None:
         query = query.filter(Question.question_category_id == category_id)
     if uncategorized:
         query = query.filter(Question.question_category_id.is_(None))
@@ -67,6 +73,20 @@ def get_bank_ids(
                 cast(Question.options, String).ilike(f"%{phrase}%"),
             )
         )
+    # Tag filter: questions must have ALL specified tags
+    if tag_ids:
+        tag_id_list = [int(t.strip()) for t in tag_ids.split(",") if t.strip().isdigit()]
+        if tag_id_list:
+            matching_ids = list(db.execute(sa_text("""
+                SELECT question_id FROM question_tag_links
+                WHERE tag_id = ANY(:tag_ids)
+                GROUP BY question_id
+                HAVING COUNT(DISTINCT tag_id) = :cnt
+            """), {"tag_ids": tag_id_list, "cnt": len(tag_id_list)}).scalars())
+            if matching_ids:
+                query = query.filter(Question.id.in_(matching_ids))
+            else:
+                return []
     return [row[0] for row in query.all()]
 
 
@@ -75,8 +95,10 @@ def get_question_bank(
     q: str | None = Query(None),
     quiz_id: int | None = Query(None),
     category_id: int | None = Query(None),
+    category_ids: str | None = Query(None, description="Comma-separated category IDs (OR filter)"),
     uncategorized: bool = Query(False),
     favorites_only: bool = Query(False),
+    tag_ids: str | None = Query(None, description="Comma-separated tag IDs (AND filter)"),
     search_mode: str = Query("hybrid"),  # "keyword" | "semantic" | "hybrid"
     limit: int = Query(50, le=200),
     offset: int = Query(0),
@@ -87,14 +109,36 @@ def get_question_bank(
     query = db.query(Question)
 
     if quiz_id:
-        query = query.filter(Question.quiz_id == quiz_id)
+        query = query.filter(Question.source_quiz_id == quiz_id)
 
-    if category_id is not None:
+    if category_ids:
+        cat_id_list = [int(c.strip()) for c in category_ids.split(",") if c.strip().isdigit()]
+        if cat_id_list:
+            query = query.filter(Question.question_category_id.in_(cat_id_list))
+    elif category_id is not None:
         query = query.filter(Question.question_category_id == category_id)
 
     if uncategorized:
         query = query.filter(Question.question_category_id.is_(None))
 
+    # Tag filter: questions must have ALL specified tags
+    if tag_ids:
+        import logging as _log
+        _log.getLogger(__name__).info(f"Tag filter: tag_ids={tag_ids!r}")
+        tag_id_list = [int(t.strip()) for t in tag_ids.split(",") if t.strip().isdigit()]
+        if tag_id_list:
+            matching_ids = list(db.execute(sa_text("""
+                SELECT question_id FROM question_tag_links
+                WHERE tag_id = ANY(:tag_ids)
+                GROUP BY question_id
+                HAVING COUNT(DISTINCT tag_id) = :cnt
+            """), {"tag_ids": tag_id_list, "cnt": len(tag_id_list)}).scalars())
+            _log.getLogger(__name__).info(f"Tag filter matched {len(matching_ids)} questions for tags {tag_id_list}")
+            if matching_ids:
+                query = query.filter(Question.id.in_(matching_ids))
+            else:
+                return {"total": 0, "questions": []}
+
     if favorites_only:
         favorite_ids = db.query(Favorite.question_id).filter(Favorite.user_id == current_user.id).all()
         fav_ids = [f[0] for f in favorite_ids]
@@ -106,7 +150,6 @@ def get_question_bank(
     semantic_ids_ordered: list[int] = []
     if q and q.strip() and search_mode in ("semantic", "hybrid"):
         from app.services.embedding_service import generate_embedding
-        from sqlalchemy import text as sa_text
         emb = generate_embedding(q.strip())
         if emb:
             # Validate all values are finite floats before interpolating into SQL
@@ -116,9 +159,9 @@ def get_question_bank(
                 FROM questions
                 WHERE embedding IS NOT NULL
                 ORDER BY embedding <=> CAST(:vec AS vector)
-                LIMIT 200
-            """), {"vec": emb_literal}).fetchall()
-            semantic_ids_ordered = [r.id for r in rows if float(r.sim) >= 0.30]
+                LIMIT :lim
+            """), {"vec": emb_literal, "lim": limit * 2}).fetchall()
+            semantic_ids_ordered = [r.id for r in rows if float(r.sim) >= 0.55]
 
     # ── Keyword filter ─────────────────────────────────────────────
     if q and q.strip() and search_mode in ("keyword", "hybrid"):
@@ -172,6 +215,7 @@ def get_question_bank(
             "options": qu.options,
             "correct_answer": qu.correct_answer,
             "explanation": qu.explanation,
+            "image_path": qu.image_path,
         })
 
     return {"total": total, "questions": result}
diff --git a/backend/app/routers/quizzes.py b/backend/app/routers/quizzes.py
index ad9de2a..4487870 100644
--- a/backend/app/routers/quizzes.py
+++ b/backend/app/routers/quizzes.py
@@ -188,16 +188,16 @@ def search_quizzes(
         query_emb = embedding_service.generate_embedding(phrase)
         if query_emb:
             # Use f-string for the vector literal — safe because it's a list of floats
-            emb_literal = "[" + ",".join(str(x) for x in query_emb) + "]"
-            rows = db.execute(sa_text(f"""
+            emb_literal = "[" + ",".join(str(float(x)) for x in query_emb) + "]"
+            rows = db.execute(sa_text("""
                 SELECT q.id, q.quiz_id, q.question_text, q.options,
                        q.correct_answer, q.explanation,
-                       1 - (q.embedding <=> '{emb_literal}'::vector) AS similarity
+                       1 - (q.embedding <=> CAST(:vec AS vector)) AS similarity
                 FROM questions q
                 WHERE q.embedding IS NOT NULL
-                ORDER BY q.embedding <=> '{emb_literal}'::vector
+                ORDER BY q.embedding <=> CAST(:vec AS vector)
                 LIMIT 40
-            """)).fetchall()
+            """), {"vec": emb_literal}).fetchall()
 
             for row in rows:
                 similarity = float(row.similarity)
diff --git a/backend/app/routers/tags.py b/backend/app/routers/tags.py
new file mode 100644
index 0000000..3a422ea
--- /dev/null
+++ b/backend/app/routers/tags.py
@@ -0,0 +1,67 @@
+"""AI-powered question tagging/classification — subjects, diseases, keywords.
+Tables are created via raw SQL in setup_pgvector() to avoid race conditions with multiple workers.
+"""
+import logging
+import uuid
+
+from fastapi import APIRouter, Depends, HTTPException
+from sqlalchemy import text
+from sqlalchemy.orm import Session
+
+from app.database import get_db
+from app.models.user import User
+from app.utils.auth import get_current_user, require_moderator
+
+router = APIRouter()
+log = logging.getLogger(__name__)
+
+
+@router.get("")
+def get_tags(db: Session = Depends(get_db), current_user: User = Depends(get_current_user)):
+    """Return all tags grouped by type, with question counts."""
+    rows = db.execute(text("""
+        SELECT t.id, t.name, t.type, COUNT(tl.question_id) AS count
+        FROM question_tags t
+        LEFT JOIN question_tag_links tl ON tl.tag_id = t.id
+        GROUP BY t.id, t.name, t.type
+        ORDER BY count DESC, t.name
+    """)).fetchall()
+
+    result = {"subjects": [], "diseases": [], "keywords": []}
+    for r in rows:
+        key = {"subject": "subjects", "disease": "diseases", "keyword": "keywords"}.get(r.type)
+        if key:
+            result[key].append({"id": r.id, "name": r.name, "count": r.count})
+    return result
+
+
+@router.post("/classify")
+def trigger_classification(
+    db: Session = Depends(get_db),
+    current_user: User = Depends(require_moderator),
+):
+    """Admin/moderator: trigger background classification of untagged questions."""
+    from app.tasks.quiz_tasks import classify_questions
+
+    job_id = str(uuid.uuid4())
+    classify_questions.delay(job_id, current_user.id)
+    return {"job_id": job_id, "status": "started"}
+
+
+@router.get("/status/{job_id}")
+def get_classification_status(
+    job_id: str,
+    current_user: User = Depends(get_current_user),
+):
+    """Check classification job progress."""
+    import json
+    import redis
+    from app.config import settings
+
+    r = redis.from_url(settings.REDIS_URL, decode_responses=True)
+    status = r.get(f"classify:status:{job_id}") or "unknown"
+    steps_raw = r.lrange(f"classify:steps:{job_id}", 0, -1)
+    steps = [json.loads(s) for s in steps_raw] if steps_raw else []
+    error = r.get(f"classify:error:{job_id}")
+
+    return {"job_id": job_id, "status": status, "steps": steps, "error": error}
diff --git a/backend/app/schemas/auth.py b/backend/app/schemas/auth.py
index 06eb712..d86afca 100644
--- a/backend/app/schemas/auth.py
+++ b/backend/app/schemas/auth.py
@@ -7,6 +7,7 @@ class UserCreate(BaseModel):
     email: EmailStr
     password: str
     name: str
+    turnstile_token: str | None = None
 
 
 class UserResponse(BaseModel):
@@ -29,6 +30,7 @@ class Token(BaseModel):
 class LoginRequest(BaseModel):
     email: EmailStr
     password: str
+    turnstile_token: str | None = None
 
 
 class UserUpdateRole(BaseModel):
diff --git a/backend/app/schemas/quiz.py b/backend/app/schemas/quiz.py
index ba74c08..2316ea2 100644
--- a/backend/app/schemas/quiz.py
+++ b/backend/app/schemas/quiz.py
@@ -4,7 +4,7 @@ from pydantic import BaseModel
 
 
 class QuizCreate(BaseModel):
-    section_id: int
+    section_id: int | None = None
     title: str
     mode: str = "timed"  # timed, learning
     time_limit_minutes: int | None = None
@@ -41,7 +41,7 @@ class QuestionWithAnswer(QuestionResponse):
 
 class QuizResponse(BaseModel):
     id: int
-    section_id: int
+    section_id: int | None = None
     user_id: int
     title: str
     questions_count: int
diff --git a/backend/app/services/ai_service.py b/backend/app/services/ai_service.py
index 9747598..a73f068 100644
--- a/backend/app/services/ai_service.py
+++ b/backend/app/services/ai_service.py
@@ -34,6 +34,7 @@ Your task: extract every question and return ONLY a JSON object in this exact fo
     "options": ["<option A text>", "<option B text>", "<option C text>", "<option D text>", "<option E text>"],
     "correct_answer": "<full text of the correct option, NOT the letter>",
     "explanation": "<ALL text verbatim from after the correct answer line to before the next question — explanation, Critique, Learning Points, Content Specifications, Suggested Reading, everything>",
+    "has_figure": false,
     "page_reference": {page_ref}
   }}
 ]}}
@@ -57,7 +58,12 @@ CRITICAL RULES — follow exactly:
 
 4. OPTIONS: Extract just the text for each option, without the letter prefix (A. B. C. D. E.).
 
-5. Return ONLY the JSON — no markdown fences, no explanation, no preamble.
+5. HAS_FIGURE: Set to true ONLY if the question text explicitly references an image, figure, photograph,
+   radiograph, X-ray, ECG, rash photo, growth chart, or similar visual that is essential to answering.
+   Do NOT set true for decorative logos, page headers, publisher icons, or repeated branding images.
+   If the question can be answered from text alone, set false.
+
+6. Return ONLY the JSON — no markdown fences, no explanation, no preamble.
 
 Content from page(s) {page_info}:
 {content}"""
@@ -92,8 +98,8 @@ def get_model_for_task(db, task: str = "extraction") -> tuple[str, str | None]:
         ).first()
         if config:
             return config.model_id, config.api_key
-    except Exception:
-        pass
+    except Exception as e:
+        logger.warning(f"Failed to load AI model config for task '{task}', using fallback: {e}")
     return settings.LITELLM_MODEL, settings.LITELLM_API_KEY or None
 
 
diff --git a/backend/app/services/extraction_modes.py b/backend/app/services/extraction_modes.py
index 41ae7a3..4ab1350 100644
--- a/backend/app/services/extraction_modes.py
+++ b/backend/app/services/extraction_modes.py
@@ -6,6 +6,7 @@ questions_only   Extract Q+options with no answers. User fills answers later via
 two_step         Separate answer key section (PREP 2013): Phase 1 = questions, Phase 2 = key, Phase 3 = match.
 regex            AI generates a regex pattern for the document's answer format, then we apply it.
 ai_decide        AI samples the document and picks standard / two_step / questions_only.
+generate         AI reads plain text/study material and creates MCQ questions from scratch.
 """
 from __future__ import annotations
 import json
@@ -34,6 +35,7 @@ Return ONLY JSON:
     "question_text": "<full vignette + stem>",
     "question_type": "mcq",
     "options": ["<A>", "<B>", "<C>", "<D>", "<E>"],
+    "has_figure": false,
     "page_reference": {page_ref}
   }}
 ]}}
@@ -42,6 +44,7 @@ Rules:
 - A new question starts with "Item NNN" or "ltem NNN".
 - Extract ALL questions even if no answer is visible.
 - Do NOT include answer explanations or "Preferred Response:" content as questions.
+- has_figure: true ONLY if the question references an image, figure, radiograph, photo, ECG, or chart essential to answering. false for decorative/branding images.
 - Return ONLY JSON — no markdown, no preamble.
 
 Content (pages {page_info}):
@@ -347,6 +350,92 @@ Return ONLY JSON:
  "reasoning": "<one sentence>"}}"""
 
 
+# ─── GENERATE FROM TEXT ──────────────────────────────────────────────────────
+
+GENERATE_PROMPT = """You are a pediatric medical education expert. Read the text below and generate {n} high-quality multiple-choice questions to test comprehension.
+
+Rules:
+- The CORRECT answer must be directly supported by the text — do not invent facts
+- Create 3 plausible but incorrect distractors using your medical knowledge
+- Questions should test understanding of concepts, not just exact word recall
+- Prefer clinical application questions over pure recall when the content allows
+- Include a 1-2 sentence explanation that cites the key concept from the text
+- Spread questions across different parts of the text, not just the first section
+- Each option should be a complete, standalone phrase (not "A", "B" labels)
+
+Return ONLY valid JSON (no markdown, no preamble):
+{{"questions": [
+  {{
+    "question_text": "<clear clinical or conceptual question>",
+    "question_type": "mcq",
+    "options": ["<correct answer text>", "<distractor B>", "<distractor C>", "<distractor D>"],
+    "correct_answer": "<exact text of the correct option>",
+    "explanation": "<1-2 sentence explanation>",
+    "page_reference": {page_ref}
+  }}
+]}}
+
+Text (pages {page_info}):
+{content}"""
+
+QUESTIONS_PER_CHUNK = 8  # target questions per ~50-page chunk
+
+
+def generate_from_text(content: str, page_info: str, page_ref: int | None,
+                       model_id: str | None, api_key: str | None,
+                       n: int = QUESTIONS_PER_CHUNK) -> list[dict]:
+    """Generate MCQ questions from plain text — correct answers from the document,
+    distractors from AI medical knowledge."""
+    content = ai_service._truncate_content(content)
+    prompt = GENERATE_PROMPT.format(
+        content=content,
+        page_info=page_info,
+        page_ref=page_ref if page_ref is not None else "null",
+        n=n,
+    )
+    for attempt in range(3):
+        try:
+            text = ai_service._call_model(prompt, model_id, api_key).strip()
+            if text.startswith("```"):
+                text = text.split("\n", 1)[1] if "\n" in text else text[3:]
+                if text.endswith("```"):
+                    text = text[:-3]
+                text = text.strip()
+            data = json.loads(text)
+            qs = data.get("questions", data) if isinstance(data, dict) else data
+            result = []
+            for q in qs:
+                if not q.get("question_text") or not q.get("correct_answer"):
+                    continue
+                options = q.get("options") or []
+                correct = q["correct_answer"]
+                # Validate correct_answer is among options
+                if options and correct not in options:
+                    # Try to find closest match
+                    matches = [o for o in options if correct.lower() in o.lower() or o.lower() in correct.lower()]
+                    if matches:
+                        correct = matches[0]
+                    else:
+                        continue  # skip malformed question
+                result.append({
+                    "question_text": q["question_text"],
+                    "question_type": q.get("question_type", "mcq"),
+                    "options": options,
+                    "correct_answer": correct,
+                    "explanation": q.get("explanation", ""),
+                    "page_reference": q.get("page_reference"),
+                    "item_number": None,
+                })
+            if result:
+                return result
+            raise ValueError("No valid questions generated")
+        except Exception as e:
+            logger.warning(f"generate_from_text attempt {attempt + 1}: {e}")
+    raise RuntimeError("generate_from_text failed after 3 attempts")
+
+
+# ─── AI DECIDES ──────────────────────────────────────────────────────────────
+
 def ai_decide_strategy(
     document_id: int,
     section_start: int,
diff --git a/backend/app/services/pdf_service.py b/backend/app/services/pdf_service.py
index 8d4e2e2..973d2ae 100644
--- a/backend/app/services/pdf_service.py
+++ b/backend/app/services/pdf_service.py
@@ -39,8 +39,17 @@ def extract_text_for_range(file_path: str, start: int, end: int) -> str:
     return "\n\n".join(texts)
 
 
+# MD5 hashes of known repeated branding images (logos, headers) to skip during extraction.
+# These appear on every page of PREP PDFs and are not clinical images.
+_SKIP_IMAGE_HASHES = {
+    "f48b094ec260f0aa8d7c52bc3cf562e4",  # AAP logo (34300 bytes, appears 869 times across PREP PDFs)
+    "82c449d72791fe181fc9964bb8efad0f",  # Sepsis document header/logo (20397 bytes, repeated per page)
+}
+
+
 def extract_images_from_page(file_path: str, page_num: int, document_id: int) -> list[str]:
     """Extract images from a specific page. Returns list of saved image paths."""
+    import hashlib
     image_dir = os.path.join(settings.UPLOAD_DIR, "images", f"doc_{document_id}")
     os.makedirs(image_dir, exist_ok=True)
 
@@ -64,8 +73,18 @@ def extract_images_from_page(file_path: str, page_num: int, document_id: int) ->
                 image_ext = base_image.get("ext", "png")
                 image_bytes = base_image["image"]
 
-                # Skip tiny images (likely icons/bullets)
-                if len(image_bytes) < 1000:
+                # Skip tiny images (likely icons/bullets/decorations)
+                if len(image_bytes) < 2000:
+                    continue
+
+                # Skip known branding/logo images by hash
+                if hashlib.md5(image_bytes).hexdigest() in _SKIP_IMAGE_HASHES:
+                    continue
+
+                # Skip images with very small dimensions (banners, line art, icons)
+                w = base_image.get("width", 0)
+                h = base_image.get("height", 0)
+                if w > 0 and h > 0 and (w < 80 or h < 80):
                     continue
 
                 filename = f"page_{page_num}_img_{img_idx}.{image_ext}"
diff --git a/backend/app/services/vector_service.py b/backend/app/services/vector_service.py
index bd90a7e..2970ac0 100644
--- a/backend/app/services/vector_service.py
+++ b/backend/app/services/vector_service.py
@@ -21,6 +21,9 @@ class LiteLLMEmbeddingFunction(EmbeddingFunction):
             content=_json.dumps(body),
             timeout=60,
         )
+        if resp.status_code != 200:
+            import logging
+            logging.getLogger(__name__).error(f"Embedding API error: model={model}, inputs={len(input)}, status={resp.status_code}, body={resp.text[:500]}")
         resp.raise_for_status()
         return [item["embedding"] for item in resp.json()["data"]]
 
@@ -49,8 +52,9 @@ def delete_collection(document_id: int):
     client = get_client()
     try:
         client.delete_collection(name=f"doc_{document_id}")
-    except Exception:
-        pass
+    except Exception as e:
+        import logging
+        logging.getLogger(__name__).warning(f"Failed to delete vector collection doc_{document_id}: {e}")
 
 
 def chunk_text(text: str, chunk_size: int = 1000, overlap: int = 200) -> list[str]:
@@ -82,14 +86,17 @@ def store_pages(document_id: int, pages: dict[int, str]):
             all_docs.append(chunk)
             all_metadatas.append({"page_num": page_num, "document_id": document_id})
 
-    # ChromaDB has a batch limit; add in batches of 500
-    batch_size = 500
+    # ChromaDB sends each batch to embedding API in one call — keep under provider limit
+    import time as _time
+    batch_size = 100
     for i in range(0, len(all_ids), batch_size):
         collection.add(
             ids=all_ids[i:i + batch_size],
             documents=all_docs[i:i + batch_size],
             metadatas=all_metadatas[i:i + batch_size],
         )
+        if i + batch_size < len(all_ids):
+            _time.sleep(3)  # rate limit buffer between batches
 
 
 def query_pages(
diff --git a/backend/app/tasks/pdf_tasks.py b/backend/app/tasks/pdf_tasks.py
index e3e8545..dacebd2 100644
--- a/backend/app/tasks/pdf_tasks.py
+++ b/backend/app/tasks/pdf_tasks.py
@@ -1,46 +1,75 @@
 import logging
+import json
+import time
 
 from app.tasks import celery_app
 from app.database import SessionLocal
 from app.models.pdf_document import PDFDocument
 from app.services import pdf_service, vector_service
+from app.config import settings
 
 logger = logging.getLogger(__name__)
 
 
+def _redis():
+    import redis
+    return redis.from_url(settings.REDIS_URL, decode_responses=True)
+
+
+def _push_step(r, doc_id: int, step: str, message: str):
+    r.rpush(f"pdf:steps:{doc_id}", json.dumps({"step": step, "message": message, "ts": time.time()}))
+    r.expire(f"pdf:steps:{doc_id}", 3600)
+
+
 @celery_app.task(name="process_pdf")
 def process_pdf(document_id: int, file_path: str):
     """Background task: extract PDF text and store in ChromaDB."""
     db = SessionLocal()
+    r = _redis()
     try:
         doc = db.query(PDFDocument).filter(PDFDocument.id == document_id).first()
         if not doc:
             logger.error(f"Document {document_id} not found")
             return
 
+        _push_step(r, document_id, "start", "Starting PDF processing…")
+
         # Get page count
         total_pages = pdf_service.get_page_count(file_path)
         doc.total_pages = total_pages
         db.commit()
+        _push_step(r, document_id, "pages", f"Found {total_pages} pages")
 
         # Extract text from all pages
+        _push_step(r, document_id, "text", "Extracting text from pages…")
         pages = pdf_service.extract_text_by_page(file_path)
         if not pages:
             doc.status = "error"
             doc.error_message = "No text could be extracted from the PDF"
             db.commit()
+            _push_step(r, document_id, "error", "No text could be extracted")
             return
 
+        _push_step(r, document_id, "text", f"Extracted text from {len(pages)} pages")
+
         # Store in ChromaDB
+        total_chunks = 0
+        for page_num, text in pages.items():
+            chunks = vector_service.chunk_text(text)
+            total_chunks += len(chunks)
+        _push_step(r, document_id, "vector", f"Vectorizing {total_chunks} chunks across {len(pages)} pages…")
         vector_service.store_pages(document_id, pages)
+        _push_step(r, document_id, "vector", "Vectorization complete")
 
         # Mark as ready
         doc.status = "ready"
         db.commit()
+        _push_step(r, document_id, "done", f"Ready — {total_pages} pages, {len(pages)} with text")
         logger.info(f"Document {document_id} processed: {total_pages} pages, {len(pages)} with text")
 
     except Exception as e:
         logger.exception(f"Error processing document {document_id}")
+        _push_step(r, document_id, "error", f"Failed: {str(e)[:200]}")
         try:
             doc = db.query(PDFDocument).filter(PDFDocument.id == document_id).first()
             if doc:
diff --git a/backend/app/tasks/quiz_tasks.py b/backend/app/tasks/quiz_tasks.py
index 1a20250..c5413d9 100644
--- a/backend/app/tasks/quiz_tasks.py
+++ b/backend/app/tasks/quiz_tasks.py
@@ -106,7 +106,7 @@ def extract_quiz(
         if extraction_mode != "standard":
             from app.services.extraction_modes import (
                 extract_questions_only, extract_two_step,
-                extract_with_regex, ai_decide_strategy,
+                extract_with_regex, ai_decide_strategy, generate_from_text,
             )
 
             resolved_mode = extraction_mode
@@ -156,6 +156,25 @@ def extract_quiz(
                     chunk_pages=CHUNK_PAGES,
                 )
 
+            elif resolved_mode == "generate":
+                _push_step(r, job_id, "ai", "Mode: Generate — AI creates questions from the text.")
+                for chunk_idx, (start_p, end_p) in enumerate(chunks, 1):
+                    if r.get(f"extraction:status:{job_id}") == "cancelled":
+                        _push_step(r, job_id, "cancelled", "Job cancelled.")
+                        return
+                    _push_step(r, job_id, "ai", f"Chunk {chunk_idx}/{n_chunks}: pages {start_p}–{end_p}…")
+                    chunk_content = vector_service.get_pages_text(
+                        document_id=section.document_id, start_page=start_p, end_page=end_p)
+                    if not chunk_content:
+                        continue
+                    try:
+                        qs = generate_from_text(_normalize_ocr(chunk_content),
+                            f"{start_p}-{end_p}", start_p, model_id, api_key)
+                        all_valid_questions.extend(qs)
+                        _push_step(r, job_id, "ai", f"  Pages {start_p}–{end_p}: {len(qs)} questions generated. Total: {len(all_valid_questions)}.")
+                    except Exception as e:
+                        _push_step(r, job_id, "ai", f"  Pages {start_p}–{end_p} failed: {e}")
+
             else:
                 # ai_decide resolved to standard — fall through to standard loop below
                 extraction_mode = "standard"
@@ -203,6 +222,18 @@ def extract_quiz(
         if not valid_questions:
             raise ValueError("No valid questions extracted. The AI could not find questions with correct answers in this page range.")
 
+        # Refresh DB connection — it may have gone stale during long LLM extraction
+        from sqlalchemy import text as _text
+        try:
+            db.execute(_text("SELECT 1"))
+        except Exception:
+            db.rollback()
+            db.close()
+            db = SessionLocal()
+            # Re-fetch objects that were bound to the old session
+            section = db.query(Section).filter(Section.id == section_id).first()
+            document = db.query(PDFDocument).filter(PDFDocument.id == section.document_id).first()
+
         # Extract images
         _push_step(r, job_id, "images", "Extracting question images…")
         file_path = os.path.join(settings.UPLOAD_DIR, document.filename)
@@ -233,7 +264,8 @@ def extract_quiz(
         for pos, q in enumerate(valid_questions):
             page_ref = q.get("page_reference")
             image_path = None
-            if page_ref and page_ref in page_images and page_images[page_ref]:
+            # Only link an image if the AI flagged the question as having a figure
+            if q.get("has_figure") and page_ref and page_ref in page_images and page_images[page_ref]:
                 image_path = page_images[page_ref].pop(0)
                 if not page_images[page_ref]:
                     del page_images[page_ref]
@@ -275,6 +307,157 @@ def extract_quiz(
         db.close()
 
 
+CLASSIFY_EXPIRE = 3600
+
+
+def _push_classify_step(r, job_id: str, step: str, message: str):
+    key = f"classify:steps:{job_id}"
+    entry = json.dumps({"step": step, "message": message, "ts": time.time()})
+    r.rpush(key, entry)
+    r.expire(key, CLASSIFY_EXPIRE)
+
+
+@celery_app.task(name="classify_questions", bind=True)
+def classify_questions(self, job_id: str, user_id: int):
+    """Classify untagged questions using AI — subjects, diseases, keywords."""
+    r = _redis()
+    r.set(f"classify:status:{job_id}", "running", ex=CLASSIFY_EXPIRE)
+
+    db = SessionLocal()
+    try:
+        from app.models.question import Question
+        from app.services import ai_service
+        from sqlalchemy import text as sa_text
+
+        _push_classify_step(r, job_id, "start", "Finding untagged questions...")
+
+        # Get IDs of questions that already have tags
+        tagged_ids_rows = db.execute(sa_text(
+            "SELECT DISTINCT question_id FROM question_tag_links"
+        )).fetchall()
+        tagged_ids = {row[0] for row in tagged_ids_rows}
+
+        # Get all questions not yet tagged
+        all_questions = db.query(Question).all()
+        untagged = [q for q in all_questions if q.id not in tagged_ids]
+
+        if not untagged:
+            _push_classify_step(r, job_id, "done", "All questions are already tagged.")
+            r.set(f"classify:status:{job_id}", "completed", ex=CLASSIFY_EXPIRE)
+            return
+
+        total = len(untagged)
+        _push_classify_step(r, job_id, "start", f"Found {total} untagged questions. Starting classification...")
+
+        # Get AI model for keyword task
+        model_id, api_key = ai_service.get_model_for_task(db, "keyword")
+
+        batch_size = 10
+        classified = 0
+
+        for i in range(0, total, batch_size):
+            if r.get(f"classify:status:{job_id}") == "cancelled":
+                _push_classify_step(r, job_id, "cancelled", "Job cancelled.")
+                return
+
+            batch = untagged[i:i + batch_size]
+            batch_num = (i // batch_size) + 1
+            total_batches = (total + batch_size - 1) // batch_size
+            _push_classify_step(r, job_id, "progress",
+                                f"Batch {batch_num}/{total_batches}: classifying {len(batch)} questions...")
+
+            # Build questions JSON for prompt
+            questions_json = json.dumps([
+                {"id": q.id, "question_text": q.question_text[:500]}
+                for q in batch
+            ], indent=2)
+
+            prompt = f"""Classify each medical question below. For each question, provide:
+- subjects: 1-3 medical subjects/specialties (e.g., "Cardiology", "Infectious Disease", "Neonatology")
+- diseases: 1-3 specific diseases/conditions mentioned (e.g., "Kawasaki Disease", "Pneumonia", "Type 1 Diabetes")
+- keywords: 2-4 key clinical concepts (e.g., "fever workup", "antibiotic resistance", "fluid management")
+
+Return ONLY JSON:
+{{"classifications": [
+  {{"id": <question_id>, "subjects": [...], "diseases": [...], "keywords": [...]}}
+]}}
+
+Questions:
+{questions_json}"""
+
+            try:
+                raw = ai_service._call_model(prompt, model_id, api_key)
+                # Parse JSON from response
+                text = raw.strip()
+                if text.startswith("```"):
+                    text = text.split("\n", 1)[1] if "\n" in text else text[3:]
+                    if text.endswith("```"):
+                        text = text[:-3]
+                    text = text.strip()
+                data = json.loads(text)
+                classifications = data.get("classifications", [])
+
+                # Store tags
+                for cls in classifications:
+                    q_id = cls.get("id")
+                    if not q_id:
+                        continue
+
+                    for tag_type, tag_list in [("subject", cls.get("subjects", [])),
+                                                ("disease", cls.get("diseases", [])),
+                                                ("keyword", cls.get("keywords", []))]:
+                        for tag_name in tag_list:
+                            if not tag_name or not isinstance(tag_name, str):
+                                continue
+                            normalized = tag_name.strip().title()
+                            if not normalized:
+                                continue
+
+                            # Insert tag (ON CONFLICT DO NOTHING for case-insensitive uniqueness)
+                            db.execute(sa_text("""
+                                INSERT INTO question_tags (name, type)
+                                VALUES (:name, :type)
+                                ON CONFLICT (LOWER(name), type) DO NOTHING
+                            """), {"name": normalized, "type": tag_type})
+                            db.flush()
+
+                            # Get the tag ID
+                            tag_row = db.execute(sa_text("""
+                                SELECT id FROM question_tags
+                                WHERE LOWER(name) = LOWER(:name) AND type = :type
+                            """), {"name": normalized, "type": tag_type}).fetchone()
+
+                            if tag_row:
+                                db.execute(sa_text("""
+                                    INSERT INTO question_tag_links (question_id, tag_id)
+                                    VALUES (:qid, :tid)
+                                    ON CONFLICT DO NOTHING
+                                """), {"qid": q_id, "tid": tag_row[0]})
+
+                db.commit()
+                classified += len(batch)
+                _push_classify_step(r, job_id, "progress",
+                                    f"Batch {batch_num}/{total_batches} done. {classified}/{total} classified.")
+
+            except Exception as e:
+                logger.warning(f"Classification batch {batch_num} failed: {e}")
+                _push_classify_step(r, job_id, "progress",
+                                    f"Batch {batch_num} failed: {e}. Continuing...")
+                continue
+
+        _push_classify_step(r, job_id, "done", f"Classification complete. {classified}/{total} questions classified.")
+        r.set(f"classify:status:{job_id}", "completed", ex=CLASSIFY_EXPIRE)
+
+    except Exception as e:
+        logger.exception(f"Classification failed for job {job_id}")
+        _push_classify_step(r, job_id, "error", f"Failed: {e}")
+        r.set(f"classify:status:{job_id}", "failed", ex=CLASSIFY_EXPIRE)
+        r.set(f"classify:error:{job_id}", str(e)[:500], ex=CLASSIFY_EXPIRE)
+        raise
+    finally:
+        db.close()
+
+
 @celery_app.task(name="regenerate_embeddings", bind=True)
 def regenerate_embeddings(self, job_id: str, user_id: int):
     """Regenerate embeddings for all questions using the current embedding model."""
diff --git a/docker-compose.yml b/docker-compose.yml
index c703d48..b2bf455 100644
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -18,6 +18,8 @@ services:
 
   frontend:
     build: ./frontend
+    env_file:
+      - ./frontend/.env
     ports:
       - "127.0.0.1:8081:80"
     depends_on:
diff --git a/docs/README.md b/docs/README.md
new file mode 100644
index 0000000..80eeb11
--- /dev/null
+++ b/docs/README.md
@@ -0,0 +1,19 @@
+# PedsHub Documentation
+
+Deep technical documentation for the PedsHub pediatric learning platform.
+
+## Pages
+
+| Document | Description |
+|----------|-------------|
+| [Architecture](architecture.md) | System overview, database schema, multi-worker setup, vector search, auth, rate limiting, concurrent quiz protection |
+| [API Reference](api-reference.md) | Every endpoint: method, path, auth, request/response, notes |
+| [Services](services.md) | Backend service layer: AI extraction, embedding, vector search, PDF processing, email, reminders |
+| [Frontend](frontend.md) | React app structure, pages, components, state patterns, runtime config |
+| [Deployment](deployment.md) | Docker setup, environment variables, HTTPS, rebuilding, monitoring, troubleshooting, scaling |
+
+## Quick Links
+
+- **Main README**: [../README.md](../README.md)
+- **Backend .env template**: [../backend/.env.example](../backend/.env.example)
+- **Docker Compose**: [../docker-compose.yml](../docker-compose.yml)
diff --git a/docs/api-reference.md b/docs/api-reference.md
new file mode 100644
index 0000000..4faced3
--- /dev/null
+++ b/docs/api-reference.md
@@ -0,0 +1,1051 @@
+# PedsHub API Reference
+
+Base URL: `/api`
+
+All endpoints return JSON unless noted otherwise. Authentication is via Bearer token in the `Authorization` header. Role hierarchy: **admin > moderator > user**.
+
+---
+
+## Auth (`/api/auth`)
+
+### POST `/api/auth/register`
+
+Register a new user account.
+
+- **Auth:** None
+- **Rate limit:** Turnstile verification required if configured
+- **Request body:**
+  ```json
+  {
+    "email": "string",
+    "password": "string (min 8 chars)",
+    "name": "string",
+    "turnstile_token": "string | null"
+  }
+  ```
+- **Response:**
+  - First user ever: `{"access_token": "...", "token_type": "bearer"}` (auto-admin, auto-verified)
+  - Subsequent users: `{"requires_verification": true, "message": "..."}`
+- **Notes:** Registration can be disabled by admin via settings. First registered user is always admin and auto-verified.
+
+### POST `/api/auth/login`
+
+Authenticate and receive a JWT token.
+
+- **Auth:** None
+- **Rate limit:** 10 attempts per IP per 15 minutes (Redis). Turnstile verification if configured.
+- **Request body:**
+  ```json
+  {
+    "email": "string",
+    "password": "string",
+    "turnstile_token": "string | null"
+  }
+  ```
+- **Response:** `{"access_token": "string", "token_type": "bearer"}`
+- **Errors:** 401 invalid credentials, 403 email not verified, 429 rate limited
+
+### GET `/api/auth/verify-email`
+
+Verify a user's email address via token link.
+
+- **Auth:** None
+- **Query params:** `token` (string, required)
+- **Response:** `{"message": "Email verified successfully! You can now log in."}`
+- **Errors:** 400 invalid/expired token
+
+### POST `/api/auth/resend-verification`
+
+Resend the email verification link.
+
+- **Auth:** None
+- **Request body:** `{"email": "string"}`
+- **Response:** `{"message": "If that email exists, a verification link has been sent."}`
+- **Notes:** Deliberately vague response to prevent email enumeration.
+
+### POST `/api/auth/forgot-password`
+
+Request a password reset link.
+
+- **Auth:** None
+- **Rate limit:** 3 reset requests per email per hour
+- **Request body:** `{"email": "string"}`
+- **Response:** `{"message": "If that email is registered, a reset link has been sent."}`
+- **Notes:** Deliberately vague response to prevent email enumeration. Sends email in background.
+
+### POST `/api/auth/reset-password`
+
+Reset password using a valid token.
+
+- **Auth:** None
+- **Request body:**
+  ```json
+  {
+    "token": "string",
+    "new_password": "string (min 8 chars)"
+  }
+  ```
+- **Response:** `{"message": "Password reset successfully. You can now log in."}`
+- **Errors:** 400 invalid/expired/used token
+
+### GET `/api/auth/me`
+
+Get the current authenticated user's profile.
+
+- **Auth:** User
+- **Response:** `UserResponse` — `{id, email, name, role, created_at}`
+
+### PUT `/api/auth/me`
+
+Update current user's profile (name, password).
+
+- **Auth:** User
+- **Request body:**
+  ```json
+  {
+    "name": "string | null",
+    "current_password": "string | null (required to change password)",
+    "new_password": "string | null (min 8 chars)"
+  }
+  ```
+- **Response:** `UserResponse`
+
+### GET `/api/auth/me/settings`
+
+Get user settings stored in Redis (e.g. Nextcloud config).
+
+- **Auth:** User
+- **Response:** `{}` or a JSON object of user settings
+
+### PUT `/api/auth/me/settings`
+
+Save user settings to Redis.
+
+- **Auth:** User
+- **Request body:** Any JSON object
+- **Response:** `{"saved": true}`
+
+---
+
+## Documents (`/api/documents`)
+
+### POST `/api/documents/upload`
+
+Upload a PDF document for processing.
+
+- **Auth:** Moderator
+- **Content-Type:** `multipart/form-data`
+- **Request:** `file` (PDF, max size from `MAX_UPLOAD_SIZE` setting)
+- **Response:** `DocumentResponse` — `{id, user_id, filename, original_filename, status, total_pages, error_message, uploaded_at}`
+- **Notes:** Processing dispatched to Celery (falls back to sync). Status starts as `"processing"`.
+
+### GET `/api/documents/`
+
+List all documents. Moderators see all; regular users see only their own.
+
+- **Auth:** User
+- **Response:** `DocumentResponse[]`
+
+### GET `/api/documents/{document_id}`
+
+Get a single document by ID.
+
+- **Auth:** User (own documents only; moderators can access any)
+- **Response:** `DocumentResponse`
+- **Errors:** 404
+
+### GET `/api/documents/{document_id}/status`
+
+Poll document processing status.
+
+- **Auth:** User (own documents only; moderators can access any)
+- **Response:** `{id, status, total_pages, error_message}`
+
+### GET `/api/documents/{document_id}/processing-steps`
+
+Get PDF processing progress steps from Redis.
+
+- **Auth:** User (own documents only; moderators can access any)
+- **Response:** `{"steps": [{step object}, ...]}`
+- **Notes:** Steps are stored in Redis list `pdf:steps:{document_id}`.
+
+### POST `/api/documents/{document_id}/sections`
+
+Create a named page range section within a document.
+
+- **Auth:** Moderator
+- **Request body:**
+  ```json
+  {
+    "name": "string",
+    "start_page": "int (>= 1)",
+    "end_page": "int (> start_page, <= total_pages)"
+  }
+  ```
+- **Response:** `SectionResponse` — `{id, document_id, name, start_page, end_page}`
+- **Errors:** 400 if document not ready, invalid page range
+
+### DELETE `/api/documents/{document_id}/sections/{section_id}`
+
+Delete a section.
+
+- **Auth:** Moderator
+- **Response:** 204 No Content
+
+### DELETE `/api/documents/{document_id}`
+
+Delete a document, its file, and its ChromaDB vector collection.
+
+- **Auth:** Moderator
+- **Response:** 204 No Content
+
+---
+
+## Quizzes (`/api/quizzes`)
+
+### POST `/api/quizzes/`
+
+Start async quiz extraction from a document section.
+
+- **Auth:** Moderator
+- **Request body:**
+  ```json
+  {
+    "section_id": "int",
+    "title": "string",
+    "mode": "timed | learning",
+    "time_limit_minutes": "int | null",
+    "model_id": "int | null (AIModelConfig.id)",
+    "question_category_id": "int | null",
+    "extraction_mode": "string | null (standard, questions_only, two_step, regex, ai_decide, generate)"
+  }
+  ```
+- **Response:** `{"job_id": "uuid", "status": "pending"}`
+- **Notes:** Poll `/api/quizzes/job/{job_id}` for progress. Falls back to sync if Celery unavailable.
+
+### GET `/api/quizzes/jobs`
+
+List all recent extraction jobs for the current user (any browser session).
+
+- **Auth:** User
+- **Response:**
+  ```json
+  [
+    {
+      "job_id": "uuid",
+      "title": "string",
+      "status": "pending | running | completed | failed | cancelled",
+      "steps_count": "int",
+      "last_step": "string (truncated to 80 chars)",
+      "quiz_id": "int | null"
+    }
+  ]
+  ```
+
+### GET `/api/quizzes/job/{job_id}`
+
+Poll extraction job progress.
+
+- **Auth:** Moderator
+- **Response:** `{"job_id", "status", "steps": [...], "quiz_id" (if completed), "error" (if failed)}`
+
+### POST `/api/quizzes/job/{job_id}/cancel`
+
+Cancel a running extraction job.
+
+- **Auth:** User (must own the job)
+- **Response:** `{"status": "cancelled"}`
+- **Errors:** 403 if not owner, 400 if not running
+
+### GET `/api/quizzes/search`
+
+Hybrid semantic + keyword search across quiz titles and questions.
+
+- **Auth:** User
+- **Query params:**
+  - `q` (string, required, 2-200 chars)
+  - `mode` (string: `"title"` | `"questions"` | `"all"`, default `"all"`)
+- **Response:** Array of search results with `quiz_id`, `quiz_title`, `match_type`, `matching_questions[]`
+- **Notes:** Uses pgvector cosine similarity (threshold 0.30) for semantic search, plus ILIKE for keyword matching.
+
+### GET `/api/quizzes/`
+
+List all quizzes. Moderators see all (non-deleted); regular users see only published.
+
+- **Auth:** User
+- **Response:** `QuizResponse[]` — `{id, section_id, user_id, title, questions_count, mode, time_limit_minutes, is_published, created_at}`
+
+### GET `/api/quizzes/{quiz_id}`
+
+Get a quiz for taking. Learning-mode quizzes include answers/explanations.
+
+- **Auth:** User
+- **Query params:** `study` (bool, default false) — forces answers/explanations to be included
+- **Response:** `QuizDetail` (timed) or `QuizLearningDetail` (learning/study)
+- **Notes:** Excludes soft-deleted quizzes.
+
+### PATCH `/api/quizzes/{quiz_id}`
+
+Update quiz metadata (title).
+
+- **Auth:** Moderator
+- **Request body:** `{"title": "string"}`
+- **Response:** `QuizResponse`
+
+### POST `/api/quizzes/{quiz_id}/shuffle`
+
+Return quiz with shuffled question and option order (does not modify DB).
+
+- **Auth:** User
+- **Query params:** `shuffle_options` (bool, default true)
+- **Response:** `QuizDetail` with shuffled questions
+
+### GET `/api/quizzes/{quiz_id}/review`
+
+Get quiz with full answers. Requires a completed attempt (or moderator role).
+
+- **Auth:** User (must have completed attempt) or Moderator
+- **Response:** `QuizReview`
+
+### GET `/api/quizzes/{quiz_id}/questions`
+
+Get all questions with answers for editing.
+
+- **Auth:** Moderator
+- **Response:** Array of `{id, question_text, question_type, options, correct_answer, explanation}`
+
+### PATCH `/api/quizzes/{quiz_id}/questions/{question_id}`
+
+Update a question. Changes are shared across all quizzes referencing this question.
+
+- **Auth:** Moderator
+- **Request body:** Any of `{question_text, options, correct_answer, explanation, question_type}`
+- **Response:** Updated question object
+- **Errors:** 400 if correct_answer does not match one of the options
+
+### DELETE `/api/quizzes/{quiz_id}/questions/{question_id}`
+
+Remove a question from this quiz. If shared with other quizzes, only the link is removed. If exclusive, the question is deleted from the bank.
+
+- **Auth:** Moderator
+- **Response:** 204 No Content
+
+### PATCH `/api/quizzes/{quiz_id}/publish`
+
+Show or hide a quiz for regular users.
+
+- **Auth:** Moderator
+- **Query params:** `published` (bool, default true)
+- **Response:** `{"quiz_id": int, "is_published": int}`
+
+### GET `/api/quizzes/trash`
+
+List soft-deleted quizzes.
+
+- **Auth:** Moderator
+- **Response:** `QuizResponse[]`
+
+### DELETE `/api/quizzes/{quiz_id}`
+
+Soft-delete a quiz (move to trash).
+
+- **Auth:** Moderator
+- **Response:** 204 No Content
+
+### PATCH `/api/quizzes/{quiz_id}/restore`
+
+Restore a soft-deleted quiz from trash.
+
+- **Auth:** Moderator
+- **Response:** `QuizResponse`
+
+### DELETE `/api/quizzes/{quiz_id}/permanent`
+
+Permanently delete a quiz that is already in trash. Exclusive questions are orphaned to the bank.
+
+- **Auth:** Moderator
+- **Response:** 204 No Content
+- **Errors:** 400 if quiz is not in trash
+
+---
+
+## Questions (`/api/questions`)
+
+### GET `/api/questions/bank`
+
+List all questions across all quizzes with filtering, search, and pagination.
+
+- **Auth:** User
+- **Query params:**
+  - `q` (string, optional) — keyword/semantic search
+  - `quiz_id` (int, optional) — filter by source quiz
+  - `category_id` (int, optional) — filter by question category
+  - `category_ids` (string, optional) — comma-separated category IDs (OR filter)
+  - `uncategorized` (bool, default false)
+  - `favorites_only` (bool, default false)
+  - `tag_ids` (string, optional) — comma-separated tag IDs (AND filter)
+  - `search_mode` (string: `"keyword"` | `"semantic"` | `"hybrid"`, default `"hybrid"`)
+  - `limit` (int, default 50, max 200)
+  - `offset` (int, default 0)
+- **Response:**
+  ```json
+  {
+    "total": "int",
+    "questions": [
+      {
+        "id": "int",
+        "quiz_id": "int",
+        "quiz_title": "string",
+        "question_category_id": "int | null",
+        "question_category_name": "string | null",
+        "question_text": "string",
+        "question_type": "string",
+        "options": ["string"],
+        "correct_answer": "string",
+        "explanation": "string",
+        "image_path": "string | null"
+      }
+    ]
+  }
+  ```
+- **Notes:** Hybrid search returns semantic matches first (pgvector cosine similarity >= 0.55), then keyword matches.
+
+### GET `/api/questions/bank/ids`
+
+Return just question IDs for all matching questions (for server-side select-all).
+
+- **Auth:** User
+- **Query params:** Same filters as `/bank` (except `limit`, `offset`, `search_mode`)
+- **Response:** `[int]`
+
+### PATCH `/api/questions/{question_id}/category`
+
+Assign or remove a question category.
+
+- **Auth:** Moderator
+- **Query params:** `category_id` (int | null)
+- **Response:** `{"question_id": int, "question_category_id": int | null}`
+
+### POST `/api/questions/from-bank`
+
+Create a new quiz by referencing existing bank questions (no copying -- edits propagate).
+
+- **Auth:** Moderator
+- **Request body:**
+  ```json
+  {
+    "title": "string",
+    "question_ids": [1, 2, 3],
+    "mode": "timed | learning",
+    "time_limit_minutes": "int | null"
+  }
+  ```
+- **Response:** `{"id": int, "title": "string", "questions_count": int}`
+
+### POST `/api/questions/bulk-category`
+
+Assign or remove a category from multiple questions at once.
+
+- **Auth:** Moderator
+- **Request body:**
+  ```json
+  {
+    "question_ids": [1, 2, 3],
+    "category_id": "int | null"
+  }
+  ```
+- **Response:** `{"updated": int, "question_category_id": int | null}`
+
+---
+
+## Attempts (`/api/attempts`)
+
+### POST `/api/attempts/start`
+
+Start a new quiz attempt (or resume the most recent incomplete one).
+
+- **Auth:** User
+- **Query params:**
+  - `quiz_id` (int, required)
+  - `fresh` (bool, default false) — force a new attempt even if one is in progress
+- **Response:** `AttemptResponse` — `{id, quiz_id, score, total_questions, percentage, started_at, completed_at}`
+
+### POST `/api/attempts/{attempt_id}/submit`
+
+Submit answers for a quiz attempt.
+
+- **Auth:** User (must own the attempt)
+- **Request body:**
+  ```json
+  {
+    "answers": [
+      {"question_id": "int", "user_answer": "string"}
+    ]
+  }
+  ```
+- **Response:** `AttemptDetail` — includes `answers[]` with full review (question text, options, user answer, correct answer, is_correct, explanation)
+- **Notes:** Updates spaced repetition reminder schedule. Clears saved progress from Redis. Unanswered questions are marked incorrect.
+
+### GET `/api/attempts/`
+
+List all attempts for the current user.
+
+- **Auth:** User
+- **Query params:** `quiz_id` (int, optional)
+- **Response:** `AttemptResponse[]`
+
+### GET `/api/attempts/{attempt_id}`
+
+Get a specific attempt with full answer details.
+
+- **Auth:** User (must own the attempt)
+- **Response:** `AttemptDetail`
+
+### GET `/api/attempts/stats/dashboard`
+
+Get dashboard statistics for the current user.
+
+- **Auth:** User
+- **Response:**
+  ```json
+  {
+    "total_documents": "int",
+    "total_quizzes": "int (distinct quizzes attempted)",
+    "total_attempts": "int",
+    "average_score": "float",
+    "quiz_stats": [
+      {
+        "quiz_id": "int",
+        "quiz_title": "string",
+        "attempts_count": "int",
+        "best_score": "float",
+        "latest_score": "float",
+        "average_score": "float"
+      }
+    ]
+  }
+  ```
+
+### GET `/api/attempts/history`
+
+Get per-quiz attempt history for the performance line graph.
+
+- **Auth:** User
+- **Response:**
+  ```json
+  [
+    {
+      "quiz_id": "int",
+      "title": "string",
+      "attempts": [
+        {"attempt_id": "int", "date": "ISO string", "percentage": "float", "score": "int", "total": "int"}
+      ]
+    }
+  ]
+  ```
+
+### GET `/api/attempts/in-progress`
+
+Return all incomplete (not yet submitted) attempts for the current user.
+
+- **Auth:** User
+- **Response:**
+  ```json
+  [
+    {
+      "attempt_id": "int",
+      "quiz_id": "int",
+      "quiz_title": "string",
+      "total_questions": "int",
+      "started_at": "ISO string"
+    }
+  ]
+  ```
+
+### GET `/api/attempts/{attempt_id}/in-progress`
+
+Return the latest incomplete attempt for a specific quiz.
+
+- **Auth:** User
+- **Query params:** `quiz_id` (int, required)
+- **Response:** `AttemptResponse | null`
+
+### POST `/api/attempts/progress`
+
+Save in-progress quiz answers to Redis (survives logout/browser change).
+
+- **Auth:** User
+- **Headers:** `x-quiz-session` (optional, for device session lock)
+- **Request body:**
+  ```json
+  {
+    "quiz_id": "int",
+    "attempt_id": "int",
+    "answers": {"question_id": "answer"},
+    "current_idx": "int",
+    "mode": "string",
+    "voice": "string | null",
+    "time_left": "int | null",
+    "started_at": "string | null (ISO timestamp)",
+    "total_time": "int | null (seconds)"
+  }
+  ```
+- **Response:** `{"saved": true}`
+- **Notes:** Progress expires after 7 days. Session lock (30s TTL) prevents concurrent resume on another device.
+
+### GET `/api/attempts/progress`
+
+Retrieve saved progress for a quiz. Auto-submits timed quizzes if timer expired.
+
+- **Auth:** User
+- **Headers:** `x-quiz-session` (optional, for device session lock)
+- **Query params:** `quiz_id` (int, required)
+- **Response:** Saved progress object or `null`
+- **Errors:** 409 if another device is actively using this attempt
+
+### DELETE `/api/attempts/progress/{attempt_id}`
+
+Clear saved progress.
+
+- **Auth:** User
+- **Response:** 204 No Content
+
+### DELETE `/api/attempts/{attempt_id}`
+
+Delete an attempt, its answers, and associated reminder schedule.
+
+- **Auth:** User (must own the attempt)
+- **Response:** 204 No Content
+
+---
+
+## Tags (`/api/tags`)
+
+### GET `/api/tags`
+
+Get all tags grouped by type (subjects, diseases, keywords), with question counts.
+
+- **Auth:** User
+- **Response:**
+  ```json
+  {
+    "subjects": [{"id": "int", "name": "string", "count": "int"}],
+    "diseases": [{"id": "int", "name": "string", "count": "int"}],
+    "keywords": [{"id": "int", "name": "string", "count": "int"}]
+  }
+  ```
+
+### POST `/api/tags/classify`
+
+Trigger background AI classification of untagged questions.
+
+- **Auth:** Moderator
+- **Response:** `{"job_id": "uuid", "status": "started"}`
+
+### GET `/api/tags/status/{job_id}`
+
+Check classification job progress.
+
+- **Auth:** User
+- **Response:** `{"job_id": "string", "status": "string", "steps": [...], "error": "string | null"}`
+
+---
+
+## Teach (`/api/teach`)
+
+### GET `/api/teach/models`
+
+Return available teach AI models.
+
+- **Auth:** User
+- **Response:** `[{"id": int, "name": "string", "model_id": "string", "is_default": bool}]`
+
+### POST `/api/teach/chat`
+
+Send a message to the AI tutor with full question context.
+
+- **Auth:** User
+- **Rate limit:** 30 messages per user per 10 minutes (admins and unthrottled users exempt)
+- **Request body:**
+  ```json
+  {
+    "question_id": "int",
+    "messages": [
+      {"role": "user | assistant", "content": "string"}
+    ],
+    "model_id": "int | null (AIModelConfig.id)"
+  }
+  ```
+- **Response:** `{"reply": "string (markdown)", "suggestions": ["string", "string", "string"]}`
+- **Notes:** System prompt includes the question, correct answer, explanation, and up to 4 semantically similar questions for broader context. Follow-up suggestions are parsed from lines starting with `> `.
+- **Errors:** 503 if no teach model configured, 502 if AI temporarily unavailable
+
+---
+
+## TTS (`/api/tts`)
+
+### GET `/api/tts/voices`
+
+Return available TTS voices. Excludes Polly voices if Polly is disabled.
+
+- **Auth:** User
+- **Response:** `[{"id": "string (model_id)", "name": "string", "is_default": bool}]`
+
+### POST `/api/tts/speak`
+
+Convert text to speech audio.
+
+- **Auth:** User
+- **Rate limit:** 60 requests per user per hour (admins and unthrottled users exempt)
+- **Request body:**
+  ```json
+  {
+    "text": "string (max 2000 chars)",
+    "voice": "string | null (model_id override)"
+  }
+  ```
+- **Response:** Binary `audio/mpeg` data
+- **Notes:** Supports OpenAI TTS (`tts-1:alloy`), ElevenLabs (`elevenlabs/<voice_id>`), Google Cloud TTS (`google/<voice_name>`), and AWS Polly (`polly/<VoiceId>`).
+
+---
+
+## Favorites (`/api/favorites`)
+
+### POST `/api/favorites`
+
+Add a question to the current user's favorites.
+
+- **Auth:** User
+- **Request body:** `{"question_id": "int"}`
+- **Response (201):** `FavoriteResponse` — `{id, user_id, question_id, created_at}`
+- **Notes:** Idempotent -- returns existing favorite if already favorited.
+
+### DELETE `/api/favorites/{question_id}`
+
+Remove a question from favorites.
+
+- **Auth:** User
+- **Response:** 204 No Content
+
+### GET `/api/favorites`
+
+Get list of favorited question IDs for the current user.
+
+- **Auth:** User
+- **Response:** `[int]`
+
+---
+
+## Categories (`/api/categories`)
+
+Quiz-level categories for organizing quizzes.
+
+### GET `/api/categories/`
+
+List all quiz categories with quiz counts.
+
+- **Auth:** User
+- **Response:** `[{"id": int, "name": "string", "quiz_count": int}]`
+
+### POST `/api/categories/`
+
+Create a new quiz category.
+
+- **Auth:** Moderator
+- **Request body:** `{"name": "string"}`
+- **Response:** `CategoryResponse`
+
+### DELETE `/api/categories/{category_id}`
+
+Delete a quiz category. Unassigns all quizzes in the category.
+
+- **Auth:** Moderator
+- **Response:** 204 No Content
+
+### PATCH `/api/categories/quizzes/{quiz_id}`
+
+Assign or remove a category from a quiz.
+
+- **Auth:** Moderator
+- **Query params:** `category_id` (int | null)
+- **Response:** `{"quiz_id": int, "category_id": int | null}`
+
+---
+
+## Question Categories (`/api/question-categories`)
+
+Question-level categories for organizing the question bank.
+
+### GET `/api/question-categories/`
+
+List all question categories with question counts.
+
+- **Auth:** User
+- **Response:** `[{"id": int, "name": "string", "description": "string | null", "question_count": int}]`
+
+### POST `/api/question-categories/`
+
+Create a new question category.
+
+- **Auth:** Moderator
+- **Request body:** `{"name": "string", "description": "string | null"}`
+- **Response:** `QCatResponse`
+
+### PATCH `/api/question-categories/{cat_id}`
+
+Update a question category.
+
+- **Auth:** Moderator
+- **Request body:** `{"name": "string", "description": "string | null"}`
+- **Response:** `QCatResponse`
+
+### DELETE `/api/question-categories/{cat_id}`
+
+Delete a question category. Optionally move its questions to another category.
+
+- **Auth:** Moderator
+- **Query params:** `move_to` (int | null) -- target category ID, or null to uncategorize
+- **Response:** 204 No Content
+
+### POST `/api/question-categories/{cat_id}/create-quiz`
+
+Create a new quiz from all questions in a question category.
+
+- **Auth:** Moderator
+- **Query params:**
+  - `title` (string, required)
+  - `mode` (string: `"timed"` | `"learning"`, default `"timed"`)
+  - `time_limit_minutes` (int | null)
+- **Response:** `{"id": int, "title": "string", "questions_count": int}`
+
+---
+
+## Contact (`/api/contact`)
+
+### POST `/api/contact`
+
+Submit a contact form (public, no auth).
+
+- **Auth:** None
+- **Request body:**
+  ```json
+  {
+    "name": "string (max 120)",
+    "email": "valid email",
+    "type": "question | moderator",
+    "message": "string (max 2000)",
+    "turnstile_token": "string | null"
+  }
+  ```
+- **Response:** `{"success": true}`
+- **Notes:** Stores submission in DB and emails admin. Turnstile verification if configured.
+
+### GET `/api/contact/submissions`
+
+List all contact submissions.
+
+- **Auth:** Admin (enforced in endpoint body, not decorator)
+- **Response:** `[{id, name, email, type, message, read, created_at}]`
+
+### PUT `/api/contact/submissions/{submission_id}/read`
+
+Mark a contact submission as read.
+
+- **Auth:** Admin (enforced in endpoint body, not decorator)
+- **Response:** `{"success": true}`
+
+---
+
+## Admin (`/api/admin`)
+
+### User Management
+
+#### GET `/api/admin/users`
+
+List all users.
+
+- **Auth:** Admin
+- **Response:** `UserResponse[]`
+
+#### POST `/api/admin/users`
+
+Create a user directly (email auto-verified).
+
+- **Auth:** Admin
+- **Request body:** `{"email": "string", "password": "string", "name": "string"}`
+- **Response:** `UserResponse`
+
+#### PUT `/api/admin/users/{user_id}/role`
+
+Change a user's role.
+
+- **Auth:** Admin
+- **Request body:** `{"role": "admin | moderator | user"}`
+- **Response:** `UserResponse`
+- **Errors:** 400 cannot change own role
+
+#### PUT `/api/admin/users/{user_id}/unthrottle`
+
+Set or clear the unthrottle flag (exempt from AI/TTS rate limits).
+
+- **Auth:** Admin
+- **Request body:** `{"unthrottled": true | false}`
+- **Response:** `UserResponse`
+
+#### DELETE `/api/admin/users/{user_id}`
+
+Delete a user and all their data.
+
+- **Auth:** Admin
+- **Response:** 204 No Content
+- **Errors:** 400 cannot delete yourself
+
+### AI Model Configuration
+
+#### GET `/api/admin/models/available`
+
+List active models for a task (for users when creating/taking quizzes).
+
+- **Auth:** User
+- **Query params:** `task` (string, default `"extraction"`)
+- **Response:** `[{"id": int | null, "name": "string", "model_id": "string", "is_default": bool}]`
+- **Notes:** Falls back to env `LITELLM_MODEL` if nothing configured.
+
+#### GET `/api/admin/models`
+
+List all AI model configurations.
+
+- **Auth:** Admin
+- **Response:** `AIModelConfigResponse[]` -- `{id, name, model_id, task, is_active, is_default, api_key (masked)}`
+
+#### POST `/api/admin/models`
+
+Create an AI model configuration.
+
+- **Auth:** Admin
+- **Request body:**
+  ```json
+  {
+    "name": "string",
+    "model_id": "string",
+    "task": "extraction | tts | teach | keyword",
+    "is_active": "bool",
+    "is_default": "bool",
+    "api_key": "string | null"
+  }
+  ```
+- **Response:** `AIModelConfigResponse`
+- **Notes:** Auto-sets as default if first model for that task. Unique constraint on (model_id, task).
+
+#### PUT `/api/admin/models/{model_id}`
+
+Update an AI model configuration.
+
+- **Auth:** Admin
+- **Request body:** Partial `AIModelConfigUpdate`
+- **Response:** `AIModelConfigResponse`
+
+#### DELETE `/api/admin/models/{model_id}`
+
+Delete an AI model configuration.
+
+- **Auth:** Admin
+- **Response:** 204 No Content
+
+#### POST `/api/admin/models/{model_id}/test`
+
+Send a test completion to verify an LLM model is reachable.
+
+- **Auth:** Admin
+- **Response:** `{"message": "model_id -> 'OK'"}`
+- **Errors:** 400 for TTS models (use Preview button instead), 502 if unreachable
+
+#### POST `/api/admin/litellm/models`
+
+Query available models from LiteLLM proxy or OpenAI-compatible API.
+
+- **Auth:** Admin
+- **Request body:** `{"api_key": "string | null", "api_base": "string | null"}`
+- **Response:** `{"models": ["string"], "source": "string"}`
+
+### TTS Voice Search
+
+#### POST `/api/admin/tts/voices`
+
+Discover available TTS voices from a provider.
+
+- **Auth:** Admin
+- **Request body:**
+  ```json
+  {
+    "provider": "elevenlabs | polly | openai",
+    "api_key": "string | null",
+    "region": "string | null"
+  }
+  ```
+- **Response:** `{"voices": [{"model_id": "string", "name": "string", "labels": {}}]}`
+- **Notes:** OpenAI returns hardcoded list of tts-1 and tts-1-hd voices.
+
+### System Settings
+
+#### GET `/api/admin/settings`
+
+Get system settings (registration enabled, embedding model, Polly enabled).
+
+- **Auth:** Admin
+- **Response:** `{"registration_enabled": bool, "embedding_model": "string", "polly_enabled": bool}`
+
+#### PUT `/api/admin/settings`
+
+Update system settings.
+
+- **Auth:** Admin
+- **Request body:** `{"registration_enabled": bool, "embedding_model": "string", "polly_enabled": bool}`
+- **Response:** `{"success": true, "message": "Settings updated"}`
+
+### Embedding Management
+
+#### POST `/api/admin/embedding/test`
+
+Test the currently configured embedding model.
+
+- **Auth:** Admin
+- **Response:** `{"model": "string", "dimensions": int, "status": "ok"}`
+
+#### POST `/api/admin/embedding/regenerate`
+
+Queue a Celery task to regenerate all question embeddings.
+
+- **Auth:** Admin
+- **Response:** `{"job_id": "uuid", "message": "Regeneration started..."}`
+
+---
+
+## Nextcloud (`/api/nextcloud`)
+
+WebDAV proxy for importing PDFs from Nextcloud (avoids browser CORS issues).
+
+### POST `/api/nextcloud/test`
+
+Test Nextcloud credentials.
+
+- **Auth:** Moderator
+- **Request body:** `{"server": "string", "username": "string", "password": "string", "path": "/"}`
+- **Response:** `{"ok": true, "message": "Connected successfully"}`
+
+### POST `/api/nextcloud/files`
+
+List PDFs and folders at a given Nextcloud path.
+
+- **Auth:** Moderator
+- **Request body:** `{"server": "string", "username": "string", "password": "string", "path": "/"}`
+- **Response:** `{"path": "string", "items": [{"name", "path", "type": "dir | pdf", "size"}]}`
+
+### POST `/api/nextcloud/download`
+
+Download a PDF from Nextcloud and stream it back.
+
+- **Auth:** Moderator
+- **Request body:** `{"server": "string", "username": "string", "password": "string", "path": "/some/file.pdf"}`
+- **Response:** Streamed `application/pdf` binary
+- **Errors:** 400 if not a PDF file
diff --git a/docs/architecture.md b/docs/architecture.md
new file mode 100644
index 0000000..05bf5d3
--- /dev/null
+++ b/docs/architecture.md
@@ -0,0 +1,533 @@
+# PedsHub Architecture
+
+Deep technical documentation for the PedsHub platform internals.
+
+## System Overview
+
+```
+                          ┌───────────────────────┐
+                          │       Browser          │
+                          │  (React 18 SPA / PWA)  │
+                          └───────────┬────────────┘
+                                      │ HTTPS
+                          ┌───────────▼────────────┐
+                          │   Caddy / Nginx (TLS)  │
+                          └───────────┬────────────┘
+                                      │ :8081
+                ┌─────────────────────▼─────────────────────┐
+                │         Nginx (frontend container)         │
+                │  static files + /api proxy to backend:8000 │
+                └──────┬──────────────────────┬─────────────┘
+                       │                      │
+              static assets           /api/* proxy
+              + config.js                     │
+                                ┌─────────────▼──────────────┐
+                                │  FastAPI (4 uvicorn workers) │
+                                └──┬────┬────┬────┬────┬─────┘
+                                   │    │    │    │    │
+                    ┌──────────────┘    │    │    │    └──────────────┐
+                    ▼                   ▼    │    ▼                   ▼
+              ┌──────────┐     ┌───────────┐ │ ┌─────────┐   ┌──────────────┐
+              │PostgreSQL│     │   Redis   │ │ │ChromaDB │   │  LiteLLM     │
+              │16+pgvector│    │  7-alpine │ │ │(embedded)│  │  proxy       │
+              └──────────┘     └─────┬─────┘ │ └─────────┘   └──────────────┘
+                                     │       │
+                               ┌─────▼─────┐ │
+                               │  Celery   │ │
+                               │ (4 fork   │ │
+                               │  workers) │ │
+                               └───────────┘ │
+                                             │
+                          ┌──────────────────┘
+                          ▼
+              ┌───────────────────────┐
+              │  External Services    │
+              │  - OpenAI (TTS)       │
+              │  - AWS Bedrock/Polly  │
+              │  - ElevenLabs         │
+              │  - Google Cloud TTS   │
+              │  - Cloudflare (CAPTCHA│
+              │  - SMTP (email)       │
+              └───────────────────────┘
+```
+
+## Request Flow
+
+```
+Browser
+  → HTTPS request
+  → Caddy/Nginx (TLS termination)
+  → Nginx (frontend container, port 80)
+      ├─ Static files: served directly (React SPA, config.js, icons)
+      └─ /api/*: reverse-proxied to backend:8000
+          → FastAPI (one of 4 uvicorn workers)
+              ├─ JWT auth middleware (validates token, refreshes if stale)
+              ├─ Route handler
+              │   ├─ PostgreSQL (SQLAlchemy ORM) — reads/writes
+              │   ├─ Redis — rate limit checks, session locks, settings
+              │   ├─ ChromaDB — RAG context retrieval
+              │   └─ LiteLLM proxy — AI completions (async)
+              └─ Response (JSON)
+          ← Backend response
+      ← Proxied response (+ CSP headers added by Nginx)
+  ← HTTPS response
+```
+
+For background jobs (PDF processing, quiz extraction, classification), the FastAPI handler enqueues a Celery task and returns a `job_id` immediately. The frontend polls Redis for progress steps.
+
+## Docker Services
+
+### postgres
+
+- **Image**: `pgvector/pgvector:pg16`
+- **Purpose**: Primary data store — users, documents, quizzes, questions, attempts, tags
+- **Extensions**: `vector` (pgvector) for 1024-dimensional question embeddings with HNSW index
+- **Volume**: `postgres_data` (persistent)
+- **Healthcheck**: `pg_isready -U pedquiz` every 5s
+
+### redis
+
+- **Image**: `redis:7-alpine`
+- **Purpose**: Celery broker, rate limiting, runtime settings, quiz progress state, extraction step logs, singleton lock, quiz session locks
+- **Volume**: `redis_data` (persistent)
+
+### backend
+
+- **Build**: `./backend/Dockerfile`
+- **Command**: `uvicorn app.main:app --host 0.0.0.0 --port 8000 --workers 4`
+- **Depends on**: postgres (healthy), redis (started)
+- **Volumes**: `uploads_data` (PDFs + extracted images), `chroma_data` (ChromaDB persistence)
+- **Key env vars**: `DATABASE_URL`, `REDIS_URL`, `SECRET_KEY`, `LITELLM_*`, `OPENAI_API_KEY`, `AWS_*`, `MAIL_*`, `TURNSTILE_SECRET_KEY`
+
+### celery
+
+- **Build**: `./backend/Dockerfile` (same image as backend)
+- **Command**: `celery -A app.tasks worker --loglevel=info --concurrency=4`
+- **Purpose**: Background task execution — PDF processing, quiz extraction, tag classification, embedding regeneration
+- **Depends on**: postgres (healthy), redis (started)
+- **Volumes**: Same as backend (needs access to uploads and ChromaDB)
+
+### frontend
+
+- **Build**: `./frontend/Dockerfile`
+- **Entrypoint**: `docker-entrypoint.sh` generates `/config.js` from env vars at startup
+- **Port**: `127.0.0.1:8081:80`
+- **Depends on**: backend
+- **Nginx config**: Serves static files, proxies `/api/*` to backend, sets CSP headers
+
+## Database Schema
+
+### Core Tables
+
+```
+users
+├── id (PK)
+├── email (unique, collation "C")
+├── hashed_password (bcrypt)
+├── name
+├── role ("admin" | "moderator" | "user")
+├── is_unthrottled (0 | 1)
+└── created_at
+
+pdf_documents
+├── id (PK)
+├── user_id → users(id) ON DELETE CASCADE
+├── filename (stored name)
+├── original_filename
+├── total_pages
+├── status ("processing" | "ready" | "error")
+├── error_message
+└── uploaded_at
+
+sections
+├── id (PK)
+├── document_id → pdf_documents(id) ON DELETE CASCADE
+├── name
+├── start_page
+└── end_page
+
+quizzes
+├── id (PK)
+├── section_id → sections(id) ON DELETE SET NULL  ← section deletion preserves quiz
+├── user_id → users(id)
+├── category_id → quiz_categories(id) ON DELETE SET NULL
+├── title
+├── questions_count
+├── time_limit_minutes (nullable)
+├── mode ("timed" | "learning")
+├── skipped_questions (JSON text)
+├── deleted_at (soft delete)
+├── is_published (0 | 1)
+└── created_at
+
+questions
+├── id (PK)
+├── quiz_id (source_quiz_id) → quizzes(id) ON DELETE SET NULL  ← informational origin
+├── question_category_id → question_categories(id) ON DELETE SET NULL
+├── question_text
+├── question_type ("mcq" | "true_false" | "fill_blank")
+├── options (JSON array)
+├── correct_answer
+├── explanation
+├── page_reference
+├── image_path
+└── embedding (vector(1024), deferred load, HNSW index)
+```
+
+### Junction and Link Tables
+
+```
+quiz_question_links (many-to-many: quizzes ↔ questions)
+├── quiz_id (PK) → quizzes(id) ON DELETE CASCADE
+├── question_id (PK) → questions(id) ON DELETE CASCADE
+└── position
+
+quiz_attempts
+├── id (PK)
+├── quiz_id → quizzes(id) ON DELETE CASCADE
+├── user_id → users(id) ON DELETE CASCADE
+├── score
+├── total_questions
+├── started_at
+└── completed_at
+
+attempt_answers
+├── id (PK)
+├── attempt_id → quiz_attempts(id) ON DELETE CASCADE
+├── question_id → questions(id) ON DELETE CASCADE
+├── user_answer
+└── is_correct
+```
+
+### Tag System
+
+```
+question_tags
+├── id (PK)
+├── name (varchar 200)
+├── type ("subject" | "disease" | "keyword")
+├── created_at
+└── UNIQUE INDEX on (LOWER(name), type)  ← case-insensitive dedup
+
+question_tag_links (many-to-many: questions ↔ tags)
+├── question_id (PK) → questions(id) ON DELETE CASCADE
+└── tag_id (PK) → question_tags(id) ON DELETE CASCADE
+```
+
+### Category Tables
+
+```
+quiz_categories
+├── id (PK)
+├── name
+├── user_id → users(id)
+└── created_at
+
+question_categories
+├── id (PK)
+├── name
+├── description
+├── user_id → users(id)
+└── created_at
+```
+
+### Auth and Lifecycle Tables
+
+```
+email_verifications
+├── id (PK)
+├── user_id → users(id) ON DELETE CASCADE (unique)
+├── token (unique, indexed)
+├── expires_at
+├── verified_at (null until verified)
+└── created_at
+
+password_resets
+├── id (PK)
+├── user_id → users(id) ON DELETE CASCADE
+├── token (unique, indexed)
+├── expires_at
+├── used (boolean)
+└── created_at
+
+favorites
+├── id (PK)
+├── user_id → users(id) ON DELETE CASCADE
+├── question_id → questions(id) ON DELETE CASCADE
+├── created_at
+└── UNIQUE(user_id, question_id)
+
+reminder_schedules
+├── id (PK)
+├── user_id → users(id) ON DELETE CASCADE
+├── quiz_id → quizzes(id) ON DELETE CASCADE
+├── next_reminder_at
+├── interval_days
+├── performance_score
+├── is_active
+├── created_at
+└── updated_at
+
+ai_model_configs
+├── id (PK)
+├── name (display name)
+├── model_id (LiteLLM model identifier)
+├── task ("extraction" | "teach" | "tts" | "keyword")
+├── api_key (optional override)
+├── is_active
+├── is_default
+├── created_at
+└── UNIQUE(model_id, task)
+
+contact_submissions
+├── id (PK)
+├── name
+├── email
+├── type
+├── message
+├── read (0 | 1)
+└── created_at
+```
+
+### Key Cascade Rules
+
+| Parent deleted | Child behavior |
+|---|---|
+| User deleted | Documents, attempts, favorites, reminders, verifications, password resets **cascade delete** |
+| Document deleted | Sections **cascade delete** |
+| Section deleted | Quizzes get `section_id = NULL` (ON DELETE SET NULL) — quizzes and questions survive |
+| Quiz deleted | Attempts and quiz_question_links **cascade delete**; questions get `quiz_id = NULL` |
+| Question deleted | Attempt answers, quiz_question_links, tag links, favorites **cascade delete** |
+| Tag deleted | Tag links **cascade delete** |
+
+## Multi-Worker Startup
+
+The backend runs **4 uvicorn workers** (separate processes). All workers execute the same `lifespan` startup sequence, but certain tasks must run only once:
+
+### What every worker does (idempotent)
+
+1. `Base.metadata.create_all()` — SQLAlchemy creates missing tables
+2. `setup_pgvector()` — enables pgvector extension, adds columns, runs DDL migrations
+3. Create upload/chroma directories
+4. `seed_admin()` — creates default admin user if none exists
+5. `seed_default_models()` — seeds AI model configs and TTS voices
+
+### What only one worker does (singleton)
+
+The `_acquire_singleton_lock()` function uses **Redis SETNX** to atomically set the key `startup:singleton_lock` with a 300-second TTL. Only the worker that successfully sets it (returns True) runs:
+
+1. `backfill_embeddings()` — background thread that generates embeddings for questions that don't have one
+2. `start_scheduler()` — APScheduler instance for periodic tasks (reminders)
+
+If Redis is unavailable, the function returns True (fail-open for single-worker deployments).
+
+### Stale Connection Cleanup
+
+Before DDL migrations, `setup_pgvector()` terminates PostgreSQL connections that have been `idle in transaction` for more than 30 seconds. This prevents hangs when a previous crashed worker left an open transaction holding a DDL lock.
+
+```sql
+SELECT pg_terminate_backend(pid)
+FROM pg_stat_activity
+WHERE datname = current_database()
+  AND state = 'idle in transaction'
+  AND query_start < NOW() - INTERVAL '30 seconds'
+  AND pid != pg_backend_pid()
+```
+
+### DDL Migration Retry Logic
+
+Schema migrations (`ALTER TABLE`, `CREATE EXTENSION`) use a 15-second `lock_timeout` and retry up to 3 times with a 5-second delay between attempts. This handles transient lock contention from Celery workers or other uvicorn processes.
+
+## Background Task System
+
+### Stack
+
+- **Broker**: Redis (same instance used for caching/rate limiting)
+- **Worker**: Celery with `--concurrency=4` (fork pool, 4 child processes)
+- **Task module**: `app.tasks` (auto-discovered by Celery)
+
+### Task Types
+
+| Task name | Module | Trigger | Purpose |
+|---|---|---|---|
+| `process_pdf` | `pdf_tasks.py` | Document upload | Extract text page-by-page, store chunks in ChromaDB |
+| `extract_quiz` | `quiz_tasks.py` | "Extract" button on document detail page | Run AI extraction (6 modes), create quiz + questions, generate embeddings |
+| `classify_questions` | `quiz_tasks.py` | Admin dashboard "Classify" button | AI tags untagged questions with subjects, diseases, keywords in batches of 10 |
+| `regenerate_embeddings` | `quiz_tasks.py` | Admin dashboard or CLI `reembed` | Regenerate 1024-dim embeddings for all questions using current embedding model |
+
+### Progress Reporting
+
+All tasks report progress via **Redis lists** (RPUSH). Each entry is a JSON object:
+
+```json
+{"step": "ai", "message": "Chunk 2/4: pages 51-100...", "ts": 1712345678.123}
+```
+
+Key patterns:
+- `extraction:steps:{job_id}` — quiz extraction progress
+- `pdf:steps:{document_id}` — PDF processing progress
+- `classify:steps:{job_id}` — classification progress
+- `extraction:status:{job_id}` — job state: `running` | `completed` | `failed` | `cancelled`
+
+The frontend polls these keys to render real-time step-by-step progress. All keys expire after 1 hour (`EXPIRE_SECONDS = 3600`).
+
+### Cancellation
+
+Extraction and classification tasks check `extraction:status:{job_id}` (or `classify:status:{job_id}`) at each chunk boundary. If the value is `cancelled`, the task exits early. The frontend can cancel a running job by setting this key.
+
+### Large Document Handling
+
+Documents over 50 pages are split into chunks of 50 pages each. Each chunk is processed independently and results are accumulated. This prevents LLM context window overflows and allows progress reporting per chunk.
+
+## Vector Search Architecture
+
+PedsHub uses a **dual-index** approach with two separate vector stores for different purposes:
+
+### ChromaDB — Document Page Vectors (RAG)
+
+- **Purpose**: Retrieval-augmented generation for the AI tutor (TeachChat)
+- **Content**: Raw PDF page text, chunked and embedded
+- **Flow**: PDF upload → `process_pdf` task → text extraction → chunking → ChromaDB storage
+- **Usage**: When the AI tutor answers a question, relevant document pages are retrieved as context
+- **Storage**: Persistent volume (`chroma_data`), embedded mode (no separate server)
+
+### pgvector — Question Embeddings (Semantic Search)
+
+- **Purpose**: "Find similar questions" in the question bank
+- **Content**: Question text embedded as 1024-dimensional vectors
+- **Index**: HNSW (`vector_cosine_ops`) for fast approximate nearest-neighbor search
+- **Flow**: Question created → `embedding_service.embed_question()` → HTTP call to LiteLLM proxy → vector stored in `questions.embedding` column
+- **Usage**: Question bank semantic search, "related questions" in TeachChat context
+- **Model**: Configurable via Admin → More Settings (stored in Redis, no restart needed)
+- **Backfill**: On startup, a background thread embeds any questions with `NULL` embedding
+
+### Why Two Stores?
+
+| Concern | ChromaDB | pgvector |
+|---|---|---|
+| Data type | Raw document text chunks | Structured question text |
+| Query pattern | "Find pages about X" (RAG context) | "Find questions similar to Y" (search) |
+| Lifecycle | Tied to document (delete document = delete vectors) | Tied to question (survives document deletion) |
+| Dimensions | ChromaDB default | 1024 (configurable model) |
+
+## Authentication
+
+### JWT Tokens with Sliding Expiration
+
+1. User logs in with email + password → backend verifies bcrypt hash
+2. Backend issues a JWT containing `sub` (email), `exp` (expiry), `iat` (issued-at)
+3. Token expiry is configured via `ACCESS_TOKEN_EXPIRE_MINUTES` (default: 1440 = 24 hours)
+4. **Sliding expiration**: `TokenRefreshMiddleware` checks every request:
+   - If token is older than 12 hours OR will expire in less than 1 hour
+   - A new token is generated and returned in the `X-New-Token` response header
+   - Frontend detects this header and updates its stored token transparently
+5. Algorithm: HS256, secret from `SECRET_KEY` env var
+
+### Password Hashing
+
+- Library: passlib with bcrypt scheme
+- All passwords are hashed before storage; plaintext is never persisted
+
+### Email Verification Flow
+
+```
+1. User registers → backend creates User + EmailVerification (token, expires_at)
+2. Verification email sent with link: {APP_URL}/verify-email?token={token}
+3. User clicks link → frontend calls POST /api/auth/verify-email
+4. Backend checks token validity + expiry → sets verified_at timestamp
+5. Until verified: get_current_user() returns 403 with X-Unverified header
+6. Frontend redirects unverified users to a "check your email" page
+```
+
+### Password Reset Flow
+
+```
+1. User requests reset → POST /api/auth/forgot-password with email
+2. Backend creates PasswordReset (token, expires_at) → sends reset email
+3. Email contains link: {APP_URL}/reset-password?token={token}
+4. User clicks link → enters new password → POST /api/auth/reset-password
+5. Backend validates token, checks expiry, marks as used, updates password hash
+```
+
+## Rate Limiting
+
+### Implementation
+
+Rate limiting uses **Redis INCR + TTL** via the `check_rate_limit()` utility:
+
+```python
+count = redis.incr(key)      # Atomic increment
+if count == 1:
+    redis.expire(key, window)  # Set TTL on first hit
+if count > max_calls:
+    raise HTTPException(429)
+```
+
+### Limits
+
+| Endpoint | Key pattern | Max calls | Window | Scope |
+|---|---|---|---|---|
+| Login | `rate:login:{ip}` | 10 | 15 min | Per IP |
+| TeachChat | `rate:teach:{user_id}` | 30 | 10 min | Per user |
+| TTS | `rate:tts:{user_id}` | 20 | 5 min | Per user |
+
+### Exemptions
+
+The following users bypass all rate limits:
+- Users with role `admin`
+- Users with role `moderator`
+- Users with `is_unthrottled = 1` (set via admin dashboard)
+
+### Graceful Degradation
+
+If Redis is unavailable (connection timeout of 1 second), rate limiting **fails open** — requests are allowed through. This prevents Redis outages from blocking legitimate users.
+
+## Runtime Configuration
+
+### No Build-Time Secrets
+
+The frontend Docker image contains only the built React SPA with no environment-specific values. At container startup, `docker-entrypoint.sh` runs:
+
+```sh
+cat > /usr/share/nginx/html/config.js <<EOF
+window.__APP_CONFIG__ = {
+  TURNSTILE_SITE_KEY: "${TURNSTILE_SITE_KEY:-}"
+};
+EOF
+exec nginx -g 'daemon off;'
+```
+
+The SPA loads `config.js` before the React bundle via a `<script>` tag in `index.html`. Components read values from `window.__APP_CONFIG__`.
+
+### Benefits
+
+- Change Turnstile keys (or add new config) by editing `frontend/.env` and restarting — no rebuild
+- Same Docker image works across staging/production with different env files
+- No risk of secrets leaking into the JS bundle via Vite's `import.meta.env`
+
+## Concurrent Quiz Protection
+
+### Problem
+
+A user could open the same in-progress quiz on two devices (or two browser tabs), causing conflicting answer submissions and corrupted progress state.
+
+### Solution
+
+Redis session locks with TTL:
+
+1. Each browser tab generates a unique session ID (stored in component state)
+2. The session ID is sent with every request via the `X-Quiz-Session` header
+3. When saving progress, the backend sets a Redis key:
+   ```
+   quiz_active:{user_id}:{attempt_id} = {session_id}   (TTL ~30s)
+   ```
+4. When resuming a quiz, the backend checks this key:
+   - If the key exists and the session ID matches → allow (same tab)
+   - If the key exists and the session ID differs → reject with HTTP 409: "This quiz is active on another device"
+   - If the key doesn't exist → allow (no active session, or previous session timed out)
+5. The lock TTL is refreshed on each progress save, so it stays active as long as the user is actively taking the quiz
+6. When the quiz is submitted (completed), the lock is released
+
+### User Experience
+
+If a user tries to resume on a second device, they see: "This quiz is active on another device. It will become available when the other session ends or times out (~30 seconds)."
diff --git a/docs/deployment.md b/docs/deployment.md
new file mode 100644
index 0000000..831ca6f
--- /dev/null
+++ b/docs/deployment.md
@@ -0,0 +1,446 @@
+# PedsHub Deployment and Operations Guide
+
+## Docker Compose Setup
+
+The application runs as 5 services defined in `docker-compose.yml`:
+
+| Service | Image | Purpose | Port |
+|---------|-------|---------|------|
+| `postgres` | `pgvector/pgvector:pg16` | PostgreSQL with pgvector extension | Internal only |
+| `redis` | `redis:7-alpine` | Caching, quiz progress, job tracking, Celery broker | Internal only |
+| `backend` | Built from `./backend` | FastAPI app (uvicorn, 4 workers) | Internal only |
+| `celery` | Built from `./backend` (same image) | Celery worker (concurrency=2) | None |
+| `frontend` | Built from `./frontend` | Nginx serving React SPA | `127.0.0.1:8081:80` |
+
+### Volumes
+
+| Volume | Used by | Purpose |
+|--------|---------|---------|
+| `postgres_data` | postgres | Database persistence |
+| `redis_data` | redis | Redis persistence |
+| `uploads_data` | backend, celery | Uploaded PDF files and extracted images |
+| `chroma_data` | backend, celery | ChromaDB vector store |
+
+### Health Checks
+
+- **postgres**: `pg_isready -U pedquiz` every 5s, 10 retries.
+- Backend and celery depend on postgres being healthy (`condition: service_healthy`) and redis being started.
+
+### Startup Order
+
+1. Redis and Postgres start first.
+2. Backend and Celery wait for Postgres to be healthy.
+3. Frontend waits for backend to start.
+
+---
+
+## Environment Variables
+
+### Backend (`backend/.env`)
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `DATABASE_URL` | `sqlite:///./quiz.db` | PostgreSQL connection string. Production: `postgresql://user:pass@postgres:5432/pedquiz` |
+| `SECRET_KEY` | `change-me-...` | JWT signing key. Generate with `openssl rand -hex 32` |
+| `ALGORITHM` | `HS256` | JWT algorithm |
+| `ACCESS_TOKEN_EXPIRE_MINUTES` | `1440` | Token lifetime (default 24 hours) |
+| `REDIS_URL` | `redis://localhost:6379/0` | Redis connection URL |
+| `LITELLM_MODEL` | `gpt-4o-mini` | Default LLM model for extraction |
+| `LITELLM_API_KEY` | (empty) | API key for LiteLLM proxy or provider |
+| `LITELLM_API_BASE` | (empty) | Custom API base URL (for LiteLLM proxy) |
+| `LITELLM_EMBEDDING_MODEL` | (empty) | Model for semantic search embeddings |
+| `OPENAI_API_KEY` | (empty) | OpenAI API key (if using OpenAI models directly) |
+| `ELEVENLABS_API_KEY` | (empty) | ElevenLabs API key for TTS voices |
+| `GOOGLE_TTS_API_KEY` | (empty) | Google Cloud TTS API key |
+| `AWS_ACCESS_KEY_ID` | (empty) | AWS credentials for Bedrock / Polly |
+| `AWS_SECRET_ACCESS_KEY` | (empty) | AWS secret key |
+| `AWS_REGION` | `us-east-1` | AWS region |
+| `AWS_BEDROCK_REGION` | `us-east-1` | AWS Bedrock region |
+| `EMBEDDING_DIMENSIONS` | `1024` | Vector embedding dimension size |
+| `CHROMA_PERSIST_DIR` | `/app/chroma_data` | ChromaDB storage directory |
+| `MAIL_USERNAME` | (empty) | SMTP username |
+| `MAIL_PASSWORD` | (empty) | SMTP password |
+| `MAIL_FROM` | (empty) | From address for emails |
+| `MAIL_PORT` | `587` | SMTP port |
+| `MAIL_SERVER` | `smtp.gmail.com` | SMTP server hostname |
+| `MAIL_STARTTLS` | `true` | Use STARTTLS |
+| `MAIL_SSL_TLS` | `false` | Use SSL/TLS |
+| `UPLOAD_DIR` | `/app/uploads` | Upload storage directory |
+| `MAX_UPLOAD_SIZE` | `524288000` | Max upload size in bytes (500MB) |
+| `APP_URL` | `https://quiz.danvics.com` | Public URL (used in emails, links) |
+| `TURNSTILE_SECRET_KEY` | (empty) | Cloudflare Turnstile secret key. Leave blank to disable captcha |
+| `ADMIN_EMAIL` | (empty) | Email address for contact form submissions |
+
+### Frontend (`frontend/.env`)
+
+| Variable | Description |
+|----------|-------------|
+| `TURNSTILE_SITE_KEY` | Cloudflare Turnstile site key (public). Injected at runtime via `docker-entrypoint.sh` into `window.__APP_CONFIG__` |
+
+---
+
+## HTTPS Setup with Caddy
+
+The frontend binds to `127.0.0.1:8081` (not exposed externally). Use a reverse proxy for HTTPS.
+
+Example Caddyfile:
+
+```caddyfile
+quiz.example.com {
+    reverse_proxy localhost:8081
+}
+```
+
+Caddy handles automatic HTTPS certificate provisioning via Let's Encrypt. No additional TLS configuration is needed.
+
+For setups where the backend needs to be accessed directly (rare):
+
+```caddyfile
+quiz.example.com {
+    reverse_proxy localhost:8081
+
+    # Optional: direct backend access for debugging
+    handle_path /api-direct/* {
+        reverse_proxy localhost:8000
+    }
+}
+```
+
+Note: The frontend's Nginx already proxies `/api` to the backend container internally, so you only need to expose the frontend port.
+
+---
+
+## Rebuilding
+
+### When to Rebuild vs Restart
+
+| Change | Action |
+|--------|--------|
+| Backend Python code | Rebuild backend: `docker compose build backend` |
+| Frontend source code | Rebuild frontend: `docker compose build frontend` |
+| Backend `.env` changes | Restart only: `docker compose restart backend celery` |
+| Frontend `.env` changes | Restart only: `docker compose restart frontend` |
+| `requirements.txt` changes | Rebuild backend: `docker compose build backend` |
+| `package.json` changes | Rebuild frontend: `docker compose build frontend` |
+| `docker-compose.yml` changes | `docker compose up -d` (recreates changed services) |
+
+### Celery shares the backend image
+
+The `celery` service builds from `./backend` — the same Dockerfile as `backend`. When you rebuild `backend`, you must also rebuild `celery`:
+
+```bash
+docker compose build backend
+docker compose up -d backend celery
+```
+
+Or build both explicitly:
+
+```bash
+docker compose build backend celery
+docker compose up -d
+```
+
+### Stale code / cache issues
+
+If code changes are not reflected after a rebuild, use `--no-cache`:
+
+```bash
+docker compose build --no-cache backend
+docker compose build --no-cache frontend
+```
+
+This forces Docker to re-run all build steps, including `pip install` and `npm ci`.
+
+---
+
+## Database
+
+### PostgreSQL with pgvector
+
+The database uses `pgvector/pgvector:pg16` which includes the `vector` extension. On startup, the backend runs:
+
+```sql
+CREATE EXTENSION IF NOT EXISTS vector;
+ALTER TABLE questions ADD COLUMN IF NOT EXISTS embedding vector(1024);
+CREATE INDEX IF NOT EXISTS questions_embedding_hnsw
+    ON questions USING hnsw (embedding vector_cosine_ops);
+```
+
+### Connection Pool
+
+SQLAlchemy engine is configured with:
+
+```python
+engine = create_engine(settings.DATABASE_URL, pool_pre_ping=True, pool_recycle=300)
+```
+
+- `pool_pre_ping=True` — Tests connections before use. Prevents "connection closed" errors after database restarts.
+- `pool_recycle=300` — Recycles connections every 5 minutes. Prevents stale connections in long-running processes (Celery workers).
+
+### Backups
+
+```bash
+# Dump the database
+docker compose exec postgres pg_dump -U pedquiz pedquiz > backup_$(date +%Y%m%d).sql
+
+# Restore from backup
+docker compose exec -T postgres psql -U pedquiz pedquiz < backup_20240101.sql
+```
+
+For automated backups, add a cron job on the host:
+
+```bash
+0 2 * * * cd /home/danvics/docker/quiz && docker compose exec -T postgres pg_dump -U pedquiz pedquiz | gzip > /backups/pedquiz_$(date +\%Y\%m\%d).sql.gz
+```
+
+---
+
+## Monitoring
+
+### Checking Logs
+
+```bash
+# Backend logs (FastAPI + uvicorn)
+docker compose logs -f backend
+
+# Celery worker logs (extraction jobs, embeddings)
+docker compose logs -f celery
+
+# All services
+docker compose logs -f
+
+# Last 100 lines
+docker compose logs --tail=100 backend
+```
+
+### Common Errors and Fixes
+
+| Error | Cause | Fix |
+|-------|-------|-----|
+| `connection already closed` | Stale DB connection in Celery | Already handled by `pool_pre_ping` and `pool_recycle`. If persistent, restart celery |
+| `lock timeout` on startup | Previous killed process holding DDL locks | Backend auto-terminates stale connections and retries 3 times with 5s delay |
+| `429 / rate limit` from LLM API | Too many extraction requests | Reduce celery concurrency or add rate limiting config |
+| `embedding failed` | Embedding API rate limit or model issue | Check LITELLM_EMBEDDING_MODEL config, verify API key |
+| `CORS error` in browser | Frontend not going through Nginx proxy | Ensure requests go through the frontend's Nginx (which proxies /api) |
+| `502 Bad Gateway` | Backend not ready yet | Wait for backend to start, check `docker compose logs backend` |
+
+---
+
+## Troubleshooting
+
+### Lock Timeout on Startup
+
+The backend runs DDL migrations (ALTER TABLE, CREATE INDEX) at startup. If a previous instance was killed while holding a lock, the new instance will hang. The startup code handles this automatically:
+
+1. Terminates stale `idle in transaction` connections older than 30 seconds.
+2. Sets `lock_timeout = '15s'` before running DDL.
+3. Retries up to 3 times with 5-second delays if a lock timeout occurs.
+
+If this still fails, manually kill stale connections:
+
+```bash
+docker compose exec postgres psql -U pedquiz -c "SELECT pg_terminate_backend(pid) FROM pg_stat_activity WHERE state = 'idle in transaction' AND pid <> pg_backend_pid();"
+```
+
+### Singleton Lock for Startup Tasks
+
+The backend uses a Redis-based singleton lock (`startup:singleton_lock`, 5-minute TTL) to ensure that only one of the 4 uvicorn workers runs the scheduler and backfill tasks. If Redis is unavailable, it assumes single-worker mode and runs everything.
+
+### Stale DB Connections in Celery Tasks
+
+Celery workers are long-running processes. Without `pool_recycle=300`, connections can go stale (especially after postgres restarts). The `pool_pre_ping=True` setting validates connections before use. If you see database errors in celery logs after a postgres restart, restart the celery service:
+
+```bash
+docker compose restart celery
+```
+
+### Embedding Batch Size / Rate Limits
+
+Embedding generation happens during quiz extraction and on startup (backfill). If the embedding API has rate limits, you may see failures in the celery logs. The embedding service handles individual failures gracefully (logs and continues). To re-embed all questions:
+
+```bash
+docker compose exec backend python manage.py reembed
+```
+
+### Docker Build Cache Issues
+
+If you update Python dependencies or JS packages but the build uses cached layers:
+
+```bash
+# Force fresh install of all dependencies
+docker compose build --no-cache backend frontend
+docker compose up -d
+```
+
+---
+
+## Scaling
+
+### Worker Counts
+
+- **Backend (uvicorn)**: Runs with `--workers 4`. For higher throughput, increase in `docker-compose.yml`. Each worker runs the startup lifespan (idempotent DDL + singleton lock for scheduler).
+- **Celery**: Runs with `--concurrency=2`. This controls how many extraction jobs run in parallel. Increase for faster throughput, but watch LLM API rate limits.
+
+### Redis Memory
+
+Redis stores:
+- Quiz progress (per-user, per-quiz)
+- Extraction job status and steps
+- Celery broker messages
+- Singleton lock
+- User job lists
+
+For most deployments, default Redis memory is sufficient. Monitor with:
+
+```bash
+docker compose exec redis redis-cli info memory
+```
+
+### ChromaDB Storage
+
+ChromaDB stores question embeddings for semantic search. Storage grows with the number of questions. The `chroma_data` volume persists this data. Monitor disk usage:
+
+```bash
+docker system df -v | grep chroma
+```
+
+---
+
+## Updating
+
+### Standard Update Flow
+
+```bash
+cd /home/danvics/docker/quiz
+git pull
+docker compose build backend frontend
+docker compose up -d
+```
+
+### Migration Safety
+
+Database migrations run automatically on startup via `Base.metadata.create_all()` and explicit DDL in `setup_pgvector()`. These are idempotent:
+- `CREATE TABLE IF NOT EXISTS`
+- `ADD COLUMN IF NOT EXISTS`
+- `CREATE INDEX IF NOT EXISTS`
+
+DDL statements use `SET lock_timeout = '15s'` and retry up to 3 times to handle concurrent lock contention from Celery workers or other uvicorn processes.
+
+### Zero-Downtime Updates
+
+For zero-downtime updates (if needed):
+
+```bash
+# Build new images first
+docker compose build backend frontend
+
+# Restart one service at a time
+docker compose up -d --no-deps backend
+docker compose up -d --no-deps celery
+docker compose up -d --no-deps frontend
+```
+
+---
+
+## CLI Tools
+
+The `manage.py` script provides management commands. Run inside the backend container:
+
+```bash
+docker compose exec backend python manage.py <command>
+```
+
+### Commands
+
+#### `reset-password <email> <new-password>`
+
+Reset a user's password. Password must be at least 8 characters.
+
+```bash
+docker compose exec backend python manage.py reset-password user@example.com newpassword123
+```
+
+#### `list-users`
+
+List all users with ID, email, role, verified status, and name.
+
+```bash
+docker compose exec backend python manage.py list-users
+```
+
+Output:
+```
+  ID  Email                                     Role          Verified  Name
+------------------------------------------------------------------------------------------
+   1  admin@example.com                         admin         yes       Admin
+   2  user@example.com                          user          yes       John
+```
+
+#### `reembed`
+
+Regenerate all question embeddings. Useful after changing the embedding model. Clears existing embeddings and re-generates them one by one.
+
+```bash
+docker compose exec backend python manage.py reembed
+```
+
+#### `extract <section_id> [options]`
+
+Run quiz extraction from a section. Can run inline (blocking) or in background (via Celery).
+
+```bash
+# Inline extraction (blocking, shows live output)
+docker compose exec backend python manage.py extract 5
+
+# With options
+docker compose exec backend python manage.py extract 5 --title "Chapter 3 Quiz" --mode learning --user admin@example.com
+
+# Background (via Celery)
+docker compose exec backend python manage.py extract 5 --bg
+```
+
+Options:
+- `--title` — Quiz title (default: auto-generated from section name)
+- `--mode` — `timed` or `learning` (default: `timed`)
+- `--user` — User email to assign the quiz to (default: first admin user)
+- `--bg` — Run in background via Celery
+
+#### `list-sections [doc_id]`
+
+List all documents and their sections. Optionally filter by document ID.
+
+```bash
+# All documents
+docker compose exec backend python manage.py list-sections
+
+# Specific document
+docker compose exec backend python manage.py list-sections 3
+```
+
+Output:
+```
+Doc 3: PREP_2024.pdf (ready, 450 pages)
+  Section 5: 'Chapter 1'  pages 1-50
+  Section 6: 'Chapter 2'  pages 51-120
+```
+
+#### `jobs [--user email]`
+
+Show recent extraction jobs from Redis. Optionally filter by user email.
+
+```bash
+# All users' jobs
+docker compose exec backend python manage.py jobs
+
+# Specific user
+docker compose exec backend python manage.py jobs --user admin@example.com
+```
+
+Output:
+```
+admin@example.com:
+  [completed ] Quiz: Chapter 1                           steps= 12 quiz_id=7
+              Saved 25 questions to quiz
+  [running   ] Quiz: Chapter 2                           steps=  5
+              Extracting questions from pages 51-80...
+```
diff --git a/docs/frontend.md b/docs/frontend.md
new file mode 100644
index 0000000..142b008
--- /dev/null
+++ b/docs/frontend.md
@@ -0,0 +1,341 @@
+# PedsHub Frontend Documentation
+
+## Architecture Overview
+
+The frontend is a React SPA built with Vite and served via Nginx. It communicates with the backend exclusively through `/api` (proxied by Nginx to the backend container).
+
+### Entry Point
+
+`main.jsx` renders `<App />` inside `<React.StrictMode>`.
+
+`App.jsx` provides the top-level provider hierarchy:
+
+```
+BrowserRouter
+  ThemeProvider
+    AuthProvider
+      AppRoutes
+```
+
+### Routing
+
+`AppRoutes` reads `useAuth()` to decide what to render:
+
+| Route | Component | Access |
+|---|---|---|
+| `/home` | LandingPage | Public (always) |
+| `/login` | LoginPage | Public (redirects to `/` if logged in) |
+| `/register` | RegisterPage | Public (redirects to `/` if logged in) |
+| `/verify-email` | VerifyEmailPage | Public |
+| `/forgot-password` | ForgotPasswordPage | Public |
+| `/reset-password` | ResetPasswordPage | Public |
+| `/` | DashboardPage | Authenticated |
+| `/quizzes` | QuizzesPage | Authenticated |
+| `/quizzes/:id` | QuizPage | Authenticated |
+| `/results/:id` | ResultsPage | Authenticated |
+| `/documents/:id` | DocumentDetailPage | Authenticated |
+| `/account` | AccountPage | Authenticated |
+| `/settings` | SettingsPage | Authenticated |
+| `/question-bank` | QuestionBankPage | Authenticated |
+| `/admin` | AdminPage | Authenticated |
+| `/upload` | UploadPage | Moderator only |
+| `/quizzes/:id/edit` | QuizEditPage | Moderator only |
+| `/jobs` | JobsPage | Moderator only |
+| `/trash` | TrashPage | Moderator only |
+| `*` | NotFoundPage or redirect to `/home` | Catch-all |
+
+Unauthenticated users hitting any protected route are redirected to `/home`. Non-moderators hitting moderator routes are redirected to `/`.
+
+`AppLayout` wraps authenticated routes with `<Navbar />`, a container div, and a footer.
+
+---
+
+## Context Providers
+
+### AuthContext (`context/AuthContext.jsx`)
+
+Provides `{ user, loading, login, loginWithToken, logout }`.
+
+- On mount, checks `localStorage.getItem('token')` and calls `GET /auth/me` to hydrate the user object.
+- `login(email, password, turnstileToken)` posts to `/auth/login`, stores the JWT, then fetches `/auth/me`.
+- `loginWithToken(token)` stores a token directly (used after registration when verification is not required).
+- `logout()` clears the token and sets user to null.
+
+### ThemeContext (`context/ThemeContext.jsx`)
+
+Provides `{ theme, setTheme }`.
+
+- Persists the active theme name in `localStorage` under key `pedquiz_theme`.
+- Applies the theme by setting `data-theme` attribute on `document.body`.
+
+---
+
+## Page Descriptions
+
+### LandingPage (`/home`)
+
+The public-facing marketing page. Sections:
+
+1. **Hero** - Gradient background with tagline "Turn your textbooks into tests". Shows Sign In / Register buttons for guests, or Dashboard / My Quizzes / Question Bank links for logged-in users.
+2. **Features** - 6 feature cards (Quiz from Any PDF, AI Tutor, Audio Mode, Question Bank, Track Your Progress, Fast by Design) rendered from a static `FEATURES` array. Cards have hover lift animations.
+3. **AI Scribe cross-sell** - Promotes the sibling PedsHub AI Scribe product (links to `https://peds.danvics.com`).
+4. **Contact form** - `ContactForm` component with name, email, type selector (Question or Apply as Moderator), and message. Validates required fields. Includes a `TurnstileWidget` for Cloudflare captcha. Posts to `POST /contact`.
+5. **Auth modal** - `AuthModal` component rendered as an overlay with Sign In / Register tabs. Handles login, registration, email verification resend, and unverified-email warnings. The Turnstile widget is embedded inside the modal. The Navbar receives `onSignIn` and `onRegister` callbacks to open the modal.
+
+**Turnstile integration**: The site key comes from `window.__APP_CONFIG__.TURNSTILE_SITE_KEY`. The Turnstile script is loaded dynamically once. `TurnstileWidget` retries rendering with a 200ms polling loop until `window.turnstile` is available.
+
+### DashboardPage (`/`)
+
+The authenticated home screen. Loads three API calls in parallel on mount:
+
+- `GET /documents/` (moderators only, otherwise skipped)
+- `GET /attempts/stats/dashboard` (total quizzes, attempts, avg score, optionally documents)
+- `GET /attempts/history` (attempt history grouped by quiz)
+
+Features:
+
+- **Greeting** - Time-of-day greeting using the user's first name.
+- **Stats cards** - Grid of stat cards (Documents for moderators, Quizzes, Attempts, Avg Score).
+- **Performance chart** - `LineChart` SVG component showing score trend for a selected quiz. Dropdown to switch between quizzes. Shows latest score, best score, and a retake button. Warns if latest score is below 75%.
+- **Attempt history** - Listed under the chart. Each attempt row shows date, score link to results, and inline delete with two-click confirmation (`confirmAttempt` state pattern).
+- **Documents list** - Moderator-only card listing uploaded PDFs with status badges and an Upload PDF button.
+
+### QuizzesPage (`/quizzes`)
+
+Loads quizzes and categories in parallel on mount.
+
+Features:
+
+- **Search bar** - Debounced search (350ms) across quizzes and questions. Three filter modes: All, Title only, Questions only. Results show quiz title matches and matching question snippets with `HighlightText` highlighting.
+- **Expanded search** - Toggle to view all matching questions in a flat list. Each question has a Study button.
+- **QuestionStudyModal** - Interactive modal that lets you answer a question, shows correct/incorrect feedback, and displays the explanation. Includes a lazy-loaded `TeachChat` with the `elevated` prop for higher z-index (above the modal).
+- **In-progress quizzes** (`InProgressSection`) - Shows quizzes the user started but hasn't finished. Resume and Delete buttons.
+- **Past attempts** (`PastAttemptsSection`) - Collapsible section, loads on demand. Delete buttons on each attempt.
+- **Quiz grid** - Quizzes grouped by category (moderator-created categories). `QuizCard` component shows title, question count, mode badge (Learning/Timed), time limit. Hover lift effect.
+- **Moderator controls** - Edit link, publish/unpublish toggle, category assignment dropdown, trash button with `ConfirmButton`.
+- **Category management** - Moderators can add categories inline, delete categories, and see quiz counts per category.
+
+### QuizPage (`/quizzes/:id`)
+
+The core quiz-taking experience. Two phases: mode selection, then quiz.
+
+**Mode selection** (`ModeSelectScreen`):
+- Study Mode: answers and explanations shown as you go.
+- Exam Mode: answers hidden until submitted.
+- Optional timer input (minutes) for exam mode.
+- TTS voice selector (if voices are configured).
+
+**Quiz phase**:
+- **Concurrent device lock** - A unique `SESSION_ID` is generated per tab (`Math.random() + Date.now()`). Sent as `x-quiz-session` header when fetching/saving progress. The backend returns 409 if the quiz is active on another device.
+- **Auto-resume** - On load, fetches `GET /attempts/progress?quiz_id=...`. If saved progress exists, calls `resumeQuiz()` which restores mode, answers, current index, timer state, and voice selection. For study mode, re-fetches the quiz with `?study=true` to get correct answers.
+- **Timer** - Uses the `timerStarted` pattern: `const timerStarted = timeLeft !== null` declared outside the effect, used as a dependency. The timer is calculated from `started_at + total_time`, so it survives page reloads. Auto-submits when `timeLeft` reaches 0.
+- **Progress save to Redis** - Debounced at 1.5 seconds. Saves `quiz_id, attempt_id, answers, current_idx, mode, voice, time_left, started_at, total_time` via `POST /attempts/progress`. Uses the session ID header.
+- **Answer tracking** - `answers` state is a `{ [questionId]: selectedOption }` object. `setAnswer` merges into the object.
+- **Navigation** - Previous/Next buttons, question number dots (desktop sidebar + mobile collapsible grid). `QuestionDot` shows active (primary), answered (green), and unanswered (gray) states.
+- **TTS** - `TTSButton` component calls `POST /tts/speak` to get audio blob, creates `Audio` object for playback. Voice selector disabled while audio is playing.
+- **Favorites** - Star toggle on each question, calls `POST /favorites` or `DELETE /favorites/:id`.
+- **Suspend** - "Suspend" button shows a confirmation dialog. Progress is already saved; timer warning shown for timed quizzes. Navigates to dashboard on confirm.
+- **beforeunload** - Browser tab close warning when mid-quiz.
+- **AI Tutor** - `TeachChat` lazy-loaded in study mode only.
+
+### ResultsPage (`/results/:id`)
+
+Shows quiz results. Accepts `location.state.result` for instant display after submission, or fetches `GET /attempts/:id` if navigated directly.
+
+Features:
+
+- **Score card** - Large percentage display with color coding (green >= 75, yellow >= 50, red < 50). Score bar visualization. Contextual message.
+- **Summary row** - Correct, Incorrect, and Skipped counts with colored backgrounds.
+- **Question review** - Full review of each question with:
+  - Correct/Incorrect/Skipped badge
+  - Option display with letter badges, color-coded (correct = green, user's wrong answer = red)
+  - Fill-in-the-blank display for non-MCQ
+  - Explanation section
+- **Actions** - Retake Quiz, All Quizzes, Dashboard, Delete Attempt (with two-click confirmation).
+
+### QuestionBankPage (`/question-bank`)
+
+The central question repository with advanced filtering.
+
+Features:
+
+- **Search modes** - Three modes available: `keyword` (text search), `semantic` (vector similarity), `hybrid` (combines both). Controlled by `searchMode` state, sent as `search_mode` param.
+- **Multi-category filter** - `filterCatIds` array state. Toggling a category adds/removes its ID. Uses `catIdsKey = filterCatIds.join(',')` as a useEffect dependency (avoids reference equality issues with arrays).
+- **Tag browser** (`TagBrowser` component) - Three sections: Subjects, Diseases, Keywords. Each section has its own search input. Tags shown as clickable buttons with counts. Selected tags turn colored. `selectedTagIds` array tracked similarly with `tagIdsKey = selectedTagIds.join(',')`.
+- **Debounced loading** - 300ms debounce on search query, category, tag, favorites, uncategorized, and page size changes.
+- **Pagination** - Configurable page size (25, 50, 100, All). Load more button appends to existing questions.
+- **Favorites filter** - Toggle to show only favorited questions.
+- **Uncategorized filter** - Toggle to show only questions without a category.
+- **Bulk operations** - Checkbox selection on questions. "Select All" fetches ALL matching IDs from `GET /questions/bank/ids` (not just the loaded page). Bulk assign category via `POST /questions/bulk-category`.
+- **Create quiz from selection** - `CreateQuizModal` lets you create a quiz from selected questions or from all questions in a category. Choose title, mode (Timed/Learning), and optional time limit.
+- **Question study modal** - Same interactive study modal as QuizzesPage with TeachChat (elevated z-index).
+- **Question edit modal** (`QuestionEditModal`) - Moderators can edit question text, options (with radio button for correct answer), category, and explanation. Warning that changes apply to all quizzes sharing the question.
+- **Tag classification** - Moderators can trigger AI classification (`POST /tags/classify`). Progress is polled every 2 seconds. Tags reload on completion.
+- **Category management** - Add new categories inline. Delete categories with optional move-to target.
+
+### DocumentDetailPage (`/documents/:id`)
+
+Moderator-focused document management page.
+
+Features:
+
+- **Document info** - Filename, page count, upload date, status badge. Delete document button.
+- **Processing progress** - When `doc.status === 'processing'`, polls `GET /documents/:id/status` and `GET /documents/:id/processing-steps` every 2 seconds. Shows step-by-step progress (text extraction, image extraction, etc.).
+- **Section management** - Form to create sections with name, start page, end page. List of existing sections with Extract & Create Quiz and Delete buttons.
+- **Quiz settings** (moderator-only panel):
+  - Quiz title (optional, auto-generated if blank)
+  - Mode: Timed or Learning
+  - Time limit (for timed mode)
+  - Extraction mode: Standard, Questions Only, Two-Step, AI + Regex, AI Decides, Generate
+  - Extraction model selector (from `GET /admin/models/available?task=extraction`)
+  - Question bank category selector with inline "New" button
+- **Extraction progress** (`ExtractionProgress` component) - Modal overlay that polls `GET /quizzes/job/:jobId` every 2 seconds. Shows step icons (text, AI, images, save, error, done) and messages. Job is tracked in `localStorage` under key `pedquiz_jobs` so the Navbar can show it. Close button dismisses the panel but the job continues in the background.
+
+### UploadPage (`/upload`)
+
+Moderator-only page for uploading PDFs. Two tabs:
+
+1. **Local File** - Drag-and-drop area or file picker. Accepts `.pdf` only, up to 500MB. Shows file name and size when selected.
+2. **Nextcloud** - `NextcloudBrowser` component. Reads credentials from `localStorage` (configured in Settings). Browses folders via `POST /nextcloud/files`, downloads PDFs via `POST /nextcloud/download`. Importing a file auto-triggers upload.
+
+**Upload progress** - Uses axios upload progress. Reads `e.progress` (axios 1.x pattern) with fallback to `e.loaded / e.total`. Shows progress bar and percentage.
+
+**Auto-upload on Nextcloud import** - When `handleFile` is called with `fromNextcloud = true`, `doUpload(f)` is called immediately without waiting for the user to click Upload.
+
+### AdminPage (`/admin`)
+
+Admin-only page with three tabs: Models, Users, Settings.
+
+**Access control**: Redirects to `/` if `user.role !== 'admin'`.
+
+**loadData(false) pattern**: After mutations (role change, model add/delete, etc.), calls `loadData(false)` which skips the loading spinner but refreshes all data.
+
+**Models tab**:
+- Lists models grouped by task (extraction, tts, teach, keyword).
+- Each model shows name, model_id, active/inactive toggle, default toggle, test button, delete button.
+- TTS models have an inline preview player.
+- **LiteLLM model search** - Posts to `POST /admin/litellm/models` with optional API key and base URL. Shows filterable results. Click "Add" to pre-fill the add-model form.
+- **TTS voice discovery** - Select provider (ElevenLabs, etc.), enter API key, search. Shows voice list with "Add" buttons.
+- Add model form: name, model_id, task dropdown, API key, active/default toggles.
+
+**Users tab**:
+- User list with name, email, role, verified status.
+- Role dropdown (user, moderator, admin).
+- Unthrottle toggle (removes rate limits for a user).
+- Delete user with Dialog confirmation.
+- Create user form.
+
+**Settings tab**:
+- Registration enabled toggle.
+- Embedding model selector with LiteLLM search, test button, and regeneration trigger if model changed.
+- Polly enabled toggle.
+
+---
+
+## Components
+
+### Navbar (`components/Navbar.jsx`)
+
+Auth-aware navigation bar. Behavior changes based on login state:
+
+- **Logged out**: Shows Sign In and Register buttons/links. If `onSignIn` and `onRegister` props are provided (from LandingPage), they trigger callbacks instead of navigating. Otherwise, links to `/login` and `/register`.
+- **Logged in**: Desktop nav with links (Home, Dashboard, Quizzes, Question Bank, Upload PDF for moderators, Settings). Mobile hamburger menu with animated bars. Logout button.
+- **JobsBadge** - Polls `GET /quizzes/jobs` for active extraction jobs. Poll interval: 3 seconds if jobs are running, 30 seconds otherwise. Shows running count or total job count. Dropdown with job details and links to completed quizzes.
+- Auto-closes mobile menu on route change.
+
+### TeachChat (`components/TeachChat.jsx`)
+
+Lazy-loaded AI tutor drawer. Appears as a floating action button (graduation cap icon).
+
+- **Mobile**: Bottom sheet, 70vh height, slides up.
+- **Desktop**: Right-side panel, 340px wide, slides in from right.
+- **Elevated mode**: When `elevated` prop is true, z-index is raised above modals (1060-1070 vs 380-400). Used when TeachChat appears alongside a study modal in QuizzesPage/QuestionBankPage.
+- **Features**:
+  - Question context chip at top.
+  - Model selector dropdown (if multiple teach models configured).
+  - Markdown rendering with `react-markdown`, `remark-gfm` (GFM tables), and `rehype-raw`.
+  - Follow-up suggestion chips on the last assistant message. Clicking fills the input.
+  - Posts to `POST /teach/chat` with question_id, messages array, and model_id.
+  - Shows "no model" error if backend returns 503.
+  - Chat clears when question changes (keyed on `question.id`).
+
+### Dialog (`components/Dialog.jsx`)
+
+Modal replacement for `window.confirm()` and `window.alert()`. Used via the `useDialog()` hook which returns `{ dialogProps, openConfirm, openAlert }`.
+
+Props: `open`, `title`, `message`, `confirmLabel`, `cancelLabel` (null = alert mode), `onConfirm`, `onCancel`, `danger` (red confirm button).
+
+### ConfirmButton (`components/ConfirmButton.jsx`)
+
+Inline two-click confirmation. First click shows "Confirm" and "Cancel" buttons. Second click fires `onConfirm`. Used throughout for delete operations.
+
+### LineChart (`components/LineChart.jsx`)
+
+Pure SVG line chart for performance trends. Renders a line with fill, dot markers (green >= 75%, red < 75%), grid lines, and a dashed 75% threshold line. Requires at least 2 data points. Responsive via `viewBox`.
+
+---
+
+## API Client (`api/client.js`)
+
+Axios instance with `baseURL: '/api'`.
+
+**Request interceptor**: Attaches `Authorization: Bearer <token>` from localStorage.
+
+**Response interceptor**:
+- **Token refresh**: Checks `x-new-token` response header on both success and error responses. If present, updates localStorage. This implements sliding token expiration.
+- **401 handling**: Clears token and redirects to `/login`. Skips redirect for auth endpoints (login, register, verify, reset, forgot).
+- **Unverified email (403)**: If response has `x-unverified: true` header, clears token and redirects to `/login` (which shows a resend verification option).
+
+---
+
+## State Patterns
+
+### Set vs Array for useEffect deps
+
+`selectedIds` in QuestionBankPage is a `Set` (for O(1) lookups). Since React compares deps by reference, toggling creates a new `Set` each time, which correctly triggers re-renders.
+
+### tagIdsKey / catIdsKey join pattern
+
+Arrays like `selectedTagIds` and `filterCatIds` would cause useEffect to fire on every render due to reference inequality. The pattern:
+
+```js
+const tagIdsKey = selectedTagIds.join(',')
+const catIdsKey = filterCatIds.join(',')
+useEffect(() => { ... }, [searchQuery, catIdsKey, tagIdsKey, ...])
+```
+
+Converts arrays to stable string keys so useEffect only fires when the actual content changes.
+
+### timerStarted pattern
+
+In QuizPage, the timer effect must only start once when `timeLeft` transitions from null to a number:
+
+```js
+const timerStarted = timeLeft !== null
+useEffect(() => {
+  if (!timerStarted) return
+  timerRef.current = setInterval(...)
+  return () => clearInterval(timerRef.current)
+}, [timerStarted])
+```
+
+This prevents the interval from being torn down and recreated every second as `timeLeft` decrements.
+
+---
+
+## Runtime Configuration
+
+The frontend Docker image uses `docker-entrypoint.sh` to inject runtime config at container startup:
+
+```sh
+cat > /usr/share/nginx/html/config.js <<EOF
+window.__APP_CONFIG__ = {
+  TURNSTILE_SITE_KEY: "${TURNSTILE_SITE_KEY:-}"
+};
+EOF
+exec nginx -g 'daemon off;'
+```
+
+`config.js` is loaded by `index.html` before the app bundle. Components access it via `window.__APP_CONFIG__?.TURNSTILE_SITE_KEY`. This avoids baking environment-specific values into the build.
+
+The frontend `.env` file sets `TURNSTILE_SITE_KEY` which is read by Docker Compose and passed to the entrypoint script.
diff --git a/docs/services.md b/docs/services.md
new file mode 100644
index 0000000..b5df17f
--- /dev/null
+++ b/docs/services.md
@@ -0,0 +1,394 @@
+# PedsHub Service Layer Documentation
+
+This document covers the backend service modules in `backend/app/services/`. These services contain the core business logic for AI extraction, PDF processing, vector storage, embeddings, email, and spaced repetition.
+
+---
+
+## ai_service.py
+
+Central module for LLM interactions: question extraction, answer key extraction, and TTS audio generation.
+
+### `_proxy_model(model_id: str) -> str`
+
+Prefixes a model ID with `openai/` when routing through a LiteLLM proxy. This is needed because LiteLLM requires a provider prefix, but models stored in the database use bare names (e.g. `gpt-4o`).
+
+- If `LITELLM_API_BASE` is set **and** the model_id contains no `/`, returns `openai/{model_id}`
+- Otherwise returns the model_id unchanged
+
+This function is used throughout the codebase (ai_service, teach router, admin router) whenever calling `litellm.completion()`.
+
+### `get_model_for_task(db, task: str) -> tuple[str, str | None]`
+
+Resolves which AI model to use for a given task by querying the `AIModelConfig` database table.
+
+**Fallback chain:**
+1. DB: active + default model for the requested task
+2. Environment: `LITELLM_MODEL` setting with `LITELLM_API_KEY`
+
+Returns `(model_id, api_key)`. The `api_key` may be `None` if the model uses the global proxy key.
+
+### `_truncate_content(content: str, max_chars: int = 100000) -> str`
+
+Truncates long content by keeping the first and last half (each `max_chars // 2`), inserting `"... [content truncated] ..."` in the middle. This prevents exceeding LLM context windows while preserving content from both the beginning and end of the document.
+
+### `_call_model(prompt: str, model_id, api_key) -> str`
+
+Low-level wrapper that calls `litellm.completion()` and returns the raw text response. Handles:
+- Model proxying via `_proxy_model()`
+- API key selection (per-model key > global `LITELLM_API_KEY`)
+- API base URL from `LITELLM_API_BASE`
+- Temperature fixed at 0.1 for faithful extraction
+
+### EXTRACTION_PROMPT
+
+The main extraction prompt template. Designed for PREP (Pediatric Review and Education Program) exam PDFs. Key instructions to the LLM:
+
+1. **Correct answer resolution:** Find "Correct Answer: X" or "Preferred Response: X", look up the full option text, never store just the letter
+2. **Explanation completeness:** Copy everything verbatim between the correct answer line and the next question (Critique, Content Specifications, Suggested Reading, etc.)
+3. **Question boundaries:** "Item NNN" or "ltem NNN" (OCR artifact) marks a new question
+4. **Options:** Extract text only, strip A/B/C/D/E letter prefixes
+5. **has_figure field:** Set to `true` only if the question references a clinical image (radiograph, ECG, photo, etc.) essential to answering. Decorative/branding images are `false`.
+6. **Output:** Raw JSON only, no markdown fences
+
+Template variables: `{content}`, `{page_info}`, `{page_ref}`
+
+### ANSWER_KEY_PROMPT
+
+Extracts answer keys from end-of-document sections where items are listed with their preferred responses. Returns `{"answers": {"193": "D", "194": "A", ...}}`. Handles OCR artifacts like `ltemXXX` (lowercase L instead of I).
+
+### `extract_questions(content, page_info, page_ref, model_id, api_key) -> list[dict]`
+
+Main extraction function. Calls the LLM with `EXTRACTION_PROMPT` and parses the response.
+
+- **Retries:** 3 attempts on failure
+- **JSON parsing:** Strips markdown code fences, handles multiple response shapes (`{"questions": [...]}`, bare arrays, `{"items": [...]}`, single question objects)
+- **Validation:** Skips questions without `question_text` or `correct_answer`. Normalizes `question_type` to one of `mcq`, `true_false`, `fill_blank`.
+- **Skipped tracking:** Questions without a correct answer are recorded in the first valid question's `skipped` list for caller visibility
+- Returns validated question dicts or raises `RuntimeError` after 3 failures
+
+### `extract_questions_no_answers(content, ...) -> list[dict]`
+
+Variant that allows `correct_answer` to be `None`. Used in two-step and regex extraction modes where questions and answers are in separate sections. Also extracts `item_number` for later matching.
+
+### `extract_answer_key(content, ...) -> dict[str, str]`
+
+Extracts item-to-letter mappings from answer key pages. Returns `{"193": "D", ...}` with normalized keys (stripped leading zeros) and uppercase letters.
+
+### `generate_tts_audio(text, model_id, api_key) -> bytes | None`
+
+Multi-provider TTS generation. Provider is determined by `model_id` convention:
+
+| Convention | Provider | Example |
+|---|---|---|
+| `tts-1:alloy` | OpenAI TTS | Voice after colon |
+| `tts-1-hd:nova` | OpenAI TTS HD | Voice after colon |
+| `elevenlabs/<voice_id>` | ElevenLabs | Uses `eleven_turbo_v2_5` model |
+| `google/<voice_name>` | Google Cloud TTS | Parses language code from voice name |
+| `polly/<VoiceId>` | AWS Polly Neural | e.g. `polly/Joanna` |
+
+**OpenAI key resolution order:** per-model API key > `OPENAI_API_KEY` (direct) > `LITELLM_API_KEY` (proxy). When using `OPENAI_API_KEY`, calls go directly to `api.openai.com`; otherwise uses `LITELLM_API_BASE`.
+
+Returns raw MP3 bytes or `None` on failure.
+
+---
+
+## extraction_modes.py
+
+Implements 6 extraction strategies that the quiz extraction task can use. Each mode handles different PDF formats.
+
+### Mode: `standard`
+
+Not defined in this file -- uses `ai_service.extract_questions()` directly. For PDFs where "Correct Answer: X" or "Preferred Response: X" appears inline after each question.
+
+### Mode: `questions_only`
+
+**Function:** `extract_questions_only(content, page_info, page_ref, model_id, api_key) -> list[dict]`
+
+Extracts questions and options **without** looking for correct answers. Sets `correct_answer = "PENDING"` as a placeholder for the admin to fill via the QuizEditPage UI.
+
+**Prompt template (`QUESTIONS_ONLY_PROMPT`):** Instructs the LLM to extract item numbers, question text, options, and the `has_figure` flag. Explicitly tells it NOT to include answer explanations or "Preferred Response:" content as questions.
+
+Use case: PDFs where answers are not extractable or need manual review.
+
+### Mode: `two_step`
+
+**Function:** `extract_two_step(document_id, section_start, section_end, model_id, api_key, push_step, chunk_pages=50) -> tuple[list[dict], list[str]]`
+
+Three-phase extraction for PDFs with questions in the first portion and a separate answer key section at the back (e.g. PREP 2013 format).
+
+**Phase 1 -- Question extraction:**
+- Scans from `min_answer_start` (20% into the section or page 20, whichever is larger) looking for "Preferred Response:" text
+- Chunks the question pages (before the answer key) into groups of `chunk_pages` (default 50)
+- Calls `ai_service.extract_questions_no_answers()` on each chunk
+
+**Phase 2 -- Answer key extraction:**
+- Reads from the detected answer section start through the end
+- Calls `ai_service.extract_answer_key()` on each chunk
+- Builds an `{item_number: letter}` mapping
+
+**Phase 3 -- Matching:**
+- Matches each question's `item_number` to the answer key
+- Converts the letter to the full option text using index lookup (`ord(letter) - ord('A')`)
+- Questions that cannot be matched are added to the skipped list
+
+Returns `(valid_questions, skipped_list)`. Raises `ValueError` if no answer key section is found.
+
+### Mode: `regex`
+
+**Function:** `extract_with_regex(document_id, section_start, section_end, model_id, api_key, push_step, chunk_pages=50) -> tuple[list[dict], list[str]]`
+
+AI-assisted regex extraction. The LLM analyses a sample of the document to determine the answer format, then generates a Python regex pattern.
+
+**Steps:**
+1. Samples the first 30 pages
+2. Sends `REGEX_ANALYSIS_PROMPT` to the LLM, which returns `{"indicator", "placement", "regex", "notes"}`
+3. If `placement == "end_of_doc"`, scans for the answer section boundary using the generated regex
+4. Extracts questions using `extract_questions_no_answers()`
+5. Applies the regex to the full document to build `{item_number: letter}` mapping (combined pattern: `Item\s+(\d+)[\s\S]{0,300}?` + the generated regex)
+6. Matches questions to answers
+
+### Mode: `ai_decide`
+
+**Function:** `ai_decide_strategy(document_id, section_start, section_end, model_id, api_key) -> tuple[str, str]`
+
+The LLM reads samples from the start (first 30 pages) and end (last 20 pages) of the document and decides which strategy to use.
+
+**Prompt (`AI_DECIDE_PROMPT`):** Asks the AI to choose between:
+- `standard` -- inline answers after each question
+- `two_step` -- separate answer key section
+- `questions_only` -- no answer indicators at all
+
+Returns `(strategy_name, reasoning)`. Falls back to `"standard"` on error.
+
+### Mode: `generate`
+
+**Function:** `generate_from_text(content, page_info, page_ref, model_id, api_key, n=8) -> list[dict]`
+
+Creates MCQ questions from scratch using plain text/study material. The LLM generates questions where:
+- The correct answer is directly supported by the source text
+- 3 plausible distractors are created from medical knowledge
+- Questions prefer clinical application over pure recall
+- Each question includes a 1-2 sentence explanation
+
+**Prompt (`GENERATE_PROMPT`):** Targets `QUESTIONS_PER_CHUNK = 8` questions per ~50-page chunk.
+
+**Validation:** Checks that `correct_answer` is among the `options` list. Attempts fuzzy matching (substring) if exact match fails. Skips malformed questions.
+
+### Helper: `_normalize(text) -> str`
+
+Fixes common OCR artifacts in PREP PDFs:
+- `"Pref erred"`, `"Pre ferred"`, `"Prefer red"` -> `"Preferred"`
+- `"ltem"`, `"ltcm"` -> `"Item"` (lowercase L misread as I)
+
+---
+
+## pdf_service.py
+
+PDF text and image extraction using PyMuPDF (fitz).
+
+### `get_page_count(file_path) -> int`
+
+Returns the total number of pages in a PDF.
+
+### `extract_text_by_page(file_path) -> dict[int, str]`
+
+Extracts text from every page. Returns `{page_number: text}` with 1-based page numbers. Skips pages with no text content.
+
+### `extract_text_for_range(file_path, start, end) -> str`
+
+Extracts text for a specific page range (1-indexed, inclusive). Each page is prefixed with `--- Page N ---`. Returns all pages joined with double newlines.
+
+### Image Extraction
+
+#### `extract_images_from_page(file_path, page_num, document_id) -> list[str]`
+
+Extracts images from a single PDF page and saves them to disk.
+
+**Filtering pipeline:**
+1. **Size filter:** Skips images smaller than 2000 bytes (icons, bullets, decorations)
+2. **MD5 hash skip list (`_SKIP_IMAGE_HASHES`):** Known repeated branding images:
+   - `f48b094ec260f0aa8d7c52bc3cf562e4` -- AAP logo (34300 bytes, appears 869 times across PREP PDFs)
+   - `82c449d72791fe181fc9964bb8efad0f` -- Sepsis document header/logo (20397 bytes, repeated per page)
+3. **Dimension filter:** Skips images where width < 80px or height < 80px
+
+Images are saved to `{UPLOAD_DIR}/images/doc_{document_id}/page_{N}_img_{idx}.{ext}`. Returns relative paths for serving (e.g. `images/doc_5/page_12_img_0.png`).
+
+#### `extract_all_images(file_path, document_id, start_page=1, end_page=None) -> dict[int, list[str]]`
+
+Batch version that extracts images from a page range. Returns `{page_num: [image_paths]}`.
+
+---
+
+## vector_service.py
+
+ChromaDB integration for storing and querying document page embeddings. Used for semantic search within documents during quiz extraction.
+
+### ChromaDB Client Singleton
+
+**`get_client() -> chromadb.PersistentClient`**
+
+Returns a module-level singleton `PersistentClient`. Persistence directory is `settings.CHROMA_PERSIST_DIR`.
+
+### `LiteLLMEmbeddingFunction`
+
+Custom ChromaDB `EmbeddingFunction` implementation that calls the LiteLLM proxy's `/v1/embeddings` endpoint directly via `httpx`. Uses the embedding model from `_get_embedding_model()` (Redis setting > env variable). Sends `dimensions` parameter from `settings.EMBEDDING_DIMENSIONS`.
+
+Only used when both an embedding model and `LITELLM_API_BASE` are configured; otherwise ChromaDB uses its default embedding function.
+
+### `get_or_create_collection(document_id) -> Collection`
+
+Gets or creates a ChromaDB collection named `doc_{document_id}`. Attaches the `LiteLLMEmbeddingFunction` if configured.
+
+### `delete_collection(document_id)`
+
+Deletes a document's ChromaDB collection. Silently handles errors.
+
+### `chunk_text(text, chunk_size=1000, overlap=200) -> list[str]`
+
+Splits text into overlapping chunks for embedding. Default: 1000-character chunks with 200-character overlap. Returns the full text as a single chunk if it is shorter than `chunk_size`.
+
+### `store_pages(document_id, pages: dict[int, str])`
+
+Stores all page text as chunked embeddings in ChromaDB.
+
+- Each chunk gets an ID of `doc_{id}_page_{num}_chunk_{i}`
+- Metadata includes `page_num` and `document_id`
+- **Batch size:** 100 chunks per API call
+- **Rate limiting:** 3-second delay between batches to avoid embedding API rate limits
+
+### `query_pages(document_id, query, start_page=None, end_page=None, n_results=20) -> list[dict]`
+
+Semantic query against a document's vector collection. Supports optional page range filter via ChromaDB `$and` / `$gte` / `$lte` operators. Returns `[{"text": "...", "page_num": N}]`.
+
+### `get_pages_text(document_id, start_page, end_page) -> str`
+
+Retrieves all stored text for a page range, reconstructing the original text from chunks.
+
+**Overlap deduplication:** When reassembling chunks for the same page, strips the first 200 characters (the overlap region) from each subsequent chunk to avoid duplicated content.
+
+Output is sorted by page number, each page prefixed with `--- Page N ---`.
+
+---
+
+## embedding_service.py
+
+Question-level embedding generation for pgvector semantic search (separate from the ChromaDB document embeddings in vector_service).
+
+### `_get_embedding_model() -> str`
+
+Resolves the active embedding model. Priority:
+1. Redis key `settings:embedding_model` (set via admin settings)
+2. Environment variable `LITELLM_EMBEDDING_MODEL`
+
+This allows changing the embedding model at runtime without restarting the application.
+
+### `generate_embedding(text: str) -> list[float] | None`
+
+Generates an embedding vector for the given text.
+
+**Input processing:** Collapses whitespace, truncates to 4000 characters.
+
+**Provider priority:**
+1. **LiteLLM proxy** (direct httpx to `/v1/embeddings`): Used when `embedding_model`, `LITELLM_API_KEY`, and `LITELLM_API_BASE` are all configured. Sends the `dimensions` parameter from `settings.EMBEDDING_DIMENSIONS`. Validates that the returned embedding has the expected dimension count.
+2. **AWS Bedrock Titan Embed V2** (direct fallback): Uses `amazon.titan-embed-text-v2:0` via `boto3`. Requires `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY`. Region from `AWS_BEDROCK_REGION` or defaults to `us-east-1`.
+
+Returns `None` if all providers fail.
+
+### `embed_question(question) -> bool`
+
+Convenience function that generates and stores an embedding on a Question ORM object.
+
+**Text construction (`_text_for_question`):** Concatenates the question stem and all options (no explanation), truncated to 4000 characters. This ensures semantic search matches on question content, not answer explanations.
+
+Returns `True` on success, `False` on failure.
+
+---
+
+## email_service.py
+
+Email sending via `fastapi-mail` with SMTP. Uses clean, minimal HTML templates.
+
+### Configuration
+
+**`get_mail_config() -> ConnectionConfig`**
+
+Builds the FastMail connection configuration from settings:
+- `MAIL_USERNAME`, `MAIL_PASSWORD`, `MAIL_FROM`, `MAIL_PORT`, `MAIL_SERVER`
+- `MAIL_STARTTLS`, `MAIL_SSL_TLS`
+- `USE_CREDENTIALS` is `True` when both username and password are set
+
+From name is hardcoded to `"PedsHub"`.
+
+### Template Rendering
+
+#### `_render(md: str) -> str`
+
+Minimal Markdown-to-HTML converter for email templates. Supports:
+- `# H1` and `## H2` headings
+- `**bold**` inline
+- `> blockquote`
+- `---` horizontal rule
+- `[button:Label](url)` -- renders as a dark call-to-action button
+- `[link:Label](url)` -- renders as a small copy-this-link line
+- Plain paragraphs
+
+Style: white background, dark text (#09090b), clean sans-serif, single column (540px max width).
+
+#### `_wrap(subject, body_md) -> str`
+
+Wraps rendered body HTML in a full email document with:
+- PedsHub logo/header
+- White card container with border
+- Footer with app URL and "Didn't expect this email?" note
+
+### `_send(to_email, subject, html)`
+
+Low-level send function. Silently logs and returns if SMTP is not configured (no `MAIL_USERNAME` or `MAIL_FROM`). Uses `fastapi-mail` `FastMail.send_message()` with HTML subtype.
+
+### Email Templates
+
+#### `send_verification_email(to_email, name, token)`
+
+Subject: "Verify your PedsHub email". Contains a verification button linking to `{APP_URL}/verify-email?token={token}`. Notes 24-hour expiry.
+
+#### `send_password_reset_email(to_email, name, token)`
+
+Subject: "Reset your PedsHub password". Contains a reset button linking to `{APP_URL}/reset-password?token={token}`. Notes 1-hour expiry and single use.
+
+#### `send_reminder_email(email, user_name, quiz_title, score, next_date)`
+
+Subject: "Time to review: {quiz_title}". Shows last score percentage with contextual message (encouraging if >= 75%, motivational if below). Contains a "Take Quiz Now" button. Mentions spaced repetition benefits.
+
+---
+
+## reminder_service.py
+
+Simplified SM-2 spaced repetition scheduler for quiz review reminders.
+
+### Interval Schedule
+
+```python
+INTERVALS = [1, 3, 7, 14, 30]  # days
+```
+
+### `update_reminder_schedule(db, user_id, quiz_id, score_percentage)`
+
+Called after every quiz attempt submission. Creates or updates a `ReminderSchedule` record.
+
+**Algorithm:**
+
+1. Find or create the reminder for this user+quiz pair
+2. Determine the current position in the interval schedule
+3. Adjust based on score:
+
+| Score | Action | Detail |
+|---|---|---|
+| < 75% | Reset to shortest interval | `INTERVALS[0]` = 1 day |
+| 75% - 89% | Advance one step | e.g. 1 -> 3 days |
+| >= 90% | Advance two steps or deactivate | If already at max interval (30 days), sets `is_active = False` (mastered) |
+
+4. Set `next_reminder_at` to `now + new_interval`
+
+**Deactivation:** When a user scores >= 90% and is already at the longest interval (30 days), the reminder is deactivated, indicating the material is considered mastered.
+
+The reminder records are used by a separate scheduled task (not in this service) to send `send_reminder_email()` notifications.
diff --git a/frontend/Dockerfile b/frontend/Dockerfile
index 940a44f..3a5439b 100644
--- a/frontend/Dockerfile
+++ b/frontend/Dockerfile
@@ -1,13 +1,15 @@
 FROM node:18-alpine AS build
 
 WORKDIR /app
-COPY package.json .
-RUN npm install
+COPY package.json package-lock.json ./
+RUN npm ci
 COPY . .
 RUN npm run build
 
 FROM nginx:alpine
 COPY --from=build /app/dist /usr/share/nginx/html
 COPY nginx.conf /etc/nginx/conf.d/default.conf
+COPY docker-entrypoint.sh /docker-entrypoint.sh
+RUN chmod +x /docker-entrypoint.sh
 EXPOSE 80
-CMD ["nginx", "-g", "daemon off;"]
+CMD ["/docker-entrypoint.sh"]
diff --git a/frontend/docker-entrypoint.sh b/frontend/docker-entrypoint.sh
new file mode 100644
index 0000000..ee2c899
--- /dev/null
+++ b/frontend/docker-entrypoint.sh
@@ -0,0 +1,10 @@
+#!/bin/sh
+# Generate runtime config from environment variables.
+# This avoids baking secrets/keys into the Docker image at build time.
+cat > /usr/share/nginx/html/config.js <<EOF
+window.__APP_CONFIG__ = {
+  TURNSTILE_SITE_KEY: "${TURNSTILE_SITE_KEY:-}"
+};
+EOF
+
+exec nginx -g 'daemon off;'
diff --git a/frontend/index.html b/frontend/index.html
index 69d2545..1b8cb15 100644
--- a/frontend/index.html
+++ b/frontend/index.html
@@ -6,6 +6,7 @@
     <title>PedsHub</title>
     <meta name="description" content="Pediatric learning platform — create quizzes from PDFs, study with AI explanations, and track your progress." />
     <link rel="icon" href="data:image/svg+xml,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 100 100'><text y='.9em' font-size='90'>🏥</text></svg>" />
+    <link rel="manifest" href="/manifest.json" />
     <!-- Inter: clean professional UI font -->
     <link rel="preconnect" href="https://fonts.googleapis.com" />
     <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
@@ -13,6 +14,14 @@
   </head>
   <body>
     <div id="root"></div>
+    <script src="/config.js"></script>
     <script type="module" src="/src/main.jsx"></script>
+    <script>
+      if ('serviceWorker' in navigator) {
+        window.addEventListener('load', () => {
+          navigator.serviceWorker.register('/sw.js').catch(() => {})
+        })
+      }
+    </script>
   </body>
 </html>
diff --git a/frontend/nginx.conf b/frontend/nginx.conf
index f3a83be..79d8f91 100644
--- a/frontend/nginx.conf
+++ b/frontend/nginx.conf
@@ -35,6 +35,16 @@ server {
         proxy_read_timeout 600s;
     }
 
+    # Uploaded images proxy to backend
+    location /uploads/ {
+        resolver 127.0.0.11 valid=10s;
+        set $backend http://backend:8000;
+        proxy_pass $backend;
+        proxy_set_header Host $host;
+        expires 7d;
+        add_header Cache-Control "public, immutable";
+    }
+
     # SPA fallback
     location / {
         try_files $uri $uri/ /index.html;
diff --git a/frontend/package-lock.json b/frontend/package-lock.json
index 6bd82c4..1a338ea 100644
--- a/frontend/package-lock.json
+++ b/frontend/package-lock.json
@@ -12,7 +12,9 @@
         "react": "^18.2.0",
         "react-dom": "^18.2.0",
         "react-markdown": "^10.1.0",
-        "react-router-dom": "^6.22.0"
+        "react-router-dom": "^6.22.0",
+        "rehype-raw": "^7.0.0",
+        "remark-gfm": "^4.0.1"
       },
       "devDependencies": {
         "@types/react": "^18.2.55",
@@ -1537,6 +1539,18 @@
       "dev": true,
       "license": "ISC"
     },
+    "node_modules/entities": {
+      "version": "6.0.1",
+      "resolved": "https://registry.npmjs.org/entities/-/entities-6.0.1.tgz",
+      "integrity": "sha512-aN97NXWF6AWBTahfVOIrB/NShkzi5H7F9r1s9mD3cDj4Ko5f2qhhVoYMibXF7GlLveb/D2ioWay8lxI97Ven3g==",
+      "license": "BSD-2-Clause",
+      "engines": {
+        "node": ">=0.12"
+      },
+      "funding": {
+        "url": "https://github.com/fb55/entities?sponsor=1"
+      }
+    },
     "node_modules/es-define-property": {
       "version": "1.0.1",
       "resolved": "https://registry.npmjs.org/es-define-property/-/es-define-property-1.0.1.tgz",
@@ -1631,6 +1645,18 @@
         "node": ">=6"
       }
     },
+    "node_modules/escape-string-regexp": {
+      "version": "5.0.0",
+      "resolved": "https://registry.npmjs.org/escape-string-regexp/-/escape-string-regexp-5.0.0.tgz",
+      "integrity": "sha512-/veY75JbMK4j1yjvuUxuVsiS/hr/4iHs9FTT6cgTexxdE0Ly/glccBAkloH/DofkjRbZU3bnoj38mOmhkZ0lHw==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=12"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
     "node_modules/estree-util-is-identifier-name": {
       "version": "3.0.0",
       "resolved": "https://registry.npmjs.org/estree-util-is-identifier-name/-/estree-util-is-identifier-name-3.0.0.tgz",
@@ -1805,6 +1831,64 @@
         "node": ">= 0.4"
       }
     },
+    "node_modules/hast-util-from-parse5": {
+      "version": "8.0.3",
+      "resolved": "https://registry.npmjs.org/hast-util-from-parse5/-/hast-util-from-parse5-8.0.3.tgz",
+      "integrity": "sha512-3kxEVkEKt0zvcZ3hCRYI8rqrgwtlIOFMWkbclACvjlDw8Li9S2hk/d51OI0nr/gIpdMHNepwgOKqZ/sy0Clpyg==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/hast": "^3.0.0",
+        "@types/unist": "^3.0.0",
+        "devlop": "^1.0.0",
+        "hastscript": "^9.0.0",
+        "property-information": "^7.0.0",
+        "vfile": "^6.0.0",
+        "vfile-location": "^5.0.0",
+        "web-namespaces": "^2.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      }
+    },
+    "node_modules/hast-util-parse-selector": {
+      "version": "4.0.0",
+      "resolved": "https://registry.npmjs.org/hast-util-parse-selector/-/hast-util-parse-selector-4.0.0.tgz",
+      "integrity": "sha512-wkQCkSYoOGCRKERFWcxMVMOcYE2K1AaNLU8DXS9arxnLOUEWbOXKXiJUNzEpqZ3JOKpnha3jkFrumEjVliDe7A==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/hast": "^3.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      }
+    },
+    "node_modules/hast-util-raw": {
+      "version": "9.1.0",
+      "resolved": "https://registry.npmjs.org/hast-util-raw/-/hast-util-raw-9.1.0.tgz",
+      "integrity": "sha512-Y8/SBAHkZGoNkpzqqfCldijcuUKh7/su31kEBp67cFY09Wy0mTRgtsLYsiIxMJxlu0f6AA5SUTbDR8K0rxnbUw==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/hast": "^3.0.0",
+        "@types/unist": "^3.0.0",
+        "@ungap/structured-clone": "^1.0.0",
+        "hast-util-from-parse5": "^8.0.0",
+        "hast-util-to-parse5": "^8.0.0",
+        "html-void-elements": "^3.0.0",
+        "mdast-util-to-hast": "^13.0.0",
+        "parse5": "^7.0.0",
+        "unist-util-position": "^5.0.0",
+        "unist-util-visit": "^5.0.0",
+        "vfile": "^6.0.0",
+        "web-namespaces": "^2.0.0",
+        "zwitch": "^2.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      }
+    },
     "node_modules/hast-util-to-jsx-runtime": {
       "version": "2.3.6",
       "resolved": "https://registry.npmjs.org/hast-util-to-jsx-runtime/-/hast-util-to-jsx-runtime-2.3.6.tgz",
@@ -1832,6 +1916,25 @@
         "url": "https://opencollective.com/unified"
       }
     },
+    "node_modules/hast-util-to-parse5": {
+      "version": "8.0.1",
+      "resolved": "https://registry.npmjs.org/hast-util-to-parse5/-/hast-util-to-parse5-8.0.1.tgz",
+      "integrity": "sha512-MlWT6Pjt4CG9lFCjiz4BH7l9wmrMkfkJYCxFwKQic8+RTZgWPuWxwAfjJElsXkex7DJjfSJsQIt931ilUgmwdA==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/hast": "^3.0.0",
+        "comma-separated-tokens": "^2.0.0",
+        "devlop": "^1.0.0",
+        "property-information": "^7.0.0",
+        "space-separated-tokens": "^2.0.0",
+        "web-namespaces": "^2.0.0",
+        "zwitch": "^2.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      }
+    },
     "node_modules/hast-util-whitespace": {
       "version": "3.0.0",
       "resolved": "https://registry.npmjs.org/hast-util-whitespace/-/hast-util-whitespace-3.0.0.tgz",
@@ -1845,6 +1948,23 @@
         "url": "https://opencollective.com/unified"
       }
     },
+    "node_modules/hastscript": {
+      "version": "9.0.1",
+      "resolved": "https://registry.npmjs.org/hastscript/-/hastscript-9.0.1.tgz",
+      "integrity": "sha512-g7df9rMFX/SPi34tyGCyUBREQoKkapwdY/T04Qn9TDWfHhAYt4/I0gMVirzK5wEzeUqIjEB+LXC/ypb7Aqno5w==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/hast": "^3.0.0",
+        "comma-separated-tokens": "^2.0.0",
+        "hast-util-parse-selector": "^4.0.0",
+        "property-information": "^7.0.0",
+        "space-separated-tokens": "^2.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      }
+    },
     "node_modules/html-url-attributes": {
       "version": "3.0.1",
       "resolved": "https://registry.npmjs.org/html-url-attributes/-/html-url-attributes-3.0.1.tgz",
@@ -1855,6 +1975,16 @@
         "url": "https://opencollective.com/unified"
       }
     },
+    "node_modules/html-void-elements": {
+      "version": "3.0.0",
+      "resolved": "https://registry.npmjs.org/html-void-elements/-/html-void-elements-3.0.0.tgz",
+      "integrity": "sha512-bEqo66MRXsUGxWHV5IP0PUiAWwoEjba4VCzg0LjFJBpchPaTfyfCKTG6bc5F8ucKec3q5y6qOdGyYTSBEvhCrg==",
+      "license": "MIT",
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/wooorm"
+      }
+    },
     "node_modules/inline-style-parser": {
       "version": "0.2.7",
       "resolved": "https://registry.npmjs.org/inline-style-parser/-/inline-style-parser-0.2.7.tgz",
@@ -1981,6 +2111,16 @@
         "yallist": "^3.0.2"
       }
     },
+    "node_modules/markdown-table": {
+      "version": "3.0.4",
+      "resolved": "https://registry.npmjs.org/markdown-table/-/markdown-table-3.0.4.tgz",
+      "integrity": "sha512-wiYz4+JrLyb/DqW2hkFJxP7Vd7JuTDm77fvbM8VfEQdmSMqcImWeeRbHwZjBjIFki/VaMK2BhFi7oUUZeM5bqw==",
+      "license": "MIT",
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/wooorm"
+      }
+    },
     "node_modules/math-intrinsics": {
       "version": "1.1.0",
       "resolved": "https://registry.npmjs.org/math-intrinsics/-/math-intrinsics-1.1.0.tgz",
@@ -1990,6 +2130,22 @@
         "node": ">= 0.4"
       }
     },
+    "node_modules/mdast-util-find-and-replace": {
+      "version": "3.0.2",
+      "resolved": "https://registry.npmjs.org/mdast-util-find-and-replace/-/mdast-util-find-and-replace-3.0.2.tgz",
+      "integrity": "sha512-Tmd1Vg/m3Xz43afeNxDIhWRtFZgM2VLyaf4vSTYwudTyeuTneoL3qtWMA5jeLyz/O1vDJmmV4QuScFCA2tBPwg==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/mdast": "^4.0.0",
+        "escape-string-regexp": "^5.0.0",
+        "unist-util-is": "^6.0.0",
+        "unist-util-visit-parents": "^6.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      }
+    },
     "node_modules/mdast-util-from-markdown": {
       "version": "2.0.3",
       "resolved": "https://registry.npmjs.org/mdast-util-from-markdown/-/mdast-util-from-markdown-2.0.3.tgz",
@@ -2014,6 +2170,107 @@
         "url": "https://opencollective.com/unified"
       }
     },
+    "node_modules/mdast-util-gfm": {
+      "version": "3.1.0",
+      "resolved": "https://registry.npmjs.org/mdast-util-gfm/-/mdast-util-gfm-3.1.0.tgz",
+      "integrity": "sha512-0ulfdQOM3ysHhCJ1p06l0b0VKlhU0wuQs3thxZQagjcjPrlFRqY215uZGHHJan9GEAXd9MbfPjFJz+qMkVR6zQ==",
+      "license": "MIT",
+      "dependencies": {
+        "mdast-util-from-markdown": "^2.0.0",
+        "mdast-util-gfm-autolink-literal": "^2.0.0",
+        "mdast-util-gfm-footnote": "^2.0.0",
+        "mdast-util-gfm-strikethrough": "^2.0.0",
+        "mdast-util-gfm-table": "^2.0.0",
+        "mdast-util-gfm-task-list-item": "^2.0.0",
+        "mdast-util-to-markdown": "^2.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      }
+    },
+    "node_modules/mdast-util-gfm-autolink-literal": {
+      "version": "2.0.1",
+      "resolved": "https://registry.npmjs.org/mdast-util-gfm-autolink-literal/-/mdast-util-gfm-autolink-literal-2.0.1.tgz",
+      "integrity": "sha512-5HVP2MKaP6L+G6YaxPNjuL0BPrq9orG3TsrZ9YXbA3vDw/ACI4MEsnoDpn6ZNm7GnZgtAcONJyPhOP8tNJQavQ==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/mdast": "^4.0.0",
+        "ccount": "^2.0.0",
+        "devlop": "^1.0.0",
+        "mdast-util-find-and-replace": "^3.0.0",
+        "micromark-util-character": "^2.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      }
+    },
+    "node_modules/mdast-util-gfm-footnote": {
+      "version": "2.1.0",
+      "resolved": "https://registry.npmjs.org/mdast-util-gfm-footnote/-/mdast-util-gfm-footnote-2.1.0.tgz",
+      "integrity": "sha512-sqpDWlsHn7Ac9GNZQMeUzPQSMzR6Wv0WKRNvQRg0KqHh02fpTz69Qc1QSseNX29bhz1ROIyNyxExfawVKTm1GQ==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/mdast": "^4.0.0",
+        "devlop": "^1.1.0",
+        "mdast-util-from-markdown": "^2.0.0",
+        "mdast-util-to-markdown": "^2.0.0",
+        "micromark-util-normalize-identifier": "^2.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      }
+    },
+    "node_modules/mdast-util-gfm-strikethrough": {
+      "version": "2.0.0",
+      "resolved": "https://registry.npmjs.org/mdast-util-gfm-strikethrough/-/mdast-util-gfm-strikethrough-2.0.0.tgz",
+      "integrity": "sha512-mKKb915TF+OC5ptj5bJ7WFRPdYtuHv0yTRxK2tJvi+BDqbkiG7h7u/9SI89nRAYcmap2xHQL9D+QG/6wSrTtXg==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/mdast": "^4.0.0",
+        "mdast-util-from-markdown": "^2.0.0",
+        "mdast-util-to-markdown": "^2.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      }
+    },
+    "node_modules/mdast-util-gfm-table": {
+      "version": "2.0.0",
+      "resolved": "https://registry.npmjs.org/mdast-util-gfm-table/-/mdast-util-gfm-table-2.0.0.tgz",
+      "integrity": "sha512-78UEvebzz/rJIxLvE7ZtDd/vIQ0RHv+3Mh5DR96p7cS7HsBhYIICDBCu8csTNWNO6tBWfqXPWekRuj2FNOGOZg==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/mdast": "^4.0.0",
+        "devlop": "^1.0.0",
+        "markdown-table": "^3.0.0",
+        "mdast-util-from-markdown": "^2.0.0",
+        "mdast-util-to-markdown": "^2.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      }
+    },
+    "node_modules/mdast-util-gfm-task-list-item": {
+      "version": "2.0.0",
+      "resolved": "https://registry.npmjs.org/mdast-util-gfm-task-list-item/-/mdast-util-gfm-task-list-item-2.0.0.tgz",
+      "integrity": "sha512-IrtvNvjxC1o06taBAVJznEnkiHxLFTzgonUdy8hzFVeDun0uTjxxrRGVaNFqkU1wJR3RBPEfsxmU6jDWPofrTQ==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/mdast": "^4.0.0",
+        "devlop": "^1.0.0",
+        "mdast-util-from-markdown": "^2.0.0",
+        "mdast-util-to-markdown": "^2.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      }
+    },
     "node_modules/mdast-util-mdx-expression": {
       "version": "2.0.1",
       "resolved": "https://registry.npmjs.org/mdast-util-mdx-expression/-/mdast-util-mdx-expression-2.0.1.tgz",
@@ -2212,6 +2469,127 @@
         "micromark-util-types": "^2.0.0"
       }
     },
+    "node_modules/micromark-extension-gfm": {
+      "version": "3.0.0",
+      "resolved": "https://registry.npmjs.org/micromark-extension-gfm/-/micromark-extension-gfm-3.0.0.tgz",
+      "integrity": "sha512-vsKArQsicm7t0z2GugkCKtZehqUm31oeGBV/KVSorWSy8ZlNAv7ytjFhvaryUiCUJYqs+NoE6AFhpQvBTM6Q4w==",
+      "license": "MIT",
+      "dependencies": {
+        "micromark-extension-gfm-autolink-literal": "^2.0.0",
+        "micromark-extension-gfm-footnote": "^2.0.0",
+        "micromark-extension-gfm-strikethrough": "^2.0.0",
+        "micromark-extension-gfm-table": "^2.0.0",
+        "micromark-extension-gfm-tagfilter": "^2.0.0",
+        "micromark-extension-gfm-task-list-item": "^2.0.0",
+        "micromark-util-combine-extensions": "^2.0.0",
+        "micromark-util-types": "^2.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      }
+    },
+    "node_modules/micromark-extension-gfm-autolink-literal": {
+      "version": "2.1.0",
+      "resolved": "https://registry.npmjs.org/micromark-extension-gfm-autolink-literal/-/micromark-extension-gfm-autolink-literal-2.1.0.tgz",
+      "integrity": "sha512-oOg7knzhicgQ3t4QCjCWgTmfNhvQbDDnJeVu9v81r7NltNCVmhPy1fJRX27pISafdjL+SVc4d3l48Gb6pbRypw==",
+      "license": "MIT",
+      "dependencies": {
+        "micromark-util-character": "^2.0.0",
+        "micromark-util-sanitize-uri": "^2.0.0",
+        "micromark-util-symbol": "^2.0.0",
+        "micromark-util-types": "^2.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      }
+    },
+    "node_modules/micromark-extension-gfm-footnote": {
+      "version": "2.1.0",
+      "resolved": "https://registry.npmjs.org/micromark-extension-gfm-footnote/-/micromark-extension-gfm-footnote-2.1.0.tgz",
+      "integrity": "sha512-/yPhxI1ntnDNsiHtzLKYnE3vf9JZ6cAisqVDauhp4CEHxlb4uoOTxOCJ+9s51bIB8U1N1FJ1RXOKTIlD5B/gqw==",
+      "license": "MIT",
+      "dependencies": {
+        "devlop": "^1.0.0",
+        "micromark-core-commonmark": "^2.0.0",
+        "micromark-factory-space": "^2.0.0",
+        "micromark-util-character": "^2.0.0",
+        "micromark-util-normalize-identifier": "^2.0.0",
+        "micromark-util-sanitize-uri": "^2.0.0",
+        "micromark-util-symbol": "^2.0.0",
+        "micromark-util-types": "^2.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      }
+    },
+    "node_modules/micromark-extension-gfm-strikethrough": {
+      "version": "2.1.0",
+      "resolved": "https://registry.npmjs.org/micromark-extension-gfm-strikethrough/-/micromark-extension-gfm-strikethrough-2.1.0.tgz",
+      "integrity": "sha512-ADVjpOOkjz1hhkZLlBiYA9cR2Anf8F4HqZUO6e5eDcPQd0Txw5fxLzzxnEkSkfnD0wziSGiv7sYhk/ktvbf1uw==",
+      "license": "MIT",
+      "dependencies": {
+        "devlop": "^1.0.0",
+        "micromark-util-chunked": "^2.0.0",
+        "micromark-util-classify-character": "^2.0.0",
+        "micromark-util-resolve-all": "^2.0.0",
+        "micromark-util-symbol": "^2.0.0",
+        "micromark-util-types": "^2.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      }
+    },
+    "node_modules/micromark-extension-gfm-table": {
+      "version": "2.1.1",
+      "resolved": "https://registry.npmjs.org/micromark-extension-gfm-table/-/micromark-extension-gfm-table-2.1.1.tgz",
+      "integrity": "sha512-t2OU/dXXioARrC6yWfJ4hqB7rct14e8f7m0cbI5hUmDyyIlwv5vEtooptH8INkbLzOatzKuVbQmAYcbWoyz6Dg==",
+      "license": "MIT",
+      "dependencies": {
+        "devlop": "^1.0.0",
+        "micromark-factory-space": "^2.0.0",
+        "micromark-util-character": "^2.0.0",
+        "micromark-util-symbol": "^2.0.0",
+        "micromark-util-types": "^2.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      }
+    },
+    "node_modules/micromark-extension-gfm-tagfilter": {
+      "version": "2.0.0",
+      "resolved": "https://registry.npmjs.org/micromark-extension-gfm-tagfilter/-/micromark-extension-gfm-tagfilter-2.0.0.tgz",
+      "integrity": "sha512-xHlTOmuCSotIA8TW1mDIM6X2O1SiX5P9IuDtqGonFhEK0qgRI4yeC6vMxEV2dgyr2TiD+2PQ10o+cOhdVAcwfg==",
+      "license": "MIT",
+      "dependencies": {
+        "micromark-util-types": "^2.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      }
+    },
+    "node_modules/micromark-extension-gfm-task-list-item": {
+      "version": "2.1.0",
+      "resolved": "https://registry.npmjs.org/micromark-extension-gfm-task-list-item/-/micromark-extension-gfm-task-list-item-2.1.0.tgz",
+      "integrity": "sha512-qIBZhqxqI6fjLDYFTBIa4eivDMnP+OZqsNwmQ3xNLE4Cxwc+zfQEfbs6tzAo2Hjq+bh6q5F+Z8/cksrLFYWQQw==",
+      "license": "MIT",
+      "dependencies": {
+        "devlop": "^1.0.0",
+        "micromark-factory-space": "^2.0.0",
+        "micromark-util-character": "^2.0.0",
+        "micromark-util-symbol": "^2.0.0",
+        "micromark-util-types": "^2.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      }
+    },
     "node_modules/micromark-factory-destination": {
       "version": "2.0.1",
       "resolved": "https://registry.npmjs.org/micromark-factory-destination/-/micromark-factory-destination-2.0.1.tgz",
@@ -2663,6 +3041,18 @@
       "integrity": "sha512-CmBKiL6NNo/OqgmMn95Fk9Whlp2mtvIv+KNpQKN2F4SjvrEesubTRWGYSg+BnWZOnlCaSTU1sMpsBOzgbYhnsA==",
       "license": "MIT"
     },
+    "node_modules/parse5": {
+      "version": "7.3.0",
+      "resolved": "https://registry.npmjs.org/parse5/-/parse5-7.3.0.tgz",
+      "integrity": "sha512-IInvU7fabl34qmi9gY8XOVxhYyMyuH2xUNpb2q8/Y+7552KlejkRvqvD19nMoUW/uQGGbqNpA6Tufu5FL5BZgw==",
+      "license": "MIT",
+      "dependencies": {
+        "entities": "^6.0.0"
+      },
+      "funding": {
+        "url": "https://github.com/inikulin/parse5?sponsor=1"
+      }
+    },
     "node_modules/picocolors": {
       "version": "1.1.1",
       "resolved": "https://registry.npmjs.org/picocolors/-/picocolors-1.1.1.tgz",
@@ -2812,6 +3202,39 @@
         "react-dom": ">=16.8"
       }
     },
+    "node_modules/rehype-raw": {
+      "version": "7.0.0",
+      "resolved": "https://registry.npmjs.org/rehype-raw/-/rehype-raw-7.0.0.tgz",
+      "integrity": "sha512-/aE8hCfKlQeA8LmyeyQvQF3eBiLRGNlfBJEvWH7ivp9sBqs7TNqBL5X3v157rM4IFETqDnIOO+z5M/biZbo9Ww==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/hast": "^3.0.0",
+        "hast-util-raw": "^9.0.0",
+        "vfile": "^6.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      }
+    },
+    "node_modules/remark-gfm": {
+      "version": "4.0.1",
+      "resolved": "https://registry.npmjs.org/remark-gfm/-/remark-gfm-4.0.1.tgz",
+      "integrity": "sha512-1quofZ2RQ9EWdeN34S79+KExV1764+wCUGop5CPL1WGdD0ocPpu91lzPGbwWMECpEpd42kJGQwzRfyov9j4yNg==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/mdast": "^4.0.0",
+        "mdast-util-gfm": "^3.0.0",
+        "micromark-extension-gfm": "^3.0.0",
+        "remark-parse": "^11.0.0",
+        "remark-stringify": "^11.0.0",
+        "unified": "^11.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      }
+    },
     "node_modules/remark-parse": {
       "version": "11.0.0",
       "resolved": "https://registry.npmjs.org/remark-parse/-/remark-parse-11.0.0.tgz",
@@ -2845,6 +3268,21 @@
         "url": "https://opencollective.com/unified"
       }
     },
+    "node_modules/remark-stringify": {
+      "version": "11.0.0",
+      "resolved": "https://registry.npmjs.org/remark-stringify/-/remark-stringify-11.0.0.tgz",
+      "integrity": "sha512-1OSmLd3awB/t8qdoEOMazZkNsfVTeY4fTsgzcQFdXNq8ToTN4ZGwrMnlda4K6smTFKD+GRV6O48i6Z4iKgPPpw==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/mdast": "^4.0.0",
+        "mdast-util-to-markdown": "^2.0.0",
+        "unified": "^11.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      }
+    },
     "node_modules/rollup": {
       "version": "4.60.1",
       "resolved": "https://registry.npmjs.org/rollup/-/rollup-4.60.1.tgz",
@@ -3113,6 +3551,20 @@
         "url": "https://opencollective.com/unified"
       }
     },
+    "node_modules/vfile-location": {
+      "version": "5.0.3",
+      "resolved": "https://registry.npmjs.org/vfile-location/-/vfile-location-5.0.3.tgz",
+      "integrity": "sha512-5yXvWDEgqeiYiBe1lbxYF7UMAIm/IcopxMHrMQDq3nvKcjPKIhZklUKL+AE7J7uApI4kwe2snsK+eI6UTj9EHg==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/unist": "^3.0.0",
+        "vfile": "^6.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      }
+    },
     "node_modules/vfile-message": {
       "version": "4.0.3",
       "resolved": "https://registry.npmjs.org/vfile-message/-/vfile-message-4.0.3.tgz",
@@ -3187,6 +3639,16 @@
         }
       }
     },
+    "node_modules/web-namespaces": {
+      "version": "2.0.1",
+      "resolved": "https://registry.npmjs.org/web-namespaces/-/web-namespaces-2.0.1.tgz",
+      "integrity": "sha512-bKr1DkiNa2krS7qxNtdrtHAmzuYGFQLiQ13TsorsdT6ULTkPLKuu5+GsFpDlg6JFjUTwX2DyhMPG2be8uPrqsQ==",
+      "license": "MIT",
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/wooorm"
+      }
+    },
     "node_modules/yallist": {
       "version": "3.1.1",
       "resolved": "https://registry.npmjs.org/yallist/-/yallist-3.1.1.tgz",
diff --git a/frontend/package.json b/frontend/package.json
index 543a58c..8e4be52 100644
--- a/frontend/package.json
+++ b/frontend/package.json
@@ -13,7 +13,9 @@
     "react": "^18.2.0",
     "react-dom": "^18.2.0",
     "react-markdown": "^10.1.0",
-    "react-router-dom": "^6.22.0"
+    "react-router-dom": "^6.22.0",
+    "rehype-raw": "^7.0.0",
+    "remark-gfm": "^4.0.1"
   },
   "devDependencies": {
     "@types/react": "^18.2.55",
diff --git a/frontend/public/config.js b/frontend/public/config.js
new file mode 100644
index 0000000..d744707
--- /dev/null
+++ b/frontend/public/config.js
@@ -0,0 +1,2 @@
+// Fallback for local dev. In production, nginx generates this from env vars.
+window.__APP_CONFIG__ = window.__APP_CONFIG__ || {};
diff --git a/frontend/public/icon.svg b/frontend/public/icon.svg
new file mode 100644
index 0000000..07ef377
--- /dev/null
+++ b/frontend/public/icon.svg
@@ -0,0 +1,4 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 100 100">
+  <rect width="100" height="100" rx="20" fill="#0f172a"/>
+  <text y=".9em" font-size="72" x="14" fill="white">🏥</text>
+</svg>
diff --git a/frontend/public/manifest.json b/frontend/public/manifest.json
new file mode 100644
index 0000000..b9e35f1
--- /dev/null
+++ b/frontend/public/manifest.json
@@ -0,0 +1,19 @@
+{
+  "name": "PedsHub",
+  "short_name": "PedsHub",
+  "description": "Pediatric learning platform — quizzes, AI tutor, and question bank",
+  "start_url": "/",
+  "scope": "/",
+  "display": "standalone",
+  "orientation": "portrait-primary",
+  "theme_color": "#0f172a",
+  "background_color": "#0f172a",
+  "icons": [
+    {
+      "src": "/icon.svg",
+      "sizes": "any",
+      "type": "image/svg+xml",
+      "purpose": "any maskable"
+    }
+  ]
+}
diff --git a/frontend/public/sw.js b/frontend/public/sw.js
new file mode 100644
index 0000000..d961c81
--- /dev/null
+++ b/frontend/public/sw.js
@@ -0,0 +1,12 @@
+// Minimal service worker — network-only, no caching.
+// This exists solely to make the app installable as a PWA.
+// Do NOT add caching here: the app loads JS modules dynamically
+// and stale cache causes blank-screen / module-not-found failures.
+
+self.addEventListener('install', () => self.skipWaiting())
+self.addEventListener('activate', event => event.waitUntil(self.clients.claim()))
+
+// Pass every fetch straight through to the network.
+self.addEventListener('fetch', event => {
+  event.respondWith(fetch(event.request))
+})
diff --git a/frontend/src/components/Navbar.jsx b/frontend/src/components/Navbar.jsx
index e475494..f4fead5 100644
--- a/frontend/src/components/Navbar.jsx
+++ b/frontend/src/components/Navbar.jsx
@@ -57,7 +57,7 @@ function JobsBadge({ jobs }) {
   )
 }
 
-export default function Navbar() {
+export default function Navbar({ onSignIn, onRegister }) {
   const { user, logout } = useAuth()
   const [menuOpen, setMenuOpen] = useState(false)
   const [jobs, setJobs] = useState([])
@@ -101,7 +101,7 @@ export default function Navbar() {
       <div className="container navbar-inner">
         <Link to="/" className="logo" onClick={() => setMenuOpen(false)}>🏥 PedsHub</Link>
 
-        {user && (
+        {user ? (
           <>
             {/* Desktop nav */}
             <nav className="nav-desktop">
@@ -143,6 +143,18 @@ export default function Navbar() {
               </button>
             </div>
           </>
+        ) : (
+          /* Logged-out: Sign In + Register */
+          <div style={{ display: 'flex', gap: 8, alignItems: 'center' }}>
+            {onSignIn
+              ? <button onClick={onSignIn} style={{ fontSize: '0.875rem', color: 'var(--navbar-fg)', opacity: 0.8, background: 'none', border: 'none', cursor: 'pointer', padding: '6px 10px' }}>Sign In</button>
+              : <Link to="/login" style={{ fontSize: '0.875rem', color: 'var(--navbar-fg)', opacity: 0.8, textDecoration: 'none', padding: '6px 10px' }}>Sign In</Link>
+            }
+            {onRegister
+              ? <button onClick={onRegister} className="btn btn-primary" style={{ fontSize: '0.85rem', padding: '6px 14px', borderRadius: 8 }}>Register</button>
+              : <Link to="/register" className="btn btn-primary" style={{ fontSize: '0.85rem', padding: '6px 14px', textDecoration: 'none', borderRadius: 8 }}>Register</Link>
+            }
+          </div>
         )}
       </div>
 
diff --git a/frontend/src/components/TeachChat.jsx b/frontend/src/components/TeachChat.jsx
index 524e07a..c082502 100644
--- a/frontend/src/components/TeachChat.jsx
+++ b/frontend/src/components/TeachChat.jsx
@@ -1,5 +1,7 @@
 import { useState, useEffect, useRef } from 'react'
 import ReactMarkdown from 'react-markdown'
+import remarkGfm from 'remark-gfm'
+import rehypeRaw from 'rehype-raw'
 import api from '../api/client'
 
 /**
@@ -12,7 +14,7 @@ import api from '../api/client'
  *   Mobile  — bottom sheet, 70vh
  *   Desktop — right-side panel inside quiz-layout, 320px wide
  */
-export default function TeachChat({ question }) {
+export default function TeachChat({ question, elevated = false }) {
   const [open, setOpen] = useState(false)
   const [messages, setMessages] = useState([])   // {role, content, suggestions?}
   const [input, setInput] = useState('')
@@ -84,7 +86,7 @@ export default function TeachChat({ question }) {
     position: 'fixed',
     bottom: 80,
     right: 18,
-    zIndex: 400,
+    zIndex: elevated ? 1070 : 400,
     width: 48,
     height: 48,
     borderRadius: '50%',
@@ -111,7 +113,7 @@ export default function TeachChat({ question }) {
     background: 'var(--card-bg)',
     borderTop: '2px solid var(--primary)',
     borderRadius: '16px 16px 0 0',
-    zIndex: 390,
+    zIndex: elevated ? 1060 : 390,
     display: 'flex',
     flexDirection: 'column',
     boxShadow: '0 -8px 32px rgba(0,0,0,0.18)',
@@ -136,7 +138,7 @@ export default function TeachChat({ question }) {
         <div
           className="teach-chat-backdrop"
           onClick={() => setOpen(false)}
-          style={{ position: 'fixed', inset: 0, zIndex: 380, background: 'rgba(0,0,0,0.3)' }}
+          style={{ position: 'fixed', inset: 0, zIndex: elevated ? 1050 : 380, background: 'rgba(0,0,0,0.3)' }}
         />
       )}
 
@@ -198,13 +200,22 @@ export default function TeachChat({ question }) {
                   border: m.role === 'assistant' ? '1px solid var(--border)' : 'none',
                 }}>
                   {m.role === 'assistant'
-                    ? <ReactMarkdown components={{
+                    ? <ReactMarkdown remarkPlugins={[remarkGfm]} rehypePlugins={[rehypeRaw]} components={{
                         p: ({children}) => <p style={{margin: '0 0 6px'}}>{children}</p>,
                         ul: ({children}) => <ul style={{margin: '4px 0', paddingLeft: 18}}>{children}</ul>,
                         ol: ({children}) => <ol style={{margin: '4px 0', paddingLeft: 18}}>{children}</ol>,
                         li: ({children}) => <li style={{marginBottom: 2}}>{children}</li>,
                         strong: ({children}) => <strong style={{fontWeight: 700}}>{children}</strong>,
                         code: ({children}) => <code style={{background: 'var(--border)', borderRadius: 3, padding: '1px 4px', fontSize: '0.82em'}}>{children}</code>,
+                        table: ({children}) => (
+                          <div style={{overflowX: 'auto', margin: '6px 0'}}>
+                            <table style={{borderCollapse: 'collapse', width: '100%', fontSize: '0.82em'}}>{children}</table>
+                          </div>
+                        ),
+                        thead: ({children}) => <thead style={{background: 'var(--border)'}}>{children}</thead>,
+                        th: ({children}) => <th style={{border: '1px solid var(--border)', padding: '5px 10px', textAlign: 'left', fontWeight: 700, whiteSpace: 'nowrap'}}>{children}</th>,
+                        td: ({children}) => <td style={{border: '1px solid var(--border)', padding: '5px 10px'}}>{children}</td>,
+                        tr: ({children}) => <tr style={{borderBottom: '1px solid var(--border)'}}>{children}</tr>,
                       }}>{m.content}</ReactMarkdown>
                     : m.content
                   }
diff --git a/frontend/src/context/AuthContext.jsx b/frontend/src/context/AuthContext.jsx
index 986cea5..b9676d7 100644
--- a/frontend/src/context/AuthContext.jsx
+++ b/frontend/src/context/AuthContext.jsx
@@ -19,8 +19,8 @@ export function AuthProvider({ children }) {
     }
   }, [])
 
-  const login = async (email, password) => {
-    const res = await api.post('/auth/login', { email, password })
+  const login = async (email, password, turnstileToken) => {
+    const res = await api.post('/auth/login', { email, password, turnstile_token: turnstileToken || null })
     localStorage.setItem('token', res.data.access_token)
     const me = await api.get('/auth/me')
     setUser(me.data)
diff --git a/frontend/src/pages/AdminPage.jsx b/frontend/src/pages/AdminPage.jsx
index 9dd44ae..f70ab74 100644
--- a/frontend/src/pages/AdminPage.jsx
+++ b/frontend/src/pages/AdminPage.jsx
@@ -5,7 +5,7 @@ import api from '../api/client'
 import Dialog from '../components/Dialog'
 import { useDialog } from '../hooks/useDialog'
 
-const TASKS = ['extraction', 'tts', 'general', 'teach']
+const TASKS = ['extraction', 'tts', 'teach', 'keyword']
 
 export default function AdminPage() {
   const { user } = useAuth()
@@ -58,8 +58,8 @@ export default function AdminPage() {
     loadData()
   }, [user])
 
-  const loadData = async () => {
-    setLoading(true)
+  const loadData = async (showSpinner = true) => {
+    if (showSpinner) setLoading(true)
     try {
       const [usersRes, modelsRes, settingsRes] = await Promise.all([
         api.get('/admin/users'),
@@ -81,17 +81,29 @@ export default function AdminPage() {
     try {
       await api.put(`/admin/users/${userId}/role`, { role })
       setSuccess(`Role updated to ${role}`)
-      loadData()
+      loadData(false)
     } catch (err) {
       setError(err.response?.data?.detail || 'Failed to update role')
     }
   }
 
+  const deleteUser = async (userId, userName) => {
+    const ok = await openConfirm(`Delete user "${userName}"? This removes all their data (attempts, favorites, settings).`, { title: 'Delete User', confirmLabel: 'Delete', danger: true })
+    if (!ok) return
+    try {
+      await api.delete(`/admin/users/${userId}`)
+      setSuccess(`User "${userName}" deleted`)
+      loadData(false)
+    } catch (err) {
+      setError(err.response?.data?.detail || 'Failed to delete user')
+    }
+  }
+
   const toggleUnthrottle = async (userId, currentVal) => {
     try {
       await api.put(`/admin/users/${userId}/unthrottle`, { unthrottled: !currentVal })
       setSuccess(currentVal ? 'Rate limits restored for user' : 'Rate limits removed for user')
-      loadData()
+      loadData(false)
     } catch (err) {
       setError(err.response?.data?.detail || 'Failed to update throttle setting')
     }
@@ -104,7 +116,7 @@ export default function AdminPage() {
       await api.post('/admin/models', newModel)
       setSuccess('Model added')
       setNewModel({ name: '', model_id: '', task: 'extraction', api_key: '', is_active: true, is_default: false })
-      loadData()
+      loadData(false)
     } catch (err) {
       setError(err.response?.data?.detail || 'Failed to add model')
     }
@@ -114,7 +126,7 @@ export default function AdminPage() {
     try {
       await api.put(`/admin/models/${modelId}`, { is_default: true })
       setSuccess('Default model updated')
-      loadData()
+      loadData(false)
     } catch (err) {
       setError(err.response?.data?.detail || 'Failed to update')
     }
@@ -123,7 +135,7 @@ export default function AdminPage() {
   const toggleActive = async (model) => {
     try {
       await api.put(`/admin/models/${model.id}`, { is_active: !model.is_active })
-      loadData()
+      loadData(false)
     } catch (err) {
       setError(err.response?.data?.detail || 'Failed to update')
     }
@@ -134,7 +146,7 @@ export default function AdminPage() {
     if (!ok) return
     try {
       await api.delete(`/admin/models/${modelId}`)
-      loadData()
+      loadData(false)
     } catch (err) {
       setError(err.response?.data?.detail || 'Failed to delete')
     }
@@ -337,7 +349,7 @@ export default function AdminPage() {
               <div className="form-group">
                 <label>Adding model for task</label>
                 <select value={searchTaskHint} onChange={e => setSearchTaskHint(e.target.value)}>
-                  {['extraction', 'teach', 'general'].map(t => <option key={t} value={t}>{t}</option>)}
+                  {TASKS.filter(t => t !== 'tts').map(t => <option key={t} value={t}>{t}</option>)}
                 </select>
               </div>
             </div>
@@ -561,7 +573,7 @@ export default function AdminPage() {
               await api.post('/admin/users', newUser)
               setSuccess(`User ${newUser.email} created`)
               setNewUser({ name: '', email: '', password: '' })
-              loadData()
+              loadData(false)
             } catch (err) { setError(err.response?.data?.detail || 'Failed to create user') }
           }}>
             <div className="grid-2">
@@ -615,6 +627,15 @@ export default function AdminPage() {
                 >
                   {u.is_unthrottled ? '🔒 Throttle' : '🚀 Unlimited'}
                 </button>
+                {u.id !== user?.id && (
+                  <button
+                    className="btn btn-danger btn-sm"
+                    onClick={() => deleteUser(u.id, u.name || u.email)}
+                    style={{ fontSize: '0.75rem', padding: '3px 8px' }}
+                  >
+                    Delete
+                  </button>
+                )}
               </div>
             </div>
           ))}
diff --git a/frontend/src/pages/DashboardPage.jsx b/frontend/src/pages/DashboardPage.jsx
index 0b3a49e..68204dc 100644
--- a/frontend/src/pages/DashboardPage.jsx
+++ b/frontend/src/pages/DashboardPage.jsx
@@ -19,6 +19,23 @@ export default function DashboardPage() {
   const [history, setHistory] = useState([])
   const [selectedQuizId, setSelectedQuizId] = useState(null)
   const [loading, setLoading] = useState(true)
+  const [deletingAttempt, setDeletingAttempt] = useState(null)
+
+  const [confirmAttempt, setConfirmAttempt] = useState(null)
+
+  const deleteAttempt = async (attemptId) => {
+    if (confirmAttempt !== attemptId) { setConfirmAttempt(attemptId); return }
+    setDeletingAttempt(attemptId)
+    setConfirmAttempt(null)
+    try {
+      await api.delete(`/attempts/${attemptId}`)
+      setHistory(prev => prev.map(q => ({
+        ...q,
+        attempts: q.attempts.filter(a => a.attempt_id !== attemptId),
+      })).filter(q => q.attempts.length > 0))
+    } catch { }
+    finally { setDeletingAttempt(null) }
+  }
 
   useEffect(() => {
     const promises = [
@@ -33,7 +50,7 @@ export default function DashboardPage() {
       if (histRes.data.length > 0) setSelectedQuizId(histRes.data[0].quiz_id)
     }).catch(console.error)
       .finally(() => setLoading(false))
-  }, [])
+  }, [isModerator])
 
   if (loading) return <div className="loading"><div className="spinner"></div> Loading...</div>
 
@@ -98,6 +115,44 @@ export default function DashboardPage() {
                   ⚠️ Below 75% — a reminder will be sent to review this quiz
                 </p>
               )}
+              {/* Attempt rows with delete */}
+              {selectedQuiz.attempts.length > 0 && (
+                <div style={{ marginTop: 14, borderTop: '1px solid var(--border)', paddingTop: 10 }}>
+                  {[...selectedQuiz.attempts].reverse().map(a => (
+                    <div key={a.attempt_id} style={{
+                      display: 'flex', alignItems: 'center', gap: 10,
+                      padding: '5px 0', borderBottom: '1px solid var(--border)',
+                      fontSize: '0.82rem', color: 'var(--text-muted)',
+                    }}>
+                      <span style={{ flex: 1 }}>{new Date(a.date).toLocaleDateString()}</span>
+                      <Link to={`/results/${a.attempt_id}`} style={{ color: 'var(--primary)', textDecoration: 'none', fontWeight: 600 }}>
+                        {a.percentage}% ({a.score}/{a.total})
+                      </Link>
+                      {confirmAttempt === a.attempt_id ? (
+                        <>
+                          <button
+                            onClick={() => deleteAttempt(a.attempt_id)}
+                            disabled={deletingAttempt === a.attempt_id}
+                            style={{ background: 'none', border: 'none', cursor: 'pointer', color: 'var(--wrong-fg)', fontSize: '0.75rem', padding: '2px 4px', fontWeight: 700 }}
+                          >
+                            {deletingAttempt === a.attempt_id ? '…' : 'Delete'}
+                          </button>
+                          <button
+                            onClick={() => setConfirmAttempt(null)}
+                            style={{ background: 'none', border: 'none', cursor: 'pointer', color: 'var(--text-muted)', fontSize: '0.75rem', padding: '2px 4px' }}
+                          >Cancel</button>
+                        </>
+                      ) : (
+                        <button
+                          onClick={() => deleteAttempt(a.attempt_id)}
+                          style={{ background: 'none', border: 'none', cursor: 'pointer', color: 'var(--wrong-fg)', fontSize: '0.78rem', padding: '2px 6px', borderRadius: 4, opacity: 0.6 }}
+                          title="Delete this attempt"
+                        >✕</button>
+                      )}
+                    </div>
+                  ))}
+                </div>
+              )}
             </>
           )}
         </div>
diff --git a/frontend/src/pages/DocumentDetailPage.jsx b/frontend/src/pages/DocumentDetailPage.jsx
index 99608df..d896990 100644
--- a/frontend/src/pages/DocumentDetailPage.jsx
+++ b/frontend/src/pages/DocumentDetailPage.jsx
@@ -141,22 +141,27 @@ export default function DocumentDetailPage() {
       api.get('/question-categories/').catch(() => ({ data: [] })),
     ]).then(([modelsRes, catsRes]) => {
       setAvailableModels(modelsRes.data)
-      const def = modelsRes.data.find(m => m.is_default)
+      const def = modelsRes.data.find(m => m.is_default) || modelsRes.data[0]
       if (def) setSelectedModelId(def.model_id)
       setQuestionCategories(catsRes.data)
     })
   }, [id])
 
+  const [processingSteps, setProcessingSteps] = useState([])
   useEffect(() => {
     if (!doc || doc.status !== 'processing') return
     const interval = setInterval(() => {
-      api.get(`/documents/${id}/status`).then(res => {
-        if (res.data.status !== 'processing') {
+      Promise.all([
+        api.get(`/documents/${id}/status`),
+        api.get(`/documents/${id}/processing-steps`).catch(() => ({ data: { steps: [] } })),
+      ]).then(([statusRes, stepsRes]) => {
+        setProcessingSteps(stepsRes.data.steps || [])
+        if (statusRes.data.status !== 'processing') {
           fetchDoc()
           clearInterval(interval)
         }
       })
-    }, 3000)
+    }, 2000)
     return () => clearInterval(interval)
   }, [doc?.status])
 
@@ -275,9 +280,20 @@ export default function DocumentDetailPage() {
         </div>
 
         {doc.status === 'processing' && (
-          <div style={{ marginTop: 16, textAlign: 'center', color: '#64748b' }}>
-            <div className="spinner"></div>
-            <p style={{ marginTop: 8 }}>Processing PDF and extracting text... This may take a while for large files.</p>
+          <div style={{ marginTop: 16 }}>
+            <div style={{ display: 'flex', alignItems: 'center', gap: 10, marginBottom: 8 }}>
+              <div className="spinner"></div>
+              <span style={{ color: 'var(--text-muted)', fontSize: '0.9rem' }}>Processing PDF…</span>
+            </div>
+            {processingSteps.length > 0 && (
+              <div style={{ padding: '10px 14px', background: 'var(--bg)', borderRadius: 8, fontSize: '0.82rem', color: 'var(--text-muted)', maxHeight: 150, overflowY: 'auto' }}>
+                {processingSteps.map((s, i) => (
+                  <div key={i} style={{ marginBottom: 2 }}>
+                    {s.step === 'error' ? '✗' : s.step === 'done' ? '✓' : '›'} {s.message}
+                  </div>
+                ))}
+              </div>
+            )}
           </div>
         )}
         {doc.status === 'error' && (
@@ -368,6 +384,7 @@ export default function DocumentDetailPage() {
                         <option value="two_step">Two-Step — separate answer key section (PREP 2013 style)</option>
                         <option value="regex">AI + Regex — AI analyses format then applies regex for answers</option>
                         <option value="ai_decide">AI Decides — AI reads the document and picks best strategy</option>
+                        <option value="generate">Generate — AI creates questions from plain text / textbook chapters</option>
                       </select>
                       <p style={{ fontSize: '0.75rem', color: 'var(--text-subtle)', marginTop: 4 }}>
                         {extractionMode === 'standard' && 'Best for PREP 2012, 2014 and most PDFs with answers inline.'}
@@ -375,6 +392,7 @@ export default function DocumentDetailPage() {
                         {extractionMode === 'two_step' && 'For PDFs where all questions come first, then all answers at the back (PREP 2013 style).'}
                         {extractionMode === 'regex' && 'AI detects the answer pattern, then uses regex for fast reliable extraction.'}
                         {extractionMode === 'ai_decide' && 'AI samples the document and automatically picks the right strategy.'}
+                        {extractionMode === 'generate' && 'For textbook chapters, lecture notes, or any material without a Q&A format. AI creates MCQ questions with correct answers from the text.'}
                       </p>
                     </div>
                     {availableModels.length > 1 && (
diff --git a/frontend/src/pages/LandingPage.jsx b/frontend/src/pages/LandingPage.jsx
index c30b80d..42af2e7 100644
--- a/frontend/src/pages/LandingPage.jsx
+++ b/frontend/src/pages/LandingPage.jsx
@@ -1,20 +1,27 @@
 import { useState, useEffect, useRef } from 'react'
-import { Link } from 'react-router-dom'
+import { Link, useNavigate } from 'react-router-dom'
 import api from '../api/client'
 import { useAuth } from '../context/AuthContext'
+import Navbar from '../components/Navbar'
 
 // ── Turnstile widget ──────────────────────────────────────────────────────────
-const TURNSTILE_SITE_KEY = import.meta.env.VITE_TURNSTILE_SITE_KEY || ''
+const TURNSTILE_SITE_KEY = window.__APP_CONFIG__?.TURNSTILE_SITE_KEY || ''
 
 function TurnstileWidget({ onVerify }) {
   const ref = useRef(null)
+  const widgetId = useRef(null)
   useEffect(() => {
-    if (!TURNSTILE_SITE_KEY || !window.turnstile) return
-    const id = window.turnstile.render(ref.current, {
-      sitekey: TURNSTILE_SITE_KEY,
-      callback: onVerify,
-    })
-    return () => { try { window.turnstile.remove(id) } catch {} }
+    if (!TURNSTILE_SITE_KEY) return
+    let timer
+    const tryRender = () => {
+      if (!window.turnstile || !ref.current) { timer = setTimeout(tryRender, 200); return }
+      widgetId.current = window.turnstile.render(ref.current, {
+        sitekey: TURNSTILE_SITE_KEY,
+        callback: onVerify,
+      })
+    }
+    tryRender()
+    return () => { clearTimeout(timer); if (widgetId.current != null) try { window.turnstile.remove(widgetId.current) } catch {} }
   }, [])
   if (!TURNSTILE_SITE_KEY) return null
   return <div ref={ref} style={{ margin: '8px 0' }} />
@@ -157,11 +164,176 @@ function ContactForm() {
   )
 }
 
+// ── Auth modal (Sign In / Register as overlay) ──────────────────────────────
+function AuthModal({ mode, onClose, onSwitch }) {
+  const { login, loginWithToken } = useAuth()
+  const navigate = useNavigate()
+  const [name, setName] = useState('')
+  const [email, setEmail] = useState('')
+  const [password, setPassword] = useState('')
+  const [error, setError] = useState('')
+  const [loading, setLoading] = useState(false)
+  const [unverified, setUnverified] = useState(false)
+  const [turnstileToken, setTurnstileToken] = useState('')
+  const [resendSent, setResendSent] = useState(false)
+  const [resending, setResending] = useState(false)
+  const [registered, setRegistered] = useState(false)
+
+  const reset = () => { setError(''); setUnverified(false); setResendSent(false); setRegistered(false) }
+  const switchMode = (m) => { reset(); setName(''); setEmail(''); setPassword(''); onSwitch(m) }
+
+  const handleLogin = async (e) => {
+    e.preventDefault()
+    setError(''); setUnverified(false)
+    setLoading(true)
+    try {
+      await login(email, password, turnstileToken)
+      onClose()
+      navigate('/')
+    } catch (err) {
+      if (err.response?.status === 403) setUnverified(true)
+      else setError(err.response?.data?.detail || 'Login failed')
+    } finally { setLoading(false) }
+  }
+
+  const handleRegister = async (e) => {
+    e.preventDefault()
+    setError('')
+    setLoading(true)
+    try {
+      const res = await api.post('/auth/register', { email, password, name, turnstile_token: turnstileToken || null })
+      if (res.data.requires_verification) {
+        setRegistered(true)
+      } else {
+        await loginWithToken(res.data.access_token)
+        onClose()
+        navigate('/')
+      }
+    } catch (err) {
+      setError(err.response?.data?.detail || 'Registration failed')
+    } finally { setLoading(false) }
+  }
+
+  const resendVerification = async () => {
+    setResending(true)
+    try { await api.post('/auth/resend-verification', { email }) } catch {}
+    setResendSent(true)
+    setResending(false)
+  }
+
+  const isLogin = mode === 'login'
+
+  return (
+    <div onClick={onClose} style={{
+      position: 'fixed', inset: 0, background: 'rgba(0,0,0,0.55)', zIndex: 1000,
+      display: 'flex', alignItems: 'center', justifyContent: 'center', padding: 16,
+    }}>
+      <div onClick={e => e.stopPropagation()} style={{
+        background: 'var(--card-bg)', borderRadius: 'var(--card-radius, 14px)',
+        padding: '28px 24px', maxWidth: 400, width: '100%',
+        boxShadow: '0 20px 60px rgba(0,0,0,0.3)', position: 'relative',
+      }}>
+        <button onClick={onClose} style={{
+          position: 'absolute', top: 12, right: 14, background: 'none',
+          border: 'none', cursor: 'pointer', color: 'var(--text-muted)', fontSize: '1.2rem',
+        }}>✕</button>
+
+        {/* Tabs */}
+        <div style={{ display: 'flex', gap: 0, marginBottom: 20, borderBottom: '2px solid var(--border)' }}>
+          {[['login', 'Sign In'], ['register', 'Register']].map(([m, label]) => (
+            <button key={m} onClick={() => switchMode(m)} style={{
+              flex: 1, padding: '10px 0', background: 'none', border: 'none', cursor: 'pointer',
+              fontWeight: mode === m ? 700 : 400, fontSize: '0.95rem',
+              color: mode === m ? 'var(--primary)' : 'var(--text-muted)',
+              borderBottom: mode === m ? '2px solid var(--primary)' : '2px solid transparent',
+              marginBottom: -2,
+            }}>{label}</button>
+          ))}
+        </div>
+
+        {/* Registration success */}
+        {registered && (
+          <div style={{ textAlign: 'center', padding: '12px 0' }}>
+            <div style={{ fontSize: '2.5rem', marginBottom: 12 }}>📧</div>
+            <h3 style={{ marginBottom: 8 }}>Check your email</h3>
+            <p style={{ color: 'var(--text-muted)', fontSize: '0.875rem', marginBottom: 16 }}>
+              We sent a verification link to <strong>{email}</strong>. Click it to activate your account.
+            </p>
+            <button className="btn btn-primary" onClick={() => { setRegistered(false); switchMode('login') }}>
+              Go to Sign In
+            </button>
+          </div>
+        )}
+
+        {/* Login form */}
+        {isLogin && !registered && (
+          <>
+            {unverified && !resendSent && (
+              <div style={{ background: '#fffbeb', border: '1px solid #fcd34d', borderRadius: 8, padding: '12px 14px', marginBottom: 14 }}>
+                <p style={{ margin: '0 0 8px', fontSize: '0.85rem', color: '#92400e', fontWeight: 500 }}>
+                  Email not verified. Check your inbox.
+                </p>
+                <button className="btn btn-sm btn-primary" onClick={resendVerification} disabled={resending}>
+                  {resending ? 'Sending…' : 'Resend verification email'}
+                </button>
+              </div>
+            )}
+            {resendSent && <div className="alert alert-success" style={{ marginBottom: 14 }}>Verification email sent.</div>}
+            {error && <div className="alert alert-error" style={{ marginBottom: 14 }}>{error}</div>}
+            <form onSubmit={handleLogin}>
+              <div className="form-group">
+                <label>Email</label>
+                <input type="email" value={email} onChange={e => setEmail(e.target.value)} required autoFocus />
+              </div>
+              <div className="form-group">
+                <label>Password</label>
+                <input type="password" value={password} onChange={e => setPassword(e.target.value)} required />
+              </div>
+              <TurnstileWidget onVerify={setTurnstileToken} />
+              <button className="btn btn-primary" style={{ width: '100%' }} disabled={loading || (TURNSTILE_SITE_KEY && !turnstileToken)}>
+                {loading ? 'Signing in…' : 'Sign In'}
+              </button>
+            </form>
+            <div style={{ textAlign: 'center', marginTop: 12, fontSize: '0.82rem' }}>
+              <Link to="/forgot-password" onClick={onClose} style={{ color: 'var(--text-muted)' }}>Forgot password?</Link>
+            </div>
+          </>
+        )}
+
+        {/* Register form */}
+        {!isLogin && !registered && (
+          <>
+            {error && <div className="alert alert-error" style={{ marginBottom: 14 }}>{error}</div>}
+            <form onSubmit={handleRegister}>
+              <div className="form-group">
+                <label>Name</label>
+                <input type="text" value={name} onChange={e => setName(e.target.value)} required autoFocus />
+              </div>
+              <div className="form-group">
+                <label>Email</label>
+                <input type="email" value={email} onChange={e => setEmail(e.target.value)} required />
+              </div>
+              <div className="form-group">
+                <label>Password</label>
+                <input type="password" value={password} onChange={e => setPassword(e.target.value)} required minLength={8} />
+              </div>
+              <TurnstileWidget onVerify={setTurnstileToken} />
+              <button className="btn btn-primary" style={{ width: '100%' }} disabled={loading || (TURNSTILE_SITE_KEY && !turnstileToken)}>
+                {loading ? 'Creating account…' : 'Sign Up'}
+              </button>
+            </form>
+          </>
+        )}
+      </div>
+    </div>
+  )
+}
+
 // ── Main landing page ─────────────────────────────────────────────────────────
-const navLink = { fontSize: '0.85rem', color: '#94a3b8', textDecoration: 'none', padding: '6px 10px', borderRadius: 6 }
 
 export default function LandingPage() {
   const { user } = useAuth()
+  const [authModal, setAuthModal] = useState(null) // null | 'login' | 'register'
 
   // Load Turnstile script once
   useEffect(() => {
@@ -176,37 +348,23 @@ export default function LandingPage() {
   return (
     <div style={{ minHeight: '100vh', background: 'var(--bg)' }}>
 
-      {/* ── Navbar ─────────────────────────────────────────────────────────── */}
-      <nav style={{
-        position: 'sticky', top: 0, zIndex: 100,
-        background: 'var(--navbar-bg)', color: 'var(--navbar-fg)',
-        borderBottom: '1px solid rgba(255,255,255,0.06)',
-        backdropFilter: 'blur(12px)',
-      }}>
-        <div style={{ maxWidth: 1100, margin: '0 auto', padding: '0 24px', height: 56, display: 'flex', alignItems: 'center', justifyContent: 'space-between' }}>
-          <span style={{ fontWeight: 800, fontSize: '1.25rem', letterSpacing: '-0.02em', color: '#e2e8f0' }}>
-            Peds<span style={{ color: '#60a5fa' }}>Hub</span>
-          </span>
-          <div style={{ display: 'flex', gap: 10, alignItems: 'center' }}>
-            {user && <>
-              <Link to="/" style={navLink}>Dashboard</Link>
-              <Link to="/quizzes" style={navLink}>Quizzes</Link>
-              <Link to="/question-bank" style={navLink}>Question Bank</Link>
-            </>}
-            <a href="https://peds.danvics.com" target="_blank" rel="noopener noreferrer" style={navLink}>AI Scribe ↗</a>
-            <a href="#contact" style={navLink}>Contact</a>
-            {user
-              ? <Link to="/" className="btn btn-primary" style={{ fontSize: '0.85rem', padding: '7px 16px', borderRadius: 8, textDecoration: 'none' }}>Go to App</Link>
-              : <Link to="/login" style={{ fontSize: '0.875rem', color: '#e2e8f0', textDecoration: 'none', padding: '7px 16px', borderRadius: 8, border: '1px solid rgba(255,255,255,0.18)' }}>Sign In</Link>
-            }
-          </div>
-        </div>
-      </nav>
+      {/* Auth modal overlay */}
+      {authModal && (
+        <AuthModal
+          mode={authModal}
+          onClose={() => setAuthModal(null)}
+          onSwitch={setAuthModal}
+        />
+      )}
+
+      {/* ── Shared Navbar (handles auth state) ─────────────────────────────── */}
+      <style>{`.navbar { margin-bottom: 0 !important; }`}</style>
+      <Navbar onSignIn={() => setAuthModal('login')} onRegister={() => setAuthModal('register')} />
 
       {/* ── Hero ───────────────────────────────────────────────────────────── */}
       <section style={{
-        background: 'linear-gradient(135deg, #0f172a 0%, #1e3a5f 50%, #0f172a 100%)',
-        color: 'white',
+        background: 'var(--navbar-bg)',
+        color: 'var(--navbar-fg)',
         padding: '96px 24px 88px',
         textAlign: 'center',
         position: 'relative',
@@ -228,18 +386,18 @@ export default function LandingPage() {
               into tests
             </span>
           </h1>
-          <p style={{ fontSize: '1.15rem', color: '#94a3b8', lineHeight: 1.7, marginBottom: 40, maxWidth: 560, margin: '0 auto 40px' }}>
+          <p style={{ fontSize: '1.15rem', color: 'rgba(226,232,240,0.75)', lineHeight: 1.7, marginBottom: 40, maxWidth: 560, margin: '0 auto 40px' }}>
             Upload any PDF — PREP materials, lecture notes, textbook chapters.
             AI extracts questions, reads them aloud, and explains every answer.
           </p>
           <div style={{ display: 'flex', gap: 14, justifyContent: 'center', flexWrap: 'wrap' }}>
             {user ? <>
               <Link to="/" className="btn btn-primary" style={{ padding: '12px 28px', fontSize: '1rem', borderRadius: 10 }}>Dashboard</Link>
-              <Link to="/quizzes" className="btn" style={{ padding: '12px 28px', fontSize: '1rem', borderRadius: 10, background: 'rgba(255,255,255,0.08)', color: 'white', border: '1px solid rgba(255,255,255,0.18)', textDecoration: 'none' }}>My Quizzes</Link>
-              <Link to="/question-bank" className="btn" style={{ padding: '12px 28px', fontSize: '1rem', borderRadius: 10, background: 'rgba(255,255,255,0.08)', color: 'white', border: '1px solid rgba(255,255,255,0.18)', textDecoration: 'none' }}>Question Bank</Link>
+              <Link to="/quizzes" className="btn" style={{ padding: '12px 28px', fontSize: '1rem', borderRadius: 10, background: 'rgba(255,255,255,0.08)', color: 'var(--navbar-fg)', border: '1px solid rgba(255,255,255,0.18)', textDecoration: 'none' }}>My Quizzes</Link>
+              <Link to="/question-bank" className="btn" style={{ padding: '12px 28px', fontSize: '1rem', borderRadius: 10, background: 'rgba(255,255,255,0.08)', color: 'var(--navbar-fg)', border: '1px solid rgba(255,255,255,0.18)', textDecoration: 'none' }}>Question Bank</Link>
             </> : <>
-              <Link to="/login" className="btn btn-primary" style={{ padding: '12px 28px', fontSize: '1rem', borderRadius: 10 }}>Sign In</Link>
-              <a href="#contact" className="btn" style={{ padding: '12px 28px', fontSize: '1rem', borderRadius: 10, background: 'rgba(255,255,255,0.08)', color: 'white', border: '1px solid rgba(255,255,255,0.18)', textDecoration: 'none' }}>Request Access</a>
+              <button onClick={() => setAuthModal('login')} className="btn btn-primary" style={{ padding: '12px 28px', fontSize: '1rem', borderRadius: 10 }}>Sign In</button>
+              <button onClick={() => setAuthModal('register')} className="btn" style={{ padding: '12px 28px', fontSize: '1rem', borderRadius: 10, background: 'rgba(255,255,255,0.08)', color: 'var(--navbar-fg)', border: '1px solid rgba(255,255,255,0.18)' }}>Register</button>
             </>}
           </div>
         </div>
@@ -351,19 +509,19 @@ export default function LandingPage() {
 
       {/* ── Footer ─────────────────────────────────────────────────────────── */}
       <footer style={{
-        background: 'var(--navbar-bg)', color: '#475569',
+        background: 'var(--navbar-bg)',
         padding: '32px 24px',
         borderTop: '1px solid rgba(255,255,255,0.05)',
       }}>
         <div style={{ maxWidth: 1100, margin: '0 auto', display: 'flex', justifyContent: 'space-between', alignItems: 'center', flexWrap: 'wrap', gap: 16 }}>
-          <span style={{ fontWeight: 700, color: '#94a3b8' }}>
-            Peds<span style={{ color: '#60a5fa' }}>Hub</span>
+          <span style={{ fontWeight: 700, color: 'rgba(226,232,240,0.6)', fontSize: '0.9rem' }}>
+            🏥 PedsHub
             <span style={{ fontWeight: 400, marginLeft: 16 }}>© {new Date().getFullYear()}</span>
           </span>
           <div style={{ display: 'flex', gap: 24, fontSize: '0.85rem' }}>
-            <Link to="/login" style={{ color: '#475569', textDecoration: 'none' }}>Sign In</Link>
-            <a href="#contact" style={{ color: '#475569', textDecoration: 'none' }}>Contact</a>
-            <a href="https://peds.danvics.com" target="_blank" rel="noopener noreferrer" style={{ color: '#475569', textDecoration: 'none' }}>AI Scribe</a>
+            <button onClick={() => setAuthModal('login')} style={{ color: 'rgba(226,232,240,0.45)', background: 'none', border: 'none', cursor: 'pointer', fontSize: 'inherit' }}>Sign In</button>
+            <a href="#contact" style={{ color: 'rgba(226,232,240,0.45)', textDecoration: 'none' }}>Contact</a>
+            <a href="https://peds.danvics.com" target="_blank" rel="noopener noreferrer" style={{ color: 'rgba(226,232,240,0.45)', textDecoration: 'none' }}>AI Scribe</a>
           </div>
         </div>
       </footer>
diff --git a/frontend/src/pages/LoginPage.jsx b/frontend/src/pages/LoginPage.jsx
index 7942bcb..e0094d3 100644
--- a/frontend/src/pages/LoginPage.jsx
+++ b/frontend/src/pages/LoginPage.jsx
@@ -1,8 +1,34 @@
-import { useState } from 'react'
+import { useState, useEffect, useRef } from 'react'
 import { useNavigate, Link } from 'react-router-dom'
 import { useAuth } from '../context/AuthContext'
 import api from '../api/client'
 
+const TURNSTILE_SITE_KEY = window.__APP_CONFIG__?.TURNSTILE_SITE_KEY || ''
+
+function TurnstileWidget({ onVerify }) {
+  const ref = useRef(null)
+  const widgetId = useRef(null)
+  useEffect(() => {
+    if (!TURNSTILE_SITE_KEY) return
+    if (!document.getElementById('cf-turnstile-script')) {
+      const s = document.createElement('script')
+      s.id = 'cf-turnstile-script'
+      s.src = 'https://challenges.cloudflare.com/turnstile/v0/api.js'
+      s.async = true
+      document.head.appendChild(s)
+    }
+    let timer
+    const tryRender = () => {
+      if (!window.turnstile || !ref.current) { timer = setTimeout(tryRender, 200); return }
+      widgetId.current = window.turnstile.render(ref.current, { sitekey: TURNSTILE_SITE_KEY, callback: onVerify })
+    }
+    tryRender()
+    return () => { clearTimeout(timer); if (widgetId.current != null) try { window.turnstile.remove(widgetId.current) } catch {} }
+  }, [])
+  if (!TURNSTILE_SITE_KEY) return null
+  return <div ref={ref} style={{ margin: '8px 0' }} />
+}
+
 export default function LoginPage() {
   const [email, setEmail] = useState('')
   const [password, setPassword] = useState('')
@@ -11,6 +37,7 @@ export default function LoginPage() {
   const [unverified, setUnverified] = useState(false)
   const [resendSent, setResendSent] = useState(false)
   const [resending, setResending] = useState(false)
+  const [turnstileToken, setTurnstileToken] = useState('')
   const { login } = useAuth()
   const navigate = useNavigate()
 
@@ -20,7 +47,7 @@ export default function LoginPage() {
     setUnverified(false)
     setLoading(true)
     try {
-      await login(email, password)
+      await login(email, password, turnstileToken)
       navigate('/')
     } catch (err) {
       if (err.response?.status === 403) {
@@ -78,7 +105,8 @@ export default function LoginPage() {
             <label>Password</label>
             <input type="password" value={password} onChange={e => setPassword(e.target.value)} required />
           </div>
-          <button className="btn btn-primary" style={{ width: '100%' }} disabled={loading}>
+          <TurnstileWidget onVerify={setTurnstileToken} />
+          <button className="btn btn-primary" style={{ width: '100%' }} disabled={loading || (TURNSTILE_SITE_KEY && !turnstileToken)}>
             {loading ? 'Signing in...' : 'Sign In'}
           </button>
         </form>
diff --git a/frontend/src/pages/QuestionBankPage.jsx b/frontend/src/pages/QuestionBankPage.jsx
index ae956f0..c3bdc1a 100644
--- a/frontend/src/pages/QuestionBankPage.jsx
+++ b/frontend/src/pages/QuestionBankPage.jsx
@@ -1,52 +1,67 @@
-import { useState, useEffect, useRef } from 'react'
+import { useState, useEffect, useRef, lazy, Suspense } from 'react'
 import { useNavigate } from 'react-router-dom'
 import { useAuth } from '../context/AuthContext'
 import api from '../api/client'
 import Dialog from '../components/Dialog'
 import { useDialog } from '../hooks/useDialog'
 
+const TeachChat = lazy(() => import('../components/TeachChat'))
+
 function QuestionStudyModal({ question, onClose }) {
   const [answered, setAnswered] = useState(null)
   return (
-    <div style={{ position: 'fixed', inset: 0, background: 'rgba(0,0,0,0.55)', zIndex: 1000, display: 'flex', alignItems: 'center', justifyContent: 'center', padding: 16 }}
-      onClick={e => e.target === e.currentTarget && onClose()}>
-      <div style={{ background: 'var(--card-bg)', borderRadius: 'var(--card-radius)', padding: 24, maxWidth: 600, width: '100%', maxHeight: '90vh', overflowY: 'auto', boxShadow: '0 20px 60px rgba(0,0,0,0.3)' }}>
-        <div style={{ display: 'flex', justifyContent: 'space-between', marginBottom: 12 }}>
-          <span style={{ fontSize: '0.75rem', fontWeight: 600, color: 'var(--text-muted)', textTransform: 'uppercase' }}>
-            {question.quiz_title}{question.question_category_name ? ` · ${question.question_category_name}` : ''}
-          </span>
-          <button onClick={onClose} style={{ background: 'none', border: 'none', cursor: 'pointer', color: 'var(--text-muted)', fontSize: '1.2rem' }}>✕</button>
-        </div>
-        <p style={{ fontWeight: 600, fontSize: '0.95rem', lineHeight: 1.6, marginBottom: 16 }}>{question.question_text}</p>
-        {question.options && (
-          <div style={{ display: 'flex', flexDirection: 'column', gap: 8, marginBottom: 16 }}>
-            {question.options.map((opt, i) => {
-              const isSelected = answered === opt
-              const hasAnswered = !!answered
-              const isCorrectOpt = opt === question.correct_answer
-              return (
-                <div key={i}
-                  className={`option ${isSelected && !hasAnswered ? 'selected' : ''} ${hasAnswered && isCorrectOpt ? 'correct' : ''} ${hasAnswered && isSelected && !isCorrectOpt ? 'incorrect' : ''}`}
-                  onClick={() => !hasAnswered && setAnswered(opt)}
-                  style={{ cursor: hasAnswered ? 'default' : 'pointer' }}>
-                  <span className="option-letter">{String.fromCharCode(65 + i)}</span>
-                  <span style={{ flex: 1 }}>{opt}</span>
-                  {hasAnswered && isCorrectOpt && <span style={{ marginLeft: 'auto', fontSize: '0.8rem', fontWeight: 700, color: 'var(--correct-fg)' }}>✓ {isSelected ? 'Your answer' : 'Correct'}</span>}
-                  {hasAnswered && isSelected && !isCorrectOpt && <span style={{ marginLeft: 'auto', fontSize: '0.8rem', fontWeight: 700, color: 'var(--wrong-fg)' }}>✗ Wrong</span>}
-                </div>
-              )
-            })}
+    <>
+      <div style={{ position: 'fixed', inset: 0, background: 'rgba(0,0,0,0.55)', zIndex: 1000, display: 'flex', alignItems: 'center', justifyContent: 'center', padding: 16 }}
+        onClick={e => e.target === e.currentTarget && onClose()}>
+        <div style={{ background: 'var(--card-bg)', borderRadius: 'var(--card-radius)', padding: 24, maxWidth: 600, width: '100%', maxHeight: '90vh', overflowY: 'auto', boxShadow: '0 20px 60px rgba(0,0,0,0.3)' }}>
+          <div style={{ display: 'flex', justifyContent: 'space-between', marginBottom: 12 }}>
+            <span style={{ fontSize: '0.75rem', fontWeight: 600, color: 'var(--text-muted)', textTransform: 'uppercase' }}>
+              {question.quiz_title}{question.question_category_name ? ` · ${question.question_category_name}` : ''}
+            </span>
+            <button onClick={onClose} style={{ background: 'none', border: 'none', cursor: 'pointer', color: 'var(--text-muted)', fontSize: '1.2rem' }}>✕</button>
           </div>
-        )}
-        {answered && question.explanation && (
-          <div className="explanation"><strong>Explanation:</strong><div style={{ marginTop: 8 }}>{question.explanation}</div></div>
-        )}
-        {answered && <div style={{ marginTop: 12, display: 'flex', gap: 8 }}>
-          <button className="btn btn-secondary btn-sm" onClick={() => setAnswered(null)}>Try again</button>
-          <button className="btn btn-secondary btn-sm" onClick={onClose}>Close</button>
-        </div>}
+          <p style={{ fontWeight: 600, fontSize: '0.95rem', lineHeight: 1.6, marginBottom: 16 }}>{question.question_text}</p>
+          {question.image_path && (
+            <div style={{ margin: '0 0 14px' }}>
+              <img src={`/uploads/${question.image_path}`} alt="Question illustration"
+                style={{ maxWidth: '100%', maxHeight: 280, borderRadius: 8, border: '1px solid var(--border)' }}
+                onError={e => e.target.style.display = 'none'} />
+            </div>
+          )}
+          {question.options && (
+            <div style={{ display: 'flex', flexDirection: 'column', gap: 8, marginBottom: 16 }}>
+              {question.options.map((opt, i) => {
+                const isSelected = answered === opt
+                const hasAnswered = !!answered
+                const isCorrectOpt = opt === question.correct_answer
+                return (
+                  <div key={i}
+                    className={`option ${isSelected && !hasAnswered ? 'selected' : ''} ${hasAnswered && isCorrectOpt ? 'correct' : ''} ${hasAnswered && isSelected && !isCorrectOpt ? 'incorrect' : ''}`}
+                    onClick={() => !hasAnswered && setAnswered(opt)}
+                    style={{ cursor: hasAnswered ? 'default' : 'pointer' }}>
+                    <span className="option-letter">{String.fromCharCode(65 + i)}</span>
+                    <span style={{ flex: 1 }}>{opt}</span>
+                    {hasAnswered && isCorrectOpt && <span style={{ marginLeft: 'auto', fontSize: '0.8rem', fontWeight: 700, color: 'var(--correct-fg)' }}>✓ {isSelected ? 'Your answer' : 'Correct'}</span>}
+                    {hasAnswered && isSelected && !isCorrectOpt && <span style={{ marginLeft: 'auto', fontSize: '0.8rem', fontWeight: 700, color: 'var(--wrong-fg)' }}>✗ Wrong</span>}
+                  </div>
+                )
+              })}
+            </div>
+          )}
+          {answered && question.explanation && (
+            <div className="explanation"><strong>Explanation:</strong><div style={{ marginTop: 8 }}>{question.explanation}</div></div>
+          )}
+          {answered && <div style={{ marginTop: 12, display: 'flex', gap: 8 }}>
+            <button className="btn btn-secondary btn-sm" onClick={() => setAnswered(null)}>Try again</button>
+            <button className="btn btn-secondary btn-sm" onClick={onClose}>Close</button>
+          </div>}
+        </div>
       </div>
-    </div>
+      {/* AI Tutor — z-index above the modal */}
+      <Suspense fallback={null}>
+        <TeachChat question={question} elevated />
+      </Suspense>
+    </>
   )
 }
 
@@ -120,6 +135,53 @@ function CreateQuizModal({ selectedIds, categories, onClose, onCreated }) {
   )
 }
 
+function TagBrowser({ tags, selectedTagIds, toggleTag }) {
+  const [search, setSearch] = useState({ subjects: '', diseases: '', keywords: '' })
+  const sections = [
+    { key: 'subjects', label: 'Subjects', color: '#8b5cf6', items: tags.subjects || [] },
+    { key: 'diseases', label: 'Diseases', color: '#ef4444', items: tags.diseases || [] },
+    { key: 'keywords', label: 'Keywords', color: '#0ea5e9', items: tags.keywords || [] },
+  ]
+  return (
+    <div style={{ display: 'grid', gridTemplateColumns: 'repeat(auto-fit, minmax(200px, 1fr))', gap: 10, marginTop: 10 }}>
+      {sections.map(sec => {
+        if (sec.items.length === 0) return null
+        const q = search[sec.key].toLowerCase()
+        const filtered = q ? sec.items.filter(t => t.name.toLowerCase().includes(q)) : sec.items
+        return (
+          <div key={sec.key} style={{ background: 'var(--bg)', borderRadius: 8, padding: 10, border: '1px solid var(--border)' }}>
+            <div style={{ fontSize: '0.75rem', fontWeight: 700, color: sec.color, textTransform: 'uppercase', marginBottom: 6 }}>
+              {sec.label} ({sec.items.length})
+            </div>
+            <input type="text" placeholder={`Search ${sec.label.toLowerCase()}...`}
+              value={search[sec.key]}
+              onChange={e => setSearch(s => ({ ...s, [sec.key]: e.target.value }))}
+              style={{ width: '100%', padding: '5px 8px', border: '1px solid var(--border)', borderRadius: 6, fontSize: '0.78rem', background: 'var(--input-bg)', color: 'var(--text)', marginBottom: 6, boxSizing: 'border-box' }} />
+            <div style={{ maxHeight: 180, overflowY: 'auto' }}>
+              {filtered.map(tag => {
+                const selected = selectedTagIds.includes(tag.id)
+                return (
+                  <button key={tag.id} onClick={() => toggleTag(tag.id)}
+                    style={{
+                      display: 'block', width: '100%', textAlign: 'left',
+                      background: selected ? sec.color : 'transparent',
+                      color: selected ? '#fff' : 'var(--text)',
+                      border: 'none', borderRadius: 4, padding: '3px 8px',
+                      fontSize: '0.78rem', cursor: 'pointer', marginBottom: 1,
+                    }}>
+                    {tag.name} <span style={{ opacity: 0.6 }}>({tag.count})</span>
+                  </button>
+                )
+              })}
+              {filtered.length === 0 && <div style={{ fontSize: '0.75rem', color: 'var(--text-muted)', padding: 4 }}>No matches</div>}
+            </div>
+          </div>
+        )
+      })}
+    </div>
+  )
+}
+
 const LETTERS = ['A','B','C','D','E','F']
 
 function QuestionEditModal({ question, categories, onSaved, onClose }) {
@@ -228,7 +290,7 @@ export default function QuestionBankPage() {
   const [categories, setCategories] = useState([])
   const [searchQuery, setSearchQuery] = useState('')
   const [searchMode, setSearchMode] = useState('hybrid')
-  const [filterCatId, setFilterCatId] = useState('')
+  const [filterCatIds, setFilterCatIds] = useState([])
   const [showUncategorized, setShowUncategorized] = useState(false)
   const [showFavorites, setShowFavorites] = useState(false)
   const [favorites, setFavorites] = useState([])
@@ -242,24 +304,37 @@ export default function QuestionBankPage() {
   const [assignCatId, setAssignCatId] = useState('')
   const [bulkError, setBulkError] = useState('')
   const [pageSize, setPageSize] = useState(50)
+  const [tags, setTags] = useState({ subjects: [], diseases: [], keywords: [] })
+  const [selectedTagIds, setSelectedTagIds] = useState([])
+  const [showTags, setShowTags] = useState(false)
+  const [classifyJobId, setClassifyJobId] = useState(null)
+  const [classifyStatus, setClassifyStatus] = useState(null)
+  const [classifySteps, setClassifySteps] = useState([])
   const debounceRef = useRef(null)
+  const classifyPollRef = useRef(null)
   const { user } = useAuth()
   const isModerator = user?.role === 'admin' || user?.role === 'moderator'
   const LIMIT = pageSize
 
+  const loadTags = () => {
+    api.get('/tags').then(res => setTags(res.data)).catch(() => {})
+  }
+
   useEffect(() => {
     api.get('/question-categories/').then(res => setCategories(res.data)).catch(() => {})
     api.get('/favorites').then(res => setFavorites(res.data)).catch(() => {})
+    loadTags()
   }, [])
 
-  const loadQuestions = async (query = searchQuery, off = 0, catId = filterCatId, uncatOnly = showUncategorized, favOnly = showFavorites, mode = searchMode, size = pageSize) => {
+  const loadQuestions = async (query = searchQuery, off = 0, catIds = filterCatIds, uncatOnly = showUncategorized, favOnly = showFavorites, mode = searchMode, size = pageSize, tagIds = selectedTagIds) => {
     setLoading(true)
     try {
       const params = { limit: size === 'all' ? 5000 : size, offset: off, search_mode: mode }
       if (query.trim()) params.q = query.trim()
-      if (catId) params.category_id = parseInt(catId)
+      if (catIds.length > 0) params.category_ids = catIds.join(',')
       if (uncatOnly) params.uncategorized = true
       if (favOnly) params.favorites_only = true
+      if (tagIds.length > 0) params.tag_ids = tagIds.join(',')
       const res = await api.get('/questions/bank', { params })
       setQuestions(off === 0 ? res.data.questions : prev => [...prev, ...res.data.questions])
       setTotal(res.data.total)
@@ -267,11 +342,49 @@ export default function QuestionBankPage() {
     } catch { } finally { setLoading(false) }
   }
 
+  const tagIdsKey = selectedTagIds.join(',')
+  const catIdsKey = filterCatIds.join(',')
   useEffect(() => {
     clearTimeout(debounceRef.current)
-    debounceRef.current = setTimeout(() => loadQuestions(searchQuery, 0, filterCatId, showUncategorized, showFavorites, searchMode, pageSize), 300)
+    debounceRef.current = setTimeout(() => loadQuestions(searchQuery, 0, filterCatIds, showUncategorized, showFavorites, searchMode, pageSize, selectedTagIds), 300)
     return () => clearTimeout(debounceRef.current)
-  }, [searchQuery, filterCatId, showUncategorized, showFavorites, searchMode, pageSize])
+  }, [searchQuery, catIdsKey, showUncategorized, showFavorites, searchMode, pageSize, tagIdsKey])
+
+  const toggleTag = (tagId) => {
+    setSelectedTagIds(prev => {
+      const n = prev.includes(tagId) ? prev.filter(id => id !== tagId) : [...prev, tagId]
+      return n
+    })
+  }
+
+  const startClassification = async () => {
+    try {
+      const res = await api.post('/tags/classify')
+      setClassifyJobId(res.data.job_id)
+      setClassifyStatus('running')
+      setClassifySteps([])
+      // Start polling
+      if (classifyPollRef.current) clearInterval(classifyPollRef.current)
+      classifyPollRef.current = setInterval(async () => {
+        try {
+          const s = await api.get(`/tags/status/${res.data.job_id}`)
+          setClassifyStatus(s.data.status)
+          setClassifySteps(s.data.steps || [])
+          if (s.data.status === 'completed' || s.data.status === 'failed') {
+            clearInterval(classifyPollRef.current)
+            classifyPollRef.current = null
+            if (s.data.status === 'completed') loadTags()
+          }
+        } catch { }
+      }, 2000)
+    } catch (err) {
+      await openAlert(err.response?.data?.detail || 'Failed to start classification', { title: 'Error' })
+    }
+  }
+
+  useEffect(() => {
+    return () => { if (classifyPollRef.current) clearInterval(classifyPollRef.current) }
+  }, [])
 
   const toggleSelect = (id) => setSelectedIds(prev => { const n = new Set(prev); n.has(id) ? n.delete(id) : n.add(id); return n })
 
@@ -280,9 +393,10 @@ export default function QuestionBankPage() {
     try {
       const params = {}
       if (searchQuery.trim()) params.q = searchQuery.trim()
-      if (filterCatId) params.category_id = parseInt(filterCatId)
+      if (filterCatIds.length > 0) params.category_ids = filterCatIds.join(',')
       if (showUncategorized) params.uncategorized = true
       if (showFavorites) params.favorites_only = true
+      if (selectedTagIds.length > 0) params.tag_ids = selectedTagIds.join(',')
       const res = await api.get('/questions/bank/ids', { params })
       setSelectedIds(new Set(res.data))
     } catch {
@@ -333,8 +447,8 @@ export default function QuestionBankPage() {
     try {
       await api.delete(`/question-categories/${catId}`, { params: moveTo ? { move_to: moveTo } : {} })
       setCategories(prev => prev.filter(c => c.id !== catId))
-      if (parseInt(filterCatId) === catId) setFilterCatId('')
-      loadQuestions(searchQuery, 0, '', showUncategorized, showFavorites)
+      setFilterCatIds(prev => prev.filter(c => c !== catId))
+      loadQuestions(searchQuery, 0, filterCatIds.filter(c => c !== catId), showUncategorized, showFavorites)
     } catch { }
   }
 
@@ -424,25 +538,82 @@ export default function QuestionBankPage() {
       {/* Category filter chips */}
       <div style={{ display: 'flex', gap: 6, flexWrap: 'wrap', marginBottom: 12, paddingBottom: 12, borderBottom: '1px solid var(--border)' }}>
         <span style={{ fontSize: '0.72rem', fontWeight: 700, color: 'var(--text-muted)', textTransform: 'uppercase', letterSpacing: '0.04em', alignSelf: 'center', marginRight: 4 }}>Filter:</span>
-        <button className={`btn btn-sm ${!filterCatId && !showUncategorized && !showFavorites ? 'btn-primary' : 'btn-secondary'}`}
-          onClick={() => { setFilterCatId(''); setShowUncategorized(false); setShowFavorites(false) }}>All ({total})</button>
+        <button className={`btn btn-sm ${filterCatIds.length === 0 && !showUncategorized && !showFavorites ? 'btn-primary' : 'btn-secondary'}`}
+          onClick={() => { setFilterCatIds([]); setShowUncategorized(false); setShowFavorites(false) }}>All ({total})</button>
         <button className={`btn btn-sm ${showFavorites ? 'btn-primary' : 'btn-secondary'}`}
-          onClick={() => { setShowFavorites(v => !v); setFilterCatId(''); setShowUncategorized(false) }}>⭐ Favorites ({favorites.length})</button>
+          onClick={() => { setShowFavorites(v => !v); setFilterCatIds([]); setShowUncategorized(false) }}>⭐ Favorites ({favorites.length})</button>
         <button className={`btn btn-sm ${showUncategorized ? 'btn-primary' : 'btn-secondary'}`}
-          onClick={() => { setShowUncategorized(v => !v); setFilterCatId(''); setShowFavorites(false) }}>Uncategorized</button>
-        {categories.map(cat => (
-          <div key={cat.id} style={{ display: 'flex', alignItems: 'center', gap: 2 }}>
-            <button className={`btn btn-sm ${filterCatId === String(cat.id) ? 'btn-primary' : 'btn-secondary'}`}
-              onClick={() => { setFilterCatId(filterCatId === String(cat.id) ? '' : String(cat.id)); setShowUncategorized(false); setShowFavorites(false) }}>
-              {cat.name} <span style={{ opacity: 0.65 }}>({cat.question_count})</span>
+          onClick={() => { setShowUncategorized(v => !v); setFilterCatIds([]); setShowFavorites(false) }}>Uncategorized</button>
+        {categories.map(cat => {
+          const isActive = filterCatIds.includes(cat.id)
+          return (
+            <div key={cat.id} style={{ display: 'flex', alignItems: 'center', gap: 2 }}>
+              <button className={`btn btn-sm ${isActive ? 'btn-primary' : 'btn-secondary'}`}
+                onClick={() => { setFilterCatIds(prev => prev.includes(cat.id) ? prev.filter(c => c !== cat.id) : [...prev, cat.id]); setShowUncategorized(false); setShowFavorites(false) }}>
+                {cat.name} <span style={{ opacity: 0.65 }}>({cat.question_count})</span>
+              </button>
+              {isModerator && <button onClick={() => deleteCategory(cat.id)}
+                style={{ background: 'none', border: 'none', cursor: 'pointer', color: '#cbd5e1', fontSize: '0.72rem', padding: '2px 3px', lineHeight: 1 }}
+                onMouseEnter={e => e.currentTarget.style.color = '#ef4444'} onMouseLeave={e => e.currentTarget.style.color = '#cbd5e1'}>✕</button>}
+            </div>
+          )
+        })}
+        {/* Active tag chips — shown inline with categories */}
+        {selectedTagIds.map(tid => {
+          const allTags = [...(tags.subjects || []), ...(tags.diseases || []), ...(tags.keywords || [])]
+          const tag = allTags.find(t => t.id === tid)
+          if (!tag) return null
+          const color = (tags.subjects || []).find(t => t.id === tid) ? '#8b5cf6' : (tags.diseases || []).find(t => t.id === tid) ? '#ef4444' : '#0ea5e9'
+          return (
+            <button key={`tag-${tid}`} onClick={() => toggleTag(tid)}
+              style={{ background: color, color: '#fff', border: 'none', fontSize: '0.72rem', padding: '3px 10px', borderRadius: 12, cursor: 'pointer', fontWeight: 600 }}>
+              {tag.name} ✕
             </button>
-            {isModerator && <button onClick={() => deleteCategory(cat.id)}
-              style={{ background: 'none', border: 'none', cursor: 'pointer', color: '#cbd5e1', fontSize: '0.72rem', padding: '2px 3px', lineHeight: 1 }}
-              onMouseEnter={e => e.currentTarget.style.color = '#ef4444'} onMouseLeave={e => e.currentTarget.style.color = '#cbd5e1'}>✕</button>}
-          </div>
-        ))}
+          )
+        })}
+        {selectedTagIds.length > 0 && (
+          <button onClick={() => setSelectedTagIds([])}
+            style={{ background: 'none', border: 'none', fontSize: '0.72rem', color: 'var(--text-muted)', cursor: 'pointer', textDecoration: 'underline' }}>
+            Clear tags
+          </button>
+        )}
       </div>
 
+      {/* Tag browser — collapsible */}
+      {(tags.subjects?.length > 0 || tags.diseases?.length > 0 || tags.keywords?.length > 0) && (
+        <div style={{ marginBottom: 12 }}>
+          <button className="btn btn-sm btn-secondary" onClick={() => setShowTags(v => !v)}
+            style={{ fontSize: '0.78rem', marginBottom: showTags ? 6 : 0 }}>
+            🏷 Browse Tags {showTags ? '▲' : '▼'}
+          </button>
+          {showTags && <TagBrowser tags={tags} selectedTagIds={selectedTagIds} toggleTag={toggleTag} />}
+        </div>
+      )}
+
+      {/* Classify + status */}
+      {isModerator && (
+        <div style={{ marginBottom: 12 }}>
+          <div style={{ display: 'flex', gap: 8, alignItems: 'center', flexWrap: 'wrap' }}>
+            <button className="btn btn-sm btn-secondary" onClick={startClassification}
+              disabled={classifyStatus === 'running'}>
+              {classifyStatus === 'running' ? 'Classifying...' : 'Classify Questions (AI)'}
+            </button>
+            {classifyStatus && (
+              <span style={{ fontSize: '0.78rem', color: classifyStatus === 'completed' ? 'var(--correct-fg)' : classifyStatus === 'failed' ? 'var(--wrong-fg)' : 'var(--text-muted)' }}>
+                {classifyStatus === 'completed' ? 'Done' : classifyStatus === 'failed' ? 'Failed' : classifyStatus === 'running' ? 'Running...' : ''}
+              </span>
+            )}
+          </div>
+          {classifySteps.length > 0 && classifyStatus === 'running' && (
+            <div style={{ marginTop: 6, padding: '8px 12px', background: 'var(--bg)', borderRadius: 8, fontSize: '0.78rem', color: 'var(--text-muted)', maxHeight: 120, overflowY: 'auto' }}>
+              {classifySteps.slice(-5).map((s, i) => (
+                <div key={i}>{s.message}</div>
+              ))}
+            </div>
+          )}
+        </div>
+      )}
+
       {/* Search row */}
       <div style={{ display: 'flex', gap: 8, marginBottom: 8, flexWrap: 'wrap', alignItems: 'center' }}>
         <div style={{ flex: 1, minWidth: 200, position: 'relative' }}>
@@ -564,7 +735,7 @@ export default function QuestionBankPage() {
 
       {questions.length < total && (
         <div style={{ textAlign: 'center', marginTop: 12 }}>
-          <button className="btn btn-secondary" onClick={() => loadQuestions(searchQuery, offset + LIMIT, filterCatId, showUncategorized, showFavorites)} disabled={loading}>
+          <button className="btn btn-secondary" onClick={() => loadQuestions(searchQuery, questions.length, filterCatIds, showUncategorized, showFavorites, searchMode, pageSize, selectedTagIds)} disabled={loading}>
             {loading ? 'Loading…' : `Load more (${total - questions.length} remaining)`}
           </button>
         </div>
diff --git a/frontend/src/pages/QuizPage.jsx b/frontend/src/pages/QuizPage.jsx
index 27bdda5..e7211b2 100644
--- a/frontend/src/pages/QuizPage.jsx
+++ b/frontend/src/pages/QuizPage.jsx
@@ -128,6 +128,9 @@ function ModeSelectScreen({ quiz, voices, onStart }) {
   )
 }
 
+// Unique session ID per tab — used to prevent concurrent resume on multiple devices
+const SESSION_ID = Math.random().toString(36).slice(2) + Date.now().toString(36)
+
 export default function QuizPage() {
   const { id } = useParams()
   const navigate = useNavigate()
@@ -172,13 +175,21 @@ export default function QuizPage() {
       try {
         const quizRes = await api.get(`/quizzes/${id}?study=true`)
         setQuiz(quizRes.data)
-      } catch { }
+      } catch (err) {
+        console.error('Failed to load quiz:', err)
+        navigate('/')
+        return
+      }
     } else {
       // For exam mode, ensure quiz data is loaded
       try {
         const quizRes = await api.get(`/quizzes/${id}`)
         setQuiz(quizRes.data)
-      } catch { }
+      } catch (err) {
+        console.error('Failed to load quiz:', err)
+        navigate('/')
+        return
+      }
     }
 
     hasStarted.current = true
@@ -224,11 +235,18 @@ export default function QuizPage() {
 
         // Check for saved progress and auto-resume
         try {
-          const progressRes = await api.get('/attempts/progress', { params: { quiz_id: id } })
+          const progressRes = await api.get('/attempts/progress', {
+            params: { quiz_id: id },
+            headers: { 'x-quiz-session': SESSION_ID },
+          })
           if (progressRes.data) {
             await resumeQuiz(progressRes.data)
           }
-        } catch {}
+        } catch (err) {
+          if (err.response?.status === 409) {
+            showToast(err.response.data.detail || 'Quiz active on another device')
+          }
+        }
       } catch { navigate('/') }
       finally { setLoading(false) }
     }
@@ -268,14 +286,19 @@ export default function QuizPage() {
     finally { setStarting(false) }
   }
 
-useEffect(() => {
-    if (timeLeft === null) return
-    if (timeLeft <= 0) { handleSubmit(true); return }
+const timerStarted = timeLeft !== null
+  useEffect(() => {
+    if (!timerStarted) return
     timerRef.current = setInterval(() => {
       setTimeLeft(t => { if (t <= 1) { clearInterval(timerRef.current); return 0 } return t - 1 })
     }, 1000)
     return () => clearInterval(timerRef.current)
-  }, [timeLeft === null])
+  }, [timerStarted])
+
+  // Auto-submit when timer reaches zero
+  useEffect(() => {
+    if (timeLeft === 0) handleSubmit(true)
+  }, [timeLeft])
 
   // Save progress to Redis (survives logout/browser change)
   const saveProgressRef = useRef(null)
@@ -293,7 +316,7 @@ useEffect(() => {
         time_left: timeLeft,
         started_at: startedAt,
         total_time: totalTime,
-      }).catch(() => {})
+      }, { headers: { 'x-quiz-session': SESSION_ID } }).catch(() => {})
     }, 1500) // debounce 1.5s
     return () => clearTimeout(saveProgressRef.current)
   }, [answers, currentIdx, attemptId, timeLeft, startedAt, totalTime])
@@ -322,7 +345,7 @@ useEffect(() => {
     } catch (err) {
       if (!autoSubmit) showToast(err.response?.data?.detail || 'Submission failed')
     } finally { setSubmitting(false) }
-  }, [attemptId, answers, submitting])
+  }, [attemptId, answers, submitting, navigate, showToast])
 
   if (loading) return <div className="loading"><div className="spinner"></div> Loading quiz...</div>
   if (!quiz) return null
diff --git a/frontend/src/pages/QuizzesPage.jsx b/frontend/src/pages/QuizzesPage.jsx
index 3d0e546..13634ef 100644
--- a/frontend/src/pages/QuizzesPage.jsx
+++ b/frontend/src/pages/QuizzesPage.jsx
@@ -1,4 +1,4 @@
-import { useState, useEffect, useRef } from 'react'
+import { useState, useEffect, useRef, lazy, Suspense } from 'react'
 import { useNavigate, Link } from 'react-router-dom'
 import { useAuth } from '../context/AuthContext'
 import api from '../api/client'
@@ -6,6 +6,8 @@ import ConfirmButton from '../components/ConfirmButton'
 import Dialog from '../components/Dialog'
 import { useDialog } from '../hooks/useDialog'
 
+const TeachChat = lazy(() => import('../components/TeachChat'))
+
 function InProgressSection() {
   const [inProgress, setInProgress] = useState([])
   const navigate = useNavigate()
@@ -56,6 +58,7 @@ function PastAttemptsSection() {
   const [open, setOpen] = useState(false)
   const [history, setHistory] = useState(null)
   const [loading, setLoading] = useState(false)
+  const [deletingId, setDeletingId] = useState(null)
 
   const load = async () => {
     if (history !== null) { setOpen(v => !v); return }
@@ -67,6 +70,19 @@ function PastAttemptsSection() {
     finally { setLoading(false); setOpen(true) }
   }
 
+  const deleteAttempt = async (attemptId) => {
+    setDeletingId(attemptId)
+    try {
+      await api.delete(`/attempts/${attemptId}`)
+      setHistory(prev =>
+        prev
+          .map(q => ({ ...q, attempts: q.attempts.filter(a => a.attempt_id !== attemptId) }))
+          .filter(q => q.attempts.length > 0)
+      )
+    } catch { }
+    finally { setDeletingId(null) }
+  }
+
   const totalCompleted = history?.reduce((s, q) => s + q.attempts.length, 0) ?? 0
 
   return (
@@ -92,13 +108,13 @@ function PastAttemptsSection() {
             <div key={quiz.quiz_id} style={{ marginBottom: 14 }}>
               <div style={{ fontWeight: 600, fontSize: '0.88rem', marginBottom: 6 }}>{quiz.title}</div>
               <div style={{ display: 'flex', flexDirection: 'column', gap: 5 }}>
-                {quiz.attempts.map((a, i) => (
+                {quiz.attempts.map((a) => (
                   <div key={a.attempt_id} style={{
-                    display: 'flex', justifyContent: 'space-between', alignItems: 'center',
+                    display: 'flex', alignItems: 'center',
                     padding: '7px 12px', background: 'var(--bg)', borderRadius: 8,
                     fontSize: '0.82rem', gap: 8,
                   }}>
-                    <span style={{ color: 'var(--text-muted)' }}>
+                    <span style={{ color: 'var(--text-muted)', flex: 1 }}>
                       {new Date(a.date).toLocaleDateString()} — {a.score}/{a.total}
                     </span>
                     <span style={{
@@ -108,6 +124,21 @@ function PastAttemptsSection() {
                     <a href={`/results/${a.attempt_id}`} style={{ color: 'var(--primary)', fontSize: '0.78rem', textDecoration: 'none', flexShrink: 0 }}>
                       Review →
                     </a>
+                    <button
+                      onClick={() => deleteAttempt(a.attempt_id)}
+                      disabled={deletingId === a.attempt_id}
+                      title="Delete this attempt"
+                      style={{
+                        background: 'none', border: 'none', cursor: 'pointer',
+                        color: 'var(--wrong-fg)', fontSize: '0.78rem',
+                        padding: '2px 4px', borderRadius: 4, flexShrink: 0,
+                        opacity: deletingId === a.attempt_id ? 0.4 : 0.6,
+                      }}
+                      onMouseEnter={e => e.currentTarget.style.opacity = '1'}
+                      onMouseLeave={e => e.currentTarget.style.opacity = deletingId === a.attempt_id ? '0.4' : '0.6'}
+                    >
+                      {deletingId === a.attempt_id ? '…' : '✕'}
+                    </button>
                   </div>
                 ))}
               </div>
@@ -135,47 +166,60 @@ function HighlightText({ text, query }) {
 function QuestionStudyModal({ question, query, onClose }) {
   const [answered, setAnswered] = useState(null)
   return (
-    <div style={{ position: 'fixed', inset: 0, background: 'rgba(0,0,0,0.55)', zIndex: 1000, display: 'flex', alignItems: 'center', justifyContent: 'center', padding: 16 }}
-      onClick={e => e.target === e.currentTarget && onClose()}>
-      <div style={{ background: 'var(--card-bg)', borderRadius: 'var(--card-radius)', padding: 24, maxWidth: 600, width: '100%', maxHeight: '90vh', overflowY: 'auto', boxShadow: '0 20px 60px rgba(0,0,0,0.3)' }}>
-        <div style={{ display: 'flex', justifyContent: 'space-between', marginBottom: 12 }}>
-          <span style={{ fontSize: '0.75rem', fontWeight: 600, color: 'var(--text-muted)', textTransform: 'uppercase' }}>Study Question</span>
-          <button onClick={onClose} style={{ background: 'none', border: 'none', cursor: 'pointer', color: 'var(--text-muted)', fontSize: '1.2rem' }}>✕</button>
+    <>
+      <div style={{ position: 'fixed', inset: 0, background: 'rgba(0,0,0,0.55)', zIndex: 1000, display: 'flex', alignItems: 'center', justifyContent: 'center', padding: 16 }}
+        onClick={e => e.target === e.currentTarget && onClose()}>
+        <div style={{ background: 'var(--card-bg)', borderRadius: 'var(--card-radius)', padding: 24, maxWidth: 600, width: '100%', maxHeight: '90vh', overflowY: 'auto', boxShadow: '0 20px 60px rgba(0,0,0,0.3)' }}>
+          <div style={{ display: 'flex', justifyContent: 'space-between', marginBottom: 12 }}>
+            <span style={{ fontSize: '0.75rem', fontWeight: 600, color: 'var(--text-muted)', textTransform: 'uppercase' }}>Study Question</span>
+            <button onClick={onClose} style={{ background: 'none', border: 'none', cursor: 'pointer', color: 'var(--text-muted)', fontSize: '1.2rem' }}>✕</button>
+          </div>
+          <p style={{ fontWeight: 600, fontSize: '0.95rem', lineHeight: 1.6, marginBottom: 16 }}>
+            <HighlightText text={question.question_text} query={query} />
+          </p>
+          {question.image_path && (
+            <div style={{ margin: '0 0 14px' }}>
+              <img src={`/uploads/${question.image_path}`} alt="Question illustration"
+                style={{ maxWidth: '100%', maxHeight: 280, borderRadius: 8, border: '1px solid var(--border)' }}
+                onError={e => e.target.style.display = 'none'} />
+            </div>
+          )}
+          {question.options && (
+            <div style={{ display: 'flex', flexDirection: 'column', gap: 8, marginBottom: 16 }}>
+              {question.options.map((opt, i) => {
+                const isSelected = answered === opt
+                const hasAnswered = !!answered
+                const isCorrectOpt = opt === question.correct_answer
+                return (
+                  <div key={i}
+                    className={`option ${isSelected && !hasAnswered ? 'selected' : ''} ${hasAnswered && isCorrectOpt ? 'correct' : ''} ${hasAnswered && isSelected && !isCorrectOpt ? 'incorrect' : ''}`}
+                    onClick={() => !hasAnswered && setAnswered(opt)}
+                    style={{ cursor: hasAnswered ? 'default' : 'pointer' }}>
+                    <span className="option-letter">{String.fromCharCode(65 + i)}</span>
+                    <span style={{ flex: 1 }}><HighlightText text={opt} query={query} /></span>
+                    {hasAnswered && isCorrectOpt && <span style={{ marginLeft: 'auto', fontSize: '0.8rem', fontWeight: 700, color: 'var(--correct-fg)' }}>✓ {isSelected ? 'Your answer' : 'Correct'}</span>}
+                    {hasAnswered && isSelected && !isCorrectOpt && <span style={{ marginLeft: 'auto', fontSize: '0.8rem', fontWeight: 700, color: 'var(--wrong-fg)' }}>✗ Wrong</span>}
+                  </div>
+                )
+              })}
+            </div>
+          )}
+          {answered && question.explanation && (
+            <div className="explanation"><strong>Explanation:</strong><div style={{ marginTop: 8 }}>{question.explanation}</div></div>
+          )}
+          {answered && (
+            <div style={{ marginTop: 14, display: 'flex', gap: 8 }}>
+              <button className="btn btn-secondary btn-sm" onClick={() => setAnswered(null)}>Try again</button>
+              <button className="btn btn-secondary btn-sm" onClick={onClose}>Close</button>
+            </div>
+          )}
         </div>
-        <p style={{ fontWeight: 600, fontSize: '0.95rem', lineHeight: 1.6, marginBottom: 16 }}>
-          <HighlightText text={question.question_text} query={query} />
-        </p>
-        {question.options && (
-          <div style={{ display: 'flex', flexDirection: 'column', gap: 8, marginBottom: 16 }}>
-            {question.options.map((opt, i) => {
-              const isSelected = answered === opt
-              const hasAnswered = !!answered
-              const isCorrectOpt = opt === question.correct_answer
-              return (
-                <div key={i}
-                  className={`option ${isSelected && !hasAnswered ? 'selected' : ''} ${hasAnswered && isCorrectOpt ? 'correct' : ''} ${hasAnswered && isSelected && !isCorrectOpt ? 'incorrect' : ''}`}
-                  onClick={() => !hasAnswered && setAnswered(opt)}
-                  style={{ cursor: hasAnswered ? 'default' : 'pointer' }}>
-                  <span className="option-letter">{String.fromCharCode(65 + i)}</span>
-                  <span style={{ flex: 1 }}><HighlightText text={opt} query={query} /></span>
-                  {hasAnswered && isCorrectOpt && <span style={{ marginLeft: 'auto', fontSize: '0.8rem', fontWeight: 700, color: 'var(--correct-fg)' }}>✓ {isSelected ? 'Your answer' : 'Correct'}</span>}
-                  {hasAnswered && isSelected && !isCorrectOpt && <span style={{ marginLeft: 'auto', fontSize: '0.8rem', fontWeight: 700, color: 'var(--wrong-fg)' }}>✗ Wrong</span>}
-                </div>
-              )
-            })}
-          </div>
-        )}
-        {answered && question.explanation && (
-          <div className="explanation"><strong>Explanation:</strong><div style={{ marginTop: 8 }}>{question.explanation}</div></div>
-        )}
-        {answered && (
-          <div style={{ marginTop: 14, display: 'flex', gap: 8 }}>
-            <button className="btn btn-secondary btn-sm" onClick={() => setAnswered(null)}>Try again</button>
-            <button className="btn btn-secondary btn-sm" onClick={onClose}>Close</button>
-          </div>
-        )}
       </div>
-    </div>
+      {/* AI Tutor — z-index above the modal */}
+      <Suspense fallback={null}>
+        <TeachChat question={question} elevated />
+      </Suspense>
+    </>
   )
 }
 
diff --git a/frontend/src/pages/RegisterPage.jsx b/frontend/src/pages/RegisterPage.jsx
index 7f44d19..b2f8af3 100644
--- a/frontend/src/pages/RegisterPage.jsx
+++ b/frontend/src/pages/RegisterPage.jsx
@@ -1,8 +1,34 @@
-import { useState } from 'react'
+import { useState, useEffect, useRef } from 'react'
 import { Link } from 'react-router-dom'
 import { useAuth } from '../context/AuthContext'
 import api from '../api/client'
 
+const TURNSTILE_SITE_KEY = window.__APP_CONFIG__?.TURNSTILE_SITE_KEY || ''
+
+function TurnstileWidget({ onVerify }) {
+  const ref = useRef(null)
+  useEffect(() => {
+    if (!TURNSTILE_SITE_KEY) return
+    // Load script if needed
+    if (!document.getElementById('cf-turnstile-script')) {
+      const s = document.createElement('script')
+      s.id = 'cf-turnstile-script'
+      s.src = 'https://challenges.cloudflare.com/turnstile/v0/api.js'
+      s.async = true
+      document.head.appendChild(s)
+    }
+    const tryRender = () => {
+      if (!window.turnstile || !ref.current) return setTimeout(tryRender, 200)
+      const id = window.turnstile.render(ref.current, { sitekey: TURNSTILE_SITE_KEY, callback: onVerify })
+      return () => { try { window.turnstile.remove(id) } catch {} }
+    }
+    const cleanup = tryRender()
+    return () => { if (typeof cleanup === 'function') cleanup() }
+  }, [])
+  if (!TURNSTILE_SITE_KEY) return null
+  return <div ref={ref} style={{ margin: '8px 0' }} />
+}
+
 export default function RegisterPage() {
   const [name, setName] = useState('')
   const [email, setEmail] = useState('')
@@ -10,6 +36,7 @@ export default function RegisterPage() {
   const [error, setError] = useState('')
   const [loading, setLoading] = useState(false)
   const [done, setDone] = useState(false)
+  const [turnstileToken, setTurnstileToken] = useState('')
   const { loginWithToken } = useAuth()
 
   const handleSubmit = async (e) => {
@@ -17,7 +44,7 @@ export default function RegisterPage() {
     setError('')
     setLoading(true)
     try {
-      const res = await api.post('/auth/register', { email, password, name })
+      const res = await api.post('/auth/register', { email, password, name, turnstile_token: turnstileToken || null })
       if (res.data.requires_verification) {
         setDone(true)
       } else {
@@ -71,7 +98,8 @@ export default function RegisterPage() {
             <label>Password</label>
             <input type="password" value={password} onChange={e => setPassword(e.target.value)} required minLength={8} />
           </div>
-          <button className="btn btn-primary" style={{ width: '100%' }} disabled={loading}>
+          <TurnstileWidget onVerify={setTurnstileToken} />
+          <button className="btn btn-primary" style={{ width: '100%' }} disabled={loading || (TURNSTILE_SITE_KEY && !turnstileToken)}>
             {loading ? 'Creating account...' : 'Sign Up'}
           </button>
         </form>
diff --git a/frontend/src/pages/ResultsPage.jsx b/frontend/src/pages/ResultsPage.jsx
index 30528a9..a6bde58 100644
--- a/frontend/src/pages/ResultsPage.jsx
+++ b/frontend/src/pages/ResultsPage.jsx
@@ -8,12 +8,26 @@ export default function ResultsPage() {
   const navigate = useNavigate()
   const [result, setResult] = useState(location.state?.result || null)
   const [loading, setLoading] = useState(!result)
+  const [deleting, setDeleting] = useState(false)
+  const [confirmDelete, setConfirmDelete] = useState(false)
+
+  const deleteAttempt = async () => {
+    if (!confirmDelete) { setConfirmDelete(true); return }
+    setDeleting(true)
+    try {
+      await api.delete(`/attempts/${result.id}`)
+      navigate('/quizzes')
+    } catch {
+      setDeleting(false)
+      setConfirmDelete(false)
+    }
+  }
 
   useEffect(() => {
     if (!result) {
       api.get(`/attempts/${id}`)
         .then(res => setResult(res.data))
-        .catch(() => navigate('/'))
+        .catch(() => navigate('/quizzes'))
         .finally(() => setLoading(false))
     }
   }, [id])
@@ -60,6 +74,27 @@ export default function ResultsPage() {
             <Link to={`/quizzes/${result.quiz_id}`} className="btn btn-primary">Retake Quiz</Link>
             <Link to="/quizzes" className="btn btn-secondary">All Quizzes</Link>
             <Link to="/" className="btn btn-secondary">Dashboard</Link>
+            {confirmDelete ? (
+              <>
+                <button
+                  onClick={deleteAttempt}
+                  disabled={deleting}
+                  className="btn btn-secondary"
+                  style={{ color: 'var(--wrong-fg)', borderColor: 'var(--wrong-bd)' }}
+                >
+                  {deleting ? 'Deleting…' : 'Confirm Delete'}
+                </button>
+                <button className="btn btn-secondary" onClick={() => setConfirmDelete(false)}>Cancel</button>
+              </>
+            ) : (
+              <button
+                onClick={deleteAttempt}
+                className="btn btn-secondary"
+                style={{ color: 'var(--wrong-fg)', borderColor: 'var(--wrong-bd)' }}
+              >
+                Delete Attempt
+              </button>
+            )}
           </div>
         </div>
       </div>
diff --git a/frontend/src/pages/UploadPage.jsx b/frontend/src/pages/UploadPage.jsx
index 7873070..b26d4d2 100644
--- a/frontend/src/pages/UploadPage.jsx
+++ b/frontend/src/pages/UploadPage.jsx
@@ -127,24 +127,19 @@ export default function UploadPage() {
 
   const hasNextcloud = !!localStorage.getItem('nc_username')
 
-  const handleFile = (f, fromNextcloud = false) => {
-    if (f && f.type === 'application/pdf') {
-      setFile(f); setError('')
-      if (!fromNextcloud) setTab('local')
-    } else {
-      setError('Please select a PDF file')
-    }
-  }
-
-  const handleUpload = async () => {
-    if (!file) return
-    setUploading(true); setError('')
+  const [uploadName, setUploadName] = useState('')
+  const doUpload = async (f) => {
+    if (!f) return
+    setUploadName(f.name)
+    setUploading(true); setError(''); setProgress(0)
     const formData = new FormData()
-    formData.append('file', file)
+    formData.append('file', f)
     try {
       const res = await api.post('/documents/upload', formData, {
-        headers: { 'Content-Type': 'multipart/form-data' },
-        onUploadProgress: (e) => { if (e.total) setProgress(Math.round((e.loaded / e.total) * 100)) },
+        onUploadProgress: (e) => {
+          if (e.progress != null) setProgress(Math.round(e.progress * 100))
+          else if (e.total) setProgress(Math.round((e.loaded / e.total) * 100))
+        },
       })
       navigate(`/documents/${res.data.id}`)
     } catch (err) {
@@ -152,6 +147,18 @@ export default function UploadPage() {
     } finally { setUploading(false) }
   }
 
+  const handleFile = (f, fromNextcloud = false) => {
+    if (f && f.type === 'application/pdf') {
+      setFile(f); setError('')
+      if (!fromNextcloud) setTab('local')
+      if (fromNextcloud) doUpload(f)
+    } else {
+      setError('Please select a PDF file')
+    }
+  }
+
+  const handleUpload = () => doUpload(file)
+
   return (
     <div>
       <div className="card">
@@ -213,17 +220,25 @@ export default function UploadPage() {
         )}
 
         {uploading && (
-          <div className="progress-bar" style={{ marginTop: 12 }}>
-            <div className="fill" style={{ width: `${progress}%` }} />
+          <div style={{ marginTop: 16, padding: '16px', background: 'var(--option-sel-bg)', borderRadius: 8, border: '1px solid var(--option-sel-bd)' }}>
+            <div style={{ display: 'flex', justifyContent: 'space-between', marginBottom: 8, fontSize: '0.9rem', fontWeight: 600 }}>
+              <span>Uploading {uploadName || file?.name || 'file'}...</span>
+              <span>{progress}%</span>
+            </div>
+            <div className="progress-bar">
+              <div className="fill" style={{ width: `${Math.max(progress, 5)}%`, transition: 'width 0.3s' }} />
+            </div>
           </div>
         )}
 
-        <div style={{ marginTop: 20, display: 'flex', gap: 12 }}>
-          <button className="btn btn-primary" onClick={handleUpload} disabled={!file || uploading}>
-            {uploading ? `Uploading ${progress}%...` : 'Upload & Process'}
-          </button>
-          <button className="btn btn-secondary" onClick={() => navigate('/')}>Cancel</button>
-        </div>
+        {!uploading && (
+          <div style={{ marginTop: 20, display: 'flex', gap: 12 }}>
+            <button className="btn btn-primary" onClick={handleUpload} disabled={!file || uploading}>
+              Upload & Process
+            </button>
+            <button className="btn btn-secondary" onClick={() => navigate('/')}>Cancel</button>
+          </div>
+        )}
       </div>
     </div>
   )