diff --git a/README.md b/README.md
index 61c2611..7598fd8 100644
--- a/README.md
+++ b/README.md
@@ -33,28 +33,34 @@ npm run setup
npm run dev
```
-Then open http://localhost:3000. The defaults need no API keys or external accounts: the AI provider is a deterministic mock, email logs to the console, and calendar sync uses a local fake.
+Then open http://localhost:3000. The defaults need no API keys or external accounts: the AI provider is a deterministic mock, email logs to the console, and calendar sync uses a local fake. Signing up logs you straight in and drops you on the dashboard with a two step welcome.
-To be blunt about the default: mock mode exists for tests. With `AI_PROVIDER` set to `mock`, sessions get template questions and canned feedback, which exercises the machinery but teaches you nothing. To actually study, set `AI_PROVIDER` to `openai` and add an `OPENAI_API_KEY` in `.env`.
+To be blunt about the default: mock mode exists for tests. With `AI_PROVIDER` set to `mock`, sessions get canned questions and canned feedback, which exercises the machinery but teaches you nothing. To actually study, set `AI_PROVIDER` to `openai` and add an `OPENAI_API_KEY` in `.env`. The settings page tells you which provider is active.
What `npm run setup` does: copies `.env.example` to `.env`, generates `NEXTAUTH_SECRET` and `TOKEN_ENC_KEY`, starts PostgreSQL through Docker, and applies all migrations. It is idempotent and never overwrites a value you set yourself.
Notes:
* No Docker? Setup says so and keeps going. Point `DATABASE_URL` in `.env` at your own PostgreSQL and run `npx prisma migrate deploy`.
-* The Docker database listens on host port 5433 to avoid clashing with a local PostgreSQL on 5432. Manage it with `npm run db:up`, `npm run db:down`, and `npm run db:logs`.
+* The Docker database listens on host port 5433 to avoid clashing with a local PostgreSQL on 5432. Start it with `npm run db:up`, watch it with `npm run db:logs`, and stop the compose stack with `npm run db:down`.
* Optional: `npm run worker` starts the background job worker for document embedding.
* Full stack alternative: `docker compose up` builds and runs the app and database together. It reads `NEXTAUTH_SECRET` from `.env`, so run `npm run setup` first.
## What it looks like
-Multiple choice questions are graded by the server, and the answer key never reaches your browser before you commit. Rate your confidence first with one tap or one key.
+Every session opens with a preflight card stating the contract: mode, scope, prompt count, deck composition, and break protocol. One button starts it.
+
+
+ 
+
+
+During a session the interface recedes: the navigation collapses to a single quiet exit link, the question is the largest thing on screen, and there is no running score to watch. Multiple choice is graded by the server, and the answer key never reaches your browser before you commit. Rate your confidence first with one tap or one key.
-Miss a question you were sure about, and the app names the moment. That is the hypercorrection effect, and the review that follows is engineered around it. Notice the next question already loaded above the feedback: zero dead time between attempts.
+Miss a question you were sure about, and the app names the moment. That is the hypercorrection effect, and the review that follows is engineered around it: the question you just answered stays on screen with its feedback, the correction is the only highlighted element, and feedback generation starts the instant your answer lands so the explanation is usually waiting before you finish reading the verdict.
@@ -66,39 +72,45 @@ Free recall questions make you answer from memory before anything is revealed, w
-Then you score yourself against an explicit model answer and key points, not a feeling. Accurate self assessment requires a reference standard.
+Then you score yourself against an explicit model answer and key points, not a feeling. Accurate self assessment requires a reference standard, and the model answer stays visible, dimmed, while you write the correction rule for an error log.
-Every session opens with a preflight card stating the contract: mode, scope, prompt count, and break protocol.
+The end screen shows accuracy, time, and a calibration chart of your confidence against your outcomes, then recommends spaced follow up dates computed from how you actually did. One tap schedules them into your plan.
-
+ 
-The dashboard tracks your daily XP goal, streak, accuracy, achievements, and a year of activity, and it stays out of your way while you study.
+Your plan is a fixture, not a popup: it greets you with a countdown to the exam, real dated day groups with a focus line per session, an exam day marker, a reschedule button for missed sessions, and calendar export. Creating a new plan for the same course replaces the old one after a confirmation, so plans never silently stack.
- 
+ 
+
+
+The dashboard leads with today: your scheduled sessions and one primary start button. Streak, XP, accuracy, and the activity heatmap are there, but demoted to a quiet strip and the bottom of the page so they never compete with starting the work.
+
+
+
## Study modes
* **Retrieval** is the default: free recall plus multiple choice generated from your materials, scored immediately with elaborated feedback.
* **Interleaved practice** runs the same loop with prompts mixed across objectives, never more than two in a row from one topic. Use it when topics are similar enough to confuse, because telling them apart is the skill.
-* **Exam simulation** withholds all feedback until the end, then walks you through scoring your locked answers. This is the one place delayed feedback is intentional.
-* **Error repair** builds a deck from your unresolved mistakes, confident misses first. Each error resolves only after two correct recalls on different days.
+* **Exam simulation** withholds all feedback until the end, then walks you through review: multiple choice is scored objectively from the answer key, and free recall is scored by you against the model answer. This is the one place delayed feedback is intentional.
+* **Error repair** builds a deck from your unresolved mistakes, confident misses first. Each error resolves only after two correct recalls on different days, and decks stay within the course you are studying.
* **Worked examples** teach procedural material by fading: study a fully worked solution with the reasoning behind each step, then solve versions with the final step missing, then the final two, then a full transfer problem.
-Every mode shares the same spine: pretest diagnostics for never studied objectives (quarantined from grading), warm ups for objectives due for review, timed work and break cycles, variant questions injected after misses, and full resumability. A refresh or crash loses nothing.
+Every mode shares the same spine: pretest diagnostics for never studied objectives (quarantined from grading), warm ups for objectives due for review, timed work and break cycles, variant questions injected after misses (announced with a quiet note, and the progress bar never moves backward), and full resumability. A refresh or crash loses nothing, including an answer you typed but had not scored yet.
## The feedback loop
1. You commit an answer, and optionally a confidence rating, before anything is revealed. No hints, excerpts, or answers leak beforehand; this is enforced server side and covered by an end to end test. Committed retrieval attempts enhance learning even when they fail, per Kornell, Hays, and Bjork (2009).
-2. Multiple choice answers are graded server side instantly, including why the distractor you picked was tempting. Free recall answers are compared against a revealed model answer with key points.
-3. Elaborated feedback cites exact excerpts from your own uploaded materials, and generation starts the moment your attempt lands so the wait is minimal. It persists with the attempt and never regenerates or disappears.
+2. Multiple choice answers are graded server side instantly, including why the distractor you picked was tempting. Free recall answers are scored by you against a revealed model answer with key points.
+3. Elaborated feedback cites exact excerpts from your own uploaded materials, and generation starts the moment your attempt lands so the wait is minimal. It persists with the attempt and never regenerates or disappears. When your materials contain nothing relevant, it says so plainly instead of pretending.
4. A miss creates an error log and injects a retry variant later in the same session. The error resolves only after two correct retrievals on different days, and a wrong retry resets the streak.
5. The whole loop runs from the keyboard: number keys answer and score, Enter advances. More feedback cycles per hour is the entire point.
@@ -110,22 +122,28 @@ Each technique below is implemented in the product. Citations are shortened here
* **Deliberate practice loops.** Immediate informative feedback on every attempt, with difficulty adapting toward a band slightly above your current level. Ericsson and colleagues (1993); Kulik and Kulik (1988); Corbett and Anderson (2001); Bjork and Bjork on desirable difficulties.
* **Elaborated, task focused feedback.** Misses always get the correct answer plus an explanation grounded in your own course materials, never a bare mark, and the framing targets the task rather than the person. Van der Kleij and colleagues (2015); Shute (2008); Kluger and DeNisi (1996).
* **Hypercorrection.** Confidence is captured before the answer is revealed; confident misses get flagged, receive the fullest correction, and jump the queue in error repair decks. Butterfield and Metcalfe (2001); Butler, Fazio, and Marsh (2011); Fazio and Marsh (2009).
-* **Spaced repetition with exam awareness.** Objective mastery and flashcards both run on an SM2 scheduler whose intervals compress as the exam approaches, and inside the final day the app deliberately lets you cram. Cepeda and colleagues (2006, 2008).
-* **Successive relearning.** Error logs resolve only after two correct retrievals on different calendar days, and follow up session dates come from the actual scheduler rather than a fixed table. Rawson and Dunlosky (2011); Rawson, Dunlosky, and Sciartelli (2013).
+* **Spaced repetition with exam awareness.** Objective mastery and flashcards both run on an SM2 scheduler whose intervals compress as the exam approaches, and inside the final days the app deliberately lets you cram. Cepeda and colleagues (2006, 2008).
+* **Successive relearning.** Error logs resolve only after two correct retrievals on different calendar days in your timezone, and follow up session dates come from the actual scheduler rather than a fixed table. Rawson and Dunlosky (2011); Rawson, Dunlosky, and Sciartelli (2013).
* **Interleaving.** Mixed practice decks alternate objectives, and AI generated decks are reinterleaved so they never collapse into blocked practice. Rohrer and Taylor (2007); Rohrer and colleagues (2020); Kornell and Bjork (2008); boundary conditions from Brunmair and Richter (2019).
* **Pretesting.** New objectives get a diagnostic question before study. Wrong answers there are expected, framed supportively, and quarantined from your grades and error logs. Richland, Kornell, and Kao (2009); Pan and Sana (2021).
* **Worked examples with backward fading.** Study a stepped solution, then complete progressively less scaffolded problems, because novices learn more from studying solutions than from unassisted problem solving, while experts should skip ahead. Sweller and Cooper (1985); Renkl and colleagues (2002); Kalyuga and colleagues (2003).
* **Multiple choice done safely.** Answer keys are withheld from the client until you answer, correct answer confirmation always closes the loop to prevent lure learning, and distractors are built from documented misconceptions. Roediger and Marsh (2005); Butler and Roediger (2008).
-* **Self explanation and generation.** After feedback you can restate the concept in your own words, invent your own example, and answer a Socratic follow up, all saved with the attempt. Chi and colleagues (1989); Bisra and colleagues (2018).
-* **Calibration.** Your confidence ratings are charted against your actual outcomes, because overconfidence produces underachievement. Dunlosky and Rawson (2012); Nelson and Dunlosky (1991).
-* **A cognitive load minimal interface.** One question at a time, the question is the largest thing on screen, status chrome sits in low contrast, and decoration is omitted. Sweller (1988); Sundararajan and Adesope (2020) on seductive details.
+* **Self explanation and generation.** After feedback you can restate the concept in your own words, invent your own example, and answer a Socratic follow up, all saved with the attempt and tucked behind a single quiet link so they never crowd the screen. Chi and colleagues (1989); Bisra and colleagues (2018).
+* **Calibration.** Your confidence ratings are charted against your actual outcomes, and only ratings you actually gave are counted. Overconfidence produces underachievement. Dunlosky and Rawson (2012); Nelson and Dunlosky (1991).
+* **A cognitive load minimal interface.** One question at a time, the question is the largest thing on screen, navigation recedes to an exit link during sessions, status chrome sits in low contrast, and decoration is omitted. Sweller (1988); Sundararajan and Adesope (2020) on seductive details.
## Feature map
-* **Content upload and search.** PDFs and notes are chunked and searched with PostgreSQL full text search, and every generated question and piece of feedback cites its exact source chunks. Optional embedding based hybrid search sits behind `HYBRID_SEARCH_ENABLED`.
+The navigation is four destinations: Dashboard, Learn, Plan, and Settings. Flashcards, study guides, and chat live one tap away inside Learn.
+
+* **Study planner.** Sessions scheduled backwards from your exam date around your availability, with pre exam tapering, a live countdown, Google Calendar sync (including free and busy detection), ICS export, and deterministic rescheduling of missed sessions with a preview before anything moves.
+* **Learn.** A recommendation engine that reads your mastery and unresolved errors, tells you which session to run next and why, and starts it in one tap.
+* **Content upload and search.** PDFs and notes are chunked and searched with PostgreSQL full text search, and every generated question and piece of feedback cites its exact source chunks. Optional embedding based hybrid search sits behind `HYBRID_SEARCH_ENABLED`. Each document also gets an AI summary.
+* **Chat.** Ask questions against your own materials and get answers with citations that quote the exact source passages.
* **Flashcards.** Decks you create, plus cards auto generated from your errors with the correction as the answer, scheduled by the same exam aware SM2.
-* **Study planner.** Sessions scheduled backwards from your exam date around your availability, with pre exam tapering, Google Calendar sync, and ICS export.
-* **Progress.** XP, achievements, streaks, per objective mastery, and a calibration dashboard. Gamification is awarded only at session boundaries so it never intrudes on the answer loop.
+* **Study guides.** Key concepts, FAQ, and cheat sheet formats generated per course from your materials.
+* **Progress.** XP with an adjustable daily goal, streaks with earned freezes, achievements, per objective mastery, and a calibration dashboard. Session XP is awarded only at session boundaries so it never intrudes on the answer loop.
+* **Account.** Full data export and account deletion, password reset by email, and a timezone setting with one tap detection so streaks roll over at your actual midnight.
## Configuration
@@ -139,6 +157,7 @@ Each technique below is implemented in the product. Citations are shortened here
* `TOKEN_ENC_KEY` encrypts stored Google OAuth tokens. Generated by setup and required in production.
* `GOOGLE_CLIENT_ID`, `GOOGLE_CLIENT_SECRET`, and `GOOGLE_PROVIDER` control calendar sync. The default `fake` provider stubs it; use `real` in production.
* `EMAIL_PROVIDER` is `console` by default, or `smtp` with the SMTP variables for real mail.
+* `REQUIRE_EMAIL_VERIFICATION` is off by default so you can sign in immediately; turn it on only once real SMTP can deliver the links.
* `LOG_LEVEL` accepts debug, info, warn, or error.
One warning: `ALLOW_TEST_AUTH` makes the app trust a header as the authenticated identity. It exists only for automated tests and must never be set in production.
@@ -148,19 +167,19 @@ One warning: `ALLOW_TEST_AUTH` makes the app trust a header as the authenticated
* **Auth gates.** `REQUIRE_EMAIL_VERIFICATION` is off by default, so new accounts can sign in immediately; enable it only once real SMTP is configured, because the console email provider prints verification links to server logs only. `ALLOW_TEST_AUTH` must never be set in production. `TOKEN_ENC_KEY` is required in production (setup generates one for local use).
* **One long lived Node process.** The app is not serverless safe. Feedback is generated eagerly when an attempt lands, and the AI rate limiter and circuit breaker hold their state in process, so run it as a single persistent Node server via `npm start` rather than as per request functions.
* **The port 3000 trap.** If something else already holds port 3000, Next silently starts on 3001 while `NEXTAUTH_URL` still points at 3000, and sign in breaks with baffling redirects. Free port 3000, or update `NEXTAUTH_URL` (plus `BASE_URL` and `NEXT_PUBLIC_APP_URL`) to the port actually in use.
-* **Admin routes.** The `/admin` pages and admin APIs are gated by `ADMIN_USER_IDS`, a comma separated list of user UUIDs. Until you set it, nobody is an admin.
+* **Admin endpoints.** The admin APIs (job queue, search health, AI usage) are gated by `ADMIN_USER_IDS`, a comma separated list of user UUIDs. Until you set it, nobody is an admin. There is no admin UI.
## Development
* `npm run dev`, `npm run build`, and `npm start` cover the dev server and production.
* `npm test` runs everything vitest knows. `npm run test:unit` needs no database.
* `npm run test:integration` needs PostgreSQL reachable through `DATABASE_URL`.
-* `npm run test:e2e` runs Playwright against a production build, also database backed. Run `npx playwright install chromium` once first.
-* `npm run worker` processes background jobs, and `npm run db:migrate` creates new migrations.
+* `npm run test:e2e` runs Playwright: against your dev server locally, or against a production build when `CI` is set. Run `npx playwright install chromium` once first.
+* `npm run worker` processes background jobs, `npm run db:migrate` creates new migrations, and `npm run db:seed-research` loads the research evidence base that grounds plan generation.
Integration and e2e tests read `DATABASE_URL`; point it at a dedicated test database rather than your dev one.
-Layout, briefly: `src/app` holds pages and API routes, `src/services` holds domain logic, `src/lib` holds the science (prompt generation, spacing, mastery) and infrastructure (AI gateway, jobs, search), `prisma` holds schema and migrations, `e2e` holds Playwright specs, and `docs` holds the learning science foundation.
+Layout, briefly: `src/app` holds pages and API routes, `src/services` holds domain logic, `src/lib` holds the science (prompt generation, spacing, mastery) and infrastructure (AI gateway, jobs, search), `src/ui` holds shared components, `prisma` holds schema and migrations, `e2e` holds Playwright specs, `scripts` holds setup and the worker, and `docs` holds the learning science foundation with the source papers in `research-papers/`.
## Architecture notes
@@ -172,4 +191,4 @@ Layout, briefly: `src/app` holds pages and API routes, `src/services` holds doma
## References
-The complete bibliography with paper titles, journals, and the mapping from each finding to a feature: [docs/LEARNING_SCIENCE.md](docs/LEARNING_SCIENCE.md). Works cited in this README: Adesope, Trevisan, and Sundararajan (2017); Bisra and colleagues (2018); Bjork and Bjork (1992, 2011); Brunmair and Richter (2019); Butler, Fazio, and Marsh (2011); Butler and Roediger (2008); Butterfield and Metcalfe (2001); Cepeda and colleagues (2006, 2008); Chi and colleagues (1989); Corbett and Anderson (2001); Dunlosky and Rawson (2012); Dunlosky and colleagues (2013); Ericsson and colleagues (1993); Fazio and Marsh (2009); Kalyuga and colleagues (2003); Kluger and DeNisi (1996); Kornell and Bjork (2008); Kornell, Hays, and Bjork (2009); Kulik and Kulik (1988); Metcalfe, Kornell, and Finn (2009); Nelson and Dunlosky (1991); Pan and Sana (2021); Rawson and Dunlosky (2011); Rawson, Dunlosky, and Sciartelli (2013); Renkl and colleagues (2002); Richland, Kornell, and Kao (2009); Roediger and Karpicke (2006); Roediger and Marsh (2005); Rohrer and Taylor (2007); Rohrer and colleagues (2020); Shute (2008); Sundararajan and Adesope (2020); Sweller (1988); Sweller and Cooper (1985); Van der Kleij and colleagues (2015).
+The complete bibliography with paper titles, journals, and the mapping from each finding to a feature: [docs/LEARNING_SCIENCE.md](docs/LEARNING_SCIENCE.md). Works cited in this README: Adesope, Trevisan, and Sundararajan (2017); Bisra and colleagues (2018); Bjork and Bjork (1992, 2011); Brunmair and Richter (2019); Butler, Fazio, and Marsh (2011); Butler and Roediger (2008); Butterfield and Metcalfe (2001); Cepeda and colleagues (2006, 2008); Chi and colleagues (1989); Corbett and Anderson (2001); Dunlosky and Rawson (2012); Dunlosky and colleagues (2013); Ericsson and colleagues (1993); Fazio and Marsh (2009); Kalyuga and colleagues (2003); Kluger and DeNisi (1996); Kornell and Bjork (2008); Kornell, Hays, and Bjork (2009); Kulik and Kulik (1988); Nelson and Dunlosky (1991); Pan and Sana (2021); Rawson and Dunlosky (2011); Rawson, Dunlosky, and Sciartelli (2013); Renkl and colleagues (2002); Richland, Kornell, and Kao (2009); Roediger and Karpicke (2006); Roediger and Marsh (2005); Rohrer and Taylor (2007); Rohrer and colleagues (2020); Shute (2008); Sundararajan and Adesope (2020); Sweller (1988); Sweller and Cooper (1985); Van der Kleij and colleagues (2015).
diff --git a/docs/images/answer_loop.gif b/docs/images/answer_loop.gif
index 7be23c9..36c9373 100644
Binary files a/docs/images/answer_loop.gif and b/docs/images/answer_loop.gif differ
diff --git a/docs/images/end_screen.png b/docs/images/end_screen.png
new file mode 100644
index 0000000..b7f66b1
Binary files /dev/null and b/docs/images/end_screen.png differ
diff --git a/docs/images/home.png b/docs/images/home.png
index 3ff8954..27d2175 100644
Binary files a/docs/images/home.png and b/docs/images/home.png differ
diff --git a/docs/images/model_answer.png b/docs/images/model_answer.png
index cc6aa6a..a921c54 100644
Binary files a/docs/images/model_answer.png and b/docs/images/model_answer.png differ
diff --git a/docs/images/plan.png b/docs/images/plan.png
new file mode 100644
index 0000000..0a4d40e
Binary files /dev/null and b/docs/images/plan.png differ
diff --git a/docs/images/preflight.png b/docs/images/preflight.png
index 73f0fad..ace1a2a 100644
Binary files a/docs/images/preflight.png and b/docs/images/preflight.png differ
diff --git a/docs/images/review_hypercorrection.png b/docs/images/review_hypercorrection.png
index 9a278be..f2dc3e8 100644
Binary files a/docs/images/review_hypercorrection.png and b/docs/images/review_hypercorrection.png differ
diff --git a/docs/images/runner_free_recall.png b/docs/images/runner_free_recall.png
index 760f218..373f943 100644
Binary files a/docs/images/runner_free_recall.png and b/docs/images/runner_free_recall.png differ
diff --git a/docs/images/runner_mcq.png b/docs/images/runner_mcq.png
index 6553ff8..64b2261 100644
Binary files a/docs/images/runner_mcq.png and b/docs/images/runner_mcq.png differ
diff --git a/docs/images/signin.png b/docs/images/signin.png
deleted file mode 100644
index dae9285..0000000
Binary files a/docs/images/signin.png and /dev/null differ
diff --git a/src/middleware.ts b/src/middleware.ts
index 424ffe1..313270c 100644
--- a/src/middleware.ts
+++ b/src/middleware.ts
@@ -13,6 +13,7 @@ const PUBLIC_PATHS = [
"/auth/forgot-password",
"/auth/reset-password",
"/api/auth",
+ "/api/config", // non-secret runtime flags; signup reads it before a session exists
"/api/health",
"/s/", // Session links are shareable; API-level auth guards operations
];