Curio/docs/implementation-plan.md

Curio — Implementation Plan (12 features)

Audience: Claude Sonnet, executing one feature at a time. Each section is self-contained: goal, verified current state (with file refs), changes, tests, and acceptance criteria.

This plan was written after mapping the codebase on 2026-06-23. Verify file:line refs before editing — code may have moved.

Global conventions (apply to every feature — non-negotiable)

These come from CLAUDE.md and the spec. Violating them is a bug:

1. All LLM calls go through src/lib/llm/client.ts. Never call a provider/AI-SDK model directly. Generator and grader must differ.
2. Prompts live in the versioned registry src/lib/llm/prompts/index.ts ({ id, version, template }). Never inline a prompt. Bump version on any semantic change.
3. Contracts are Zod schemas in src/schemas/, shared by LLM ↔ API ↔ UI. Validate LLM structured output against them.
4. Serve path reads the buffer; jobs generate. No synchronous generation in request handlers except the documented cold-start gate. Postgres is source of truth.
5. Paid background jobs are idempotent (idempotency key + durable jobs ledger row). A retry must never regenerate-and-rebill.
6. Per-session token budget is enforced in code (src/lib/budget/index.ts) — call checkBudget before any new paid LLM call, recordUsage after.
7. Migrations are append-only. Never edit an applied migration. Add a new one via pnpm db:generate then pnpm db:migrate. (Note: the migrations dir already contains a few accidental duplicate migrations — do not "fix" them, just add new ones.)
8. i18n: every user-facing string goes in BOTH messages/en.json and messages/fr.json under the right namespace, read via useTranslations (client) or getTranslations (server). No hardcoded copy.
9. Tests with every change. Unit tests mock the LLM (Vitest, deterministic fixtures). Real-model calls only in tests/golden/. Run pnpm test before declaring done.
10. Design quality floor: responsive, visible keyboard focus, reduced-motion respected, WCAG-AA contrast, dark-mode tokens. Reading surface stays calm/editorial; no gamification.

Stack reference: Next.js 15 App Router + React 19, Drizzle + Postgres/pgvector, Redis (ioredis + Upstash ratelimit), BullMQ workers (jobs/, run via pnpm workers), Vercel AI SDK, next-auth v5 (JWT), next-intl, nodemailer (SMTP), Langfuse. Vitest + Playwright.

---

Suggested execution order

Dependency-aware. Do them in this order unless told otherwise:

1. #7 (audit migration) — small, de-risks the account story others build on.
2. #10 (dark-mode polish) — small, isolated; extracts the setTheme helper #13 reuses.
3. #13 (settings upgrade) — needs #10's setTheme helper; otherwise self-contained UI.
4. #12 (review upgrade) — extracts the shared grading hook from the lesson reader.
5. #2 (content versioning) — foundational; #1 and #3 lean on version/provenance.
6. #1 (novel-misconception harvest loop) — moat; table already exists.
7. #3 (false-fail dashboard) — consumes #1's labeled data + grades.
8. #6 (multi-lesson journey) — product; #5 and #11's due-zone build on journey/mastery state.
9. #11 (mastery upgrade) — surfaces due reviews; pairs with #6/#5.
10. #5 (returning-learner home) — product; needs #6's journey state.
11. #9 (streaming generation) — infra polish.
12. #8 (due-review email digest) — retention; independent, do last.

