feat(quiz): rebuild the quiz UI from the approved designs (#537 frontend)

.github/workflows/e2e.yml

@@ -83,6 +83,12 @@ jobs:
  # Dummy on purpose: the below-seam RAG embed path (#439) must not
  # be able to bill; its failures are swallowed by design.
  GEMINI_API_KEY: e2e-dummy-key-no-billing
+ # #537: the quiz-generation guard keeps its sliding window in a
+ # process-local dict, so ONE Playwright run shares a single
+ # 8-per-300s budget across every spec and the quiz specs that run
+ # last 429. e2e-up.sh sets the same value; kept here so what the
+ # lane actually runs under is visible beside the rest of the seam.
+ QUIZ_GENERATE_RATE_LIMIT: "1000"
  run: make e2e-up
 
  - name: Run Playwright suite

backend/.env.example

@@ -69,3 +69,12 @@ GEMINI_VISION_OCR_ENABLED=false
 GEMINI_VISION_OCR_MAX_PAGES=10
 # The transcription model is the ADR-0008 per-task slot, not a knob of its own:
 # SAPLING_MODEL_OCR_VISION=gemini-2.5-flash
+
+# Quiz generation abuse guard (#544 F1; env-overridable since #537). The window
+# lives in a process-local dict, so ONE Playwright run spends a single budget
+# across every spec — the E2E lanes raise this; production keeps the default.
+# Unparseable or non-positive values fall back to the default.
+# QUIZ_GENERATE_RATE_LIMIT=8
+# Sliding-window length for that limit, in seconds. E2E lanes raise the limit
+# rather than shrink the window; production keeps the default.
+# QUIZ_GENERATE_RATE_WINDOW_SEC=300

backend/services/quiz_config.py

@@ -9,6 +9,41 @@
 Standalone constants module: no imports from models/routes/services so
 it can be imported from anywhere without cycles.
 """
+import logging
+import os
+
+logger = logging.getLogger(__name__)
+
+
+def _positive_int_env(name: str, default: int) -> int:
+ """A deployment override for one guard constant, read at import.
+
+ Deliberately fail-SAFE rather than fail-fast: an unparseable or
+ non-positive value falls back to the shipped default (the conservative
+ one) with a warning, so a stray env var cannot boot the app with a
+ disabled guard — or refuse to boot at all. Read once at import time,
+ which is also when `routes/quiz.py` binds the value, so a mid-process
+ `os.environ` change has no effect.
+ """
+ raw = os.getenv(name)
+ if raw is None or not raw.strip():
+ return default
+ try:
+ value = int(raw.strip())
+ except ValueError:
+ logger.warning(
+ "quiz_config: %s=%r is not an integer — using the default %d",
+ name, raw, default,
+ )
+ return default
+ if value <= 0:
+ logger.warning(
+ "quiz_config: %s=%d is not positive — using the default %d",
+ name, value, default,
+ )
+ return default
+ return value
+
 
 QUIZ_MIN_QUESTIONS = 1
 
@@ -87,8 +122,18 @@ def mastery_after(before: float, *, score: int, total: int) -> float:
 # The rate limit is sized for a human: a student comparing difficulties or
 # retaking a concept might legitimately generate a handful of quizzes in a
 # few minutes; nobody legitimately generates 10 in one.
-QUIZ_GENERATE_RATE_LIMIT = 8
-QUIZ_GENERATE_RATE_WINDOW_SEC = 300 # 5 minutes
+#
+# Both are env-overridable (#537) for one reason: `request_limits._rate_state`
+# is a module-level dict, so a whole Playwright run — every spec, every
+# worker-shared window — spends ONE 8-per-300s budget that only a backend
+# restart clears. The redesigned quiz lane needs ~20 real generations, and a
+# function-mode generation costs nothing, so the E2E stacks raise the limit
+# (scripts/e2e-up.sh, .github/workflows/e2e.yml). Production sets neither and
+# keeps the defaults below.
+QUIZ_GENERATE_RATE_LIMIT = _positive_int_env("QUIZ_GENERATE_RATE_LIMIT", 8)
+QUIZ_GENERATE_RATE_WINDOW_SEC = _positive_int_env(
+ "QUIZ_GENERATE_RATE_WINDOW_SEC", 300, # 5 minutes
+)
 
 # Daily per-user LLM spend ceiling. The SPEND it measures is cross-feature
 # (llm_usage records every agent call, not just quiz ones), but the ceiling

backend/tests/test_quiz_cost_observability_f.py

@@ -132,6 +132,87 @@ def test_limit_is_per_user(self):
  assert other.status_code == 200
 
 
+class TestGenerateRateLimitIsEnvOverridable:
+ """#537: the two guard constants read the environment; defaults intact.
+
+ `request_limits._rate_state` is module-level, so a whole Playwright run
+ shares ONE window that only a backend restart clears — and the redesigned
+ quiz lane needs more generations than any human would. The E2E stacks
+ raise the limit through the environment; production sets nothing and must
+ keep the shipped defaults.
+ """
+
+ @staticmethod
+ def _reloaded():
+ """Re-import services.quiz_config against the current environment.
+
+ `importlib.reload` mutates the module in place, so every caller must
+ restore it (see `_restore`) or later tests inherit the override.
+ """
+ import importlib
+
+ from services import quiz_config
+
+ return importlib.reload(quiz_config)
+
+ @classmethod
+ def _restore(cls):
+ cls._reloaded()
+
+ def test_defaults_hold_when_unset(self, monkeypatch):
+ monkeypatch.delenv("QUIZ_GENERATE_RATE_LIMIT", raising=False)
+ monkeypatch.delenv("QUIZ_GENERATE_RATE_WINDOW_SEC", raising=False)
+ try:
+ cfg = self._reloaded()
+ assert cfg.QUIZ_GENERATE_RATE_LIMIT == 8
+ assert cfg.QUIZ_GENERATE_RATE_WINDOW_SEC == 300
+ finally:
+ monkeypatch.undo()
+ self._restore()
+
+ def test_an_override_is_honoured(self, monkeypatch):
+ monkeypatch.setenv("QUIZ_GENERATE_RATE_LIMIT", "1000")
+ monkeypatch.setenv("QUIZ_GENERATE_RATE_WINDOW_SEC", "60")
+ try:
+ cfg = self._reloaded()
+ assert cfg.QUIZ_GENERATE_RATE_LIMIT == 1000
+ assert cfg.QUIZ_GENERATE_RATE_WINDOW_SEC == 60
+ finally:
+ monkeypatch.undo()
+ self._restore()
+
+ def test_a_junk_override_falls_back_to_the_default(self, monkeypatch):
+ """Fail-safe, not fail-fast: a stray value must neither disable the
+ guard (limit=0 would 429 everyone, a negative window never expires)
+ nor stop the app from booting."""
+ for bad in ("", " ", "eight", "0", "-5", "3.5"):
+ monkeypatch.setenv("QUIZ_GENERATE_RATE_LIMIT", bad)
+ monkeypatch.setenv("QUIZ_GENERATE_RATE_WINDOW_SEC", bad)
+ try:
+ cfg = self._reloaded()
+ assert cfg.QUIZ_GENERATE_RATE_LIMIT == 8, bad
+ assert cfg.QUIZ_GENERATE_RATE_WINDOW_SEC == 300, bad
+ finally:
+ monkeypatch.undo()
+ self._restore()
+
+ def test_the_route_still_enforces_whatever_was_resolved(self):
+ """The env seam moves the NUMBER, never the behaviour: the route binds
+ the value at its own import and still 429s one call past it."""
+ from routes import quiz as quiz_route
+ from services.quiz_config import QUIZ_GENERATE_RATE_LIMIT
+
+ assert quiz_route.QUIZ_GENERATE_RATE_LIMIT == QUIZ_GENERATE_RATE_LIMIT
+ run = AsyncMock(return_value=SimpleNamespace(output=_quiz()))
+ with (
+ patch("routes.quiz.table", side_effect=_factory()),
+ patch("routes.quiz.quiz_agent.run", new=run),
+ ):
+ for _ in range(quiz_route.QUIZ_GENERATE_RATE_LIMIT):
+ assert _generate().status_code == 200
+ assert _generate().status_code == 429
+
+
 class TestDailySpendGuard:
  def test_over_budget_user_is_refused_before_the_model_runs(self):
  from services.quiz_config import QUIZ_DAILY_SPEND_CAP_USD

docs/e2e-exploration.md

@@ -226,7 +226,10 @@ byte-for-byte match to one of `function_handlers_e2e.py`'s `E2E_DOC_*` (or
 `E2E_TUTOR_REPLY`, `E2E_QUIZ_*`) constants — here, `E2E_DOC_ABSTRACT`'s
 "gradient descent... loss surface... learning rate" wording and the fixed
 `lecture_notes` category. If a finding's "wrong" content matches one of
-those constants verbatim, it's the seam, not the app — drop it, and if it
+those constants verbatim, it's the seam, not the app (likewise the quiz's
+"Only 3 questions were ready for this concept" toast: the function-mode quiz handler always
+returns exactly 3 questions, so any requested length above 3 is reported as a short delivery —
+the honesty check working, not a generation bug) — drop it, and if it
 recurs, improve `scripts/explore/explorer-prompt.md`'s ground rules to name
 the pattern explicitly so a future explorer recognizes it before writing the
 stub, rather than filing an issue against the harness's own known-fixed

docs/frontend-testids.md

@@ -71,7 +71,7 @@ renders the element.
 | Onboarding | `onboarding` | `frontend/src/components/screens/Onboarding.tsx` (the first-run funnel, rendered bare outside `(shell)`) |
 | Upload modal | `upload-modal` | `frontend/src/components/DocumentUploadModal.tsx` |
 | Tutor | `tutor` | `frontend/src/components/chat/ChatPanel.tsx` (rendered by `screens/Learn.tsx`; + the session-resume rows in `src/components/screens/Learn.tsx` itself) |
-| Quiz | `quiz` | `frontend/src/components/QuizPanel.tsx` (rendered by `screens/Quiz.tsx`) |
+| Quiz | `quiz` | `frontend/src/components/quiz/**` — `QuizScreen.tsx` (route root + error card) switching on phase between `home/QuizHome.tsx` (+ `ConceptDialog`/`AdjustDialog`/`PickList`/`QuizSettings`), `question/QuizQuestion.tsx` (+ `AskPanel`/`LeaveDialog`) and `results/QuizResults.tsx` (+ `MissedList`); the ids on the shared `ui/` primitives and `graph/ConceptNeighbourhood.tsx` are passed in from those files as a `testid` prop (#537) |
 | Knowledge graph | `graph` | `frontend/src/components/graph/KnowledgeGraph.tsx` (wrapper: container root + mode toggle) plus `KnowledgeGraph2D.tsx`/`KnowledgeGraph3D.tsx` (the render/data-layer seam — hidden a11y node list, SVG node/edge marks, zoom controls — added with the #395 graph-integrity journey) |
 | App shell | `app` | `frontend/src/components/ShellFrame.tsx` (the authed layout frame every `(shell)` route renders inside) |
 | Study rooms | `social` | `frontend/src/components/screens/Social.tsx` (rooms sidebar, chat, overview, study match, directory — added with the #394 two-context journey) |
@@ -95,8 +95,16 @@ route:
  and the send `<button>` render in `ChatPanel.tsx`. `ChatPanel` has exactly one
  consumer (Learn), so tagging it there is unambiguous. The notetaker's chat is
  a separate `AIChatPanel` and is out of scope.
-- **Quiz.** `screens/Quiz.tsx` only fetches concepts and mounts `QuizPanel`;
- every answer/submit control renders in `QuizPanel.tsx`.
+- **Quiz.** The route mounts one component, `components/quiz/QuizScreen.tsx`,
+ which switches on phase between `home/QuizHome.tsx`,
+ `question/QuizQuestion.tsx` and `results/QuizResults.tsx`; each of the three
+ owns its own ids and its own dialogs. Three shared `ui/` primitives
+ (`AnswerOption`, `SegmentedControl`, `Sheet`) are in the eslint file list too:
+ the controls render inside them, so a testid-less `<button>` there would
+ un-anchor the surface from outside the screen files. Those primitives — plus
+ `ui/EmptyState`, `ui/InlineBanner`, `ui/ProgressDots` and
+ `graph/ConceptNeighbourhood` — take the id as a `testid` prop, so the value is
+ always written at the quiz call site, never inside the primitive.
 
 ## Current inventory
 
@@ -174,22 +182,87 @@ route:
 
 ### `quiz`
 
+The quiz is one surface: `components/quiz/QuizScreen.tsx` reads the entry off
+the URL and switches on phase between `home/QuizHome.tsx`,
+`question/QuizQuestion.tsx` and `results/QuizResults.tsx`. The table is grouped
+in that order; the screen-level ids (the error card) come last, followed by the
+entry points the quiz wave added inside other surfaces' files.
+
+Three ids are **renamed** from the pre-#537 quiz — same role, clearer name:
+`quiz-exit` → `quiz-leave`, `quiz-retake` → `quiz-again`,
+`quiz-explain-concept` → `quiz-ask`. Eleven are **kept** verbatim so existing
+journeys keep anchoring: `quiz-panel`, `quiz-start`, `quiz-cancel`,
+`quiz-answer-options`, `quiz-answer-option-{label}`, `quiz-submit-answer`,
+`quiz-next`, `quiz-review-verdict`, `quiz-results-score`,
+`quiz-results-mastery`, `quiz-done`.
+
 | testid | element |
 | --- | --- |
-| `quiz-panel` | panel root (all phases) |
-| `quiz-cancel` | "Cancel" (select phase) |
-| `quiz-start` | "Start quiz" |
+| `quiz-home` | quiz-home root (`phase: home \| configuring`) |
+| `quiz-resume-strip` | the "you left a quiz on X" banner (`ui/InlineBanner`) |
+| `quiz-resume` | "Resume" on that banner |
+| `quiz-resume-discard` | "Discard" — hides the attempt client-side; there is no abandon endpoint |
+| `quiz-proposal` | the "Ready for you" primary proposal card |
+| `quiz-start` | "Start" on that card |
+| `quiz-cancel` | "Cancel" — leaves for the entry source, or `/dashboard` when there is none |
+| `quiz-adjust` | "adjust" on the card — toggles the adjust dialog (`aria-pressed`) |
+| `quiz-alternative-{nodeId}` | one "Also worth a look" row |
+| `quiz-review-due` | "Review everything due" row |
+| `quiz-pick-open` | "Pick something specific →" |
+| `quiz-pick-list` | the grouped concept list it reveals |
+| `quiz-pick-{nodeId}` | one concept row in that list |
+| `quiz-pick-back` | "← Back" out of that list |
+| `quiz-empty-state` | the home's empty states (`ui/EmptyState`) — no courses, empty tree, or nothing left to propose; they are alternatives, so only one ever mounts |
+| `quiz-home-error` | the home's load-failure card |
+| `quiz-home-retry` | "Retry" inside it |
+| `quiz-concept-dialog` | the concept dialog opened from an alternative or a pick row |
+| `quiz-concept-start` | "Start · {count} {difficulty}" inside it |
+| `quiz-concept-cancel` | its "Cancel" |
+| `quiz-adjust-dialog` | "Adjust this quiz" dialog |
+| `quiz-adjust-done` | its "Done" — keeps the settings without starting |
+| `quiz-adjust-start` | its "Start · {count} {difficulty}" — saves and starts in one |
+| `quiz-seg-count` / `quiz-seg-difficulty` / `quiz-seg-feedback` | the three `ui/SegmentedControl`s both dialogs share; each option is `${testid}-${value}` |
+| `quiz-generating` | the skeleton question screen while a quiz is being written |
+| `quiz-panel` | question root (`phase: active \| answered`) |
+| `quiz-progress` | the question rail's progress dots (`ui/ProgressDots`) |
 | `quiz-answer-options` | answer radiogroup |
-| `quiz-answer-option-{label}` | one answer choice, suffixed with its label (`A`…) |
-| `quiz-submit-answer` | "Submit answer" |
-| `quiz-exit` | "Exit" (active phase) |
+| `quiz-answer-option-{label}` | one answer choice (`ui/AnswerOption`), suffixed with its label (`A`…) |
+| `quiz-submit-answer` | the footer's primary button while the answer is unrevealed |
+| `quiz-next` | the same footer button once the verdict is showing — "Next question" / "See results" |
 | `quiz-review-verdict` | "Correct." / "Not quite." banner |
-| `quiz-explain-concept` | "Explain this" |
-| `quiz-next` | "Next question" / "See results" |
-| `quiz-results-score` | the score percentage |
-| `quiz-results-mastery` | the "X / Y correct · mastery B% → A%" line |
-| `quiz-retake` | "Retake" |
-| `quiz-done` | "Done" |
+| `quiz-flag` | "This question is confusing" (toggles, `aria-pressed`; persists nothing) |
+| `quiz-ask` | "Ask about this" — opens the tutor sheet |
+| `quiz-leave` | "Leave" |
+| `quiz-leave-dialog` / `quiz-leave-cancel` / `quiz-leave-confirm` | the leave confirmation |
+| `quiz-ask-panel` | the tutor sheet (`ui/Sheet`) |
+| `quiz-ask-panel-close` | its × — the `Sheet` derives it as `${testid}-close` |
+| `quiz-ask-seed` | the composed first message shown at the top of the sheet |
+| `quiz-ask-retry` | "Try again" when the tutor stream failed |
+| `quiz-ask-input` / `quiz-ask-send` | the sheet's composer |
+| `quiz-results` | results root |
+| `quiz-results-graph` | the concept neighbourhood above the score (`graph/ConceptNeighbourhood`) |
+| `quiz-results-score` | the "{n} of {total} correct" line — a count, not a percentage |
+| `quiz-results-mastery` | the mastery delta line, "B% → A% · tier-before → tier-after" |
+| `quiz-results-xp` | "+{Δ} XP · {streak}-day streak" — absent when either gamification read failed |
+| `quiz-results-perfect` | the line shown instead of the missed list on a clean sweep |
+| `quiz-missed-list` | the "to look at" section |
+| `quiz-missed-{questionId}` | one missed item |
+| `quiz-missed-explain-{questionId}` | its "Show explanation" disclosure |
+| `quiz-missed-ask-{questionId}` | its "Ask about this" |
+| `quiz-practise-missed` | "Practise the one(s) you missed" |
+| `quiz-next-concept` | "Next: {concept} →" while the scope queue has more |
+| `quiz-again` | "Keep going — quiz again" (mounts in `quiz-practise-missed`'s place on a clean sweep) |
+| `quiz-back-to-source` | the secondary exit, labelled by where the quiz was entered from |
+| `quiz-done` | "Done" — back to `/quiz` |
+| `quiz-error` | the route-level error card (mapped copy + retry/back), rendered by `QuizScreen` in place of the phase |
+| `quiz-error-retry` / `quiz-error-back` | its "Try again" and "Back" |
+| `tree-node-recent-quizzes` | the tree node panel's "Recent quizzes" block (`screens/Tree.tsx`) |
+| `tree-node-recent-quiz-{attemptId}` | one row in it, suffixed with the attempt's `quiz_id` per the stable-domain-id rule |
+| `dashboard-review-due` | the "Review what's due" quiz entry point (`screens/Dashboard.tsx`) — three call sites, but exactly one mounts for a given layout/viewport |
+
+The last three carry another surface's prefix because they render in that
+surface's file. They are listed here because they are quiz entry points, and a
+quiz journey is what drives them.
 
 ### `graph`
 
@@ -279,6 +352,9 @@ never collide in the DOM.
 | `dashboard-courses-manage` | the cog inside the expanded key that opens the Courses & Semesters hub (the hub's own semester tabs are plain text buttons — journeys select them by role/name, e.g. "All semesters" / "Fall 2025") |
 | `dashboard-resume-{sessionId}` | a "Where you left off" card — deep-links to `/learn?resume={sessionId}` (#164), suffixed with the session's own id per the stable-domain-id rule |
 
+`dashboard-review-due` also lives in `screens/Dashboard.tsx`; it is documented
+with the `quiz` surface it links into.
+
 ### `calendar`
 
 Added with the #185 load-failure fix (a failed initial fetch must be
@@ -300,6 +376,7 @@ inside the `role="grid"` "Courses" grid.
 | testid | element |
 | --- | --- |
 | `gradebook-term-gpa` | landing: the selected term's credit-weighted GPA next to the chips (absent while the term has no graded work) |
+| `gradebook-upload-syllabus` | landing: the blank-semester empty state's "Upload syllabus" CTA (`ui/EmptyState` action slot) |
 | `gradebook-transcript-open` | landing: "Transcript" button opening the transcript modal |
 | `gradebook-transcript-gpa` | transcript modal: the cumulative GPA value |
 | `gradebook-transcript-retry` | transcript modal: inline "Try again" after a failed load (#463 catch+toast pattern) |

.github/workflows/e2e.yml

@@ -83,6 +83,12 @@ jobs:
  # Dummy on purpose: the below-seam RAG embed path (#439) must not
  # be able to bill; its failures are swallowed by design.
  GEMINI_API_KEY: e2e-dummy-key-no-billing
+ # #537: the quiz-generation guard keeps its sliding window in a
+ # process-local dict, so ONE Playwright run shares a single
+ # 8-per-300s budget across every spec and the quiz specs that run
+ # last 429. e2e-up.sh sets the same value; kept here so what the
+ # lane actually runs under is visible beside the rest of the seam.
+ QUIZ_GENERATE_RATE_LIMIT: "1000"
  run: make e2e-up
 
  - name: Run Playwright suite

backend/.env.example

@@ -69,3 +69,12 @@ GEMINI_VISION_OCR_ENABLED=false
 GEMINI_VISION_OCR_MAX_PAGES=10
 # The transcription model is the ADR-0008 per-task slot, not a knob of its own:
 # SAPLING_MODEL_OCR_VISION=gemini-2.5-flash
+
+# Quiz generation abuse guard (#544 F1; env-overridable since #537). The window
+# lives in a process-local dict, so ONE Playwright run spends a single budget
+# across every spec — the E2E lanes raise this; production keeps the default.
+# Unparseable or non-positive values fall back to the default.
+# QUIZ_GENERATE_RATE_LIMIT=8
+# Sliding-window length for that limit, in seconds. E2E lanes raise the limit
+# rather than shrink the window; production keeps the default.
+# QUIZ_GENERATE_RATE_WINDOW_SEC=300

backend/services/quiz_config.py

@@ -9,6 +9,41 @@
 Standalone constants module: no imports from models/routes/services so
 it can be imported from anywhere without cycles.
 """
+import logging
+import os
+
+logger = logging.getLogger(__name__)
+
+
+def _positive_int_env(name: str, default: int) -> int:
+ """A deployment override for one guard constant, read at import.
+
+ Deliberately fail-SAFE rather than fail-fast: an unparseable or
+ non-positive value falls back to the shipped default (the conservative
+ one) with a warning, so a stray env var cannot boot the app with a
+ disabled guard — or refuse to boot at all. Read once at import time,
+ which is also when `routes/quiz.py` binds the value, so a mid-process
+ `os.environ` change has no effect.
+ """
+ raw = os.getenv(name)
+ if raw is None or not raw.strip():
+ return default
+ try:
+ value = int(raw.strip())
+ except ValueError:
+ logger.warning(
+ "quiz_config: %s=%r is not an integer — using the default %d",
+ name, raw, default,
+ )
+ return default
+ if value <= 0:
+ logger.warning(
+ "quiz_config: %s=%d is not positive — using the default %d",
+ name, value, default,
+ )
+ return default
+ return value
+
 
 QUIZ_MIN_QUESTIONS = 1
 
@@ -87,8 +122,18 @@ def mastery_after(before: float, *, score: int, total: int) -> float:
 # The rate limit is sized for a human: a student comparing difficulties or
 # retaking a concept might legitimately generate a handful of quizzes in a
 # few minutes; nobody legitimately generates 10 in one.
-QUIZ_GENERATE_RATE_LIMIT = 8
-QUIZ_GENERATE_RATE_WINDOW_SEC = 300 # 5 minutes
+#
+# Both are env-overridable (#537) for one reason: `request_limits._rate_state`
+# is a module-level dict, so a whole Playwright run — every spec, every
+# worker-shared window — spends ONE 8-per-300s budget that only a backend
+# restart clears. The redesigned quiz lane needs ~20 real generations, and a
+# function-mode generation costs nothing, so the E2E stacks raise the limit
+# (scripts/e2e-up.sh, .github/workflows/e2e.yml). Production sets neither and
+# keeps the defaults below.
+QUIZ_GENERATE_RATE_LIMIT = _positive_int_env("QUIZ_GENERATE_RATE_LIMIT", 8)
+QUIZ_GENERATE_RATE_WINDOW_SEC = _positive_int_env(
+ "QUIZ_GENERATE_RATE_WINDOW_SEC", 300, # 5 minutes
+)
 
 # Daily per-user LLM spend ceiling. The SPEND it measures is cross-feature
 # (llm_usage records every agent call, not just quiz ones), but the ceiling

backend/tests/test_quiz_cost_observability_f.py

@@ -132,6 +132,87 @@ def test_limit_is_per_user(self):
  assert other.status_code == 200
 
 
+class TestGenerateRateLimitIsEnvOverridable:
+ """#537: the two guard constants read the environment; defaults intact.
+
+ `request_limits._rate_state` is module-level, so a whole Playwright run
+ shares ONE window that only a backend restart clears — and the redesigned
+ quiz lane needs more generations than any human would. The E2E stacks
+ raise the limit through the environment; production sets nothing and must
+ keep the shipped defaults.
+ """
+
+ @staticmethod
+ def _reloaded():
+ """Re-import services.quiz_config against the current environment.
+
+ `importlib.reload` mutates the module in place, so every caller must
+ restore it (see `_restore`) or later tests inherit the override.
+ """
+ import importlib
+
+ from services import quiz_config
+
+ return importlib.reload(quiz_config)
+
+ @classmethod
+ def _restore(cls):
+ cls._reloaded()
+
+ def test_defaults_hold_when_unset(self, monkeypatch):
+ monkeypatch.delenv("QUIZ_GENERATE_RATE_LIMIT", raising=False)
+ monkeypatch.delenv("QUIZ_GENERATE_RATE_WINDOW_SEC", raising=False)
+ try:
+ cfg = self._reloaded()
+ assert cfg.QUIZ_GENERATE_RATE_LIMIT == 8
+ assert cfg.QUIZ_GENERATE_RATE_WINDOW_SEC == 300
+ finally:
+ monkeypatch.undo()
+ self._restore()
+
+ def test_an_override_is_honoured(self, monkeypatch):
+ monkeypatch.setenv("QUIZ_GENERATE_RATE_LIMIT", "1000")
+ monkeypatch.setenv("QUIZ_GENERATE_RATE_WINDOW_SEC", "60")
+ try:
+ cfg = self._reloaded()
+ assert cfg.QUIZ_GENERATE_RATE_LIMIT == 1000
+ assert cfg.QUIZ_GENERATE_RATE_WINDOW_SEC == 60
+ finally:
+ monkeypatch.undo()
+ self._restore()
+
+ def test_a_junk_override_falls_back_to_the_default(self, monkeypatch):
+ """Fail-safe, not fail-fast: a stray value must neither disable the
+ guard (limit=0 would 429 everyone, a negative window never expires)
+ nor stop the app from booting."""
+ for bad in ("", " ", "eight", "0", "-5", "3.5"):
+ monkeypatch.setenv("QUIZ_GENERATE_RATE_LIMIT", bad)
+ monkeypatch.setenv("QUIZ_GENERATE_RATE_WINDOW_SEC", bad)
+ try:
+ cfg = self._reloaded()
+ assert cfg.QUIZ_GENERATE_RATE_LIMIT == 8, bad
+ assert cfg.QUIZ_GENERATE_RATE_WINDOW_SEC == 300, bad
+ finally:
+ monkeypatch.undo()
+ self._restore()
+
+ def test_the_route_still_enforces_whatever_was_resolved(self):
+ """The env seam moves the NUMBER, never the behaviour: the route binds
+ the value at its own import and still 429s one call past it."""
+ from routes import quiz as quiz_route
+ from services.quiz_config import QUIZ_GENERATE_RATE_LIMIT
+
+ assert quiz_route.QUIZ_GENERATE_RATE_LIMIT == QUIZ_GENERATE_RATE_LIMIT
+ run = AsyncMock(return_value=SimpleNamespace(output=_quiz()))
+ with (
+ patch("routes.quiz.table", side_effect=_factory()),
+ patch("routes.quiz.quiz_agent.run", new=run),
+ ):
+ for _ in range(quiz_route.QUIZ_GENERATE_RATE_LIMIT):
+ assert _generate().status_code == 200
+ assert _generate().status_code == 429
+
+
 class TestDailySpendGuard:
  def test_over_budget_user_is_refused_before_the_model_runs(self):
  from services.quiz_config import QUIZ_DAILY_SPEND_CAP_USD

docs/e2e-exploration.md

@@ -226,7 +226,10 @@ byte-for-byte match to one of `function_handlers_e2e.py`'s `E2E_DOC_*` (or
 `E2E_TUTOR_REPLY`, `E2E_QUIZ_*`) constants — here, `E2E_DOC_ABSTRACT`'s
 "gradient descent... loss surface... learning rate" wording and the fixed
 `lecture_notes` category. If a finding's "wrong" content matches one of
