diff --git a/docs/quiz-revamp-plan.md b/docs/quiz-revamp-plan.md
new file mode 100644
index 0000000..92ca86a
--- /dev/null
+++ b/docs/quiz-revamp-plan.md
@@ -0,0 +1,73 @@
+# Orthobullets-inspired quiz revamp
+
+Status: scoped, not implemented. User requested Git tracking and Forgejo synchronization.
+
+## Confirmed requirements
+
+- Close Orthobullets look and quiz workflow, with PedsHub branding and responsive desktop/mobile layouts.
+- Users create custom tests from existing categories/question bank and can share them.
+- Include question-count selection, study/exam modes, and all/unused/incorrect/bookmarked filtering.
+- Include answer distributions, explanations/references, keyboard shortcuts, calculator, lab-reference panel, topic reading, flashcards and educator-moderated comments.
+- Topic links can target a whole article or a subsection; support category/topic breadcrumbs. Educators add and refine articles and cards gradually, but the infrastructure is part of this revamp.
+- Keep current categories and assignments; add optional hierarchy without automatic recategorization.
+- AI assistance for categorization, articles and flashcards.
+- Preserve question/explanation text, existing features and course-quiz isolation.
+
+Orthobullets was inspected through its UI. Its supplied milestone exam is timed and single-attempt, so it was not started. The custom-test builder was inspected without creating a test. No question-bank content, articles, flashcards or branding assets were imported.
+
+## Git and recovery
+
+- Remote: Forgejo `danvics/pdf-quiz-generator`.
+- Development branch: `feat/orthobullets-quiz-revamp`.
+- Original synchronized master: `e7f91e5`.
+- Existing local work preserved in commit `3cf21d4` and tag `baseline/pre-orthobullets-2026-09-06`; both pushed before revamp work.
+- Snapshot contains 24 previously uncommitted files, including explanation images, classification snapshots, quiz visibility/resume changes, quiz codes, TTS options and bot formatting.
+- Baseline validation: diff whitespace check; 15 changed Python files parsed; heuristic secret scan found no likely credentials. These are NOT full behavioral tests or a deployment certification.
+- Use focused commits for subsequent phases, record checks and push to this branch. No force-pushes or implicit production deployment. Keep credentials, uploads, databases, generated builds and backups outside Git.
+- Before migrations/deployment, verify database recovery and current schema/image state. Do not restart backend/Celery during running jobs; rebuild matching images as described in `CLAUDE.md`.
+
+## Reuse and implementation plan
+
+### 1. Custom tests and hierarchy
+
+Extend `backend/app/models/question_category.py` and `routers/question_categories.py` with an optional parent, breadcrumbs, descendant selection and cycle-safe editing. Existing categories remain roots and retain their IDs.
+
+Extend `routers/questions.py`, the existing quiz model/junction and `frontend/src/pages/QuestionBankPage.jsx` with a learner-facing category builder: accurate counts, server-side random sampling without duplicates, state filters, count/mode selection and saved question membership. Reuse attempts and favorites for progress/history/bookmarks.
+
+Category-to-quiz creation currently requires moderator privileges and an origin quiz; ordinary users only have selected-question creation. Unify these paths rather than build another quiz engine. The current `/questions/from-bank` lookup does not filter requested IDs through bank visibility: fix the underlying access checks before exposing sharing. Enforce consistent private/shared access on quizzes, questions, attempts and related content; keep course-only questions isolated. `is_shared` exists but current quiz access relies on ownership/`is_published`, so a UI toggle alone is insufficient.
+
+Keep a saved test's membership fixed through category edits. Preserve completed scores/history; add minimal historical snapshots where required instead of copying the whole question bank.
+
+### 2. Runner and review
+
+Restyle `QuizPage.jsx`, `ResultsPage.jsx` and relevant CSS: compact top navigation, question counter/navigator, breadcrumbs, numbered options, clear selection/correctness and full explanations. Preserve images, highlighting, notes, AI tutor and existing useful controls.
+
+Compute answer distributions from real recorded answers with a stated sample count. Never invent statistics or expose answers, distributions or teaching material early in exam mode. Add input-safe shortcuts, an accessible calculator without `eval`, and an accessible lab-reference panel. Lab values need a cited, educator-approved source; do not infer clinical ranges from screenshots or AI.
+
+### 3. Articles, subsections and linked cards
+
+Reuse `RichEditor.jsx` (Milkdown) and existing markdown/AI editor patterns for a focused topic/article library with draft/published states. Link questions to articles or stable section IDs and show category breadcrumbs. Heading renames must not break subsection links; validate/remediate deleted sections.
+
+Provide side-by-side reading on desktop and an accessible mobile drawer. Treat external references as links unless embedding is supported. Reuse existing flashcard models, sharing, edit and study UI; add manual card creation and question/category/article associations instead of a second card system. Empty content is clearly labeled, with educator-only author/link actions.
+
+### 4. AI authoring and moderation
+
+Reuse `get_model_for_task`, existing LiteLLM configuration, Celery and job-progress UI. Existing classification produces tags, not category hierarchy; add reviewable category suggestions rather than automatically moving questions. Support article drafting/refinement and cards from authorized questions/articles.
+
+Proposed default (pending confirmation): shared educational AI content is educator-authored and remains draft until approved. Do not fabricate reference claims or auto-publish generated material. Learner-private AI drafting is a separate permissions/cost decision.
+
+Add comments with author ownership, moderation state, pagination and server-side educator controls. Proposed default: learners see their own pending comments; public visibility requires educator approval. Sanitize rendered content and bound request sizes/rates.
+
+### 5. Verification and release
+
+Use existing Vitest/Testing Library and backend tests. Cover category cycles/descendants, available counts/sampling, question permissions, saved membership, sharing/revocation, course isolation, exam secrecy, historical attempts, article anchors, AI drafts and comment moderation. Check calculator/keyboard boundaries and desktop/mobile accessibility.
+
+Run frontend build and targeted/full relevant suites; obtain independent review, inspect actual diffs and browser-check visible outcomes. Use versioned reversible migrations, a database recovery point and matching backend/Celery/frontend builds. Verify live behavior after an approved rollout; retain rollback information.
+
+## Remaining product decisions
+
+1. AI authorship: educators/admins only, or learner-private generation too (shared publication still moderated)?
+2. Lab content: educator-supplied data with an initially empty panel, or cited pediatric age-specific seed data for educator review before publication?
+3. Confirm the proposed staged implementation and moderation defaults before application edits.
+
+No app implementation, migrations, AI-generation jobs or deployments were performed during this scoping/Git synchronization work.