UI features (#11/#12/#13) are loosely ordered — they can move earlier if a UI pass is wanted sooner; only #13→#10 (theme helper) and #12→lesson-reader (shared hook) are hard dependencies.

Each feature is one focused PR/commit. Keep Route Handlers thin; logic in src/lib/.

---

#7 — Anonymous → account progress migration (AUDIT + HARDEN)

Status: already implemented. This is an audit/harden task, NOT a build.

Current state (verified):

• src/app/api/auth/migrate-session/route.ts exists. In a transaction it reassigns responses, mastery (with on-conflict skip when the auth user already has that concept), and journeyInstances from anonUserId → authUserId, then renames the Redis budget:{id} key. Has __tests__/.
• Called from src/app/auth/login/login-client.tsx and src/app/auth/register/page.tsx after auth success; clears sessionStorage curio_uid.

Goal: make it correct and complete, not bigger.

Changes / checks:

1. Mastery conflict policy. Today conflicting concepts are skipped (anon progress dropped). Decide intended behavior: keep the higher score / more-recent lastSeen instead of silently dropping. If changing, do it in the onConflictDoUpdate and document why.
2. Auth coverage. Confirm migration fires for ALL sign-in paths: credentials login, register, AND OAuth (Google/GitHub/OIDC) first sign-in. OAuth users never hit login-client.tsx. Add a migration trigger on the OAuth callback path (e.g. a client effect on first authenticated landing, or a signIn event in src/auth.ts events) — without it, OAuth users lose anon progress.
3. Idempotency / double-call. Calling migrate twice (or with no anon data) must be a no-op, not an error. Verify.
4. Validation & authz. The route must take anonUserId from the request but authUserId strictly from the server session (never trust a client-supplied authUserId). Confirm a malicious anonUserId can only move data INTO the caller's own account.
5. accounts/sessions tables must not be touched by migration (those are auth-adapter owned).

Tests: extend migrate-session/__tests__: (a) conflict resolution keeps best mastery; (b) OAuth-path migration; (c) double-call no-op; (d) authz — session id always wins over body.

Acceptance: A user who learns anonymously, then signs up OR logs in via any provider, keeps all mastery/responses/journey. No data loss on concept conflicts. pnpm test green.

---

#10 — Dark mode (AUDIT + POLISH)

Status: already implemented. Audit/polish task.

Current state (verified):

• src/styles/tokens.css has a full dark token block under :root[data-theme='dark'] plus a @media (prefers-color-scheme: dark) fallback for :root:not([data-theme='light']).
• src/app/layout.tsx runs a no-flash theme bootstrap (reads localStorage('curio-theme'), sets data-theme on <html>).
• src/components/site-header.tsx has a ThemeToggle cycling system → dark → light.

Goal: verified-correct dark mode on every surface + a settings entry.

Changes:

1. Settings selector. Add a theme control to src/app/settings/settings-client.tsx (System / Light / Dark) that writes the same localStorage('curio-theme') key + data-theme the header toggle uses (share one helper — extract setTheme() to e.g. src/lib/theme.ts). Add i18n keys under settings.appearance.* in both locales.
2. Contrast audit (WCAG-AA, spec §7.5 non-negotiable). Verify every diagnosis-state color in dark mode meets AA against its background: --color-mastered/partial/misconception/uncertain and their -subtle pairs, plus --color-tutor marginalia and accent on --color-surface. Fix any token that fails. This is the highest-risk part — the diagnosis colors carry meaning.
3. Surface sweep. Manually verify dark rendering on: home, learn/reading surface + marginalia, checkpoint input, review, mastery map, auth pages, admin, settings. Look for hardcoded colors (e.g. #fff) that ignore tokens — grep -rn "#fff\|#000\|rgb(" src/app src/components src/styles and replace with tokens.
4. Persisted preference (optional). If a user is logged in, persist theme in users.preferences (jsonb already exists) so it follows them across devices; localStorage remains the anon/no-flash source.

Tests: unit test the setTheme helper. Playwright: toggle to dark, assert data-theme="dark" on <html> and a known token's computed value.

Acceptance: Theme switchable from header AND settings; persists; no flash on reload; all diagnosis colors pass AA in both themes; no hardcoded non-token colors remain on core surfaces.

---

#2 — Content versioning + lazy invalidation

Goal: when a blueprint's generator model or prompt version changes, mark its content stale and regenerate lazily (on next serve or via a job), without regenerate-and-rebill races. Spec §10 / invariant #10.

Current state (verified):

• blueprints.modelVersion (text) + blueprints.contentVersion (int, default 1). segments.contentVersion + checkpoints.contentVersion exist but are never incremented and never read (generate-blueprint.ts:~85 writes modelVersion = process.env.LLM_GENERATOR_MODEL, contentVersion = 1).
• Prompt registry has versions (e.g. GENERATE_LESSON is v5) but nothing ties a blueprint to the prompt version it was built with.
• jobs/promote-blueprint-job.ts already invalidates the Redis cache after promotion — reuse that invalidation primitive.

Define "current content signature": a tuple (generatorModel, generateLessonPromptVersion). Persist what each blueprint was built with; compare against current at serve/audit time.

Changes:

1. Schema migration: add blueprints.promptVersion (int) and blueprints.staleAt (timestamp, nullable). Optionally blueprints.lastBuiltModel if modelVersion semantics are ambiguous. Generate via pnpm db:generate.
2. Stamp on generation: in src/lib/generation/generate-lesson.ts / generate-blueprint.ts, write the current prompts.GENERATE_LESSON.version and generator model id at build time.
3. Staleness check: add src/lib/generation/staleness.ts exporting isBlueprintStale(blueprint): boolean (compares stored model+promptVersion to current config) and markStale(blueprintId).
4. Invalidation trigger: add an admin action (button on src/app/admin/blueprints/[id]) + an internal function to mark a blueprint stale and bump contentVersion. On the serve path (getLessonResponse in src/lib/db/queries.ts / src/app/learn/[key]/page.tsx), if stale, enqueue a regeneration job (do NOT regenerate synchronously) and keep serving the old version until the new one is ready (lazy invalidation — spec invariant #10).
5. Regeneration job: add jobs/regenerate-blueprint-job.ts (or extend generate-lesson-job) that regenerates segments/checkpoints at a new contentVersion, re-runs T0/T1 (and T2 at promotion), and swaps the cache. Idempotency key must include the target contentVersion so a retry never double-bills. Reuse the jobs ledger pattern from generate-lesson-job.ts.
6. Flagged-item regeneration: autoFlagCheckpointIfNeeded (already in queries.ts) sets a checkpoint to verifyStatus='fail'. Add an endpoint/admin action to regenerate just the flagged checkpoint at a bumped contentVersion (cheaper than whole-blueprint).

Tests: unit (LLM mocked): isBlueprintStale truth table; regeneration job bumps contentVersion and is idempotent under retry (same key → no second generation); serve path enqueues but does not block on stale.

Acceptance: Changing LLM_GENERATOR_MODEL or bumping the lesson prompt version causes new serves to enqueue regeneration; learners keep seeing valid old content until the new version verifies; retried jobs never double-generate; admin can force-regenerate a blueprint or a single flagged checkpoint.

---

#1 — Novel-misconception harvest loop

Goal: close the moat flywheel — turn novel-tagged grades into labeled misconceptions that grow the misconception library AND the golden set. Spec §10.2 / §10.4 / §15.

Current state (verified):

• grades.misconceptionTag can be 'novel'. src/lib/verification/grader.ts:~183 already enqueues novel cases into the novelMisconductQueue table ({ gradeId, checkpointId, responseText, evidenceSpan, processed:boolean default false, createdAt }, schema ~line 268).
• getPersonalizationContext (queries.ts:~394) already excludes 'novel' from personalization (only labeled misconceptions are used). So once a novel case is labeled into misconceptions, it automatically starts being used.
• There is no UI to review the queue, no labeling action, and no path from a labeled item into tests/golden/misconception-cases.ts. That's the gap.

Changes:

1. Queries (src/lib/db/queries.ts): getNovelQueue({ processed:false, limit }) returning queue rows joined with checkpoint + concept context; labelNovelMisconception({ queueId, conceptId, tag, signature, description, correction }) which (a) inserts a row into misconceptions with verifyStatus='pending', (b) marks the queue row processed=true, in one transaction; dismissNovelQueueItem(queueId) for false positives.
2. Admin page src/app/admin/misconceptions/ (new): list unprocessed queue items showing the learner response with the evidenceSpan highlighted (reuse the marginalia highlight idiom from grade-display.tsx), the checkpoint prompt, reference answer, and existing misconceptions for that concept. Provide a label form (tag, signature, description, correction) and a dismiss button. Add to admin nav (src/app/admin/layout.tsx).
3. Verification hook: after labeling, the new misconception is verifyStatus='pending'. Run it through the existing verifyMisconceptions (src/lib/verification/verify-misconceptions.ts) — either inline on label or via a small job — so only verified misconceptions go live.
4. Golden-set growth: add appendMisconceptionGoldenCase() that writes a new case to tests/golden/misconception-cases.ts (or a sibling JSON the runner reads). At minimum, the admin label action should offer "also add as golden case" producing { response, expectedTag, conceptId }. Keep the golden file the source of truth for the eval.
5. Optional clustering: if the queue is large, add a cheap-model job to cluster similar novel responses (group by embedding similarity of responseText) so a human labels a cluster once. Use client.cheapGrader / embedText. Defer if time-boxed.

Tests: unit (LLM mocked): labeling inserts misconception + flips processed atomically; dismiss leaves no misconception; labeled+verified misconception appears in getPersonalizationContext for that concept. Add ≥2 new cases to misconception-cases.ts and confirm pnpm test:golden:misconceptions still passes thresholds.

Acceptance: An admin can see novel responses, label or dismiss them; labeled items become verified misconceptions used in future grading/personalization; the golden set grows; the queue drains (processed=true). No new uncontrolled LLM cost on the serve path.

---

#3 — False-fail monitoring dashboard

Goal: make the spec's core quality metric — false-fail rate (telling a correct learner they're wrong) — continuously visible, not just a CI gate. Spec §15.

Current state (verified):

• tests/golden/run-grading-eval.ts computes false-fail rate and verdict accuracy against frozen cases; CI-gated (pnpm test:golden, fails if false-fail > 10% or accuracy < 70%). Writes no persistent results (console only).
• Live signal exists but isn't aggregated: grades (verdict, confidence, payloadJson), contentReports with reason='grade_wrong' (learner-disputed grades), getCheckpointFailureRate + autoFlagCheckpointIfNeeded in queries.ts.
• src/app/admin/reports/ lists raw content reports; no metrics/aggregation.

Two data sources, show both:

• Offline (golden): trend of false-fail rate / accuracy per eval run.
• Online (production): grade_wrong report rate vs total grades; misconception/uncertain verdict distribution; checkpoints auto-flagged.

Changes:

1. Persist golden runs: new table eval_runs (id, suite, falseFailRate, accuracy, total, model, promptVersion, gitSha nullable, createdAt). Make run-grading-eval.ts (and the content/misconception runners) insert a row at the end (guard behind an env flag so local runs can skip DB writes). Keep console output.
2. Aggregation queries (src/lib/db/queries.ts or src/lib/metrics.ts): getEvalTrend(suite, limit); getOnlineGradeMetrics(window) → counts by verdict, grade_wrong report rate, # auto-flagged checkpoints, optionally per-blueprint.
3. Admin dashboard src/app/admin/quality/ (new; link in admin nav): show latest false-fail rate with the 10% threshold marked (red if breached), a small trend (sparkline/table) from eval_runs, the online verdict distribution, and a list of checkpoints with the highest dispute/failure rate (drill into /admin/blueprints/[id]). Keep it calm and tabular — admin tool, not the learner surface.
4. Alerting (optional): if the latest persisted false-fail rate breaches threshold, surface a banner on /admin.

Tests: unit: aggregation queries over seeded grades/reports return correct counts and rates; eval_runs insert is gated by env flag. No need to run real models in unit tests.

Acceptance: After a golden run, the admin quality page shows the latest + historical false-fail rate against the threshold; production grade/dispute metrics are visible; high-dispute checkpoints are findable. False-fail is now observable continuously.

---

#6 — Multi-lesson journey continuity

Goal: a Journey is a sequence of bounded lessons through a blueprint, not a single lesson. Let a learner finish lesson N and continue to N+1, with visible progress. Spec §1, §3.

Current state (verified):

• blueprints → concepts (ord) → lessons (ord, depth, locale) → segments → checkpoints. journeyInstances.position is incremented by advanceJourneyPosition (queries.ts:~675) on lesson complete, but nothing reads position and there is no next-lesson chaining. /learn/[key] serves one lesson per intent (getLessonResponse).
• LessonComplete in lesson-reader.tsx calls POST /api/advance then shows "Progress saved" — a dead end.

Decision to confirm with product: does one blueprint contain multiple lessons (multi-lesson per intent), or is each intent one lesson and a "journey" spans related blueprints? The schema supports multiple lessons per blueprint (lessons.ord), so default assumption: multiple lessons per blueprint, ordered by lessons.ord. Generation currently makes one lesson — extending generation to produce a multi-lesson arc is a larger content change; for this feature, support serving and navigating multiple lessons and generate subsequent lessons lazily on advance.

Changes:

1. Serve by position: extend getLessonResponse (or add getLessonAtPosition(intentKey, userId, position, ...)) to return the lesson at the learner's current journeyInstances.position (default 0 → first lesson by lessons.ord). /learn/[key]/page.tsx reads the user's position to pick the lesson.
2. Advance → next: on lesson complete, after advanceJourneyPosition, if a next lesson exists (or can be generated), navigate to it (e.g. /learn/[key]?pos=N or just re-fetch since position advanced). If the next lesson isn't generated yet, enqueue generate-lesson-job for (blueprintId, ord=position) and show the outline/poll state (reuse existing polling). If no next lesson and the blueprint is complete, show a real "Journey complete" terminal state (not just "saved").
3. Lesson generation for position N: generate-lesson.ts / generate-lesson-job.ts currently assume ord 0. Parameterize by ord/position and pass the concept(s) for that position. Idempotency key must include ord.
4. Progress UI: add a journey progress indicator to the reading surface header (e.g. "Lesson 2 of 5") sourced from lessons count + position. Calm, non-gamified (spec §7). i18n both locales.
5. Cross-check #5: the returning-home "continue" surface will read the same journeyInstances + position.

Tests: unit (LLM mocked): position increments serve the next lesson; terminal state when position ≥ lesson count; advance enqueues generation for an ungenerated next lesson with an ord-scoped idempotency key. Playwright: complete a lesson → land on the next or a real completion screen.

Acceptance: Completing a lesson advances to the next lesson in the blueprint (generating it lazily if needed) with a visible "Lesson N of M"; finishing the last lesson shows a Journey-complete state; position persists per user. No synchronous generation on the serve path.

---

#5 — Returning-learner home

Goal: give the second visit a story — resume in-progress journeys, see due reviews, glance at mastery — instead of only an intent box. Spec §16 (mastery map, Daily Review).

Current state (verified):

• src/app/page.tsx is intent entry only (title, lede, input, depth/mode, example chips, "spark"). No resume surface.
• Data already available: journeyInstances (position) — after #6 this is meaningful; getMasteryMap(userId); getReviewCheckpoints(userId) / getDueReviews. Anonymous users have a curio_uid; logged-in users have session.user.id.

Changes:

1. Detect "returning": a learner is "returning" if they have any journeyInstances, mastery, or due reviews. For anon users this requires the client curio_uid; the home page is a client component already, so fetch on mount (or add a GET /api/home-summary?userId= that returns { inProgress: [{intentKey, title, position, total}], dueReviewCount, recentMastery: [...] }). For logged-in users, prefer the session id.
2. New endpoint src/app/api/home-summary/route.ts: aggregates in-progress journeys (join journeyInstances → blueprints, compute position/total), dueReviewCount (from getReviewCheckpoints), and a small recent-mastery slice. Reuse existing queries; add a getInProgressJourneys(userId) query.
3. Home UI: when summary is non-empty, render (above or beside the intent box) a calm "Continue" section: resume cards linking to /learn/[intentKey] (which #6 resolves to the right lesson via position), a "Review (N due)" link to /review when dueReviewCount > 0, and a "Mastery" link. When empty (first visit), show today's intent-first layout unchanged. Keep editorial calm; no streaks/XP (spec anti-pattern).
4. i18n: home.continue.*, home.dueReviews, etc., both locales.
5. Loading/empty states: skeleton while summary loads; never block the intent box on the summary fetch (intent entry must always be instant).

Tests: unit: getInProgressJourneys + home-summary aggregation over seeded data; empty summary → first-visit layout. Playwright: a user with progress sees Continue cards + due-review link; a fresh user sees only the intent entry.

Acceptance: Returning learners (anon or logged-in) land on a home that surfaces in-progress journeys, due-review count, and mastery, each one click away; first-time visitors see the existing clean intent entry; the intent box is never delayed by the summary.

---

#9 — Streaming generation (skeleton-first)

Goal: replace the 4-second poll with true streamed delivery so a cold-start lesson appears progressively. Spec §8.3 (skeleton-first + buffer).

Current state (verified):

• Cold start returns an outline state; src/components/lesson-reader.tsx:~97 polls router.refresh() every 4000ms until the lesson is ready. Generation runs in jobs/generate-lesson-job.ts (BullMQ), warming the Redis buffer.
• Vercel AI SDK supports streaming; client.ts uses structured output (generateObject-style). Lesson generation is schema-constrained, which complicates token-streaming of structured output.

Approach (pick the lower-risk one that fits):

• Option A — Stream segment-by-segment from the buffer (recommended). Keep generation in the job, but as each segment is generated + T0/T1-verified, push it to the Redis buffer (buffer:{...} per spec §17) and expose GET /api/lessons/stream?key=... as an SSE endpoint that emits segments as they land. LessonReader consumes the SSE and appends segments, replacing the poll. This honors invariant #4 (serve reads buffer, jobs generate) and degrades to the existing poll if SSE drops.
• Option B — Stream the model directly via streamObject for the reading text only (checkpoints still structured). More premium feel but riskier with schema validation + provenance (source_chunk_ids) + verification. Only if Option A is insufficient.

Changes (Option A):

1. Buffer incrementally: in generate-lesson-job.ts, write each verified segment to the Redis buffer as it completes (not only the whole lesson at the end). Keep the final whole-lesson cache write for the fast path.
2. SSE route src/app/api/lessons/stream/route.ts: Node runtime (not edge — needs timeout headroom), reads the buffer, emits segment events as they appear, a ready event when complete, and closes. Respect the per-session budget only for the generation job, not the read.
3. Client: in lesson-reader.tsx, when in outline/cold-start state, open an EventSource to the stream and append segments with the existing View-Transition reveal; fall back to the 4s poll if EventSource errors or is unsupported. Remove the poll once ready.
4. Reduced motion: segment-in animation must respect prefers-reduced-motion (already handled in reading.css).

Tests: unit: buffer write-per-segment ordering; SSE route emits segments then ready (mock the buffer). Playwright: cold-start lesson shows segments appearing without a full reload.

Acceptance: A cold-start lesson streams in segment-by-segment instead of popping after a 4s poll; falls back gracefully to polling; no synchronous generation on the request path; reduced-motion respected.

---

#8 — Due-review email digest

Goal: bring learners back when reviews are due — the spaced-repetition retention loop. Email infra already exists; only transactional sends today.

Current state (verified):

• src/lib/email/index.ts sendEmail({to,subject,html,text?}) over nodemailer SMTP (dev: jsonTransport→console). src/lib/email/templates.ts has verification/invite/reset templates. No scheduled sending.
• src/lib/memory/spaced-rep.ts (isDue, scheduleNextReview) + getReviewCheckpoints(userId) / getDueReviews give due items. mastery.nextReview is the schedule. Only logged-in users have an email (users.email); anon users can't be emailed.

Changes:

1. Digest template: add reviewDigestEmail({ name, dueCount, topConcepts, reviewUrl }) to templates.ts (+ both-locale subject/body via the user's users.locale). Calm, on the learner's side; one clear CTA to /review. No gamified streak language.
2. Recipient query (src/lib/db/queries.ts): getUsersWithDueReviews(now) → users with email IS NOT NULL, emailVerified, ≥1 mastery row where nextReview <= now, with a due count + a few concept names. Respect an opt-out preference (see 4).
3. Scheduled job: add a BullMQ repeatable job (or a cron-invoked Route Handler protected by a secret header, e.g. for Vercel Cron) jobs/review-digest-job.ts that runs daily, fetches due users, and sends at most one digest per user per day. Idempotency: key on (userId, yyyy-mm-dd) via the jobs ledger so a re-run never double-sends. Throttle/batch sends.
4. Opt-out: add emailDigest: boolean (default true) to users.preferences (jsonb exists) with a toggle in settings-client.tsx (+ i18n). Include an unsubscribe link (signed token route) in the email — required for good email hygiene.
5. Config: guard the whole feature behind an env flag (e.g. REVIEW_DIGEST_ENABLED) and document SMTP + cron setup in .env.example / docs.

Tests: unit (mock sendEmail): getUsersWithDueReviews filters correctly (no email / unverified / opted-out excluded); digest job sends once per user per day (idempotency key blocks re-send); unsubscribe flips the preference. Do not send real email in tests.

Acceptance: A daily job emails verified, opted-in users who have reviews due, at most once/day, idempotently, with a working unsubscribe and locale-correct copy; feature is env-gated and documented; anon users are never emailed.

---

#11 — Mastery page upgrade

Goal: turn the mastery page from a flat card grid into a calm "state of your learning" dashboard, and surface the actionable thing (due reviews). Spec §16 (mastery map). Stays editorial, non-gamified (spec §7).

Current state (verified):

• src/components/mastery-map.tsx — title + per-blueprint groups of ConceptCards (name, score bar, %, a small "due" tag). Data from GET /api/mastery?userId=. src/app/mastery/page.tsx just renders <MasteryMap/>. Styles live in src/styles/reading.css under .mastery-*.
• BUG (fix as part of this): mastery-map.tsx:39-43 scoreLabel() returns hardcoded French ("Maîtrisé/En cours/À revoir") in an i18n app — EN users see French. Also "Mastery Map", "Loading…", "due", and the empty-state string are hardcoded English. None go through useTranslations.

Changes:

1. Localize everything first (bug fix). Move all strings to messages/en.json + fr.json under a mastery.* namespace (title, loading, empty, due, status.mastered|learning|needsWork, overview labels). Read via useTranslations('mastery'). No hardcoded copy.
2. Overview header. Above the groups, a summary strip: counts of mastered / learning / needs-work and one progress meter (mastered ÷ total). Derive client-side from the fetched groups. Calm, tabular — not a gamified dashboard.
3. Due-for-review zone. Pull concepts where nextReview <= now into a top "Due for review (N)" section with a direct Start review → link to /review. Today "due" is a buried tag; it's the actionable item.
4. Sort + optional filter. Within each blueprint, order concepts needs-work → learning → mastered so weak spots rise. Optional filter chips (All / Due / Needs work) reusing the .home-chip pill idiom from app.css.
5. Card polish. Add marginalia status border-left using existing --color-mastered / --color-tutor / --color-misconception; demote the raw % to secondary; let the bar carry the signal. Keep the existing role="meter" a11y.
6. Empty state with CTA → link to home, not a dead sentence.

Tests: unit: scoreStatus/label mapping localized (no French leakage in en); overview counts correct over seeded groups; due-zone includes only nextReview <= now. Playwright: EN locale shows English status labels; due concept shows in the due zone with a working review link.

Acceptance: Mastery page opens with a counts overview + a meter, a prominent due-review zone linking to /review, status-ordered cards, and fully localized copy (no French for EN users). Passes the design floor in both themes.

---

#12 — Review page upgrade

Goal: make Daily Review diagnose as richly as a lesson and make the mastery movement visible — it's the whole point of reviewing. Spec §11 (memory engine), §4 (tutoring loop).

Current state (verified):

• src/components/review-reader.tsx — sequential carousel (currentIdx), per-item ScoreBar, CheckpointInput, GradeDisplay, Next/Finish. Data from GET /api/review?userId=.
• Degraded vs lessons: review-reader.tsx:~162 renders GradeDisplay WITHOUT onSocraticSubmit, onExplain, or the document.startViewTransition considering→reveal beat that lesson-reader.tsx uses. So partial verdicts in review have no Socratic probe, no re-explain, no motion.
• Completion is a flat "Session complete / scores updated".

Changes:

1. Restore full diagnosis (parity with lesson). Wire the same handlers lesson-reader.tsx uses: Socratic follow-up (/api/socratic), re-explain (/api/explain), and wrap the grade reveal in document.startViewTransition with the considering beat. Factor the shared grade-handling out of lesson-reader.tsx into a hook (e.g. src/components/use-checkpoint-grading.ts) so both readers share one implementation instead of diverging again.
2. Visible mastery delta. After grading, animate the ScoreBar from the pre-grade score to the new score (fetch/return updated mastery from the grade response or recompute) — e.g. "62% → 71% ↑". This is the payoff of review.
3. Session summary. Replace the terminal state with a real recap: concepts reviewed, net mastery change, count still due / next-due hint. Quiet, not a score screen.
4. Progress bar. Thin top bar with one segment per item filled as you go, replacing/augmenting the "N of M" text.
5. Keyboard flow. Cmd/Ctrl+Enter to submit, Enter to advance to next. Review is repetitive — keyboard makes it fast. Respect existing a11y/focus.

Tests: unit: shared grading hook drives both readers (partial verdict in review now exposes Socratic probe); delta computed correctly; summary aggregates per session. Playwright: complete a review item with a partial verdict → Socratic probe appears; finishing shows the recap with a net delta.

Acceptance: Review supports Socratic probe + re-explain + the reveal beat exactly like lessons (shared code path), shows the score moving per item, and ends on a meaningful session recap. Reduced-motion respected.

---

#13 — Settings page upgrade

Goal: bring Settings in line with the app's design system (tokens + CSS file, not inline styles), make it navigable, and reuse existing control idioms.

Current state (verified):

• src/app/settings/settings-client.tsx — one long stacked column: Profile, Language, Learning (age/difficulty/depth/hint), Security, Danger.
• DEBT (fix as part of this): the entire page is inline-styled via a const s = {} object (~lines 281-372), with hardcoded #fff on buttons (~354, ~366) and hardcoded error strings ("Failed to save.", "Linked: …", "Failed."). Violates the token-centralization convention (CLAUDE.md design invariants) and diverges from the home/reading idiom. Uses raw OS radios where home has polished segmented controls.

Changes:

1. De-inline (debt fix). Move all styles to a stylesheet (src/styles/settings.css, imported in globals.css, or extend app.css) using design tokens. Remove the s object and every #fff (→ --color-surface). This also makes the page dark-mode-correct.
2. Localize stray strings. "Failed to save.", "Linked:", "Failed." → settings.* i18n keys in both locales.
3. Two-column layout (desktop). Left = section nav (Profile / Learning / Language / Appearance / Security / Danger) as anchor links or tabs; right = panels. Single column on mobile. The page is long enough to warrant structure.
4. Reuse the segmented-control idiom. Replace the raw radio groups (age / difficulty / depth) with the home .home-depth-options-style pill segments for visual consistency. Keep them real <fieldset>/radio semantics for a11y.
5. Add the Appearance section (ties to #10). Theme selector (System / Light / Dark) sharing the extracted setTheme helper from src/lib/theme.ts. i18n settings.appearance.*.
6. Tighten the danger zone. Keep the type-your-email confirm; make the destructive button visually distinct (already uses --color-misconception) and the warning unmissable.

Tests: unit: locale change / preference save handlers unchanged and still call the right endpoints; no inline-style regressions (snapshot or lint rule if one exists). Playwright: section nav scrolls/switches panels; theme selector flips data-theme; settings render correctly in dark mode.

Acceptance: Settings uses tokens via a CSS file (no inline s object, no #fff), is navigable on desktop and stacks on mobile, reuses the segmented-control look, includes a working theme selector, and is fully localized — visually consistent with home and the reading surface in both themes.

---

Notes for the executor

• Confirm before large content changes. #6's "generate a multi-lesson arc" and #2's regeneration touch paid generation — keep them idempotent and budget-checked, and surface the design choice (multi-lesson-per-blueprint assumption) before building if anything contradicts it.
• Don't regress golden evals. #1 and #3 touch the grading/eval path. Run pnpm test:golden before/after; add cases, never weaken thresholds.
• Each feature: update CLAUDE.md if a convention changes, in the same commit.
• Keep the reading surface calm. Every UI addition (#3 dashboard, #5 home, #6 progress) must pass the design floor: responsive, AA contrast in both themes, visible focus, reduced-motion, no gamification.