-those constants verbatim, it's the seam, not the app — drop it, and if it
+those constants verbatim, it's the seam, not the app (likewise the quiz's
+"Only 3 questions were ready for this concept" toast: the function-mode quiz handler always
+returns exactly 3 questions, so any requested length above 3 is reported as a short delivery —
+the honesty check working, not a generation bug) — drop it, and if it
 recurs, improve `scripts/explore/explorer-prompt.md`'s ground rules to name
 the pattern explicitly so a future explorer recognizes it before writing the
 stub, rather than filing an issue against the harness's own known-fixed

docs/frontend-testids.md

@@ -71,7 +71,7 @@ renders the element.
 | Onboarding | `onboarding` | `frontend/src/components/screens/Onboarding.tsx` (the first-run funnel, rendered bare outside `(shell)`) |
 | Upload modal | `upload-modal` | `frontend/src/components/DocumentUploadModal.tsx` |
 | Tutor | `tutor` | `frontend/src/components/chat/ChatPanel.tsx` (rendered by `screens/Learn.tsx`; + the session-resume rows in `src/components/screens/Learn.tsx` itself) |
-| Quiz | `quiz` | `frontend/src/components/QuizPanel.tsx` (rendered by `screens/Quiz.tsx`) |
+| Quiz | `quiz` | `frontend/src/components/quiz/**` — `QuizScreen.tsx` (route root + error card) switching on phase between `home/QuizHome.tsx` (+ `ConceptDialog`/`AdjustDialog`/`PickList`/`QuizSettings`), `question/QuizQuestion.tsx` (+ `AskPanel`/`LeaveDialog`) and `results/QuizResults.tsx` (+ `MissedList`); the ids on the shared `ui/` primitives and `graph/ConceptNeighbourhood.tsx` are passed in from those files as a `testid` prop (#537) |
 | Knowledge graph | `graph` | `frontend/src/components/graph/KnowledgeGraph.tsx` (wrapper: container root + mode toggle) plus `KnowledgeGraph2D.tsx`/`KnowledgeGraph3D.tsx` (the render/data-layer seam — hidden a11y node list, SVG node/edge marks, zoom controls — added with the #395 graph-integrity journey) |
 | App shell | `app` | `frontend/src/components/ShellFrame.tsx` (the authed layout frame every `(shell)` route renders inside) |
 | Study rooms | `social` | `frontend/src/components/screens/Social.tsx` (rooms sidebar, chat, overview, study match, directory — added with the #394 two-context journey) |
@@ -95,8 +95,16 @@ route:
  and the send `<button>` render in `ChatPanel.tsx`. `ChatPanel` has exactly one
  consumer (Learn), so tagging it there is unambiguous. The notetaker's chat is
  a separate `AIChatPanel` and is out of scope.
-- **Quiz.** `screens/Quiz.tsx` only fetches concepts and mounts `QuizPanel`;
- every answer/submit control renders in `QuizPanel.tsx`.
+- **Quiz.** The route mounts one component, `components/quiz/QuizScreen.tsx`,
+ which switches on phase between `home/QuizHome.tsx`,
+ `question/QuizQuestion.tsx` and `results/QuizResults.tsx`; each of the three
+ owns its own ids and its own dialogs. Three shared `ui/` primitives
+ (`AnswerOption`, `SegmentedControl`, `Sheet`) are in the eslint file list too:
+ the controls render inside them, so a testid-less `<button>` there would
+ un-anchor the surface from outside the screen files. Those primitives — plus
+ `ui/EmptyState`, `ui/InlineBanner`, `ui/ProgressDots` and
+ `graph/ConceptNeighbourhood` — take the id as a `testid` prop, so the value is
+ always written at the quiz call site, never inside the primitive.
 
 ## Current inventory
 
@@ -174,22 +182,87 @@ route:
 
 ### `quiz`
 
+The quiz is one surface: `components/quiz/QuizScreen.tsx` reads the entry off
+the URL and switches on phase between `home/QuizHome.tsx`,
+`question/QuizQuestion.tsx` and `results/QuizResults.tsx`. The table is grouped
+in that order; the screen-level ids (the error card) come last, followed by the
+entry points the quiz wave added inside other surfaces' files.
+
+Three ids are **renamed** from the pre-#537 quiz — same role, clearer name:
+`quiz-exit` → `quiz-leave`, `quiz-retake` → `quiz-again`,
+`quiz-explain-concept` → `quiz-ask`. Eleven are **kept** verbatim so existing
+journeys keep anchoring: `quiz-panel`, `quiz-start`, `quiz-cancel`,
+`quiz-answer-options`, `quiz-answer-option-{label}`, `quiz-submit-answer`,
+`quiz-next`, `quiz-review-verdict`, `quiz-results-score`,
+`quiz-results-mastery`, `quiz-done`.
+
 | testid | element |
 | --- | --- |
-| `quiz-panel` | panel root (all phases) |
-| `quiz-cancel` | "Cancel" (select phase) |
-| `quiz-start` | "Start quiz" |
+| `quiz-home` | quiz-home root (`phase: home \| configuring`) |
+| `quiz-resume-strip` | the "you left a quiz on X" banner (`ui/InlineBanner`) |
+| `quiz-resume` | "Resume" on that banner |
+| `quiz-resume-discard` | "Discard" — hides the attempt client-side; there is no abandon endpoint |
+| `quiz-proposal` | the "Ready for you" primary proposal card |
+| `quiz-start` | "Start" on that card |
+| `quiz-cancel` | "Cancel" — leaves for the entry source, or `/dashboard` when there is none |
+| `quiz-adjust` | "adjust" on the card — toggles the adjust dialog (`aria-pressed`) |
+| `quiz-alternative-{nodeId}` | one "Also worth a look" row |
+| `quiz-review-due` | "Review everything due" row |
+| `quiz-pick-open` | "Pick something specific →" |
+| `quiz-pick-list` | the grouped concept list it reveals |
+| `quiz-pick-{nodeId}` | one concept row in that list |
+| `quiz-pick-back` | "← Back" out of that list |
+| `quiz-empty-state` | the home's empty states (`ui/EmptyState`) — no courses, empty tree, or nothing left to propose; they are alternatives, so only one ever mounts |
+| `quiz-home-error` | the home's load-failure card |
+| `quiz-home-retry` | "Retry" inside it |
+| `quiz-concept-dialog` | the concept dialog opened from an alternative or a pick row |
+| `quiz-concept-start` | "Start · {count} {difficulty}" inside it |
+| `quiz-concept-cancel` | its "Cancel" |
+| `quiz-adjust-dialog` | "Adjust this quiz" dialog |
+| `quiz-adjust-done` | its "Done" — keeps the settings without starting |
+| `quiz-adjust-start` | its "Start · {count} {difficulty}" — saves and starts in one |
+| `quiz-seg-count` / `quiz-seg-difficulty` / `quiz-seg-feedback` | the three `ui/SegmentedControl`s both dialogs share; each option is `${testid}-${value}` |
+| `quiz-generating` | the skeleton question screen while a quiz is being written |
+| `quiz-panel` | question root (`phase: active \| answered`) |
+| `quiz-progress` | the question rail's progress dots (`ui/ProgressDots`) |
 | `quiz-answer-options` | answer radiogroup |
-| `quiz-answer-option-{label}` | one answer choice, suffixed with its label (`A`…) |
-| `quiz-submit-answer` | "Submit answer" |
-| `quiz-exit` | "Exit" (active phase) |
+| `quiz-answer-option-{label}` | one answer choice (`ui/AnswerOption`), suffixed with its label (`A`…) |
+| `quiz-submit-answer` | the footer's primary button while the answer is unrevealed |
+| `quiz-next` | the same footer button once the verdict is showing — "Next question" / "See results" |
 | `quiz-review-verdict` | "Correct." / "Not quite." banner |
-| `quiz-explain-concept` | "Explain this" |
-| `quiz-next` | "Next question" / "See results" |
-| `quiz-results-score` | the score percentage |
-| `quiz-results-mastery` | the "X / Y correct · mastery B% → A%" line |
-| `quiz-retake` | "Retake" |
-| `quiz-done` | "Done" |
+| `quiz-flag` | "This question is confusing" (toggles, `aria-pressed`; persists nothing) |
+| `quiz-ask` | "Ask about this" — opens the tutor sheet |
+| `quiz-leave` | "Leave" |
+| `quiz-leave-dialog` / `quiz-leave-cancel` / `quiz-leave-confirm` | the leave confirmation |
+| `quiz-ask-panel` | the tutor sheet (`ui/Sheet`) |
+| `quiz-ask-panel-close` | its × — the `Sheet` derives it as `${testid}-close` |
+| `quiz-ask-seed` | the composed first message shown at the top of the sheet |
+| `quiz-ask-retry` | "Try again" when the tutor stream failed |
+| `quiz-ask-input` / `quiz-ask-send` | the sheet's composer |
+| `quiz-results` | results root |
+| `quiz-results-graph` | the concept neighbourhood above the score (`graph/ConceptNeighbourhood`) |
+| `quiz-results-score` | the "{n} of {total} correct" line — a count, not a percentage |
+| `quiz-results-mastery` | the mastery delta line, "B% → A% · tier-before → tier-after" |
+| `quiz-results-xp` | "+{Δ} XP · {streak}-day streak" — absent when either gamification read failed |
+| `quiz-results-perfect` | the line shown instead of the missed list on a clean sweep |
+| `quiz-missed-list` | the "to look at" section |
+| `quiz-missed-{questionId}` | one missed item |
+| `quiz-missed-explain-{questionId}` | its "Show explanation" disclosure |
+| `quiz-missed-ask-{questionId}` | its "Ask about this" |
+| `quiz-practise-missed` | "Practise the one(s) you missed" |
+| `quiz-next-concept` | "Next: {concept} →" while the scope queue has more |
+| `quiz-again` | "Keep going — quiz again" (mounts in `quiz-practise-missed`'s place on a clean sweep) |
+| `quiz-back-to-source` | the secondary exit, labelled by where the quiz was entered from |
+| `quiz-done` | "Done" — back to `/quiz` |
+| `quiz-error` | the route-level error card (mapped copy + retry/back), rendered by `QuizScreen` in place of the phase |
+| `quiz-error-retry` / `quiz-error-back` | its "Try again" and "Back" |
+| `tree-node-recent-quizzes` | the tree node panel's "Recent quizzes" block (`screens/Tree.tsx`) |
+| `tree-node-recent-quiz-{attemptId}` | one row in it, suffixed with the attempt's `quiz_id` per the stable-domain-id rule |
+| `dashboard-review-due` | the "Review what's due" quiz entry point (`screens/Dashboard.tsx`) — three call sites, but exactly one mounts for a given layout/viewport |
+
+The last three carry another surface's prefix because they render in that
+surface's file. They are listed here because they are quiz entry points, and a
+quiz journey is what drives them.
 
 ### `graph`
 
@@ -279,6 +352,9 @@ never collide in the DOM.
 | `dashboard-courses-manage` | the cog inside the expanded key that opens the Courses & Semesters hub (the hub's own semester tabs are plain text buttons — journeys select them by role/name, e.g. "All semesters" / "Fall 2025") |
 | `dashboard-resume-{sessionId}` | a "Where you left off" card — deep-links to `/learn?resume={sessionId}` (#164), suffixed with the session's own id per the stable-domain-id rule |
 
+`dashboard-review-due` also lives in `screens/Dashboard.tsx`; it is documented
+with the `quiz` surface it links into.
+
 ### `calendar`
 
 Added with the #185 load-failure fix (a failed initial fetch must be
@@ -300,6 +376,7 @@ inside the `role="grid"` "Courses" grid.
 | testid | element |
 | --- | --- |
 | `gradebook-term-gpa` | landing: the selected term's credit-weighted GPA next to the chips (absent while the term has no graded work) |
+| `gradebook-upload-syllabus` | landing: the blank-semester empty state's "Upload syllabus" CTA (`ui/EmptyState` action slot) |
 | `gradebook-transcript-open` | landing: "Transcript" button opening the transcript modal |
 | `gradebook-transcript-gpa` | transcript modal: the cumulative GPA value |
 | `gradebook-transcript-retry` | transcript modal: inline "Try again" after a failed load (#463 catch+toast pattern) |

.github/workflows/e2e.yml

@@ -83,6 +83,12 @@ jobs:
  # Dummy on purpose: the below-seam RAG embed path (#439) must not
  # be able to bill; its failures are swallowed by design.
  GEMINI_API_KEY: e2e-dummy-key-no-billing
+ # #537: the quiz-generation guard keeps its sliding window in a
+ # process-local dict, so ONE Playwright run shares a single
+ # 8-per-300s budget across every spec and the quiz specs that run
+ # last 429. e2e-up.sh sets the same value; kept here so what the
+ # lane actually runs under is visible beside the rest of the seam.
+ QUIZ_GENERATE_RATE_LIMIT: "1000"
  run: make e2e-up
 
  - name: Run Playwright suite

backend/.env.example

@@ -69,3 +69,12 @@ GEMINI_VISION_OCR_ENABLED=false
 GEMINI_VISION_OCR_MAX_PAGES=10
 # The transcription model is the ADR-0008 per-task slot, not a knob of its own:
 # SAPLING_MODEL_OCR_VISION=gemini-2.5-flash
+
+# Quiz generation abuse guard (#544 F1; env-overridable since #537). The window
+# lives in a process-local dict, so ONE Playwright run spends a single budget
+# across every spec — the E2E lanes raise this; production keeps the default.
+# Unparseable or non-positive values fall back to the default.
+# QUIZ_GENERATE_RATE_LIMIT=8
+# Sliding-window length for that limit, in seconds. E2E lanes raise the limit
+# rather than shrink the window; production keeps the default.
+# QUIZ_GENERATE_RATE_WINDOW_SEC=300

backend/services/quiz_config.py

@@ -9,6 +9,41 @@
 Standalone constants module: no imports from models/routes/services so
 it can be imported from anywhere without cycles.
 """
+import logging
+import os
+
+logger = logging.getLogger(__name__)
+
+
+def _positive_int_env(name: str, default: int) -> int:
+ """A deployment override for one guard constant, read at import.
+
+ Deliberately fail-SAFE rather than fail-fast: an unparseable or
+ non-positive value falls back to the shipped default (the conservative
+ one) with a warning, so a stray env var cannot boot the app with a
+ disabled guard — or refuse to boot at all. Read once at import time,
+ which is also when `routes/quiz.py` binds the value, so a mid-process
+ `os.environ` change has no effect.
+ """
+ raw = os.getenv(name)
+ if raw is None or not raw.strip():
+ return default
+ try:
+ value = int(raw.strip())
+ except ValueError:
+ logger.warning(
+ "quiz_config: %s=%r is not an integer — using the default %d",
+ name, raw, default,
+ )
+ return default
+ if value <= 0:
+ logger.warning(
+ "quiz_config: %s=%d is not positive — using the default %d",
+ name, value, default,
+ )
+ return default
+ return value
+
 
 QUIZ_MIN_QUESTIONS = 1
 
@@ -87,8 +122,18 @@ def mastery_after(before: float, *, score: int, total: int) -> float:
 # The rate limit is sized for a human: a student comparing difficulties or
 # retaking a concept might legitimately generate a handful of quizzes in a
 # few minutes; nobody legitimately generates 10 in one.
-QUIZ_GENERATE_RATE_LIMIT = 8
-QUIZ_GENERATE_RATE_WINDOW_SEC = 300 # 5 minutes
+#
+# Both are env-overridable (#537) for one reason: `request_limits._rate_state`
+# is a module-level dict, so a whole Playwright run — every spec, every
+# worker-shared window — spends ONE 8-per-300s budget that only a backend
+# restart clears. The redesigned quiz lane needs ~20 real generations, and a
+# function-mode generation costs nothing, so the E2E stacks raise the limit
+# (scripts/e2e-up.sh, .github/workflows/e2e.yml). Production sets neither and
+# keeps the defaults below.
+QUIZ_GENERATE_RATE_LIMIT = _positive_int_env("QUIZ_GENERATE_RATE_LIMIT", 8)
+QUIZ_GENERATE_RATE_WINDOW_SEC = _positive_int_env(
+ "QUIZ_GENERATE_RATE_WINDOW_SEC", 300, # 5 minutes
+)
 
 # Daily per-user LLM spend ceiling. The SPEND it measures is cross-feature
 # (llm_usage records every agent call, not just quiz ones), but the ceiling

backend/tests/test_quiz_cost_observability_f.py

@@ -132,6 +132,87 @@ def test_limit_is_per_user(self):
  assert other.status_code == 200
 
 
+class TestGenerateRateLimitIsEnvOverridable:
+ """#537: the two guard constants read the environment; defaults intact.
+
+ `request_limits._rate_state` is module-level, so a whole Playwright run
+ shares ONE window that only a backend restart clears — and the redesigned
+ quiz lane needs more generations than any human would. The E2E stacks
+ raise the limit through the environment; production sets nothing and must
+ keep the shipped defaults.
+ """
+
+ @staticmethod
+ def _reloaded():
+ """Re-import services.quiz_config against the current environment.
+
+ `importlib.reload` mutates the module in place, so every caller must
+ restore it (see `_restore`) or later tests inherit the override.
+ """
+ import importlib
+
+ from services import quiz_config
+
+ return importlib.reload(quiz_config)
+
+ @classmethod
+ def _restore(cls):
+ cls._reloaded()
+
+ def test_defaults_hold_when_unset(self, monkeypatch):
+ monkeypatch.delenv("QUIZ_GENERATE_RATE_LIMIT", raising=False)
+ monkeypatch.delenv("QUIZ_GENERATE_RATE_WINDOW_SEC", raising=False)
+ try:
+ cfg = self._reloaded()
+ assert cfg.QUIZ_GENERATE_RATE_LIMIT == 8
+ assert cfg.QUIZ_GENERATE_RATE_WINDOW_SEC == 300
+ finally:
+ monkeypatch.undo()
+ self._restore()
+
+ def test_an_override_is_honoured(self, monkeypatch):
+ monkeypatch.setenv("QUIZ_GENERATE_RATE_LIMIT", "1000")
+ monkeypatch.setenv("QUIZ_GENERATE_RATE_WINDOW_SEC", "60")
+ try:
+ cfg = self._reloaded()
+ assert cfg.QUIZ_GENERATE_RATE_LIMIT == 1000
+ assert cfg.QUIZ_GENERATE_RATE_WINDOW_SEC == 60
+ finally:
+ monkeypatch.undo()
+ self._restore()
+
+ def test_a_junk_override_falls_back_to_the_default(self, monkeypatch):
+ """Fail-safe, not fail-fast: a stray value must neither disable the
+ guard (limit=0 would 429 everyone, a negative window never expires)
+ nor stop the app from booting."""
+ for bad in ("", " ", "eight", "0", "-5", "3.5"):
+ monkeypatch.setenv("QUIZ_GENERATE_RATE_LIMIT", bad)
+ monkeypatch.setenv("QUIZ_GENERATE_RATE_WINDOW_SEC", bad)
+ try:
+ cfg = self._reloaded()
+ assert cfg.QUIZ_GENERATE_RATE_LIMIT == 8, bad
+ assert cfg.QUIZ_GENERATE_RATE_WINDOW_SEC == 300, bad
+ finally:
+ monkeypatch.undo()
+ self._restore()
+
+ def test_the_route_still_enforces_whatever_was_resolved(self):
+ """The env seam moves the NUMBER, never the behaviour: the route binds
+ the value at its own import and still 429s one call past it."""
+ from routes import quiz as quiz_route
+ from services.quiz_config import QUIZ_GENERATE_RATE_LIMIT
+
+ assert quiz_route.QUIZ_GENERATE_RATE_LIMIT == QUIZ_GENERATE_RATE_LIMIT
+ run = AsyncMock(return_value=SimpleNamespace(output=_quiz()))
+ with (
+ patch("routes.quiz.table", side_effect=_factory()),
+ patch("routes.quiz.quiz_agent.run", new=run),
+ ):
+ for _ in range(quiz_route.QUIZ_GENERATE_RATE_LIMIT):
+ assert _generate().status_code == 200
+ assert _generate().status_code == 429
+
+
 class TestDailySpendGuard:
  def test_over_budget_user_is_refused_before_the_model_runs(self):
  from services.quiz_config import QUIZ_DAILY_SPEND_CAP_USD

docs/e2e-exploration.md

@@ -226,7 +226,10 @@ byte-for-byte match to one of `function_handlers_e2e.py`'s `E2E_DOC_*` (or
 `E2E_TUTOR_REPLY`, `E2E_QUIZ_*`) constants — here, `E2E_DOC_ABSTRACT`'s
 "gradient descent... loss surface... learning rate" wording and the fixed
 `lecture_notes` category. If a finding's "wrong" content matches one of
-those constants verbatim, it's the seam, not the app — drop it, and if it
+those constants verbatim, it's the seam, not the app (likewise the quiz's
+"Only 3 questions were ready for this concept" toast: the function-mode quiz handler always
+returns exactly 3 questions, so any requested length above 3 is reported as a short delivery —
+the honesty check working, not a generation bug) — drop it, and if it
 recurs, improve `scripts/explore/explorer-prompt.md`'s ground rules to name
 the pattern explicitly so a future explorer recognizes it before writing the
 stub, rather than filing an issue against the harness's own known-fixed

docs/frontend-testids.md

@@ -71,7 +71,7 @@ renders the element.
 | Onboarding | `onboarding` | `frontend/src/components/screens/Onboarding.tsx` (the first-run funnel, rendered bare outside `(shell)`) |
 | Upload modal | `upload-modal` | `frontend/src/components/DocumentUploadModal.tsx` |
 | Tutor | `tutor` | `frontend/src/components/chat/ChatPanel.tsx` (rendered by `screens/Learn.tsx`; + the session-resume rows in `src/components/screens/Learn.tsx` itself) |
-| Quiz | `quiz` | `frontend/src/components/QuizPanel.tsx` (rendered by `screens/Quiz.tsx`) |
+| Quiz | `quiz` | `frontend/src/components/quiz/**` — `QuizScreen.tsx` (route root + error card) switching on phase between `home/QuizHome.tsx` (+ `ConceptDialog`/`AdjustDialog`/`PickList`/`QuizSettings`), `question/QuizQuestion.tsx` (+ `AskPanel`/`LeaveDialog`) and `results/QuizResults.tsx` (+ `MissedList`); the ids on the shared `ui/` primitives and `graph/ConceptNeighbourhood.tsx` are passed in from those files as a `testid` prop (#537) |
 | Knowledge graph | `graph` | `frontend/src/components/graph/KnowledgeGraph.tsx` (wrapper: container root + mode toggle) plus `KnowledgeGraph2D.tsx`/`KnowledgeGraph3D.tsx` (the render/data-layer seam — hidden a11y node list, SVG node/edge marks, zoom controls — added with the #395 graph-integrity journey) |
 | App shell | `app` | `frontend/src/components/ShellFrame.tsx` (the authed layout frame every `(shell)` route renders inside) |
 | Study rooms | `social` | `frontend/src/components/screens/Social.tsx` (rooms sidebar, chat, overview, study match, directory — added with the #394 two-context journey) |
@@ -95,8 +95,16 @@ route:
  and the send `<button>` render in `ChatPanel.tsx`. `ChatPanel` has exactly one
  consumer (Learn), so tagging it there is unambiguous. The notetaker's chat is
  a separate `AIChatPanel` and is out of scope.
-- **Quiz.** `screens/Quiz.tsx` only fetches concepts and mounts `QuizPanel`;
- every answer/submit control renders in `QuizPanel.tsx`.
+- **Quiz.** The route mounts one component, `components/quiz/QuizScreen.tsx`,
+ which switches on phase between `home/QuizHome.tsx`,
+ `question/QuizQuestion.tsx` and `results/QuizResults.tsx`; each of the three
+ owns its own ids and its own dialogs. Three shared `ui/` primitives
+ (`AnswerOption`, `SegmentedControl`, `Sheet`) are in the eslint file list too:
+ the controls render inside them, so a testid-less `<button>` there would
+ un-anchor the surface from outside the screen files. Those primitives — plus
+ `ui/EmptyState`, `ui/InlineBanner`, `ui/ProgressDots` and
+ `graph/ConceptNeighbourhood` — take the id as a `testid` prop, so the value is
+ always written at the quiz call site, never inside the primitive.
 
 ## Current inventory
 
@@ -174,22 +182,87 @@ route:
 
 ### `quiz`
 
+The quiz is one surface: `components/quiz/QuizScreen.tsx` reads the entry off
+the URL and switches on phase between `home/QuizHome.tsx`,
+`question/QuizQuestion.tsx` and `results/QuizResults.tsx`. The table is grouped
+in that order; the screen-level ids (the error card) come last, followed by the
+entry points the quiz wave added inside other surfaces' files.
+
+Three ids are **renamed** from the pre-#537 quiz — same role, clearer name:
+`quiz-exit` → `quiz-leave`, `quiz-retake` → `quiz-again`,
+`quiz-explain-concept` → `quiz-ask`. Eleven are **kept** verbatim so existing
+journeys keep anchoring: `quiz-panel`, `quiz-start`, `quiz-cancel`,
+`quiz-answer-options`, `quiz-answer-option-{label}`, `quiz-submit-answer`,
+`quiz-next`, `quiz-review-verdict`, `quiz-results-score`,
+`quiz-results-mastery`, `quiz-done`.
+
 | testid | element |
 | --- | --- |
-| `quiz-panel` | panel root (all phases) |
-| `quiz-cancel` | "Cancel" (select phase) |
-| `quiz-start` | "Start quiz" |
+| `quiz-home` | quiz-home root (`phase: home \| configuring`) |
+| `quiz-resume-strip` | the "you left a quiz on X" banner (`ui/InlineBanner`) |
+| `quiz-resume` | "Resume" on that banner |
+| `quiz-resume-discard` | "Discard" — hides the attempt client-side; there is no abandon endpoint |
+| `quiz-proposal` | the "Ready for you" primary proposal card |
+| `quiz-start` | "Start" on that card |
+| `quiz-cancel` | "Cancel" — leaves for the entry source, or `/dashboard` when there is none |
+| `quiz-adjust` | "adjust" on the card — toggles the adjust dialog (`aria-pressed`) |
+| `quiz-alternative-{nodeId}` | one "Also worth a look" row |
+| `quiz-review-due` | "Review everything due" row |
+| `quiz-pick-open` | "Pick something specific →" |
+| `quiz-pick-list` | the grouped concept list it reveals |
+| `quiz-pick-{nodeId}` | one concept row in that list |
+| `quiz-pick-back` | "← Back" out of that list |
+| `quiz-empty-state` | the home's empty states (`ui/EmptyState`) — no courses, empty tree, or nothing left to propose; they are alternatives, so only one ever mounts |
+| `quiz-home-error` | the home's load-failure card |
+| `quiz-home-retry` | "Retry" inside it |
+| `quiz-concept-dialog` | the concept dialog opened from an alternative or a pick row |
+| `quiz-concept-start` | "Start · {count} {difficulty}" inside it |
+| `quiz-concept-cancel` | its "Cancel" |
+| `quiz-adjust-dialog` | "Adjust this quiz" dialog |
+| `quiz-adjust-done` | its "Done" — keeps the settings without starting |
+| `quiz-adjust-start` | its "Start · {count} {difficulty}" — saves and starts in one |
+| `quiz-seg-count` / `quiz-seg-difficulty` / `quiz-seg-feedback` | the three `ui/SegmentedControl`s both dialogs share; each option is `${testid}-${value}` |
+| `quiz-generating` | the skeleton question screen while a quiz is being written |
+| `quiz-panel` | question root (`phase: active \| answered`) |
+| `quiz-progress` | the question rail's progress dots (`ui/ProgressDots`) |
 | `quiz-answer-options` | answer radiogroup |
-| `quiz-answer-option-{label}` | one answer choice, suffixed with its label (`A`…) |
-| `quiz-submit-answer` | "Submit answer" |
-| `quiz-exit` | "Exit" (active phase) |
+| `quiz-answer-option-{label}` | one answer choice (`ui/AnswerOption`), suffixed with its label (`A`…) |
+| `quiz-submit-answer` | the footer's primary button while the answer is unrevealed |
+| `quiz-next` | the same footer button once the verdict is showing — "Next question" / "See results" |
 | `quiz-review-verdict` | "Correct." / "Not quite." banner |
-| `quiz-explain-concept` | "Explain this" |
-| `quiz-next` | "Next question" / "See results" |
-| `quiz-results-score` | the score percentage |
-| `quiz-results-mastery` | the "X / Y correct · mastery B% → A%" line |
-| `quiz-retake` | "Retake" |
-| `quiz-done` | "Done" |
+| `quiz-flag` | "This question is confusing" (toggles, `aria-pressed`; persists nothing) |
+| `quiz-ask` | "Ask about this" — opens the tutor sheet |
+| `quiz-leave` | "Leave" |
+| `quiz-leave-dialog` / `quiz-leave-cancel` / `quiz-leave-confirm` | the leave confirmation |
+| `quiz-ask-panel` | the tutor sheet (`ui/Sheet`) |
+| `quiz-ask-panel-close` | its × — the `Sheet` derives it as `${testid}-close` |
+| `quiz-ask-seed` | the composed first message shown at the top of the sheet |
+| `quiz-ask-retry` | "Try again" when the tutor stream failed |
+| `quiz-ask-input` / `quiz-ask-send` | the sheet's composer |
+| `quiz-results` | results root |
+| `quiz-results-graph` | the concept neighbourhood above the score (`graph/ConceptNeighbourhood`) |
+| `quiz-results-score` | the "{n} of {total} correct" line — a count, not a percentage |
+| `quiz-results-mastery` | the mastery delta line, "B% → A% · tier-before → tier-after" |
+| `quiz-results-xp` | "+{Δ} XP · {streak}-day streak" — absent when either gamification read failed |
+| `quiz-results-perfect` | the line shown instead of the missed list on a clean sweep |
+| `quiz-missed-list` | the "to look at" section |
+| `quiz-missed-{questionId}` | one missed item |
+| `quiz-missed-explain-{questionId}` | its "Show explanation" disclosure |
+| `quiz-missed-ask-{questionId}` | its "Ask about this" |
+| `quiz-practise-missed` | "Practise the one(s) you missed" |
+| `quiz-next-concept` | "Next: {concept} →" while the scope queue has more |
+| `quiz-again` | "Keep going — quiz again" (mounts in `quiz-practise-missed`'s place on a clean sweep) |
+| `quiz-back-to-source` | the secondary exit, labelled by where the quiz was entered from |
+| `quiz-done` | "Done" — back to `/quiz` |
+| `quiz-error` | the route-level error card (mapped copy + retry/back), rendered by `QuizScreen` in place of the phase |
+| `quiz-error-retry` / `quiz-error-back` | its "Try again" and "Back" |
+| `tree-node-recent-quizzes` | the tree node panel's "Recent quizzes" block (`screens/Tree.tsx`) |
+| `tree-node-recent-quiz-{attemptId}` | one row in it, suffixed with the attempt's `quiz_id` per the stable-domain-id rule |
+| `dashboard-review-due` | the "Review what's due" quiz entry point (`screens/Dashboard.tsx`) — three call sites, but exactly one mounts for a given layout/viewport |
+
+The last three carry another surface's prefix because they render in that
+surface's file. They are listed here because they are quiz entry points, and a
+quiz journey is what drives them.
 
 ### `graph`
 
@@ -279,6 +352,9 @@ never collide in the DOM.
 | `dashboard-courses-manage` | the cog inside the expanded key that opens the Courses & Semesters hub (the hub's own semester tabs are plain text buttons — journeys select them by role/name, e.g. "All semesters" / "Fall 2025") |
 | `dashboard-resume-{sessionId}` | a "Where you left off" card — deep-links to `/learn?resume={sessionId}` (#164), suffixed with the session's own id per the stable-domain-id rule |
 
+`dashboard-review-due` also lives in `screens/Dashboard.tsx`; it is documented
+with the `quiz` surface it links into.
+
 ### `calendar`
 
 Added with the #185 load-failure fix (a failed initial fetch must be
@@ -300,6 +376,7 @@ inside the `role="grid"` "Courses" grid.
 | testid | element |
 | --- | --- |
 | `gradebook-term-gpa` | landing: the selected term's credit-weighted GPA next to the chips (absent while the term has no graded work) |
+| `gradebook-upload-syllabus` | landing: the blank-semester empty state's "Upload syllabus" CTA (`ui/EmptyState` action slot) |
 | `gradebook-transcript-open` | landing: "Transcript" button opening the transcript modal |
 | `gradebook-transcript-gpa` | transcript modal: the cumulative GPA value |
 | `gradebook-transcript-retry` | transcript modal: inline "Try again" after a failed load (#463 catch+toast pattern) |

.github/workflows/e2e.yml

@@ -83,6 +83,12 @@ jobs:
  # Dummy on purpose: the below-seam RAG embed path (#439) must not
  # be able to bill; its failures are swallowed by design.
  GEMINI_API_KEY: e2e-dummy-key-no-billing
+ # #537: the quiz-generation guard keeps its sliding window in a
+ # process-local dict, so ONE Playwright run shares a single
+ # 8-per-300s budget across every spec and the quiz specs that run
+ # last 429. e2e-up.sh sets the same value; kept here so what the
+ # lane actually runs under is visible beside the rest of the seam.
+ QUIZ_GENERATE_RATE_LIMIT: "1000"
  run: make e2e-up
 
  - name: Run Playwright suite

backend/.env.example

@@ -69,3 +69,12 @@ GEMINI_VISION_OCR_ENABLED=false
 GEMINI_VISION_OCR_MAX_PAGES=10
 # The transcription model is the ADR-0008 per-task slot, not a knob of its own:
 # SAPLING_MODEL_OCR_VISION=gemini-2.5-flash
+
+# Quiz generation abuse guard (#544 F1; env-overridable since #537). The window
+# lives in a process-local dict, so ONE Playwright run spends a single budget
+# across every spec — the E2E lanes raise this; production keeps the default.
+# Unparseable or non-positive values fall back to the default.
+# QUIZ_GENERATE_RATE_LIMIT=8
+# Sliding-window length for that limit, in seconds. E2E lanes raise the limit
+# rather than shrink the window; production keeps the default.
+# QUIZ_GENERATE_RATE_WINDOW_SEC=300

backend/services/quiz_config.py

@@ -9,6 +9,41 @@
 Standalone constants module: no imports from models/routes/services so
 it can be imported from anywhere without cycles.
 """
+import logging
+import os
+
+logger = logging.getLogger(__name__)
+
+
+def _positive_int_env(name: str, default: int) -> int:
+ """A deployment override for one guard constant, read at import.
+
+ Deliberately fail-SAFE rather than fail-fast: an unparseable or
+ non-positive value falls back to the shipped default (the conservative
+ one) with a warning, so a stray env var cannot boot the app with a
+ disabled guard — or refuse to boot at all. Read once at import time,
+ which is also when `routes/quiz.py` binds the value, so a mid-process
+ `os.environ` change has no effect.
+ """
+ raw = os.getenv(name)
+ if raw is None or not raw.strip():
+ return default
+ try:
+ value = int(raw.strip())
+ except ValueError:
+ logger.warning(
+ "quiz_config: %s=%r is not an integer — using the default %d",
+ name, raw, default,
+ )
+ return default
+ if value <= 0:
+ logger.warning(
+ "quiz_config: %s=%d is not positive — using the default %d",
+ name, value, default,
+ )
+ return default
+ return value
+
 
 QUIZ_MIN_QUESTIONS = 1
 
@@ -87,8 +122,18 @@ def mastery_after(before: float, *, score: int, total: int) -> float:
 # The rate limit is sized for a human: a student comparing difficulties or
 # retaking a concept might legitimately generate a handful of quizzes in a
 # few minutes; nobody legitimately generates 10 in one.
-QUIZ_GENERATE_RATE_LIMIT = 8
-QUIZ_GENERATE_RATE_WINDOW_SEC = 300 # 5 minutes
+#
+# Both are env-overridable (#537) for one reason: `request_limits._rate_state`
+# is a module-level dict, so a whole Playwright run — every spec, every
+# worker-shared window — spends ONE 8-per-300s budget that only a backend
+# restart clears. The redesigned quiz lane needs ~20 real generations, and a
+# function-mode generation costs nothing, so the E2E stacks raise the limit
+# (scripts/e2e-up.sh, .github/workflows/e2e.yml). Production sets neither and
+# keeps the defaults below.
+QUIZ_GENERATE_RATE_LIMIT = _positive_int_env("QUIZ_GENERATE_RATE_LIMIT", 8)
+QUIZ_GENERATE_RATE_WINDOW_SEC = _positive_int_env(
+ "QUIZ_GENERATE_RATE_WINDOW_SEC", 300, # 5 minutes
+)
 
 # Daily per-user LLM spend ceiling. The SPEND it measures is cross-feature
 # (llm_usage records every agent call, not just quiz ones), but the ceiling

backend/tests/test_quiz_cost_observability_f.py

@@ -132,6 +132,87 @@ def test_limit_is_per_user(self):
  assert other.status_code == 200
 
 
+class TestGenerateRateLimitIsEnvOverridable:
+ """#537: the two guard constants read the environment; defaults intact.
+
+ `request_limits._rate_state` is module-level, so a whole Playwright run
+ shares ONE window that only a backend restart clears — and the redesigned
+ quiz lane needs more generations than any human would. The E2E stacks
+ raise the limit through the environment; production sets nothing and must
+ keep the shipped defaults.
+ """
+
+ @staticmethod
+ def _reloaded():
+ """Re-import services.quiz_config against the current environment.
+
+ `importlib.reload` mutates the module in place, so every caller must
+ restore it (see `_restore`) or later tests inherit the override.
+ """
+ import importlib
+
+ from services import quiz_config
+
+ return importlib.reload(quiz_config)
+
+ @classmethod
+ def _restore(cls):
+ cls._reloaded()
+
+ def test_defaults_hold_when_unset(self, monkeypatch):
+ monkeypatch.delenv("QUIZ_GENERATE_RATE_LIMIT", raising=False)
+ monkeypatch.delenv("QUIZ_GENERATE_RATE_WINDOW_SEC", raising=False)
+ try:
+ cfg = self._reloaded()
+ assert cfg.QUIZ_GENERATE_RATE_LIMIT == 8
+ assert cfg.QUIZ_GENERATE_RATE_WINDOW_SEC == 300
+ finally:
+ monkeypatch.undo()
+ self._restore()
+
+ def test_an_override_is_honoured(self, monkeypatch):
+ monkeypatch.setenv("QUIZ_GENERATE_RATE_LIMIT", "1000")
+ monkeypatch.setenv("QUIZ_GENERATE_RATE_WINDOW_SEC", "60")
+ try:
+ cfg = self._reloaded()
+ assert cfg.QUIZ_GENERATE_RATE_LIMIT == 1000
+ assert cfg.QUIZ_GENERATE_RATE_WINDOW_SEC == 60
+ finally:
+ monkeypatch.undo()
+ self._restore()
+
+ def test_a_junk_override_falls_back_to_the_default(self, monkeypatch):
+ """Fail-safe, not fail-fast: a stray value must neither disable the
+ guard (limit=0 would 429 everyone, a negative window never expires)
+ nor stop the app from booting."""
+ for bad in ("", " ", "eight", "0", "-5", "3.5"):
+ monkeypatch.setenv("QUIZ_GENERATE_RATE_LIMIT", bad)
+ monkeypatch.setenv("QUIZ_GENERATE_RATE_WINDOW_SEC", bad)
+ try:
+ cfg = self._reloaded()
+ assert cfg.QUIZ_GENERATE_RATE_LIMIT == 8, bad
+ assert cfg.QUIZ_GENERATE_RATE_WINDOW_SEC == 300, bad
+ finally:
+ monkeypatch.undo()
+ self._restore()
+
+ def test_the_route_still_enforces_whatever_was_resolved(self):
+ """The env seam moves the NUMBER, never the behaviour: the route binds
+ the value at its own import and still 429s one call past it."""
+ from routes import quiz as quiz_route
+ from services.quiz_config import QUIZ_GENERATE_RATE_LIMIT
+
+ assert quiz_route.QUIZ_GENERATE_RATE_LIMIT == QUIZ_GENERATE_RATE_LIMIT
+ run = AsyncMock(return_value=SimpleNamespace(output=_quiz()))
+ with (
+ patch("routes.quiz.table", side_effect=_factory()),
+ patch("routes.quiz.quiz_agent.run", new=run),
+ ):
+ for _ in range(quiz_route.QUIZ_GENERATE_RATE_LIMIT):
+ assert _generate().status_code == 200
+ assert _generate().status_code == 429
+
+
 class TestDailySpendGuard:
  def test_over_budget_user_is_refused_before_the_model_runs(self):
  from services.quiz_config import QUIZ_DAILY_SPEND_CAP_USD

docs/e2e-exploration.md

@@ -226,7 +226,10 @@ byte-for-byte match to one of `function_handlers_e2e.py`'s `E2E_DOC_*` (or
 `E2E_TUTOR_REPLY`, `E2E_QUIZ_*`) constants — here, `E2E_DOC_ABSTRACT`'s
 "gradient descent... loss surface... learning rate" wording and the fixed
 `lecture_notes` category. If a finding's "wrong" content matches one of
-those constants verbatim, it's the seam, not the app — drop it, and if it
+those constants verbatim, it's the seam, not the app (likewise the quiz's
+"Only 3 questions were ready for this concept" toast: the function-mode quiz handler always
+returns exactly 3 questions, so any requested length above 3 is reported as a short delivery —
+the honesty check working, not a generation bug) — drop it, and if it
 recurs, improve `scripts/explore/explorer-prompt.md`'s ground rules to name
 the pattern explicitly so a future explorer recognizes it before writing the
 stub, rather than filing an issue against the harness's own known-fixed

docs/frontend-testids.md

@@ -71,7 +71,7 @@ renders the element.
 | Onboarding | `onboarding` | `frontend/src/components/screens/Onboarding.tsx` (the first-run funnel, rendered bare outside `(shell)`) |
 | Upload modal | `upload-modal` | `frontend/src/components/DocumentUploadModal.tsx` |
 | Tutor | `tutor` | `frontend/src/components/chat/ChatPanel.tsx` (rendered by `screens/Learn.tsx`; + the session-resume rows in `src/components/screens/Learn.tsx` itself) |
-| Quiz | `quiz` | `frontend/src/components/QuizPanel.tsx` (rendered by `screens/Quiz.tsx`) |
+| Quiz | `quiz` | `frontend/src/components/quiz/**` — `QuizScreen.tsx` (route root + error card) switching on phase between `home/QuizHome.tsx` (+ `ConceptDialog`/`AdjustDialog`/`PickList`/`QuizSettings`), `question/QuizQuestion.tsx` (+ `AskPanel`/`LeaveDialog`) and `results/QuizResults.tsx` (+ `MissedList`); the ids on the shared `ui/` primitives and `graph/ConceptNeighbourhood.tsx` are passed in from those files as a `testid` prop (#537) |
 | Knowledge graph | `graph` | `frontend/src/components/graph/KnowledgeGraph.tsx` (wrapper: container root + mode toggle) plus `KnowledgeGraph2D.tsx`/`KnowledgeGraph3D.tsx` (the render/data-layer seam — hidden a11y node list, SVG node/edge marks, zoom controls — added with the #395 graph-integrity journey) |
 | App shell | `app` | `frontend/src/components/ShellFrame.tsx` (the authed layout frame every `(shell)` route renders inside) |
 | Study rooms | `social` | `frontend/src/components/screens/Social.tsx` (rooms sidebar, chat, overview, study match, directory — added with the #394 two-context journey) |
@@ -95,8 +95,16 @@ route:
  and the send `<button>` render in `ChatPanel.tsx`. `ChatPanel` has exactly one
  consumer (Learn), so tagging it there is unambiguous. The notetaker's chat is
  a separate `AIChatPanel` and is out of scope.
-- **Quiz.** `screens/Quiz.tsx` only fetches concepts and mounts `QuizPanel`;
- every answer/submit control renders in `QuizPanel.tsx`.
+- **Quiz.** The route mounts one component, `components/quiz/QuizScreen.tsx`,
+ which switches on phase between `home/QuizHome.tsx`,
+ `question/QuizQuestion.tsx` and `results/QuizResults.tsx`; each of the three
+ owns its own ids and its own dialogs. Three shared `ui/` primitives
+ (`AnswerOption`, `SegmentedControl`, `Sheet`) are in the eslint file list too:
+ the controls render inside them, so a testid-less `<button>` there would
+ un-anchor the surface from outside the screen files. Those primitives — plus
+ `ui/EmptyState`, `ui/InlineBanner`, `ui/ProgressDots` and
+ `graph/ConceptNeighbourhood` — take the id as a `testid` prop, so the value is
+ always written at the quiz call site, never inside the primitive.
 
 ## Current inventory
 
@@ -174,22 +182,87 @@ route:
 
 ### `quiz`
 
+The quiz is one surface: `components/quiz/QuizScreen.tsx` reads the entry off
+the URL and switches on phase between `home/QuizHome.tsx`,
+`question/QuizQuestion.tsx` and `results/QuizResults.tsx`. The table is grouped
+in that order; the screen-level ids (the error card) come last, followed by the
+entry points the quiz wave added inside other surfaces' files.
+
+Three ids are **renamed** from the pre-#537 quiz — same role, clearer name:
+`quiz-exit` → `quiz-leave`, `quiz-retake` → `quiz-again`,
+`quiz-explain-concept` → `quiz-ask`. Eleven are **kept** verbatim so existing
+journeys keep anchoring: `quiz-panel`, `quiz-start`, `quiz-cancel`,
+`quiz-answer-options`, `quiz-answer-option-{label}`, `quiz-submit-answer`,
+`quiz-next`, `quiz-review-verdict`, `quiz-results-score`,
+`quiz-results-mastery`, `quiz-done`.
+
 | testid | element |
 | --- | --- |
-| `quiz-panel` | panel root (all phases) |
-| `quiz-cancel` | "Cancel" (select phase) |
-| `quiz-start` | "Start quiz" |
+| `quiz-home` | quiz-home root (`phase: home \| configuring`) |
+| `quiz-resume-strip` | the "you left a quiz on X" banner (`ui/InlineBanner`) |
+| `quiz-resume` | "Resume" on that banner |
+| `quiz-resume-discard` | "Discard" — hides the attempt client-side; there is no abandon endpoint |
+| `quiz-proposal` | the "Ready for you" primary proposal card |
+| `quiz-start` | "Start" on that card |
+| `quiz-cancel` | "Cancel" — leaves for the entry source, or `/dashboard` when there is none |
+| `quiz-adjust` | "adjust" on the card — toggles the adjust dialog (`aria-pressed`) |
+| `quiz-alternative-{nodeId}` | one "Also worth a look" row |
+| `quiz-review-due` | "Review everything due" row |
+| `quiz-pick-open` | "Pick something specific →" |
+| `quiz-pick-list` | the grouped concept list it reveals |
+| `quiz-pick-{nodeId}` | one concept row in that list |
+| `quiz-pick-back` | "← Back" out of that list |
+| `quiz-empty-state` | the home's empty states (`ui/EmptyState`) — no courses, empty tree, or nothing left to propose; they are alternatives, so only one ever mounts |
+| `quiz-home-error` | the home's load-failure card |
+| `quiz-home-retry` | "Retry" inside it |
+| `quiz-concept-dialog` | the concept dialog opened from an alternative or a pick row |
+| `quiz-concept-start` | "Start · {count} {difficulty}" inside it |
+| `quiz-concept-cancel` | its "Cancel" |
+| `quiz-adjust-dialog` | "Adjust this quiz" dialog |
+| `quiz-adjust-done` | its "Done" — keeps the settings without starting |
+| `quiz-adjust-start` | its "Start · {count} {difficulty}" — saves and starts in one |
+| `quiz-seg-count` / `quiz-seg-difficulty` / `quiz-seg-feedback` | the three `ui/SegmentedControl`s both dialogs share; each option is `${testid}-${value}` |
+| `quiz-generating` | the skeleton question screen while a quiz is being written |
+| `quiz-panel` | question root (`phase: active \| answered`) |
+| `quiz-progress` | the question rail's progress dots (`ui/ProgressDots`) |
 | `quiz-answer-options` | answer radiogroup |
-| `quiz-answer-option-{label}` | one answer choice, suffixed with its label (`A`…) |
-| `quiz-submit-answer` | "Submit answer" |
-| `quiz-exit` | "Exit" (active phase) |
+| `quiz-answer-option-{label}` | one answer choice (`ui/AnswerOption`), suffixed with its label (`A`…) |
+| `quiz-submit-answer` | the footer's primary button while the answer is unrevealed |
+| `quiz-next` | the same footer button once the verdict is showing — "Next question" / "See results" |
 | `quiz-review-verdict` | "Correct." / "Not quite." banner |
-| `quiz-explain-concept` | "Explain this" |
-| `quiz-next` | "Next question" / "See results" |
-| `quiz-results-score` | the score percentage |
-| `quiz-results-mastery` | the "X / Y correct · mastery B% → A%" line |
-| `quiz-retake` | "Retake" |
-| `quiz-done` | "Done" |
+| `quiz-flag` | "This question is confusing" (toggles, `aria-pressed`; persists nothing) |
+| `quiz-ask` | "Ask about this" — opens the tutor sheet |
+| `quiz-leave` | "Leave" |
+| `quiz-leave-dialog` / `quiz-leave-cancel` / `quiz-leave-confirm` | the leave confirmation |
+| `quiz-ask-panel` | the tutor sheet (`ui/Sheet`) |
+| `quiz-ask-panel-close` | its × — the `Sheet` derives it as `${testid}-close` |
+| `quiz-ask-seed` | the composed first message shown at the top of the sheet |
+| `quiz-ask-retry` | "Try again" when the tutor stream failed |
+| `quiz-ask-input` / `quiz-ask-send` | the sheet's composer |
+| `quiz-results` | results root |
+| `quiz-results-graph` | the concept neighbourhood above the score (`graph/ConceptNeighbourhood`) |
+| `quiz-results-score` | the "{n} of {total} correct" line — a count, not a percentage |
+| `quiz-results-mastery` | the mastery delta line, "B% → A% · tier-before → tier-after" |
+| `quiz-results-xp` | "+{Δ} XP · {streak}-day streak" — absent when either gamification read failed |
+| `quiz-results-perfect` | the line shown instead of the missed list on a clean sweep |
+| `quiz-missed-list` | the "to look at" section |
+| `quiz-missed-{questionId}` | one missed item |
+| `quiz-missed-explain-{questionId}` | its "Show explanation" disclosure |
+| `quiz-missed-ask-{questionId}` | its "Ask about this" |
+| `quiz-practise-missed` | "Practise the one(s) you missed" |
+| `quiz-next-concept` | "Next: {concept} →" while the scope queue has more |
+| `quiz-again` | "Keep going — quiz again" (mounts in `quiz-practise-missed`'s place on a clean sweep) |
+| `quiz-back-to-source` | the secondary exit, labelled by where the quiz was entered from |
+| `quiz-done` | "Done" — back to `/quiz` |
+| `quiz-error` | the route-level error card (mapped copy + retry/back), rendered by `QuizScreen` in place of the phase |
+| `quiz-error-retry` / `quiz-error-back` | its "Try again" and "Back" |
+| `tree-node-recent-quizzes` | the tree node panel's "Recent quizzes" block (`screens/Tree.tsx`) |
+| `tree-node-recent-quiz-{attemptId}` | one row in it, suffixed with the attempt's `quiz_id` per the stable-domain-id rule |
+| `dashboard-review-due` | the "Review what's due" quiz entry point (`screens/Dashboard.tsx`) — three call sites, but exactly one mounts for a given layout/viewport |
+
+The last three carry another surface's prefix because they render in that
+surface's file. They are listed here because they are quiz entry points, and a
+quiz journey is what drives them.
 
 ### `graph`
 
@@ -279,6 +352,9 @@ never collide in the DOM.
 | `dashboard-courses-manage` | the cog inside the expanded key that opens the Courses & Semesters hub (the hub's own semester tabs are plain text buttons — journeys select them by role/name, e.g. "All semesters" / "Fall 2025") |
 | `dashboard-resume-{sessionId}` | a "Where you left off" card — deep-links to `/learn?resume={sessionId}` (#164), suffixed with the session's own id per the stable-domain-id rule |
 
+`dashboard-review-due` also lives in `screens/Dashboard.tsx`; it is documented
+with the `quiz` surface it links into.
+
 ### `calendar`
 
 Added with the #185 load-failure fix (a failed initial fetch must be
@@ -300,6 +376,7 @@ inside the `role="grid"` "Courses" grid.
 | testid | element |
 | --- | --- |
 | `gradebook-term-gpa` | landing: the selected term's credit-weighted GPA next to the chips (absent while the term has no graded work) |
+| `gradebook-upload-syllabus` | landing: the blank-semester empty state's "Upload syllabus" CTA (`ui/EmptyState` action slot) |
 | `gradebook-transcript-open` | landing: "Transcript" button opening the transcript modal |
 | `gradebook-transcript-gpa` | transcript modal: the cumulative GPA value |
 | `gradebook-transcript-retry` | transcript modal: inline "Try again" after a failed load (#463 catch+toast pattern) |

.github/workflows/e2e.yml

@@ -83,6 +83,12 @@ jobs:
  # Dummy on purpose: the below-seam RAG embed path (#439) must not
  # be able to bill; its failures are swallowed by design.
  GEMINI_API_KEY: e2e-dummy-key-no-billing
+ # #537: the quiz-generation guard keeps its sliding window in a
+ # process-local dict, so ONE Playwright run shares a single
+ # 8-per-300s budget across every spec and the quiz specs that run
+ # last 429. e2e-up.sh sets the same value; kept here so what the
+ # lane actually runs under is visible beside the rest of the seam.
+ QUIZ_GENERATE_RATE_LIMIT: "1000"
  run: make e2e-up
 
  - name: Run Playwright suite

backend/.env.example

@@ -69,3 +69,12 @@ GEMINI_VISION_OCR_ENABLED=false
 GEMINI_VISION_OCR_MAX_PAGES=10
 # The transcription model is the ADR-0008 per-task slot, not a knob of its own:
 # SAPLING_MODEL_OCR_VISION=gemini-2.5-flash
+
+# Quiz generation abuse guard (#544 F1; env-overridable since #537). The window
+# lives in a process-local dict, so ONE Playwright run spends a single budget
+# across every spec — the E2E lanes raise this; production keeps the default.
+# Unparseable or non-positive values fall back to the default.
+# QUIZ_GENERATE_RATE_LIMIT=8
+# Sliding-window length for that limit, in seconds. E2E lanes raise the limit
+# rather than shrink the window; production keeps the default.
+# QUIZ_GENERATE_RATE_WINDOW_SEC=300

backend/services/quiz_config.py

@@ -9,6 +9,41 @@
 Standalone constants module: no imports from models/routes/services so
 it can be imported from anywhere without cycles.
 """
+import logging
+import os
+
+logger = logging.getLogger(__name__)
+
+
+def _positive_int_env(name: str, default: int) -> int:
+ """A deployment override for one guard constant, read at import.
+
+ Deliberately fail-SAFE rather than fail-fast: an unparseable or
+ non-positive value falls back to the shipped default (the conservative
+ one) with a warning, so a stray env var cannot boot the app with a
+ disabled guard — or refuse to boot at all. Read once at import time,
+ which is also when `routes/quiz.py` binds the value, so a mid-process
+ `os.environ` change has no effect.
+ """
+ raw = os.getenv(name)
+ if raw is None or not raw.strip():
+ return default
+ try:
+ value = int(raw.strip())
+ except ValueError:
+ logger.warning(
+ "quiz_config: %s=%r is not an integer — using the default %d",
+ name, raw, default,
+ )
+ return default
+ if value <= 0:
+ logger.warning(
+ "quiz_config: %s=%d is not positive — using the default %d",
+ name, value, default,
+ )
+ return default
+ return value
+
 
 QUIZ_MIN_QUESTIONS = 1
 
@@ -87,8 +122,18 @@ def mastery_after(before: float, *, score: int, total: int) -> float:
 # The rate limit is sized for a human: a student comparing difficulties or
 # retaking a concept might legitimately generate a handful of quizzes in a
 # few minutes; nobody legitimately generates 10 in one.
-QUIZ_GENERATE_RATE_LIMIT = 8
-QUIZ_GENERATE_RATE_WINDOW_SEC = 300 # 5 minutes
+#
+# Both are env-overridable (#537) for one reason: `request_limits._rate_state`
+# is a module-level dict, so a whole Playwright run — every spec, every
+# worker-shared window — spends ONE 8-per-300s budget that only a backend
+# restart clears. The redesigned quiz lane needs ~20 real generations, and a
+# function-mode generation costs nothing, so the E2E stacks raise the limit
+# (scripts/e2e-up.sh, .github/workflows/e2e.yml). Production sets neither and
+# keeps the defaults below.
+QUIZ_GENERATE_RATE_LIMIT = _positive_int_env("QUIZ_GENERATE_RATE_LIMIT", 8)
+QUIZ_GENERATE_RATE_WINDOW_SEC = _positive_int_env(
+ "QUIZ_GENERATE_RATE_WINDOW_SEC", 300, # 5 minutes
+)
 
 # Daily per-user LLM spend ceiling. The SPEND it measures is cross-feature
 # (llm_usage records every agent call, not just quiz ones), but the ceiling

backend/tests/test_quiz_cost_observability_f.py

@@ -132,6 +132,87 @@ def test_limit_is_per_user(self):
  assert other.status_code == 200
 
 
+class TestGenerateRateLimitIsEnvOverridable:
+ """#537: the two guard constants read the environment; defaults intact.
+
+ `request_limits._rate_state` is module-level, so a whole Playwright run
+ shares ONE window that only a backend restart clears — and the redesigned
+ quiz lane needs more generations than any human would. The E2E stacks
+ raise the limit through the environment; production sets nothing and must
+ keep the shipped defaults.
+ """
+
+ @staticmethod
+ def _reloaded():
+ """Re-import services.quiz_config against the current environment.
+
+ `importlib.reload` mutates the module in place, so every caller must
+ restore it (see `_restore`) or later tests inherit the override.
+ """
+ import importlib
+
+ from services import quiz_config
+
+ return importlib.reload(quiz_config)
+
+ @classmethod
+ def _restore(cls):
+ cls._reloaded()
+
+ def test_defaults_hold_when_unset(self, monkeypatch):
+ monkeypatch.delenv("QUIZ_GENERATE_RATE_LIMIT", raising=False)
+ monkeypatch.delenv("QUIZ_GENERATE_RATE_WINDOW_SEC", raising=False)
+ try:
+ cfg = self._reloaded()
+ assert cfg.QUIZ_GENERATE_RATE_LIMIT == 8
+ assert cfg.QUIZ_GENERATE_RATE_WINDOW_SEC == 300
+ finally:
+ monkeypatch.undo()
+ self._restore()
+
+ def test_an_override_is_honoured(self, monkeypatch):
+ monkeypatch.setenv("QUIZ_GENERATE_RATE_LIMIT", "1000")
+ monkeypatch.setenv("QUIZ_GENERATE_RATE_WINDOW_SEC", "60")
+ try:
+ cfg = self._reloaded()
+ assert cfg.QUIZ_GENERATE_RATE_LIMIT == 1000
+ assert cfg.QUIZ_GENERATE_RATE_WINDOW_SEC == 60
+ finally:
+ monkeypatch.undo()
+ self._restore()
+
+ def test_a_junk_override_falls_back_to_the_default(self, monkeypatch):
+ """Fail-safe, not fail-fast: a stray value must neither disable the
+ guard (limit=0 would 429 everyone, a negative window never expires)
+ nor stop the app from booting."""
+ for bad in ("", " ", "eight", "0", "-5", "3.5"):
+ monkeypatch.setenv("QUIZ_GENERATE_RATE_LIMIT", bad)
+ monkeypatch.setenv("QUIZ_GENERATE_RATE_WINDOW_SEC", bad)
+ try:
+ cfg = self._reloaded()
+ assert cfg.QUIZ_GENERATE_RATE_LIMIT == 8, bad
+ assert cfg.QUIZ_GENERATE_RATE_WINDOW_SEC == 300, bad
+ finally:
+ monkeypatch.undo()
+ self._restore()
+
+ def test_the_route_still_enforces_whatever_was_resolved(self):
+ """The env seam moves the NUMBER, never the behaviour: the route binds
+ the value at its own import and still 429s one call past it."""
+ from routes import quiz as quiz_route
+ from services.quiz_config import QUIZ_GENERATE_RATE_LIMIT
+
+ assert quiz_route.QUIZ_GENERATE_RATE_LIMIT == QUIZ_GENERATE_RATE_LIMIT
+ run = AsyncMock(return_value=SimpleNamespace(output=_quiz()))
+ with (
+ patch("routes.quiz.table", side_effect=_factory()),
+ patch("routes.quiz.quiz_agent.run", new=run),
+ ):
+ for _ in range(quiz_route.QUIZ_GENERATE_RATE_LIMIT):
+ assert _generate().status_code == 200
+ assert _generate().status_code == 429
+
+
 class TestDailySpendGuard:
  def test_over_budget_user_is_refused_before_the_model_runs(self):
  from services.quiz_config import QUIZ_DAILY_SPEND_CAP_USD

docs/e2e-exploration.md

@@ -226,7 +226,10 @@ byte-for-byte match to one of `function_handlers_e2e.py`'s `E2E_DOC_*` (or
 `E2E_TUTOR_REPLY`, `E2E_QUIZ_*`) constants — here, `E2E_DOC_ABSTRACT`'s
 "gradient descent... loss surface... learning rate" wording and the fixed
 `lecture_notes` category. If a finding's "wrong" content matches one of
-those constants verbatim, it's the seam, not the app — drop it, and if it
+those constants verbatim, it's the seam, not the app (likewise the quiz's
+"Only 3 questions were ready for this concept" toast: the function-mode quiz handler always
+returns exactly 3 questions, so any requested length above 3 is reported as a short delivery —
+the honesty check working, not a generation bug) — drop it, and if it
 recurs, improve `scripts/explore/explorer-prompt.md`'s ground rules to name
 the pattern explicitly so a future explorer recognizes it before writing the
 stub, rather than filing an issue against the harness's own known-fixed

docs/frontend-testids.md

@@ -71,7 +71,7 @@ renders the element.
 | Onboarding | `onboarding` | `frontend/src/components/screens/Onboarding.tsx` (the first-run funnel, rendered bare outside `(shell)`) |
 | Upload modal | `upload-modal` | `frontend/src/components/DocumentUploadModal.tsx` |
 | Tutor | `tutor` | `frontend/src/components/chat/ChatPanel.tsx` (rendered by `screens/Learn.tsx`; + the session-resume rows in `src/components/screens/Learn.tsx` itself) |
-| Quiz | `quiz` | `frontend/src/components/QuizPanel.tsx` (rendered by `screens/Quiz.tsx`) |
+| Quiz | `quiz` | `frontend/src/components/quiz/**` — `QuizScreen.tsx` (route root + error card) switching on phase between `home/QuizHome.tsx` (+ `ConceptDialog`/`AdjustDialog`/`PickList`/`QuizSettings`), `question/QuizQuestion.tsx` (+ `AskPanel`/`LeaveDialog`) and `results/QuizResults.tsx` (+ `MissedList`); the ids on the shared `ui/` primitives and `graph/ConceptNeighbourhood.tsx` are passed in from those files as a `testid` prop (#537) |
 | Knowledge graph | `graph` | `frontend/src/components/graph/KnowledgeGraph.tsx` (wrapper: container root + mode toggle) plus `KnowledgeGraph2D.tsx`/`KnowledgeGraph3D.tsx` (the render/data-layer seam — hidden a11y node list, SVG node/edge marks, zoom controls — added with the #395 graph-integrity journey) |
 | App shell | `app` | `frontend/src/components/ShellFrame.tsx` (the authed layout frame every `(shell)` route renders inside) |
 | Study rooms | `social` | `frontend/src/components/screens/Social.tsx` (rooms sidebar, chat, overview, study match, directory — added with the #394 two-context journey) |
@@ -95,8 +95,16 @@ route:
  and the send `<button>` render in `ChatPanel.tsx`. `ChatPanel` has exactly one
  consumer (Learn), so tagging it there is unambiguous. The notetaker's chat is
  a separate `AIChatPanel` and is out of scope.
-- **Quiz.** `screens/Quiz.tsx` only fetches concepts and mounts `QuizPanel`;
- every answer/submit control renders in `QuizPanel.tsx`.
+- **Quiz.** The route mounts one component, `components/quiz/QuizScreen.tsx`,
+ which switches on phase between `home/QuizHome.tsx`,
+ `question/QuizQuestion.tsx` and `results/QuizResults.tsx`; each of the three
+ owns its own ids and its own dialogs. Three shared `ui/` primitives
+ (`AnswerOption`, `SegmentedControl`, `Sheet`) are in the eslint file list too:
+ the controls render inside them, so a testid-less `<button>` there would
+ un-anchor the surface from outside the screen files. Those primitives — plus
+ `ui/EmptyState`, `ui/InlineBanner`, `ui/ProgressDots` and
+ `graph/ConceptNeighbourhood` — take the id as a `testid` prop, so the value is
+ always written at the quiz call site, never inside the primitive.
 
 ## Current inventory
 
@@ -174,22 +182,87 @@ route:
 
 ### `quiz`
 
+The quiz is one surface: `components/quiz/QuizScreen.tsx` reads the entry off
+the URL and switches on phase between `home/QuizHome.tsx`,
+`question/QuizQuestion.tsx` and `results/QuizResults.tsx`. The table is grouped
+in that order; the screen-level ids (the error card) come last, followed by the
+entry points the quiz wave added inside other surfaces' files.
+
+Three ids are **renamed** from the pre-#537 quiz — same role, clearer name:
+`quiz-exit` → `quiz-leave`, `quiz-retake` → `quiz-again`,
+`quiz-explain-concept` → `quiz-ask`. Eleven are **kept** verbatim so existing
+journeys keep anchoring: `quiz-panel`, `quiz-start`, `quiz-cancel`,
+`quiz-answer-options`, `quiz-answer-option-{label}`, `quiz-submit-answer`,
+`quiz-next`, `quiz-review-verdict`, `quiz-results-score`,
+`quiz-results-mastery`, `quiz-done`.
+
 | testid | element |
 | --- | --- |
-| `quiz-panel` | panel root (all phases) |
-| `quiz-cancel` | "Cancel" (select phase) |
-| `quiz-start` | "Start quiz" |
+| `quiz-home` | quiz-home root (`phase: home \| configuring`) |
+| `quiz-resume-strip` | the "you left a quiz on X" banner (`ui/InlineBanner`) |
+| `quiz-resume` | "Resume" on that banner |
+| `quiz-resume-discard` | "Discard" — hides the attempt client-side; there is no abandon endpoint |
+| `quiz-proposal` | the "Ready for you" primary proposal card |
+| `quiz-start` | "Start" on that card |
+| `quiz-cancel` | "Cancel" — leaves for the entry source, or `/dashboard` when there is none |
+| `quiz-adjust` | "adjust" on the card — toggles the adjust dialog (`aria-pressed`) |
+| `quiz-alternative-{nodeId}` | one "Also worth a look" row |
+| `quiz-review-due` | "Review everything due" row |
+| `quiz-pick-open` | "Pick something specific →" |
+| `quiz-pick-list` | the grouped concept list it reveals |
+| `quiz-pick-{nodeId}` | one concept row in that list |
+| `quiz-pick-back` | "← Back" out of that list |
+| `quiz-empty-state` | the home's empty states (`ui/EmptyState`) — no courses, empty tree, or nothing left to propose; they are alternatives, so only one ever mounts |
+| `quiz-home-error` | the home's load-failure card |
+| `quiz-home-retry` | "Retry" inside it |
+| `quiz-concept-dialog` | the concept dialog opened from an alternative or a pick row |
+| `quiz-concept-start` | "Start · {count} {difficulty}" inside it |
+| `quiz-concept-cancel` | its "Cancel" |
+| `quiz-adjust-dialog` | "Adjust this quiz" dialog |
+| `quiz-adjust-done` | its "Done" — keeps the settings without starting |
+| `quiz-adjust-start` | its "Start · {count} {difficulty}" — saves and starts in one |
+| `quiz-seg-count` / `quiz-seg-difficulty` / `quiz-seg-feedback` | the three `ui/SegmentedControl`s both dialogs share; each option is `${testid}-${value}` |
+| `quiz-generating` | the skeleton question screen while a quiz is being written |
+| `quiz-panel` | question root (`phase: active \| answered`) |
+| `quiz-progress` | the question rail's progress dots (`ui/ProgressDots`) |
 | `quiz-answer-options` | answer radiogroup |
-| `quiz-answer-option-{label}` | one answer choice, suffixed with its label (`A`…) |
-| `quiz-submit-answer` | "Submit answer" |
-| `quiz-exit` | "Exit" (active phase) |
+| `quiz-answer-option-{label}` | one answer choice (`ui/AnswerOption`), suffixed with its label (`A`…) |
+| `quiz-submit-answer` | the footer's primary button while the answer is unrevealed |
+| `quiz-next` | the same footer button once the verdict is showing — "Next question" / "See results" |
 | `quiz-review-verdict` | "Correct." / "Not quite." banner |
-| `quiz-explain-concept` | "Explain this" |
-| `quiz-next` | "Next question" / "See results" |
-| `quiz-results-score` | the score percentage |
-| `quiz-results-mastery` | the "X / Y correct · mastery B% → A%" line |
-| `quiz-retake` | "Retake" |
-| `quiz-done` | "Done" |
+| `quiz-flag` | "This question is confusing" (toggles, `aria-pressed`; persists nothing) |
+| `quiz-ask` | "Ask about this" — opens the tutor sheet |
+| `quiz-leave` | "Leave" |
+| `quiz-leave-dialog` / `quiz-leave-cancel` / `quiz-leave-confirm` | the leave confirmation |
+| `quiz-ask-panel` | the tutor sheet (`ui/Sheet`) |
+| `quiz-ask-panel-close` | its × — the `Sheet` derives it as `${testid}-close` |
+| `quiz-ask-seed` | the composed first message shown at the top of the sheet |
+| `quiz-ask-retry` | "Try again" when the tutor stream failed |
+| `quiz-ask-input` / `quiz-ask-send` | the sheet's composer |
+| `quiz-results` | results root |
+| `quiz-results-graph` | the concept neighbourhood above the score (`graph/ConceptNeighbourhood`) |
+| `quiz-results-score` | the "{n} of {total} correct" line — a count, not a percentage |
+| `quiz-results-mastery` | the mastery delta line, "B% → A% · tier-before → tier-after" |
+| `quiz-results-xp` | "+{Δ} XP · {streak}-day streak" — absent when either gamification read failed |
+| `quiz-results-perfect` | the line shown instead of the missed list on a clean sweep |
+| `quiz-missed-list` | the "to look at" section |
+| `quiz-missed-{questionId}` | one missed item |
+| `quiz-missed-explain-{questionId}` | its "Show explanation" disclosure |
+| `quiz-missed-ask-{questionId}` | its "Ask about this" |
+| `quiz-practise-missed` | "Practise the one(s) you missed" |
+| `quiz-next-concept` | "Next: {concept} →" while the scope queue has more |
+| `quiz-again` | "Keep going — quiz again" (mounts in `quiz-practise-missed`'s place on a clean sweep) |
+| `quiz-back-to-source` | the secondary exit, labelled by where the quiz was entered from |
+| `quiz-done` | "Done" — back to `/quiz` |
+| `quiz-error` | the route-level error card (mapped copy + retry/back), rendered by `QuizScreen` in place of the phase |
+| `quiz-error-retry` / `quiz-error-back` | its "Try again" and "Back" |
+| `tree-node-recent-quizzes` | the tree node panel's "Recent quizzes" block (`screens/Tree.tsx`) |
+| `tree-node-recent-quiz-{attemptId}` | one row in it, suffixed with the attempt's `quiz_id` per the stable-domain-id rule |
+| `dashboard-review-due` | the "Review what's due" quiz entry point (`screens/Dashboard.tsx`) — three call sites, but exactly one mounts for a given layout/viewport |
+
+The last three carry another surface's prefix because they render in that
+surface's file. They are listed here because they are quiz entry points, and a
+quiz journey is what drives them.
 
 ### `graph`
 
@@ -279,6 +352,9 @@ never collide in the DOM.
 | `dashboard-courses-manage` | the cog inside the expanded key that opens the Courses & Semesters hub (the hub's own semester tabs are plain text buttons — journeys select them by role/name, e.g. "All semesters" / "Fall 2025") |
 | `dashboard-resume-{sessionId}` | a "Where you left off" card — deep-links to `/learn?resume={sessionId}` (#164), suffixed with the session's own id per the stable-domain-id rule |
 
+`dashboard-review-due` also lives in `screens/Dashboard.tsx`; it is documented
+with the `quiz` surface it links into.
+
 ### `calendar`
 
 Added with the #185 load-failure fix (a failed initial fetch must be
@@ -300,6 +376,7 @@ inside the `role="grid"` "Courses" grid.
 | testid | element |
 | --- | --- |
 | `gradebook-term-gpa` | landing: the selected term's credit-weighted GPA next to the chips (absent while the term has no graded work) |
+| `gradebook-upload-syllabus` | landing: the blank-semester empty state's "Upload syllabus" CTA (`ui/EmptyState` action slot) |
 | `gradebook-transcript-open` | landing: "Transcript" button opening the transcript modal |
 | `gradebook-transcript-gpa` | transcript modal: the cumulative GPA value |
 | `gradebook-transcript-retry` | transcript modal: inline "Try again" after a failed load (#463 catch+toast pattern) |

.github/workflows/e2e.yml

@@ -83,6 +83,12 @@ jobs:
  # Dummy on purpose: the below-seam RAG embed path (#439) must not
  # be able to bill; its failures are swallowed by design.
  GEMINI_API_KEY: e2e-dummy-key-no-billing
+ # #537: the quiz-generation guard keeps its sliding window in a
+ # process-local dict, so ONE Playwright run shares a single
+ # 8-per-300s budget across every spec and the quiz specs that run
+ # last 429. e2e-up.sh sets the same value; kept here so what the
+ # lane actually runs under is visible beside the rest of the seam.
+ QUIZ_GENERATE_RATE_LIMIT: "1000"
  run: make e2e-up
 
  - name: Run Playwright suite

backend/.env.example

@@ -69,3 +69,12 @@ GEMINI_VISION_OCR_ENABLED=false
 GEMINI_VISION_OCR_MAX_PAGES=10
 # The transcription model is the ADR-0008 per-task slot, not a knob of its own:
 # SAPLING_MODEL_OCR_VISION=gemini-2.5-flash
+
+# Quiz generation abuse guard (#544 F1; env-overridable since #537). The window
+# lives in a process-local dict, so ONE Playwright run spends a single budget
+# across every spec — the E2E lanes raise this; production keeps the default.
+# Unparseable or non-positive values fall back to the default.
+# QUIZ_GENERATE_RATE_LIMIT=8
+# Sliding-window length for that limit, in seconds. E2E lanes raise the limit
+# rather than shrink the window; production keeps the default.
+# QUIZ_GENERATE_RATE_WINDOW_SEC=300

backend/services/quiz_config.py

@@ -9,6 +9,41 @@
 Standalone constants module: no imports from models/routes/services so
 it can be imported from anywhere without cycles.
 """
+import logging
+import os
+
+logger = logging.getLogger(__name__)
+
+
+def _positive_int_env(name: str, default: int) -> int:
+ """A deployment override for one guard constant, read at import.
+
+ Deliberately fail-SAFE rather than fail-fast: an unparseable or
+ non-positive value falls back to the shipped default (the conservative
+ one) with a warning, so a stray env var cannot boot the app with a
+ disabled guard — or refuse to boot at all. Read once at import time,
+ which is also when `routes/quiz.py` binds the value, so a mid-process
+ `os.environ` change has no effect.
+ """
+ raw = os.getenv(name)
+ if raw is None or not raw.strip():
+ return default
+ try:
+ value = int(raw.strip())
+ except ValueError:
+ logger.warning(
+ "quiz_config: %s=%r is not an integer — using the default %d",
+ name, raw, default,
+ )
+ return default
+ if value <= 0:
+ logger.warning(
+ "quiz_config: %s=%d is not positive — using the default %d",
+ name, value, default,
+ )
+ return default
+ return value
+
 
 QUIZ_MIN_QUESTIONS = 1
 
@@ -87,8 +122,18 @@ def mastery_after(before: float, *, score: int, total: int) -> float:
 # The rate limit is sized for a human: a student comparing difficulties or
 # retaking a concept might legitimately generate a handful of quizzes in a
 # few minutes; nobody legitimately generates 10 in one.
-QUIZ_GENERATE_RATE_LIMIT = 8
-QUIZ_GENERATE_RATE_WINDOW_SEC = 300 # 5 minutes
+#
+# Both are env-overridable (#537) for one reason: `request_limits._rate_state`
+# is a module-level dict, so a whole Playwright run — every spec, every
+# worker-shared window — spends ONE 8-per-300s budget that only a backend
+# restart clears. The redesigned quiz lane needs ~20 real generations, and a
+# function-mode generation costs nothing, so the E2E stacks raise the limit
+# (scripts/e2e-up.sh, .github/workflows/e2e.yml). Production sets neither and
+# keeps the defaults below.
+QUIZ_GENERATE_RATE_LIMIT = _positive_int_env("QUIZ_GENERATE_RATE_LIMIT", 8)
+QUIZ_GENERATE_RATE_WINDOW_SEC = _positive_int_env(
+ "QUIZ_GENERATE_RATE_WINDOW_SEC", 300, # 5 minutes
+)
 
 # Daily per-user LLM spend ceiling. The SPEND it measures is cross-feature
 # (llm_usage records every agent call, not just quiz ones), but the ceiling

backend/tests/test_quiz_cost_observability_f.py

@@ -132,6 +132,87 @@ def test_limit_is_per_user(self):
  assert other.status_code == 200
 
 
+class TestGenerateRateLimitIsEnvOverridable:
+ """#537: the two guard constants read the environment; defaults intact.
+
+ `request_limits._rate_state` is module-level, so a whole Playwright run
+ shares ONE window that only a backend restart clears — and the redesigned
+ quiz lane needs more generations than any human would. The E2E stacks
+ raise the limit through the environment; production sets nothing and must
+ keep the shipped defaults.
+ """
+
+ @staticmethod
+ def _reloaded():
+ """Re-import services.quiz_config against the current environment.
+
+ `importlib.reload` mutates the module in place, so every caller must
+ restore it (see `_restore`) or later tests inherit the override.
+ """
+ import importlib
+
+ from services import quiz_config
+
+ return importlib.reload(quiz_config)
+
+ @classmethod
+ def _restore(cls):
+ cls._reloaded()
+
+ def test_defaults_hold_when_unset(self, monkeypatch):
+ monkeypatch.delenv("QUIZ_GENERATE_RATE_LIMIT", raising=False)
+ monkeypatch.delenv("QUIZ_GENERATE_RATE_WINDOW_SEC", raising=False)
+ try:
+ cfg = self._reloaded()
+ assert cfg.QUIZ_GENERATE_RATE_LIMIT == 8
+ assert cfg.QUIZ_GENERATE_RATE_WINDOW_SEC == 300
+ finally:
+ monkeypatch.undo()
+ self._restore()
+
+ def test_an_override_is_honoured(self, monkeypatch):
+ monkeypatch.setenv("QUIZ_GENERATE_RATE_LIMIT", "1000")
+ monkeypatch.setenv("QUIZ_GENERATE_RATE_WINDOW_SEC", "60")
+ try:
+ cfg = self._reloaded()
+ assert cfg.QUIZ_GENERATE_RATE_LIMIT == 1000
+ assert cfg.QUIZ_GENERATE_RATE_WINDOW_SEC == 60
+ finally:
+ monkeypatch.undo()
+ self._restore()
+
+ def test_a_junk_override_falls_back_to_the_default(self, monkeypatch):
+ """Fail-safe, not fail-fast: a stray value must neither disable the
+ guard (limit=0 would 429 everyone, a negative window never expires)
+ nor stop the app from booting."""
+ for bad in ("", " ", "eight", "0", "-5", "3.5"):
+ monkeypatch.setenv("QUIZ_GENERATE_RATE_LIMIT", bad)
+ monkeypatch.setenv("QUIZ_GENERATE_RATE_WINDOW_SEC", bad)
+ try:
+ cfg = self._reloaded()
+ assert cfg.QUIZ_GENERATE_RATE_LIMIT == 8, bad
+ assert cfg.QUIZ_GENERATE_RATE_WINDOW_SEC == 300, bad
+ finally:
+ monkeypatch.undo()
+ self._restore()
+
+ def test_the_route_still_enforces_whatever_was_resolved(self):
+ """The env seam moves the NUMBER, never the behaviour: the route binds
+ the value at its own import and still 429s one call past it."""
+ from routes import quiz as quiz_route
+ from services.quiz_config import QUIZ_GENERATE_RATE_LIMIT
+
+ assert quiz_route.QUIZ_GENERATE_RATE_LIMIT == QUIZ_GENERATE_RATE_LIMIT
+ run = AsyncMock(return_value=SimpleNamespace(output=_quiz()))
+ with (
+ patch("routes.quiz.table", side_effect=_factory()),
+ patch("routes.quiz.quiz_agent.run", new=run),
+ ):
+ for _ in range(quiz_route.QUIZ_GENERATE_RATE_LIMIT):
+ assert _generate().status_code == 200
+ assert _generate().status_code == 429
+
+
 class TestDailySpendGuard:
  def test_over_budget_user_is_refused_before_the_model_runs(self):
  from services.quiz_config import QUIZ_DAILY_SPEND_CAP_USD

docs/e2e-exploration.md

@@ -226,7 +226,10 @@ byte-for-byte match to one of `function_handlers_e2e.py`'s `E2E_DOC_*` (or
 `E2E_TUTOR_REPLY`, `E2E_QUIZ_*`) constants — here, `E2E_DOC_ABSTRACT`'s
 "gradient descent... loss surface... learning rate" wording and the fixed
 `lecture_notes` category. If a finding's "wrong" content matches one of
-those constants verbatim, it's the seam, not the app — drop it, and if it
+those constants verbatim, it's the seam, not the app (likewise the quiz's
+"Only 3 questions were ready for this concept" toast: the function-mode quiz handler always
+returns exactly 3 questions, so any requested length above 3 is reported as a short delivery —
+the honesty check working, not a generation bug) — drop it, and if it
 recurs, improve `scripts/explore/explorer-prompt.md`'s ground rules to name
 the pattern explicitly so a future explorer recognizes it before writing the
 stub, rather than filing an issue against the harness's own known-fixed

docs/frontend-testids.md

@@ -71,7 +71,7 @@ renders the element.
 | Onboarding | `onboarding` | `frontend/src/components/screens/Onboarding.tsx` (the first-run funnel, rendered bare outside `(shell)`) |
 | Upload modal | `upload-modal` | `frontend/src/components/DocumentUploadModal.tsx` |
 | Tutor | `tutor` | `frontend/src/components/chat/ChatPanel.tsx` (rendered by `screens/Learn.tsx`; + the session-resume rows in `src/components/screens/Learn.tsx` itself) |
-| Quiz | `quiz` | `frontend/src/components/QuizPanel.tsx` (rendered by `screens/Quiz.tsx`) |
+| Quiz | `quiz` | `frontend/src/components/quiz/**` — `QuizScreen.tsx` (route root + error card) switching on phase between `home/QuizHome.tsx` (+ `ConceptDialog`/`AdjustDialog`/`PickList`/`QuizSettings`), `question/QuizQuestion.tsx` (+ `AskPanel`/`LeaveDialog`) and `results/QuizResults.tsx` (+ `MissedList`); the ids on the shared `ui/` primitives and `graph/ConceptNeighbourhood.tsx` are passed in from those files as a `testid` prop (#537) |
 | Knowledge graph | `graph` | `frontend/src/components/graph/KnowledgeGraph.tsx` (wrapper: container root + mode toggle) plus `KnowledgeGraph2D.tsx`/`KnowledgeGraph3D.tsx` (the render/data-layer seam — hidden a11y node list, SVG node/edge marks, zoom controls — added with the #395 graph-integrity journey) |
 | App shell | `app` | `frontend/src/components/ShellFrame.tsx` (the authed layout frame every `(shell)` route renders inside) |
 | Study rooms | `social` | `frontend/src/components/screens/Social.tsx` (rooms sidebar, chat, overview, study match, directory — added with the #394 two-context journey) |
@@ -95,8 +95,16 @@ route:
  and the send `<button>` render in `ChatPanel.tsx`. `ChatPanel` has exactly one
  consumer (Learn), so tagging it there is unambiguous. The notetaker's chat is
  a separate `AIChatPanel` and is out of scope.
-- **Quiz.** `screens/Quiz.tsx` only fetches concepts and mounts `QuizPanel`;
- every answer/submit control renders in `QuizPanel.tsx`.
+- **Quiz.** The route mounts one component, `components/quiz/QuizScreen.tsx`,
+ which switches on phase between `home/QuizHome.tsx`,
+ `question/QuizQuestion.tsx` and `results/QuizResults.tsx`; each of the three
+ owns its own ids and its own dialogs. Three shared `ui/` primitives
+ (`AnswerOption`, `SegmentedControl`, `Sheet`) are in the eslint file list too:
+ the controls render inside them, so a testid-less `<button>` there would
+ un-anchor the surface from outside the screen files. Those primitives — plus
+ `ui/EmptyState`, `ui/InlineBanner`, `ui/ProgressDots` and
+ `graph/ConceptNeighbourhood` — take the id as a `testid` prop, so the value is
+ always written at the quiz call site, never inside the primitive.
 
 ## Current inventory
 
@@ -174,22 +182,87 @@ route:
 
 ### `quiz`
 
+The quiz is one surface: `components/quiz/QuizScreen.tsx` reads the entry off
+the URL and switches on phase between `home/QuizHome.tsx`,
+`question/QuizQuestion.tsx` and `results/QuizResults.tsx`. The table is grouped
+in that order; the screen-level ids (the error card) come last, followed by the
+entry points the quiz wave added inside other surfaces' files.
+
+Three ids are **renamed** from the pre-#537 quiz — same role, clearer name:
+`quiz-exit` → `quiz-leave`, `quiz-retake` → `quiz-again`,
+`quiz-explain-concept` → `quiz-ask`. Eleven are **kept** verbatim so existing
+journeys keep anchoring: `quiz-panel`, `quiz-start`, `quiz-cancel`,
+`quiz-answer-options`, `quiz-answer-option-{label}`, `quiz-submit-answer`,
+`quiz-next`, `quiz-review-verdict`, `quiz-results-score`,
+`quiz-results-mastery`, `quiz-done`.
+
 | testid | element |
 | --- | --- |
-| `quiz-panel` | panel root (all phases) |
-| `quiz-cancel` | "Cancel" (select phase) |
-| `quiz-start` | "Start quiz" |
+| `quiz-home` | quiz-home root (`phase: home \| configuring`) |
+| `quiz-resume-strip` | the "you left a quiz on X" banner (`ui/InlineBanner`) |
+| `quiz-resume` | "Resume" on that banner |
+| `quiz-resume-discard` | "Discard" — hides the attempt client-side; there is no abandon endpoint |
+| `quiz-proposal` | the "Ready for you" primary proposal card |
+| `quiz-start` | "Start" on that card |
+| `quiz-cancel` | "Cancel" — leaves for the entry source, or `/dashboard` when there is none |
+| `quiz-adjust` | "adjust" on the card — toggles the adjust dialog (`aria-pressed`) |
+| `quiz-alternative-{nodeId}` | one "Also worth a look" row |
+| `quiz-review-due` | "Review everything due" row |
+| `quiz-pick-open` | "Pick something specific →" |
+| `quiz-pick-list` | the grouped concept list it reveals |
+| `quiz-pick-{nodeId}` | one concept row in that list |
+| `quiz-pick-back` | "← Back" out of that list |
+| `quiz-empty-state` | the home's empty states (`ui/EmptyState`) — no courses, empty tree, or nothing left to propose; they are alternatives, so only one ever mounts |
+| `quiz-home-error` | the home's load-failure card |
+| `quiz-home-retry` | "Retry" inside it |
+| `quiz-concept-dialog` | the concept dialog opened from an alternative or a pick row |
+| `quiz-concept-start` | "Start · {count} {difficulty}" inside it |
+| `quiz-concept-cancel` | its "Cancel" |
+| `quiz-adjust-dialog` | "Adjust this quiz" dialog |
+| `quiz-adjust-done` | its "Done" — keeps the settings without starting |
+| `quiz-adjust-start` | its "Start · {count} {difficulty}" — saves and starts in one |
+| `quiz-seg-count` / `quiz-seg-difficulty` / `quiz-seg-feedback` | the three `ui/SegmentedControl`s both dialogs share; each option is `${testid}-${value}` |
+| `quiz-generating` | the skeleton question screen while a quiz is being written |
+| `quiz-panel` | question root (`phase: active \| answered`) |
+| `quiz-progress` | the question rail's progress dots (`ui/ProgressDots`) |
 | `quiz-answer-options` | answer radiogroup |
-| `quiz-answer-option-{label}` | one answer choice, suffixed with its label (`A`…) |
-| `quiz-submit-answer` | "Submit answer" |
-| `quiz-exit` | "Exit" (active phase) |
+| `quiz-answer-option-{label}` | one answer choice (`ui/AnswerOption`), suffixed with its label (`A`…) |
+| `quiz-submit-answer` | the footer's primary button while the answer is unrevealed |
+| `quiz-next` | the same footer button once the verdict is showing — "Next question" / "See results" |
 | `quiz-review-verdict` | "Correct." / "Not quite." banner |
-| `quiz-explain-concept` | "Explain this" |
-| `quiz-next` | "Next question" / "See results" |
-| `quiz-results-score` | the score percentage |
-| `quiz-results-mastery` | the "X / Y correct · mastery B% → A%" line |
-| `quiz-retake` | "Retake" |
-| `quiz-done` | "Done" |
+| `quiz-flag` | "This question is confusing" (toggles, `aria-pressed`; persists nothing) |
+| `quiz-ask` | "Ask about this" — opens the tutor sheet |
+| `quiz-leave` | "Leave" |
+| `quiz-leave-dialog` / `quiz-leave-cancel` / `quiz-leave-confirm` | the leave confirmation |
+| `quiz-ask-panel` | the tutor sheet (`ui/Sheet`) |
+| `quiz-ask-panel-close` | its × — the `Sheet` derives it as `${testid}-close` |
+| `quiz-ask-seed` | the composed first message shown at the top of the sheet |
+| `quiz-ask-retry` | "Try again" when the tutor stream failed |
+| `quiz-ask-input` / `quiz-ask-send` | the sheet's composer |
+| `quiz-results` | results root |
+| `quiz-results-graph` | the concept neighbourhood above the score (`graph/ConceptNeighbourhood`) |
+| `quiz-results-score` | the "{n} of {total} correct" line — a count, not a percentage |
+| `quiz-results-mastery` | the mastery delta line, "B% → A% · tier-before → tier-after" |
+| `quiz-results-xp` | "+{Δ} XP · {streak}-day streak" — absent when either gamification read failed |
+| `quiz-results-perfect` | the line shown instead of the missed list on a clean sweep |
+| `quiz-missed-list` | the "to look at" section |
+| `quiz-missed-{questionId}` | one missed item |
+| `quiz-missed-explain-{questionId}` | its "Show explanation" disclosure |
+| `quiz-missed-ask-{questionId}` | its "Ask about this" |
+| `quiz-practise-missed` | "Practise the one(s) you missed" |
+| `quiz-next-concept` | "Next: {concept} →" while the scope queue has more |
+| `quiz-again` | "Keep going — quiz again" (mounts in `quiz-practise-missed`'s place on a clean sweep) |
+| `quiz-back-to-source` | the secondary exit, labelled by where the quiz was entered from |
+| `quiz-done` | "Done" — back to `/quiz` |
+| `quiz-error` | the route-level error card (mapped copy + retry/back), rendered by `QuizScreen` in place of the phase |
+| `quiz-error-retry` / `quiz-error-back` | its "Try again" and "Back" |
+| `tree-node-recent-quizzes` | the tree node panel's "Recent quizzes" block (`screens/Tree.tsx`) |
+| `tree-node-recent-quiz-{attemptId}` | one row in it, suffixed with the attempt's `quiz_id` per the stable-domain-id rule |
+| `dashboard-review-due` | the "Review what's due" quiz entry point (`screens/Dashboard.tsx`) — three call sites, but exactly one mounts for a given layout/viewport |
+
+The last three carry another surface's prefix because they render in that
+surface's file. They are listed here because they are quiz entry points, and a
+quiz journey is what drives them.
 
 ### `graph`
 
@@ -279,6 +352,9 @@ never collide in the DOM.
 | `dashboard-courses-manage` | the cog inside the expanded key that opens the Courses & Semesters hub (the hub's own semester tabs are plain text buttons — journeys select them by role/name, e.g. "All semesters" / "Fall 2025") |
 | `dashboard-resume-{sessionId}` | a "Where you left off" card — deep-links to `/learn?resume={sessionId}` (#164), suffixed with the session's own id per the stable-domain-id rule |
 
+`dashboard-review-due` also lives in `screens/Dashboard.tsx`; it is documented
+with the `quiz` surface it links into.
+
 ### `calendar`
 
 Added with the #185 load-failure fix (a failed initial fetch must be
@@ -300,6 +376,7 @@ inside the `role="grid"` "Courses" grid.
 | testid | element |
 | --- | --- |
 | `gradebook-term-gpa` | landing: the selected term's credit-weighted GPA next to the chips (absent while the term has no graded work) |
+| `gradebook-upload-syllabus` | landing: the blank-semester empty state's "Upload syllabus" CTA (`ui/EmptyState` action slot) |
 | `gradebook-transcript-open` | landing: "Transcript" button opening the transcript modal |
 | `gradebook-transcript-gpa` | transcript modal: the cumulative GPA value |
 | `gradebook-transcript-retry` | transcript modal: inline "Try again" after a failed load (#463 catch+toast pattern) |

.github/workflows/e2e.yml

@@ -83,6 +83,12 @@ jobs:
  # Dummy on purpose: the below-seam RAG embed path (#439) must not
  # be able to bill; its failures are swallowed by design.
  GEMINI_API_KEY: e2e-dummy-key-no-billing
+ # #537: the quiz-generation guard keeps its sliding window in a
+ # process-local dict, so ONE Playwright run shares a single
+ # 8-per-300s budget across every spec and the quiz specs that run
+ # last 429. e2e-up.sh sets the same value; kept here so what the
+ # lane actually runs under is visible beside the rest of the seam.
+ QUIZ_GENERATE_RATE_LIMIT: "1000"
  run: make e2e-up
 
  - name: Run Playwright suite

backend/.env.example

@@ -69,3 +69,12 @@ GEMINI_VISION_OCR_ENABLED=false
 GEMINI_VISION_OCR_MAX_PAGES=10
 # The transcription model is the ADR-0008 per-task slot, not a knob of its own:
 # SAPLING_MODEL_OCR_VISION=gemini-2.5-flash
+
+# Quiz generation abuse guard (#544 F1; env-overridable since #537). The window
+# lives in a process-local dict, so ONE Playwright run spends a single budget
+# across every spec — the E2E lanes raise this; production keeps the default.
+# Unparseable or non-positive values fall back to the default.
+# QUIZ_GENERATE_RATE_LIMIT=8
+# Sliding-window length for that limit, in seconds. E2E lanes raise the limit
+# rather than shrink the window; production keeps the default.
+# QUIZ_GENERATE_RATE_WINDOW_SEC=300

backend/services/quiz_config.py

@@ -9,6 +9,41 @@
 Standalone constants module: no imports from models/routes/services so
 it can be imported from anywhere without cycles.
 """
+import logging
+import os
+
+logger = logging.getLogger(__name__)
+
+
+def _positive_int_env(name: str, default: int) -> int:
+ """A deployment override for one guard constant, read at import.
+
+ Deliberately fail-SAFE rather than fail-fast: an unparseable or
+ non-positive value falls back to the shipped default (the conservative
+ one) with a warning, so a stray env var cannot boot the app with a
+ disabled guard — or refuse to boot at all. Read once at import time,
+ which is also when `routes/quiz.py` binds the value, so a mid-process
+ `os.environ` change has no effect.
+ """
+ raw = os.getenv(name)
+ if raw is None or not raw.strip():
+ return default
+ try:
+ value = int(raw.strip())
+ except ValueError:
+ logger.warning(
+ "quiz_config: %s=%r is not an integer — using the default %d",
+ name, raw, default,
+ )
+ return default
+ if value <= 0:
+ logger.warning(
+ "quiz_config: %s=%d is not positive — using the default %d",
+ name, value, default,
+ )
+ return default
+ return value
+
 
 QUIZ_MIN_QUESTIONS = 1
 
@@ -87,8 +122,18 @@ def mastery_after(before: float, *, score: int, total: int) -> float:
 # The rate limit is sized for a human: a student comparing difficulties or
 # retaking a concept might legitimately generate a handful of quizzes in a
 # few minutes; nobody legitimately generates 10 in one.
-QUIZ_GENERATE_RATE_LIMIT = 8
-QUIZ_GENERATE_RATE_WINDOW_SEC = 300 # 5 minutes
+#
+# Both are env-overridable (#537) for one reason: `request_limits._rate_state`
+# is a module-level dict, so a whole Playwright run — every spec, every
+# worker-shared window — spends ONE 8-per-300s budget that only a backend
+# restart clears. The redesigned quiz lane needs ~20 real generations, and a
+# function-mode generation costs nothing, so the E2E stacks raise the limit
+# (scripts/e2e-up.sh, .github/workflows/e2e.yml). Production sets neither and
+# keeps the defaults below.
+QUIZ_GENERATE_RATE_LIMIT = _positive_int_env("QUIZ_GENERATE_RATE_LIMIT", 8)
+QUIZ_GENERATE_RATE_WINDOW_SEC = _positive_int_env(
+ "QUIZ_GENERATE_RATE_WINDOW_SEC", 300, # 5 minutes
+)
 
 # Daily per-user LLM spend ceiling. The SPEND it measures is cross-feature
 # (llm_usage records every agent call, not just quiz ones), but the ceiling

backend/tests/test_quiz_cost_observability_f.py

@@ -132,6 +132,87 @@ def test_limit_is_per_user(self):
  assert other.status_code == 200
 
 
+class TestGenerateRateLimitIsEnvOverridable:
+ """#537: the two guard constants read the environment; defaults intact.
+
+ `request_limits._rate_state` is module-level, so a whole Playwright run
+ shares ONE window that only a backend restart clears — and the redesigned
+ quiz lane needs more generations than any human would. The E2E stacks
+ raise the limit through the environment; production sets nothing and must
+ keep the shipped defaults.
+ """
+
+ @staticmethod
+ def _reloaded():
+ """Re-import services.quiz_config against the current environment.
+
+ `importlib.reload` mutates the module in place, so every caller must
+ restore it (see `_restore`) or later tests inherit the override.
+ """
+ import importlib
+
+ from services import quiz_config
+
+ return importlib.reload(quiz_config)
+
+ @classmethod
+ def _restore(cls):
+ cls._reloaded()
+
+ def test_defaults_hold_when_unset(self, monkeypatch):
+ monkeypatch.delenv("QUIZ_GENERATE_RATE_LIMIT", raising=False)
+ monkeypatch.delenv("QUIZ_GENERATE_RATE_WINDOW_SEC", raising=False)
+ try:
+ cfg = self._reloaded()
+ assert cfg.QUIZ_GENERATE_RATE_LIMIT == 8
+ assert cfg.QUIZ_GENERATE_RATE_WINDOW_SEC == 300
+ finally:
+ monkeypatch.undo()
+ self._restore()
+
+ def test_an_override_is_honoured(self, monkeypatch):
+ monkeypatch.setenv("QUIZ_GENERATE_RATE_LIMIT", "1000")
+ monkeypatch.setenv("QUIZ_GENERATE_RATE_WINDOW_SEC", "60")
+ try:
+ cfg = self._reloaded()
+ assert cfg.QUIZ_GENERATE_RATE_LIMIT == 1000
+ assert cfg.QUIZ_GENERATE_RATE_WINDOW_SEC == 60
+ finally:
+ monkeypatch.undo()
+ self._restore()
+
+ def test_a_junk_override_falls_back_to_the_default(self, monkeypatch):
+ """Fail-safe, not fail-fast: a stray value must neither disable the
+ guard (limit=0 would 429 everyone, a negative window never expires)
+ nor stop the app from booting."""
+ for bad in ("", " ", "eight", "0", "-5", "3.5"):
+ monkeypatch.setenv("QUIZ_GENERATE_RATE_LIMIT", bad)
+ monkeypatch.setenv("QUIZ_GENERATE_RATE_WINDOW_SEC", bad)
+ try:
+ cfg = self._reloaded()
+ assert cfg.QUIZ_GENERATE_RATE_LIMIT == 8, bad
+ assert cfg.QUIZ_GENERATE_RATE_WINDOW_SEC == 300, bad
+ finally:
+ monkeypatch.undo()
+ self._restore()
+
+ def test_the_route_still_enforces_whatever_was_resolved(self):
+ """The env seam moves the NUMBER, never the behaviour: the route binds
+ the value at its own import and still 429s one call past it."""
+ from routes import quiz as quiz_route
+ from services.quiz_config import QUIZ_GENERATE_RATE_LIMIT
+
+ assert quiz_route.QUIZ_GENERATE_RATE_LIMIT == QUIZ_GENERATE_RATE_LIMIT
+ run = AsyncMock(return_value=SimpleNamespace(output=_quiz()))
+ with (
+ patch("routes.quiz.table", side_effect=_factory()),
+ patch("routes.quiz.quiz_agent.run", new=run),
+ ):
+ for _ in range(quiz_route.QUIZ_GENERATE_RATE_LIMIT):
+ assert _generate().status_code == 200
+ assert _generate().status_code == 429
+
+
 class TestDailySpendGuard:
  def test_over_budget_user_is_refused_before_the_model_runs(self):
  from services.quiz_config import QUIZ_DAILY_SPEND_CAP_USD

docs/e2e-exploration.md

@@ -226,7 +226,10 @@ byte-for-byte match to one of `function_handlers_e2e.py`'s `E2E_DOC_*` (or
 `E2E_TUTOR_REPLY`, `E2E_QUIZ_*`) constants — here, `E2E_DOC_ABSTRACT`'s
 "gradient descent... loss surface... learning rate" wording and the fixed
 `lecture_notes` category. If a finding's "wrong" content matches one of
-those constants verbatim, it's the seam, not the app — drop it, and if it
+those constants verbatim, it's the seam, not the app (likewise the quiz's
+"Only 3 questions were ready for this concept" toast: the function-mode quiz handler always
+returns exactly 3 questions, so any requested length above 3 is reported as a short delivery —
+the honesty check working, not a generation bug) — drop it, and if it
 recurs, improve `scripts/explore/explorer-prompt.md`'s ground rules to name
 the pattern explicitly so a future explorer recognizes it before writing the
 stub, rather than filing an issue against the harness's own known-fixed

docs/frontend-testids.md

@@ -71,7 +71,7 @@ renders the element.
 | Onboarding | `onboarding` | `frontend/src/components/screens/Onboarding.tsx` (the first-run funnel, rendered bare outside `(shell)`) |
 | Upload modal | `upload-modal` | `frontend/src/components/DocumentUploadModal.tsx` |
 | Tutor | `tutor` | `frontend/src/components/chat/ChatPanel.tsx` (rendered by `screens/Learn.tsx`; + the session-resume rows in `src/components/screens/Learn.tsx` itself) |
-| Quiz | `quiz` | `frontend/src/components/QuizPanel.tsx` (rendered by `screens/Quiz.tsx`) |
+| Quiz | `quiz` | `frontend/src/components/quiz/**` — `QuizScreen.tsx` (route root + error card) switching on phase between `home/QuizHome.tsx` (+ `ConceptDialog`/`AdjustDialog`/`PickList`/`QuizSettings`), `question/QuizQuestion.tsx` (+ `AskPanel`/`LeaveDialog`) and `results/QuizResults.tsx` (+ `MissedList`); the ids on the shared `ui/` primitives and `graph/ConceptNeighbourhood.tsx` are passed in from those files as a `testid` prop (#537) |
 | Knowledge graph | `graph` | `frontend/src/components/graph/KnowledgeGraph.tsx` (wrapper: container root + mode toggle) plus `KnowledgeGraph2D.tsx`/`KnowledgeGraph3D.tsx` (the render/data-layer seam — hidden a11y node list, SVG node/edge marks, zoom controls — added with the #395 graph-integrity journey) |
 | App shell | `app` | `frontend/src/components/ShellFrame.tsx` (the authed layout frame every `(shell)` route renders inside) |
 | Study rooms | `social` | `frontend/src/components/screens/Social.tsx` (rooms sidebar, chat, overview, study match, directory — added with the #394 two-context journey) |
@@ -95,8 +95,16 @@ route:
  and the send `<button>` render in `ChatPanel.tsx`. `ChatPanel` has exactly one
  consumer (Learn), so tagging it there is unambiguous. The notetaker's chat is
  a separate `AIChatPanel` and is out of scope.
-- **Quiz.** `screens/Quiz.tsx` only fetches concepts and mounts `QuizPanel`;
- every answer/submit control renders in `QuizPanel.tsx`.
+- **Quiz.** The route mounts one component, `components/quiz/QuizScreen.tsx`,
+ which switches on phase between `home/QuizHome.tsx`,
+ `question/QuizQuestion.tsx` and `results/QuizResults.tsx`; each of the three
+ owns its own ids and its own dialogs. Three shared `ui/` primitives
+ (`AnswerOption`, `SegmentedControl`, `Sheet`) are in the eslint file list too:
+ the controls render inside them, so a testid-less `<button>` there would
+ un-anchor the surface from outside the screen files. Those primitives — plus
+ `ui/EmptyState`, `ui/InlineBanner`, `ui/ProgressDots` and
+ `graph/ConceptNeighbourhood` — take the id as a `testid` prop, so the value is
+ always written at the quiz call site, never inside the primitive.
 
 ## Current inventory
 
@@ -174,22 +182,87 @@ route:
 
 ### `quiz`
 
+The quiz is one surface: `components/quiz/QuizScreen.tsx` reads the entry off
+the URL and switches on phase between `home/QuizHome.tsx`,
+`question/QuizQuestion.tsx` and `results/QuizResults.tsx`. The table is grouped
+in that order; the screen-level ids (the error card) come last, followed by the
+entry points the quiz wave added inside other surfaces' files.
+
+Three ids are **renamed** from the pre-#537 quiz — same role, clearer name:
+`quiz-exit` → `quiz-leave`, `quiz-retake` → `quiz-again`,
+`quiz-explain-concept` → `quiz-ask`. Eleven are **kept** verbatim so existing
+journeys keep anchoring: `quiz-panel`, `quiz-start`, `quiz-cancel`,
+`quiz-answer-options`, `quiz-answer-option-{label}`, `quiz-submit-answer`,
+`quiz-next`, `quiz-review-verdict`, `quiz-results-score`,
+`quiz-results-mastery`, `quiz-done`.
+
 | testid | element |
 | --- | --- |
-| `quiz-panel` | panel root (all phases) |
-| `quiz-cancel` | "Cancel" (select phase) |
-| `quiz-start` | "Start quiz" |
+| `quiz-home` | quiz-home root (`phase: home \| configuring`) |
+| `quiz-resume-strip` | the "you left a quiz on X" banner (`ui/InlineBanner`) |
+| `quiz-resume` | "Resume" on that banner |
+| `quiz-resume-discard` | "Discard" — hides the attempt client-side; there is no abandon endpoint |
+| `quiz-proposal` | the "Ready for you" primary proposal card |
+| `quiz-start` | "Start" on that card |
+| `quiz-cancel` | "Cancel" — leaves for the entry source, or `/dashboard` when there is none |
+| `quiz-adjust` | "adjust" on the card — toggles the adjust dialog (`aria-pressed`) |
+| `quiz-alternative-{nodeId}` | one "Also worth a look" row |
+| `quiz-review-due` | "Review everything due" row |
+| `quiz-pick-open` | "Pick something specific →" |
+| `quiz-pick-list` | the grouped concept list it reveals |
+| `quiz-pick-{nodeId}` | one concept row in that list |
+| `quiz-pick-back` | "← Back" out of that list |
+| `quiz-empty-state` | the home's empty states (`ui/EmptyState`) — no courses, empty tree, or nothing left to propose; they are alternatives, so only one ever mounts |
+| `quiz-home-error` | the home's load-failure card |
+| `quiz-home-retry` | "Retry" inside it |
+| `quiz-concept-dialog` | the concept dialog opened from an alternative or a pick row |
+| `quiz-concept-start` | "Start · {count} {difficulty}" inside it |
+| `quiz-concept-cancel` | its "Cancel" |
+| `quiz-adjust-dialog` | "Adjust this quiz" dialog |
+| `quiz-adjust-done` | its "Done" — keeps the settings without starting |
+| `quiz-adjust-start` | its "Start · {count} {difficulty}" — saves and starts in one |
+| `quiz-seg-count` / `quiz-seg-difficulty` / `quiz-seg-feedback` | the three `ui/SegmentedControl`s both dialogs share; each option is `${testid}-${value}` |
+| `quiz-generating` | the skeleton question screen while a quiz is being written |
+| `quiz-panel` | question root (`phase: active \| answered`) |
+| `quiz-progress` | the question rail's progress dots (`ui/ProgressDots`) |
 | `quiz-answer-options` | answer radiogroup |
-| `quiz-answer-option-{label}` | one answer choice, suffixed with its label (`A`…) |
-| `quiz-submit-answer` | "Submit answer" |
-| `quiz-exit` | "Exit" (active phase) |
+| `quiz-answer-option-{label}` | one answer choice (`ui/AnswerOption`), suffixed with its label (`A`…) |
+| `quiz-submit-answer` | the footer's primary button while the answer is unrevealed |
+| `quiz-next` | the same footer button once the verdict is showing — "Next question" / "See results" |
 | `quiz-review-verdict` | "Correct." / "Not quite." banner |
-| `quiz-explain-concept` | "Explain this" |
-| `quiz-next` | "Next question" / "See results" |
-| `quiz-results-score` | the score percentage |
-| `quiz-results-mastery` | the "X / Y correct · mastery B% → A%" line |
-| `quiz-retake` | "Retake" |
-| `quiz-done` | "Done" |
+| `quiz-flag` | "This question is confusing" (toggles, `aria-pressed`; persists nothing) |
+| `quiz-ask` | "Ask about this" — opens the tutor sheet |
+| `quiz-leave` | "Leave" |
+| `quiz-leave-dialog` / `quiz-leave-cancel` / `quiz-leave-confirm` | the leave confirmation |
+| `quiz-ask-panel` | the tutor sheet (`ui/Sheet`) |
+| `quiz-ask-panel-close` | its × — the `Sheet` derives it as `${testid}-close` |
+| `quiz-ask-seed` | the composed first message shown at the top of the sheet |
+| `quiz-ask-retry` | "Try again" when the tutor stream failed |
+| `quiz-ask-input` / `quiz-ask-send` | the sheet's composer |
+| `quiz-results` | results root |
+| `quiz-results-graph` | the concept neighbourhood above the score (`graph/ConceptNeighbourhood`) |
+| `quiz-results-score` | the "{n} of {total} correct" line — a count, not a percentage |
+| `quiz-results-mastery` | the mastery delta line, "B% → A% · tier-before → tier-after" |
+| `quiz-results-xp` | "+{Δ} XP · {streak}-day streak" — absent when either gamification read failed |
+| `quiz-results-perfect` | the line shown instead of the missed list on a clean sweep |
+| `quiz-missed-list` | the "to look at" section |
+| `quiz-missed-{questionId}` | one missed item |
+| `quiz-missed-explain-{questionId}` | its "Show explanation" disclosure |
+| `quiz-missed-ask-{questionId}` | its "Ask about this" |
+| `quiz-practise-missed` | "Practise the one(s) you missed" |
+| `quiz-next-concept` | "Next: {concept} →" while the scope queue has more |
+| `quiz-again` | "Keep going — quiz again" (mounts in `quiz-practise-missed`'s place on a clean sweep) |
+| `quiz-back-to-source` | the secondary exit, labelled by where the quiz was entered from |
+| `quiz-done` | "Done" — back to `/quiz` |
+| `quiz-error` | the route-level error card (mapped copy + retry/back), rendered by `QuizScreen` in place of the phase |
+| `quiz-error-retry` / `quiz-error-back` | its "Try again" and "Back" |
+| `tree-node-recent-quizzes` | the tree node panel's "Recent quizzes" block (`screens/Tree.tsx`) |
+| `tree-node-recent-quiz-{attemptId}` | one row in it, suffixed with the attempt's `quiz_id` per the stable-domain-id rule |
+| `dashboard-review-due` | the "Review what's due" quiz entry point (`screens/Dashboard.tsx`) — three call sites, but exactly one mounts for a given layout/viewport |
+
+The last three carry another surface's prefix because they render in that
+surface's file. They are listed here because they are quiz entry points, and a
+quiz journey is what drives them.
 
 ### `graph`
 
@@ -279,6 +352,9 @@ never collide in the DOM.
 | `dashboard-courses-manage` | the cog inside the expanded key that opens the Courses & Semesters hub (the hub's own semester tabs are plain text buttons — journeys select them by role/name, e.g. "All semesters" / "Fall 2025") |
 | `dashboard-resume-{sessionId}` | a "Where you left off" card — deep-links to `/learn?resume={sessionId}` (#164), suffixed with the session's own id per the stable-domain-id rule |
 
+`dashboard-review-due` also lives in `screens/Dashboard.tsx`; it is documented
+with the `quiz` surface it links into.
+
 ### `calendar`
 
 Added with the #185 load-failure fix (a failed initial fetch must be
@@ -300,6 +376,7 @@ inside the `role="grid"` "Courses" grid.
 | testid | element |
 | --- | --- |
 | `gradebook-term-gpa` | landing: the selected term's credit-weighted GPA next to the chips (absent while the term has no graded work) |
+| `gradebook-upload-syllabus` | landing: the blank-semester empty state's "Upload syllabus" CTA (`ui/EmptyState` action slot) |
 | `gradebook-transcript-open` | landing: "Transcript" button opening the transcript modal |
 | `gradebook-transcript-gpa` | transcript modal: the cumulative GPA value |
 | `gradebook-transcript-retry` | transcript modal: inline "Try again" after a failed load (#463 catch+toast pattern) |

.github/workflows/e2e.yml

@@ -83,6 +83,12 @@ jobs:
  # Dummy on purpose: the below-seam RAG embed path (#439) must not
  # be able to bill; its failures are swallowed by design.
  GEMINI_API_KEY: e2e-dummy-key-no-billing
+ # #537: the quiz-generation guard keeps its sliding window in a
+ # process-local dict, so ONE Playwright run shares a single
+ # 8-per-300s budget across every spec and the quiz specs that run
+ # last 429. e2e-up.sh sets the same value; kept here so what the
+ # lane actually runs under is visible beside the rest of the seam.
+ QUIZ_GENERATE_RATE_LIMIT: "1000"
  run: make e2e-up
 
  - name: Run Playwright suite

backend/.env.example

@@ -69,3 +69,12 @@ GEMINI_VISION_OCR_ENABLED=false
 GEMINI_VISION_OCR_MAX_PAGES=10
 # The transcription model is the ADR-0008 per-task slot, not a knob of its own:
 # SAPLING_MODEL_OCR_VISION=gemini-2.5-flash
+
+# Quiz generation abuse guard (#544 F1; env-overridable since #537). The window
+# lives in a process-local dict, so ONE Playwright run spends a single budget
+# across every spec — the E2E lanes raise this; production keeps the default.
+# Unparseable or non-positive values fall back to the default.
+# QUIZ_GENERATE_RATE_LIMIT=8
+# Sliding-window length for that limit, in seconds. E2E lanes raise the limit
+# rather than shrink the window; production keeps the default.
+# QUIZ_GENERATE_RATE_WINDOW_SEC=300

backend/services/quiz_config.py

@@ -9,6 +9,41 @@
 Standalone constants module: no imports from models/routes/services so
 it can be imported from anywhere without cycles.
 """
+import logging
+import os
+
+logger = logging.getLogger(__name__)
+
+
+def _positive_int_env(name: str, default: int) -> int:
+ """A deployment override for one guard constant, read at import.
+
+ Deliberately fail-SAFE rather than fail-fast: an unparseable or
+ non-positive value falls back to the shipped default (the conservative
+ one) with a warning, so a stray env var cannot boot the app with a
+ disabled guard — or refuse to boot at all. Read once at import time,
+ which is also when `routes/quiz.py` binds the value, so a mid-process
+ `os.environ` change has no effect.
+ """
+ raw = os.getenv(name)
+ if raw is None or not raw.strip():
+ return default
+ try:
+ value = int(raw.strip())
+ except ValueError:
+ logger.warning(
+ "quiz_config: %s=%r is not an integer — using the default %d",
+ name, raw, default,
+ )
+ return default
+ if value <= 0:
+ logger.warning(
+ "quiz_config: %s=%d is not positive — using the default %d",
+ name, value, default,
+ )
+ return default
+ return value
+
 
 QUIZ_MIN_QUESTIONS = 1
 
@@ -87,8 +122,18 @@ def mastery_after(before: float, *, score: int, total: int) -> float:
 # The rate limit is sized for a human: a student comparing difficulties or
 # retaking a concept might legitimately generate a handful of quizzes in a
 # few minutes; nobody legitimately generates 10 in one.
-QUIZ_GENERATE_RATE_LIMIT = 8
-QUIZ_GENERATE_RATE_WINDOW_SEC = 300 # 5 minutes
+#
+# Both are env-overridable (#537) for one reason: `request_limits._rate_state`
+# is a module-level dict, so a whole Playwright run — every spec, every
+# worker-shared window — spends ONE 8-per-300s budget that only a backend
+# restart clears. The redesigned quiz lane needs ~20 real generations, and a
+# function-mode generation costs nothing, so the E2E stacks raise the limit
+# (scripts/e2e-up.sh, .github/workflows/e2e.yml). Production sets neither and
+# keeps the defaults below.
+QUIZ_GENERATE_RATE_LIMIT = _positive_int_env("QUIZ_GENERATE_RATE_LIMIT", 8)
+QUIZ_GENERATE_RATE_WINDOW_SEC = _positive_int_env(
+ "QUIZ_GENERATE_RATE_WINDOW_SEC", 300, # 5 minutes
+)
 
 # Daily per-user LLM spend ceiling. The SPEND it measures is cross-feature
 # (llm_usage records every agent call, not just quiz ones), but the ceiling

backend/tests/test_quiz_cost_observability_f.py

@@ -132,6 +132,87 @@ def test_limit_is_per_user(self):
  assert other.status_code == 200
 
 
+class TestGenerateRateLimitIsEnvOverridable:
+ """#537: the two guard constants read the environment; defaults intact.
+
+ `request_limits._rate_state` is module-level, so a whole Playwright run
+ shares ONE window that only a backend restart clears — and the redesigned
+ quiz lane needs more generations than any human would. The E2E stacks
+ raise the limit through the environment; production sets nothing and must
+ keep the shipped defaults.
+ """
+
+ @staticmethod
+ def _reloaded():
+ """Re-import services.quiz_config against the current environment.
+
+ `importlib.reload` mutates the module in place, so every caller must
+ restore it (see `_restore`) or later tests inherit the override.
+ """
+ import importlib
+
+ from services import quiz_config
+
+ return importlib.reload(quiz_config)
+
+ @classmethod
+ def _restore(cls):
+ cls._reloaded()
+
+ def test_defaults_hold_when_unset(self, monkeypatch):
+ monkeypatch.delenv("QUIZ_GENERATE_RATE_LIMIT", raising=False)
+ monkeypatch.delenv("QUIZ_GENERATE_RATE_WINDOW_SEC", raising=False)
+ try:
+ cfg = self._reloaded()
+ assert cfg.QUIZ_GENERATE_RATE_LIMIT == 8
+ assert cfg.QUIZ_GENERATE_RATE_WINDOW_SEC == 300
+ finally:
+ monkeypatch.undo()
+ self._restore()
+
+ def test_an_override_is_honoured(self, monkeypatch):
+ monkeypatch.setenv("QUIZ_GENERATE_RATE_LIMIT", "1000")
+ monkeypatch.setenv("QUIZ_GENERATE_RATE_WINDOW_SEC", "60")
+ try:
+ cfg = self._reloaded()
+ assert cfg.QUIZ_GENERATE_RATE_LIMIT == 1000
+ assert cfg.QUIZ_GENERATE_RATE_WINDOW_SEC == 60
+ finally:
+ monkeypatch.undo()
+ self._restore()
+
+ def test_a_junk_override_falls_back_to_the_default(self, monkeypatch):
+ """Fail-safe, not fail-fast: a stray value must neither disable the
+ guard (limit=0 would 429 everyone, a negative window never expires)
+ nor stop the app from booting."""
+ for bad in ("", " ", "eight", "0", "-5", "3.5"):
+ monkeypatch.setenv("QUIZ_GENERATE_RATE_LIMIT", bad)
+ monkeypatch.setenv("QUIZ_GENERATE_RATE_WINDOW_SEC", bad)
+ try:
+ cfg = self._reloaded()
+ assert cfg.QUIZ_GENERATE_RATE_LIMIT == 8, bad
+ assert cfg.QUIZ_GENERATE_RATE_WINDOW_SEC == 300, bad
+ finally:
+ monkeypatch.undo()
+ self._restore()
+
+ def test_the_route_still_enforces_whatever_was_resolved(self):
+ """The env seam moves the NUMBER, never the behaviour: the route binds
+ the value at its own import and still 429s one call past it."""
+ from routes import quiz as quiz_route
+ from services.quiz_config import QUIZ_GENERATE_RATE_LIMIT
+
+ assert quiz_route.QUIZ_GENERATE_RATE_LIMIT == QUIZ_GENERATE_RATE_LIMIT
+ run = AsyncMock(return_value=SimpleNamespace(output=_quiz()))
+ with (
+ patch("routes.quiz.table", side_effect=_factory()),
+ patch("routes.quiz.quiz_agent.run", new=run),
+ ):
+ for _ in range(quiz_route.QUIZ_GENERATE_RATE_LIMIT):
+ assert _generate().status_code == 200
+ assert _generate().status_code == 429
+
+
 class TestDailySpendGuard:
  def test_over_budget_user_is_refused_before_the_model_runs(self):
  from services.quiz_config import QUIZ_DAILY_SPEND_CAP_USD

docs/e2e-exploration.md

@@ -226,7 +226,10 @@ byte-for-byte match to one of `function_handlers_e2e.py`'s `E2E_DOC_*` (or
 `E2E_TUTOR_REPLY`, `E2E_QUIZ_*`) constants — here, `E2E_DOC_ABSTRACT`'s
 "gradient descent... loss surface... learning rate" wording and the fixed
 `lecture_notes` category. If a finding's "wrong" content matches one of
-those constants verbatim, it's the seam, not the app — drop it, and if it
+those constants verbatim, it's the seam, not the app (likewise the quiz's
+"Only 3 questions were ready for this concept" toast: the function-mode quiz handler always
+returns exactly 3 questions, so any requested length above 3 is reported as a short delivery —
+the honesty check working, not a generation bug) — drop it, and if it
 recurs, improve `scripts/explore/explorer-prompt.md`'s ground rules to name
 the pattern explicitly so a future explorer recognizes it before writing the
 stub, rather than filing an issue against the harness's own known-fixed

docs/frontend-testids.md

@@ -71,7 +71,7 @@ renders the element.
 | Onboarding | `onboarding` | `frontend/src/components/screens/Onboarding.tsx` (the first-run funnel, rendered bare outside `(shell)`) |
 | Upload modal | `upload-modal` | `frontend/src/components/DocumentUploadModal.tsx` |
 | Tutor | `tutor` | `frontend/src/components/chat/ChatPanel.tsx` (rendered by `screens/Learn.tsx`; + the session-resume rows in `src/components/screens/Learn.tsx` itself) |
-| Quiz | `quiz` | `frontend/src/components/QuizPanel.tsx` (rendered by `screens/Quiz.tsx`) |
+| Quiz | `quiz` | `frontend/src/components/quiz/**` — `QuizScreen.tsx` (route root + error card) switching on phase between `home/QuizHome.tsx` (+ `ConceptDialog`/`AdjustDialog`/`PickList`/`QuizSettings`), `question/QuizQuestion.tsx` (+ `AskPanel`/`LeaveDialog`) and `results/QuizResults.tsx` (+ `MissedList`); the ids on the shared `ui/` primitives and `graph/ConceptNeighbourhood.tsx` are passed in from those files as a `testid` prop (#537) |
 | Knowledge graph | `graph` | `frontend/src/components/graph/KnowledgeGraph.tsx` (wrapper: container root + mode toggle) plus `KnowledgeGraph2D.tsx`/`KnowledgeGraph3D.tsx` (the render/data-layer seam — hidden a11y node list, SVG node/edge marks, zoom controls — added with the #395 graph-integrity journey) |
 | App shell | `app` | `frontend/src/components/ShellFrame.tsx` (the authed layout frame every `(shell)` route renders inside) |
 | Study rooms | `social` | `frontend/src/components/screens/Social.tsx` (rooms sidebar, chat, overview, study match, directory — added with the #394 two-context journey) |
@@ -95,8 +95,16 @@ route:
  and the send `<button>` render in `ChatPanel.tsx`. `ChatPanel` has exactly one
  consumer (Learn), so tagging it there is unambiguous. The notetaker's chat is
  a separate `AIChatPanel` and is out of scope.
-- **Quiz.** `screens/Quiz.tsx` only fetches concepts and mounts `QuizPanel`;
- every answer/submit control renders in `QuizPanel.tsx`.
+- **Quiz.** The route mounts one component, `components/quiz/QuizScreen.tsx`,
+ which switches on phase between `home/QuizHome.tsx`,
+ `question/QuizQuestion.tsx` and `results/QuizResults.tsx`; each of the three
+ owns its own ids and its own dialogs. Three shared `ui/` primitives
+ (`AnswerOption`, `SegmentedControl`, `Sheet`) are in the eslint file list too:
+ the controls render inside them, so a testid-less `<button>` there would
+ un-anchor the surface from outside the screen files. Those primitives — plus
+ `ui/EmptyState`, `ui/InlineBanner`, `ui/ProgressDots` and
+ `graph/ConceptNeighbourhood` — take the id as a `testid` prop, so the value is
+ always written at the quiz call site, never inside the primitive.
 
 ## Current inventory
 
@@ -174,22 +182,87 @@ route:
 
 ### `quiz`
 
+The quiz is one surface: `components/quiz/QuizScreen.tsx` reads the entry off
+the URL and switches on phase between `home/QuizHome.tsx`,
+`question/QuizQuestion.tsx` and `results/QuizResults.tsx`. The table is grouped
+in that order; the screen-level ids (the error card) come last, followed by the
+entry points the quiz wave added inside other surfaces' files.
+
+Three ids are **renamed** from the pre-#537 quiz — same role, clearer name:
+`quiz-exit` → `quiz-leave`, `quiz-retake` → `quiz-again`,
+`quiz-explain-concept` → `quiz-ask`. Eleven are **kept** verbatim so existing
+journeys keep anchoring: `quiz-panel`, `quiz-start`, `quiz-cancel`,
+`quiz-answer-options`, `quiz-answer-option-{label}`, `quiz-submit-answer`,
+`quiz-next`, `quiz-review-verdict`, `quiz-results-score`,
+`quiz-results-mastery`, `quiz-done`.
+
 | testid | element |
 | --- | --- |
-| `quiz-panel` | panel root (all phases) |
-| `quiz-cancel` | "Cancel" (select phase) |
-| `quiz-start` | "Start quiz" |
+| `quiz-home` | quiz-home root (`phase: home \| configuring`) |
+| `quiz-resume-strip` | the "you left a quiz on X" banner (`ui/InlineBanner`) |
+| `quiz-resume` | "Resume" on that banner |
+| `quiz-resume-discard` | "Discard" — hides the attempt client-side; there is no abandon endpoint |
+| `quiz-proposal` | the "Ready for you" primary proposal card |
+| `quiz-start` | "Start" on that card |
+| `quiz-cancel` | "Cancel" — leaves for the entry source, or `/dashboard` when there is none |
+| `quiz-adjust` | "adjust" on the card — toggles the adjust dialog (`aria-pressed`) |
+| `quiz-alternative-{nodeId}` | one "Also worth a look" row |
+| `quiz-review-due` | "Review everything due" row |
+| `quiz-pick-open` | "Pick something specific →" |
+| `quiz-pick-list` | the grouped concept list it reveals |
+| `quiz-pick-{nodeId}` | one concept row in that list |
+| `quiz-pick-back` | "← Back" out of that list |
+| `quiz-empty-state` | the home's empty states (`ui/EmptyState`) — no courses, empty tree, or nothing left to propose; they are alternatives, so only one ever mounts |
+| `quiz-home-error` | the home's load-failure card |
+| `quiz-home-retry` | "Retry" inside it |
+| `quiz-concept-dialog` | the concept dialog opened from an alternative or a pick row |
+| `quiz-concept-start` | "Start · {count} {difficulty}" inside it |
+| `quiz-concept-cancel` | its "Cancel" |
+| `quiz-adjust-dialog` | "Adjust this quiz" dialog |
+| `quiz-adjust-done` | its "Done" — keeps the settings without starting |
+| `quiz-adjust-start` | its "Start · {count} {difficulty}" — saves and starts in one |
+| `quiz-seg-count` / `quiz-seg-difficulty` / `quiz-seg-feedback` | the three `ui/SegmentedControl`s both dialogs share; each option is `${testid}-${value}` |
+| `quiz-generating` | the skeleton question screen while a quiz is being written |
+| `quiz-panel` | question root (`phase: active \| answered`) |
+| `quiz-progress` | the question rail's progress dots (`ui/ProgressDots`) |
 | `quiz-answer-options` | answer radiogroup |
-| `quiz-answer-option-{label}` | one answer choice, suffixed with its label (`A`…) |
-| `quiz-submit-answer` | "Submit answer" |
-| `quiz-exit` | "Exit" (active phase) |
+| `quiz-answer-option-{label}` | one answer choice (`ui/AnswerOption`), suffixed with its label (`A`…) |
+| `quiz-submit-answer` | the footer's primary button while the answer is unrevealed |
+| `quiz-next` | the same footer button once the verdict is showing — "Next question" / "See results" |
 | `quiz-review-verdict` | "Correct." / "Not quite." banner |
-| `quiz-explain-concept` | "Explain this" |
-| `quiz-next` | "Next question" / "See results" |
-| `quiz-results-score` | the score percentage |
-| `quiz-results-mastery` | the "X / Y correct · mastery B% → A%" line |
-| `quiz-retake` | "Retake" |
-| `quiz-done` | "Done" |
+| `quiz-flag` | "This question is confusing" (toggles, `aria-pressed`; persists nothing) |
+| `quiz-ask` | "Ask about this" — opens the tutor sheet |
+| `quiz-leave` | "Leave" |
+| `quiz-leave-dialog` / `quiz-leave-cancel` / `quiz-leave-confirm` | the leave confirmation |
+| `quiz-ask-panel` | the tutor sheet (`ui/Sheet`) |
+| `quiz-ask-panel-close` | its × — the `Sheet` derives it as `${testid}-close` |
+| `quiz-ask-seed` | the composed first message shown at the top of the sheet |
+| `quiz-ask-retry` | "Try again" when the tutor stream failed |
+| `quiz-ask-input` / `quiz-ask-send` | the sheet's composer |
+| `quiz-results` | results root |
+| `quiz-results-graph` | the concept neighbourhood above the score (`graph/ConceptNeighbourhood`) |
+| `quiz-results-score` | the "{n} of {total} correct" line — a count, not a percentage |
+| `quiz-results-mastery` | the mastery delta line, "B% → A% · tier-before → tier-after" |
+| `quiz-results-xp` | "+{Δ} XP · {streak}-day streak" — absent when either gamification read failed |
+| `quiz-results-perfect` | the line shown instead of the missed list on a clean sweep |
+| `quiz-missed-list` | the "to look at" section |
+| `quiz-missed-{questionId}` | one missed item |
+| `quiz-missed-explain-{questionId}` | its "Show explanation" disclosure |
+| `quiz-missed-ask-{questionId}` | its "Ask about this" |
+| `quiz-practise-missed` | "Practise the one(s) you missed" |
+| `quiz-next-concept` | "Next: {concept} →" while the scope queue has more |
+| `quiz-again` | "Keep going — quiz again" (mounts in `quiz-practise-missed`'s place on a clean sweep) |
+| `quiz-back-to-source` | the secondary exit, labelled by where the quiz was entered from |
+| `quiz-done` | "Done" — back to `/quiz` |
+| `quiz-error` | the route-level error card (mapped copy + retry/back), rendered by `QuizScreen` in place of the phase |
+| `quiz-error-retry` / `quiz-error-back` | its "Try again" and "Back" |
+| `tree-node-recent-quizzes` | the tree node panel's "Recent quizzes" block (`screens/Tree.tsx`) |
+| `tree-node-recent-quiz-{attemptId}` | one row in it, suffixed with the attempt's `quiz_id` per the stable-domain-id rule |
+| `dashboard-review-due` | the "Review what's due" quiz entry point (`screens/Dashboard.tsx`) — three call sites, but exactly one mounts for a given layout/viewport |
+
+The last three carry another surface's prefix because they render in that
+surface's file. They are listed here because they are quiz entry points, and a
+quiz journey is what drives them.
 
 ### `graph`
 
@@ -279,6 +352,9 @@ never collide in the DOM.
 | `dashboard-courses-manage` | the cog inside the expanded key that opens the Courses & Semesters hub (the hub's own semester tabs are plain text buttons — journeys select them by role/name, e.g. "All semesters" / "Fall 2025") |
 | `dashboard-resume-{sessionId}` | a "Where you left off" card — deep-links to `/learn?resume={sessionId}` (#164), suffixed with the session's own id per the stable-domain-id rule |
 
+`dashboard-review-due` also lives in `screens/Dashboard.tsx`; it is documented
+with the `quiz` surface it links into.
+
 ### `calendar`
 
 Added with the #185 load-failure fix (a failed initial fetch must be
@@ -300,6 +376,7 @@ inside the `role="grid"` "Courses" grid.
 | testid | element |
 | --- | --- |
 | `gradebook-term-gpa` | landing: the selected term's credit-weighted GPA next to the chips (absent while the term has no graded work) |
+| `gradebook-upload-syllabus` | landing: the blank-semester empty state's "Upload syllabus" CTA (`ui/EmptyState` action slot) |
 | `gradebook-transcript-open` | landing: "Transcript" button opening the transcript modal |
 | `gradebook-transcript-gpa` | transcript modal: the cumulative GPA value |
 | `gradebook-transcript-retry` | transcript modal: inline "Try again" after a failed load (#463 catch+toast pattern) |