# Session handoff — living doc

> **This is a LIVING doc. Update it at the end of every meaningful chunk of work, not just at session-end.** Long Claude Code sessions burn tokens and risk losing context to summarization; a freshly-updated handoff lets the next CC instance pick up cleanly without re-deriving state from the chat transcript.
>
> **Update cadence:** after every commit, after every reproduced bug, after every product decision. If you're about to spend more than 5 minutes on something, write the intent here first so future-you can resume if interrupted.
>
> **Where this lives:** `mathapi11v2/docs/SESSION_HANDOFF.md`. The Flutter repo `flutter_demo/` does not have its own handoff doc — cross-repo notes live here under the FE section.

---

## Session handoff — 2026-06-07 (Kindy K1/K2 taxonomy seeded as DRAFT · kiasu-floor bug fix · PR #39)

**State is safe to close.** Self-contained data-seeding task; no prod touched, no migrations, no schema changes. All work is on a **new branch off `master`** (NOT the tenancy branch) and pushed.

### What landed (branch `feat/kindy-taxonomy`, off `master` @ `49b557f6`, PR #39 → master)

| Commit | What |
|---|---|
| `14a3e4a3` | `fix(adaptive)` — add `status_id = 3` guard to 5 kiasu-navigation helpers in `AdaptiveLevelService` (`getStartingMaxile`, `getNextLevelUp`, `getNextLevelDown`, `getMin/MaxLevelForField`). They joined `levels↔tracks` with **no** status filter, unlike `MaxileCascade`, so any draft level below the live band would lower the kiasu floor. Standalone latent-bug fix. |
| `9976432b` | `feat(kindy)` — `database/seeders/KindyTaxonomySeeder.php`: 2 levels (K1 `[0,50)`, K2 `[50,100)`), 20 tracks (9 K1 + 11 K2), 73 skills + 73 `skill_track` pivots, under existing Public fields 37–41. All NEW rows are **DRAFT (`status_id = 4`)**. Idempotent. NOT wired into `DatabaseSeeder`. |

- **PR #39:** https://github.com/2ppaamm/capstoneapi/pull/39 (opened via GitHub API + git credential — `gh` not installed on this machine).
- Run the seeder explicitly: `php artisan db:seed --class=KindyTaxonomySeeder`.

### Key facts discovered (carry forward)

- **DRAFT = `status_id 4`, Public = 3.** The maxile cascade (`MaxileCascade`) gates on `status_id = 3` at every tier (skills, tracks, **levels** inside `pickTrackForSkill`, fields), so draft content is fully invisible to it. Verified empirically: kiasu floor for fields 37–41 stayed at 100, user-maxile recalc byte-identical to baseline.
- **No per-skill maxile column exists** — `skills`/`skill_track`/`tracks` have none; maxile banding lives only on `levels.start/end_maxile_level` (and per-user runtime on `skill_user.skill_maxile`). So kindy "banding" = the K1/K2 level bands, nothing per-skill.
- **Level id 1 ("Kindergarten", level 0, band [0,100], Public) is NOT empty** — it carries 12 legacy **Restricted** tracks `K1T1W1…W12` in field 1 (Arithmetic, "Only Me"), 23 `track_user` rows. Left **untouched** (we chose two new draft levels rather than mutating it).
- New tenancy columns `scope`/`org_id`/`house_id` on tracks & skills default to `systemwide`/null/null; the seeder relies on those defaults (doesn't reference them), so it's schema-portable to master too.
- The design list enumerates **73** skills, not the "~60" estimate in the brief.

### To promote kindy later
Flip the 2 levels + 20 tracks + 73 skills to `status_id = 3`. Because the kiasu helpers are now status-aware, the kindy band joins the kiasu floor automatically at that point — review the maxile bands before flipping.

### Local-only residue (not committed, not a concern)
The seeded kindy rows exist in the **local XAMPP DB** from verification runs (levels 18/19 there; on the branch they regenerate to fresh ids via the idempotent seeder). The `feat/b2b-tenancy` working tree was restored to HEAD (the hardening + seeder live only on `feat/kindy-taxonomy`).

---

## Session handoff — 2026-05-30 (P5/P6 ingest COMPLETE · SVG solution generators built · raw crops live)

**State is safe to close.** Long heavy ingest session; closing to save tokens. Two named follow-ups for the next CC session — both are detailed below under "Pick up here next session".

### What landed on prod this session

| Area | Result |
|---|--:|
| **P5/P6 ingest** | **256/256 papers (P5 152, P6 104)** — ALL `.url` seeds consumed |
| New questions inserted (3 load passes) | **~3,041** as Draft (`qa_status=ai_generated`, `status_id` 4=image-pending or 6=AGS Tutor Input) |
| Sentence-per-line baked into stored text | **11,810 questions + 9,797 solutions** (also still the final step of the pipeline, idempotent — `_sentence_break.php`) |
| Raw figure crops uploaded as `question_image` | **1,837** (P5 824, P6 1,013) |
| Figure questions flipped `ai_generated → unreviewed` | **1,018** |
| Bar-model PNG solutions live (drawn boxes) | **20 P6 papers, 180 diagrams** under `solutions.solution` `[[model:p6/solutions/…]]` marker |
| Sentence-break Flutter patch | `MathTextUtils.renderSolution` + `breakSentences` param wired into question-text, FIB stems, diagnostic, solution modal, feedback area — **needs app redeploy** |
| 4 corrupt-PDF papers flagged | 130 questions → `qa_status='flagged'` for manual answer-check (ACS(P)'24, ACSJ'23, ACSJ'24, CH'24 — all contaminated with "Nan Hua 2022"; figures recovered from original `fig-q*.png`) |

### Tooling built / extended

- **`tools/svg_generators/bar_model.py`** — Singapore Math model method, 4 types: `part_whole`, `comparison`, `multiplication`, `unitary`. Brand CSS-vars throughout (crimson #960000 / gold #BF9237 / dusty-rose #D0ACAC border / cream #FAF5EE / ink #2A2A2A). Alternating per-entity colour, MIN_SEG=40, BH=40, GAP=16.
- **`tools/svg_generators/equation_line.py`** — single equation line, optional `emphasize=True` (crimson).
- **`tools/svg_generators/solution_block.py`** — composes instruction → setup bar model → solved bar model → working steps → "Answer: …". **Algebra schema embedded NOW for the P5-P6 algebra-toggle sprint** (no retrofit needed): `algebra={"variables":[…], "entity_expressions":[…], "equations":[…]}` is JSON-serialised onto root `<svg data-algebra=…>`; each working step's `{"text":…, "algebra":…}` round-trips on its own `<text data-algebra=…>`; bar_model entity dicts accept an `expression` field.
- Samples at `tools/samples/{bar_model_*,equation_line,solution_block_unitary}.svg`.

The earlier `docs/past year questions/_barmodel.py` (still in use by Workstream B for P6 PNG attach) is the simpler renderer that powers the 180 live diagrams. The new SVG generators above are the **richer Singapore-Math layout** for the upcoming explanation pass.

### Important reality-checks landed this session

- **`math.allgifted.com/{chars,objects}/<id>.webp` is NOT live yet.** The 200 OK returns the 1236-byte SPA index shell for every path — confirmed by rasterising a CDN-referencing New Images SVG and seeing broken-image placeholders. The webp assets live in-repo at `public/assets/math/` but aren't served at that host. So any pipeline that depends on rasterising CDN-referencing SVGs is blocked until those assets are actually deployed to that vhost.
- **Headless Chrome rasterisation works for SVGs *without* CDN deps.** The new bar_model / solution_block SVGs render correctly via `chrome.exe --headless --screenshot=… --window-size=W,H file:///…`. Used this for sample verification. (PyMuPDF/cairosvg still fail locally.)
- **4 (so far) P5-2024/2025 + P6-2023/2024 paper.pdf files are scrambled concatenations** containing pages from unrelated schools (commonly "Nan Hua 2022"). The crop agents now auto-halt + report on these (added that instruction mid-session). **Crucially the prod questions+answers were transcribed from the *correct* originals at ingestion** — the `fig-q*.png` in each folder are correct ACS/etc figures — so the data on prod is fine; only re-cropping and re-verification against the *current* PDF is blocked.
- The "raw crops now, swap to finished later" workflow Pam approved is in place: `fig-q*.png` → `Only Images/<slug>-q<n>.png` → tar → `storage/app/public/p{5,6}/images/` → flip to `unreviewed`. Re-runnable as more crops land.

### Pick up here next session (Pam's two named follow-ups + smaller residuals)

1. **Singapore-Math-style solutions for the relevant P3–P6 questions** — `tools/svg_generators/{bar_model,solution_block}.py` are ready. Suggested pipeline:
   - per-paper agent reads each question's manifest + worked explanation, decides whether it suits a model (same selection criteria as `docs/past year questions/_BARMODEL_SPEC.md`), and emits `solution_block.generate(...)` params PLUS the algebra metadata.
   - I (next session) render to SVG, rasterise via headless Chrome to PNG (these SVGs have no CDN deps so they render cleanly), upload to `storage/app/public/p{n}/solutions/`, and attach to `solutions.solution` via the existing `[[model:…]]` marker (the Flutter `MathTextUtils.renderSolution` already handles it).
   - Carry the algebra metadata into the stored solution row so the future toggle has no retrofit.
2. **Image upload as the OTHER AGENT's New Images become available** — Pam's other agent is producing colourised New Images SVGs from the Only Images crops I'm filling. Mechanism for the next session:
   - watch `docs/past year questions/New Images/` for new finished SVGs;
   - rasterise each via headless Chrome — **only after** the `chars/objects` webp library is actually live at math.allgifted.com (currently SPA shell);
   - upload PNG to `storage/app/public/p{n}/images/<slug>-q<n>.png`, replacing the raw crop;
   - flip `status_id` from 4 (Draft / image-pending) to 6 (AGS Tutor Input — ready for review).
   - Re-runnable sweep — idempotent, picks up new arrivals each run.
3. **Residual cleanup** (small, non-blocking): wrap ~28-50 stems where the agent left bare `\frac`/`\angle` without `\(...\)`; convert ~30-50 non-numeric FIB answers (Pistachio / "5 200 060" / "P, R, Q" etc.) to MCQ.
4. **Bar-model PNG solutions** — Workstream B paused at 20/57 P6 papers. The pipeline (`_BARMODEL_SPEC.md` → `_barmodel.py` → `_barmodel_apply.py` → `_barmodel_attach.php`) is proven; just resume the per-paper agent fan-out.
5. **4 corrupt PDFs** — need correct scans dropped into `P6/p6-{acsp-2024,acsj-2023,acsj-2024,ch-2024}-prelim/paper.pdf` for clean re-cropping and re-verification of those 130 flagged questions.

### Where the key artifacts live

| Artifact | Path |
|---|---|
| Ingestion spec (agents read this) | `docs/past year questions/_INGESTION_SPEC.md` |
| Bar-model PNG spec (Workstream B agents) | `docs/past year questions/_BARMODEL_SPEC.md` |
| Crop-agent spec (figure extraction) | `docs/past year questions/_IMGCROP_SPEC.md` |
| New SVG generators (solution explanations) | `tools/svg_generators/{bar_model,equation_line,solution_block}.py` |
| SVG samples | `tools/samples/` |
| Renderer + apply tooling for the older bar-model PNG flow | `docs/past year questions/{_barmodel,_barmodel_apply}.py`, `_barmodel_attach.php` |
| Sentence-break prod transform | `docs/past year questions/_sentence_break.php` (idempotent, scoped to `qa_status IN ('ai_generated','unreviewed','flagged')`) |
| Raw-crop upload sweep | `docs/past year questions/_stagecrops.py` |
| Ingest gap / shards | `docs/past year questions/_ingest_shards/shard_NN.txt` (all consumed) |
| Prod backups | `storage/app/_sbreak_backup_*.jsonl`, `storage/app/_flip_backup_*.json`, `storage/app/dedupe_backup_*.json` |

### Flutter side — needs Pam's redeploy

Three patches landed in `flutter_demo/lib/` and are committed locally on `rename/ags-math-brand` *only if Pam commits them* — currently uncommitted. Files touched:
- `lib/utils/math_text_utils.dart` — new `renderSolution()` (handles `[[model:path]]` marker → `Image.network`), new `breakSentences` param on `renderMathText()`.
- `lib/widgets/ags_tutor_solution_modal.dart` — String solution branch + step explanation use the new methods.
- `lib/widgets/question_feedback_area.dart` — solution + explanation rendering use them.
- `lib/widgets/question_display_widgets.dart` — regular question card + with-image card + FIB-inline stem segments all pass `breakSentences: true`.
- `lib/screens/diagnostic/diagnostic_screen.dart` — diagnostic question text passes `breakSentences: true`.
`flutter analyze` clean (the 12 reported issues are pre-existing). Verified the lookbehind regex compiles and behaves on Dart with a standalone test.

### One-line lessons worth carrying forward

- **Don't trust a 200 OK from `math.allgifted.com/{chars,objects}/…`** — it's the SPA index for any path. Confirm asset deployment by checking body length / content type, not status code.
- **Crop agents that view PDFs double as PDF-integrity auditors** — let them halt-and-report on scrambled concatenations instead of producing wrong-paper crops.
- **Loader dedup is on `source` alone** — convert-blanks mutates the question text, so `source+question` re-inserted duplicates. Was fixed for P4/P5/P6 mid-session; preserved.
- **Sentence-break + Flutter `breakSentences` coexist without doubling** — once data has `<br>` after a sentence period, the period is no longer followed by whitespace, so the Flutter regex no-ops on that boundary.

---

## Session handoff — 2026-05-27 → 2026-05-28 end (Pamela closing for the night)

**State is safe to close.** No half-applied migrations, no uncommitted prod-bound work, no orphan jobs. Launch BE is on prod and stable.

### What landed on prod today (in order)

| Commit | Repo | What |
|---|---|---|
| `334e742`–`7027462` | mathapi | Deploy.sh capture from prod, launch checklist, FK type fix on int-unsigned ids |
| `d9da8b7` → `ed95564` | mathapi | SSO bridge (account.* → math via HS256 JWT, lives=5 forceFill seed) |
| `6c78c24` | account | `POST /api/users/lookup` resolver (canonical DOB + identity) |
| `1464897` | mathapi | CORS fix — quiz.* + account.* added to default allowed_origins |
| `0198b23` | account | `POST /api/kudos/events` aggregator + `account.kudo_events` ledger |
| `8e69452` | mathapi | Kudos federation: local ledger + `OutboundKudosSync` + `kudos:sync` cron, `effectiveKudosTotal` in API responses, lives=5 seed |
| `e37bff9`/`522cf5e`/etc | vocab | Same kudos pattern wired in (port already existed) + her in-flight feature commits |
| `6719905` → `959a059` → `6c78c24` | account | PWA manifest + sw.js + onboarding form (DOB, parent_student_links) + UserLookupController |
| `d0ccebe` | mathapi | AI Tutor endpoints (`/diagnose`, `/solution`, `/vote`) gated to Premium |
| `8ca627a` | flutter_demo | Heart layout fix, MCQ image-only options render, post-topup resume to next question, premium-unified gates (videos + AI tutor) |
| `18f7150` → `8ca627a` FE bundle | quiz.allgifted.com | All FE work tar-piped to `/var/www/html/quiz/build/web/` throughout the day |

**Prod URLs alive + functional:**

- `mathapi.allgifted.com` — BE on `d0ccebe` (feat/cascade-stripe-filament-2026-05-23)
- `account.allgifted.com` — on `6c78c24` (main), PWA-installable, onboarding + SSO + user-lookup + kudos aggregator all live
- `vocabapi.allgifted.com` — on `522cf5e` (main)
- `quiz.allgifted.com` — Flutter web bundle from `8ca627a`, served from disk; source git checkout matches
- Kudos cron — `*/5 * * * *` running on both mathapi + vocabapi prod, shipping unsynced events to account

**Account-side kudos rollup confirmed working** — Pamela's account row shows `kudos_global=1372` (1222 from math + 150 from vocab).

### Today's product decisions

- **Stripe live mode deferred.** Prod `.env` stays on `sk_test_...lBb3`. Pamela wants to do test-mode rehearsals first; switch to live only after confidence.
- **AI Tutor enabled** (`AI_TUTOR_ENABLED=true`) AND **gated to Premium-only**. Free users hit `403 premium_required` on `/diagnose`, `/solution`, `/vote`. Solve stays admin-only.
- **Parent.allgifted.com path chosen:** keep `ags_parent` (Node + React PWA) as another AGS app like math/vocab/forma, NOT a separate identity system. SSO via account.* planned for the next session. Identity + parent-student relationships live canonically on `account.parent_student_links`; ags_parent reads via the resolver. `ags_parent` is deployed nowhere yet.
- **Single gate UX:** all premium-locked features (kiasu / videos / AI tutor / diagnostic) go through `PremiumRequiredDialog` with the unified `GateDialog` shell. Only `OutOfLivesModal` differs (Buy Lives + Subscribe vs Subscribe-only), because lives can be topped up without subscribing.
- **Post-topup resume:** when a user runs out of lives mid-test, the FE saves the question batch + next-index to SharedPreferences before showing OutOfLivesModal. After Stripe success + lives credit, `PaymentReturnScreen` reopens `QuestionScreen` at the first question AFTER the one whose answer was just submitted. Stale-guarded to 30 min.
- **Kudos federation lesson:** `parent_students.account_user_id` resolver (POST `account.allgifted.com/api/users/lookup`) implements the TODO ags_parent had been carrying. Cross-DB read also wired via a secondary 'account' connection in math + vocab `config/database.php`.

### Open items / picked up next session

1. **Videos** — `onShowVideos` callback is wired (with premium gate) but no UI element actually invokes it. Pamela said "we will fix the videos tomorrow." Need Figma reference to know where the video button lives + what conditions trigger it.
2. **Stripe live keys** — when ready, `sk_live_` + `pk_live_` + the registered live-mode `whsec_` go into prod `.env`. Procedure documented in `docs/sprints/launch-checklist-2026-05-27.md`.
3. **Parent endpoint deploy** — Pamela's commit `1739160` on mathapi adds `MathStateController` + parent routes + `MaxileLevel` migration. **NOT deployed** — prod is intentionally on `d0ccebe`. Deploy whenever the parent portal is ready to consume.
4. **ags_parent codebase** — uncommitted mix of Pamela's in-flight work + my edits (atlas.js wired to resolver, gradebook.js DOB-from-account, schema.sql DOB column dropped, AddChild.jsx + web/api.js DOB capture removed, account.js client added, .env seeded with `ALLGIFTED_ACCOUNT_TOKEN` + `MATH_API_TOKEN` + `VOCAB_API_TOKEN`). She'll commit when ready. **Don't touch this working tree without her say-so.**
5. **Per-tap answer submission** — Stage B FE refactor still pending. Current FE batches and only flushes the queue at end of test (or on lives-0). Mid-test exit = lost answers. BE endpoint `POST /api/answers` is ready (Phase 1B); FE just needs to call it per-Submit instead of buffering.
6. **Cross-session resume of arbitrary tests** — only post-topup resume is wired today. A general "you were on question X of test Y last login → tap to resume" feature is not built. `users.resume_state` JSON column was scoped but not added.
7. **Parent.allgifted.com SSO wiring** — `client_apps` row + `/sso/callback` in orion_parent_signin + dashboard tile on account.* + deploy of ags_parent to prod. Whole sprint.
8. **flutterquiz prod source parity** ✓ — auto-pulls since the SSH alias `github-flutterquiz` works; today's pulls happened.

### State by repo at session-end

| Repo | Branch | HEAD (local) | HEAD (prod) | Dirty? | Notes |
|---|---|---|---|---|---|
| mathapi | feat/cascade-stripe-filament-2026-05-23 | `1739160` | `d0ccebe` | clean (untracked docs/ only) | Prod intentionally 1 commit behind — parent endpoints not yet shipped |
| account | main | `6c78c24` | `6c78c24` | clean | Up to date |
| vocab | main | `522cf5e` | `522cf5e` | clean | Up to date |
| flutter_demo | rename/ags-math-brand | `8ca627a` | served bundle: same | clean | quiz.allgifted.com source checkout also at `8ca627a` |
| ags_parent | main | `c6b255a` (initial release) | n/a (not deployed) | **dirty — preserve** | 8 modified + 9 untracked files; mix of Pam's in-flight and my edits. See "Open items" #4. |

### What "safe to close" means here

- No migrations partially applied
- No queue jobs in-flight (`jobs=0 failed=0` on math, last verified ~14:00)
- No tokens leaked to chat history (all tokens fingerprint-only printed)
- All chat-derived edits either committed-and-pushed OR explicitly left as in-flight in Pamela's workspace per her instruction
- Stripe still test-mode (no live charges possible)
- AI Tutor Premium gate enforced both BE (403) and FE (preempt) — no free-tier LLM spend possible

---

## Currently in flight — 2026-05-27 morning (BE deployed, Stripe live mode blocks launch)

**BE deploy: DONE.** Prod HEAD now `7027462` on `feat/cascade-stripe-filament-2026-05-23` (PR-to-master deferred for later). All 4 new routes verified 401 publicly (`/api/lives/checkout-session`, `/api/subscription/checkout-session`, `/api/subscription/verify-session`, `/api/questions/{id}/solution/vote`). 4 migrations applied (AI diagnoses table, AGS Tutor status, qa_status enum extension, student vetting). Full per-step record in `docs/sprints/launch-checklist-2026-05-27.md` item 1.

**Surprises caught and fixed this morning:**
- Prod `deploy.sh` had been hand-upgraded in place (set -euo pipefail, --dry-run, rollback-on-migrate-fail, logging) — captured back into repo at `334e742` so future PR-to-master doesn't overwrite the better script.
- 2873 PNGs showed `M` on prod due to `chmod -R 755 public/images` in the new deploy.sh — pure mode-only. Set `git config core.fileMode false` in prod's checkout to suppress; mode-only changes now invisible to `git status`.
- 33 working-tree deletions on prod (phpinfo.php, QA_Reviewer_Manual.pdf, ~30 missing question PNGs) preserved across the branch checkout — `git checkout BRANCH` keeps uncommitted local deletions when the destination matches HEAD.
- First migrate run failed: `questions.id` / `users.id` / `solutions.id` are legacy `int unsigned`, not Laravel-default `bigint unsigned`. The AI tutor migrations used `unsignedBigInteger`. FK constraint refused. Fixed across 3 migration files (commit `7027462`).
- No queue worker was running on prod (`QUEUE_CONNECTION=database`, 1 job sitting since 2025-09-27). Installed `/etc/systemd/system/laravel-queue.service` (User=www-data, `artisan queue:work --queue=default --sleep=3 --tries=3 --max-time=3600 --backoff=30`). Stale job processed, `jobs=0 failed=0`.

**Launch blocker remaining: Stripe live mode.** Prod `.env` has `STRIPE_SECRET_KEY=sk_test_...lBb3` (TEST mode). Live `.env` not yet installed. Live-mode webhook endpoint not yet registered in Stripe Dashboard. The 7 events to subscribe and the exact URL are in `docs/sprints/launch-checklist-2026-05-27.md` items 2-4. Until this is sorted, real customers cannot pay.

**SSO to account.allgifted.com — built + deployed 2026-05-27 PM.**
Pamela flagged the SSO gap mid-deploy. Vocab was already wired; ported the
same per-app HS256 JWT pattern to math. Files: migration
2026_05_27_120000_add_external_id_to_users, app/Http/Controllers/API/
SsoController.php, POST /api/sso/exchange in routes/api.php,
services.sso.jwt_secret in config/services.php + .env, firebase/php-jwt
in composer. FE (flutter_demo) boot-time handler in main.dart +
AuthService::ssoExchange that mirrors OTPVerifyScreen's persistence.
account.* client_apps row for slug=math already existed
(launch_url=https://quiz.allgifted.com/sso/callback); jwt_secret copied
to mathapi .env via fingerprint-safe pipeline. Synthetic JWT round-trip
verified twice on prod (lives=5 seed for new SSO users via forceFill,
since `lives` is intentionally excluded from $fillable). Ready for
Pamela's real account.* → math.* dashboard-click test.

**Other prod findings:**
- `ANTHROPIC_API_KEY` present (`sk-ant...6AAA`, length 108). `AI_TUTOR_ENABLED` unset — Pam's call whether to flip true at launch.
- `quiz.allgifted.com` FE bundle: previously had NO Sentry DSN; the SSO redeploy 2026-05-27 PM rebuilt without `--dart-define=SENTRY_DSN=`, so the default DSN baked in. Observability is now ON.
- `public/assets` and `public/storage` on prod are symlinks into `/var/www/html/mathapi/storage/app/public/` — standard Laravel storage:link layout. `php artisan storage:link` errors with "[public/assets] link already exists" but that's informational, not broken.
- Prod SSH pubkey for flutterquiz deploy-key (item 9): `ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIMjaYlhw0vytztx9EqR+HVW4GxR9RfjZJ0tz0aXsZw2N mathapi-prod-deploy` — Pam needs to paste on GitHub for source parity.

**Local working tree:** 3 unpushed commits on `feat/cascade-stripe-filament-2026-05-23` from this morning: `334e742` (deploy.sh capture), `9fa9e48` (launch checklist), `7027462` (FK type fix). All pushed.

---

## Earlier — 2026-05-26 session-end snapshot

**Code: committed + pushed.** BE commit `b84ec0a` on `feat/cascade-stripe-filament-2026-05-23` (pushed to origin). FE commit `d0a7d69` on `rename/ags-math-brand` (pushed to origin). See the "2026-05-26 PM" section below for the full inventory of what landed.

**Deploy: incomplete.** End-of-session smoke test (curl from the public internet) confirms:
- `mathapi.allgifted.com/api/health` → 200 ✓ BE alive
- `mathapi.allgifted.com/api/stripe/webhook` → 400 (missing signature) ✓ existing route OK
- `mathapi.allgifted.com/api/lives/checkout-session` → **404** ✗ new route NOT deployed
- `mathapi.allgifted.com/api/subscription/checkout-session` → **404** ✗ new route NOT deployed
- `mathapi.allgifted.com/api/subscription/verify-session` → **404** ✗ new route NOT deployed
- `mathapi.allgifted.com/api/questions/{id}/solution/vote` → **404** ✗ new route NOT deployed

So Apache + Laravel are running on the OLD code. Either `git pull` didn't actually fetch on prod, or `php artisan route:cache` wasn't rebuilt after the pull. Pamela attempted the deploy but the new routes are still 404 — the deploy SCRIPT may not have actually executed (host-key acceptance loop, or paste-into-wrong-shell). The new migration's status on prod DB is also unknown.

**FE deploy: DONE at quiz.allgifted.com (~2026-05-26 23:35 local).** Flutter web lives at `/var/www/html/quiz` on the same DigitalOcean droplet as mathapi. Apache vhost `quiz.allgifted.com-le-ssl.conf` is preconfigured with `DocumentRoot /var/www/html/quiz/build/web`, Let's Encrypt SSL, and SPA rewrite rules (`!-f / !-d → /index.html`). Deploy method tonight: built locally with `flutter build web --release --dart-define=API_BASE_URL=https://mathapi.allgifted.com --dart-define=SENTRY_DSN=`, then tar-piped over SSH to extract into `/var/www/html/quiz/build/web/`, chowned to `www-data`. Smoke test confirmed HTTP 200, title `<title>AGS Math</title>`, manifest serves with `display: standalone`, service worker + icons available, PWA-installable on mobile.

**Prod source out of sync:** `/var/www/html/quiz` git checkout is still on `master` (HEAD `fc61e0d initial quiz changes`). Couldn't update because the prod SSH key is registered as a deploy key on `capstoneapi` only, not on `flutterquiz`. Tomorrow: add the prod server's SSH public key as a deploy key on the `flutterquiz` repo (GitHub → repo → Settings → Deploy keys → Add deploy key), then `cd /var/www/html/quiz && git checkout rename/ags-math-brand && git pull`. Doesn't affect what's served (Apache serves `build/web/` artifacts which are the latest), but the source-on-prod state is stale for audit purposes.

**Local `.env` state at session-end:** Live Stripe keys are in local `.env` (intentionally swapped from test for end-to-end testing). Be aware: any `flutter run` against this `.env` will hit live Stripe. To swap back to test keys (recommended for ongoing local dev): `cp .env.backup-pre-test-swap-20260526-160153 .env && php artisan config:clear`.

## Tomorrow's first actions (pick up here)

1. **Complete the BE deploy on prod.** SSH to `root@mathapi.allgifted.com`. Run the diagnostic script in the deploy-followup section below — it confirms current state, pulls cleanly, rebuilds route cache, restarts apache, and verifies the new routes return 401 (not 404). Test endpoints externally:
   ```bash
   curl -s -o /dev/null -w "%{http_code}\n" -X POST https://mathapi.allgifted.com/api/lives/checkout-session -H "Accept: application/json"
   # Expected: 401 (auth required) → confirms route exists
   ```

2. **Validate the live Stripe webhook with "Send test webhook"** in the Stripe Dashboard → Developers → Webhooks → click the prod endpoint → "Send test webhook" → pick `payment_intent.succeeded`. Should return 200 OK. If 400/401: `whsec_` on prod doesn't match the registered endpoint's signing secret.

3. **FE deploy DONE at quiz.allgifted.com.** Sanity check from a mobile browser:
   - Open `https://quiz.allgifted.com`
   - Title bar reads "AGS Math"
   - Browser offers "Add to Home Screen" (PWA install)
   - Try the OutOfLivesModal → confirm Unlimited Lives card on top, "BEST VALUE" badge
   - **DO NOT do a real test purchase until BE deploy is complete** — the FE will call mathapi.allgifted.com/api/lives/checkout-session which still returns 404 today.

**Redeploy procedure (when there are more FE changes):**
```bash
# On local
cd C:/allgifted/flutter_demo
flutter build web --release --dart-define=API_BASE_URL=https://mathapi.allgifted.com --dart-define=SENTRY_DSN=
cd build/web
tar czf - . | ssh root@mathapi.allgifted.com 'cd /var/www/html/quiz/build/web && tar xzf - && chown -R www-data:www-data .'
```
No apache restart needed — Apache serves the static files immediately. Browser may cache the service worker; users may need a hard refresh (Ctrl+Shift+R) once.

**Add the flutterquiz deploy key** (10 sec on GitHub) so future deploys can also `git pull` on prod for source parity:
```bash
# On prod, copy the public key
ssh root@mathapi.allgifted.com 'cat ~/.ssh/id_*.pub | head -3'
# Then paste on GitHub: flutterquiz repo → Settings → Deploy keys → Add deploy key
# After adding:
ssh root@mathapi.allgifted.com 'cd /var/www/html/quiz && git remote set-url origin git@github.com:2ppaamm/flutterquiz.git && git fetch origin && git checkout rename/ags-math-brand && git pull'
```

4. **Do one real test purchase** (test card on live mode is rejected — must use a small real amount with a card you control) to confirm:
   - Stripe Checkout opens
   - Redirect lands on `/payment-success?session_id=…` (PaymentReturnScreen)
   - verify-session calls succeed and Premium status credits without manual refresh
   - Webhook event also fires (visible in Stripe Dashboard endpoint event log)

5. **Confirm the 99k overflow fix held.** Pamela hadn't yet retested after the last `Math.tex(textStyle: inherit:false)` fix. If still appearing, the next call site to patch is likely inside `ags_tutor_solution_modal.dart::_buildSteps` (also calls `MathTextUtils.renderMathText`, indirectly hits `Math.tex`).

### Deploy-followup diagnostic script (paste on prod SSH)

```bash
cd /var/www/html/mathapi
echo "=== Branch + HEAD ==="
git branch --show-current
git log --oneline -3
echo
echo "=== Uncommitted/dirty? ==="
git status --short
echo
echo "=== Pull latest ==="
git fetch origin
git pull origin feat/cascade-stripe-filament-2026-05-23
echo
echo "=== Migrate ==="
php artisan migrate --force 2>&1 | tail -5
echo
echo "=== Rebuild caches ==="
php artisan route:clear && php artisan config:clear
php artisan route:cache && php artisan config:cache
echo
echo "=== New routes registered? ==="
php artisan route:list 2>&1 | grep -E "lives/checkout-session|subscription/checkout-session|subscription/verify-session|solution/vote"
echo
echo "=== Restart workers + Apache ==="
php artisan queue:restart
systemctl restart apache2
chown -R www-data:www-data storage bootstrap/cache
echo
echo "=== Verify HTTP ==="
curl -s -o /dev/null -w "lives/checkout-session: HTTP %{http_code} (expect 401)\n" -X POST http://localhost/api/lives/checkout-session -H "Accept: application/json"
curl -s -o /dev/null -w "subscription/checkout-session: HTTP %{http_code} (expect 401)\n" -X POST http://localhost/api/subscription/checkout-session -H "Accept: application/json"
echo
echo "=== Tail log for 30s ==="
timeout 30 tail -f storage/logs/laravel.log || true
```

---

## Most recent session — 2026-05-26 PM (Pamela + Claude Opus 4.7 1M)

Single massive session, ~10 hours of accumulated work across BE + FE + DB + docs. Roughly grouped by area below. Everything is on the local working tree of `feat/cascade-stripe-filament-2026-05-23` (BE) and `rename/ags-math-brand` (FE); nothing pushed yet. Tinker workarounds were used liberally during testing because `stripe listen` was never installed.

### Lives logic — final state in `question_screen.dart`

The original Phase 1B server-side grading went to prod in the AM session (commit `b48d028`). This PM session bolted UX polish on top:

- **Hard gate at submit time** — top of `_submitAnswer`: if `track && !unlimited && state.lives <= 0`, immediately call `_sendResults()` and return. User can never answer another question with 0 hearts.
- **Eager life deduction in `_submitAnswer`** (was deferred to `_nextQuestion` previously). Heart count animates down alongside the wrong-final feedback, not on Next-tap. `_nextQuestion`'s `shouldReduceLives` branch is now a no-op safety net.
- **Wrong-then-Skip in track mode** — Skip Question after a wrong attempt now queues the wrong answer + deducts (forfeits the Try Again grace).
- **Kiasu-skip** — separate branch that queues the question (with answer or null) but does NOT deduct lives (kiasu is premium / unlimited). Without this, kiasu skip dropped the user to home instead of advancing.
- **Heart UI redesign** — single doodle/Material heart + animated count via `AnimatedSwitcher` (220ms scale+fade) on home + question header. At 0 lives, the empty heart sits as a backdrop with the `+1 in Xh Ym` countdown overlaid, both fading together via a 1.2s repeating opacity pulse.
- **Home top bar consolidation** — kudos on the left, hearts on the right, single padded row; replaces the old full-width LivesHeader strip. The `compact: true` flag on `LivesHeader` strips the outer chrome.

### Subscription gating + auto-refresh on home

- **`_handleSubjectSelectTap`** in home_screen short-circuits to `OutOfLivesModal` when `lives==0 && !unlimited`, instead of pushing the subject-select screen → flash of question screen → gate. Subject Select tile is dimmed (opacity 0.5) with a lock icon when out of lives.
- **Premium user detection** comes from prefs `unlimited` boolean (synced from `/api/user/subscription-status`). Kiasu Path and Subject Select hide hearts entirely for premium.
- Tap LivesHeader → opens OutOfLivesModal directly (no need to enter a test first to discover you're locked out).

### Stripe — web buy-lives (full new flow)

- **BE**: `LivesPurchaseService::createCheckoutSession(user, quantity, success_url, cancel_url)` — creates a Stripe Checkout Session in `mode: payment` with `unit_amount=99`, `quantity=quantity/5`. Metadata `{user_id, lives, type: 'lives_purchase_web', package: 'web_{quantity}_lives'}` propagated to the resulting Payment Intent via `payment_intent_data.metadata`.
- **BE**: `LivesController::createCheckoutSession` + `POST /api/lives/checkout-session` route. Validates `quantity` is integer in [5,100] and multiple of 5; URLs as `starts_with:http://,https://` (not Laravel's `url` rule — Stripe's `{CHECKOUT_SESSION_ID}` placeholder contains curly braces that `filter_var` rejects).
- **BE webhook**: `StripeWebhookController::handle` `payment_intent.succeeded` branch — added `lives_purchase_web` handler that validates `amount_cents = (lives/5) * 99` and credits via `User::increment('lives', $lives)`. Fixed a latent bug where the legacy `lives_purchase` (mobile) handler was reading `$paymentIntent->metadata->lives` which was never set on creation — now derives lives count via `packageLivesCount($package)` lookup.
- **FE**: `BuyLivesBottomSheet` web branch — replaced `GetTheAppPanel` dead-end with a Material `Slider` (5-100, step 5) + live price display. Hits the BE endpoint and `web.window.location.assign(url)` to redirect.
- **FE**: `PaymentReturnScreen` (new) at `/payment-success` and `/payment-cancel` — polls `/api/user/subscription-status` every 800ms × 10 attempts (~8s) until lives credit lands, then shows "Lives credited!" and forwards to home.

### Stripe — web subscription (full new flow)

- **DB**: `subscription_plans.id=3` price 30 → 20 (premium_monthly is now SGD 20/month).
- **BE**: `PaymentController::createSubscriptionCheckoutSession` — Stripe Checkout in `mode: subscription` with inline `price_data` (no pre-registered Stripe Price IDs needed). Whitelists `plan_code IN ('premium_monthly', 'premium_annual')` only — SIMBA/Free/unknown get 422 PLAN_NOT_PURCHASABLE.
- **BE**: `POST /api/subscription/checkout-session` route.
- **BE**: `PaymentController::verifySubscriptionSession` — FE-driven sync credit. Takes `session_id` from the redirect URL, retrieves the Stripe Checkout Session, confirms ownership via `client_reference_id` + `metadata.user_id`, calls `SubscriptionService::handleSubscriptionUpdate($subscription)` directly. Idempotent — webhook can fire later without double-effect. Crucial because local dev has no `stripe listen`.
- **BE**: `POST /api/subscription/verify-session` route.
- **BE fix**: `SubscriptionService::handleSubscriptionUpdate` — plan resolution now falls back to `subscription.metadata.plan_id` when the `stripe_price_id` lookup misses. **Critical for inline-price-data subscriptions** — without this, inline-price subs are never matched and Premium status is silently never credited.
- **FE**: `SubscriptionOptionsSheet` web branch — dropped `GetTheAppPanel`, renders the Monthly SGD $20 + Annual SGD $200 cards (with "Save 17%" / "BEST VALUE" annual badge). Tap → `_handleWebSubscribe(planId)` → POST → redirect via `window.location.assign`. Mobile branch's stale `$35/mo` + wrong `planId: 2` (was SIMBA, not Premium) also fixed.
- **FE**: `PaymentReturnScreen` upgraded — extracts `session_id` from `web.window.location.href`, calls `verify-session` first, THEN starts the polling loop. Auto-refresh works without `stripe listen`.

### URL routing (web)

- **`usePathUrlStrategy()`** added in `main.dart::main` for web. Without it, Flutter web uses hash routes (`#/path`), and Stripe's `https://localhost:5050/payment-success?session_id=…` redirect didn't match the `/payment-success` route — Flutter would fall back to splash/home, the verify-session call never ran, and Premium credit never landed. **This was the root cause of the "subscription paid but no kiasu/subject access" symptom Pamela hit twice.**
- Removed the hardcoded `MaterialApp.initialRoute: '/'` — that was overriding the URL-based routing even after PathUrlStrategy was in place.

### Stripe `.env` swap (DEV ONLY — must be reverted for prod)

Current `.env` on local has:
- `STRIPE_SECRET_KEY=sk_test_51NcKSe…oXMX` (test secret)
- `STRIPE_KEY=pk_test_51NcKSe…IVL0` (test publishable)
- `STRIPE_WEBHOOK_SECRET=whse…fP3Y` (current value — needs verification; see below)

Backup at `.env.backup-pre-test-swap-20260526-160153` has the live `sk_live_` / `pk_live_` originally.

**Two webhook secrets to keep straight before deploy:**

1. **Test-mode endpoint on prod URL** (registered in Stripe Dashboard test mode) — `whsec_3M68rDtGXbIFATgtO3Mtv0MgfFspsK6g`. Belongs in **prod** `.env` if you ever want to run test-mode purchases against the deployed prod URL.
2. **Live-mode endpoint** — NOT YET REGISTERED in the Stripe Dashboard (as far as the session knows). Before going live in prod, register a webhook endpoint at `https://mathapi.allgifted.com/api/stripe/webhook` in **live mode**, subscribe to the 7 events listed in `[[reference_stripe_webhook_events]]` (or this doc, below), and put the live `whsec_` into prod `.env`.

### OutOfLivesModal / gates unified into one design system

- **New widget**: `widgets/gate_dialog.dart` — `GateDialog` shell + `GateActionCard` reusable card.
- **Refactored to use it**: `OutOfLivesModal`, `PremiumRequiredDialog`, `DiagnosticUnavailableDialog`. All three now render through the same chrome: 24px white card, soft shadow, max 400 width, X close button top-right routed through a single `_close` helper, 80px icon in 12%-alpha colored circle, 22pt bold darkRed centered title, 14pt grey subtitle, optional info card, optional section divider, action cards list, optional dismiss link.
- **OutOfLivesModal** also reordered the two action cards: Unlimited (highlighted, "BEST VALUE" badge) on top, Buy Lives below. Updated the comparison copy to use real DB-derived prices ($16.67/mo equivalent from $200/yr).

### AGS AI Math Tutor

- **Brand rename**: "AGS Math Tutor" → "AGS AI Math Tutor" in user-facing strings (FE: `question_feedback_area.dart`, `ags_tutor_solution_modal.dart`; BE prompt: `MathTutorPrompts::solveSystem`). Internal class names stay generic per `[[reference_ags_math_tutor_brand]]` memory.
- **Solve prompt nudge** — `MathTutorPrompts::solveSystem`: L200-499 band now also includes a short Algebraic section when the problem admits a one-line equation (was only L500+). Added the 30-students bar-model example as a few-shot.
- **FE labels** in `ags_tutor_solution_modal.dart`: "Bar model" → "Singapore (Bar Model)"; "Algebra (simultaneous equations)" → "Algebraic".

### Student vetting on AGS AI solutions (NEW feature)

- **Migration**: `2026_05_26_120000_add_student_vetting_to_solutions.php` — adds `solutions.student_vetted_at` (timestamp, nullable, indexed) + `solutions.student_vetted_by` (FK to users). New table `solution_votes (id, solution_id, user_id, vote enum[helpful, not_helpful], timestamps)` with unique `(solution_id, user_id)` and index on `(solution_id, vote)`. **Already run on local DB.**
- **BE**: `MathTutorController::voteOnSolution` + `POST /api/questions/{question}/solution/vote`. Validates `vote ∈ {helpful, not_helpful}`. `updateOrInsert` into `solution_votes` (re-voting flips the row). On first `helpful` vote (and only the first), stamps `solutions.student_vetted_at = now()` + `student_vetted_by = user.id`. Threshold = 1 helpful per launch product call.
- **FE**: `AgsTutorSolutionModal` converted to StatefulWidget. Footer with thumbs-up "This helped" / thumbs-down "Didn't help" buttons. After voting, footer flips to a "Thanks!" confirmation, buttons disabled. `question_feedback_area.dart` now passes `questionId` to the modal.

### Kiasu Path — dedup + skip behavior

- **`KiasuPathService::getKiasuPathQuestions`** — added `NOT IN ($alreadyPicked)` placeholder threading through all 3 selection steps (level loop, unpassed-track fallback, final random fallback) + a defensive `unique()` before assignment. No more duplicate questions within a single batch (cross-step overlap).
- **FE**: Kiasu Skip now queues the wrong answer + advances (instead of falling through to `_sendResults`'s empty-batch guard which dropped the user to home). No life deduction on kiasu (it's premium / unlimited by design).
- **Audit completed** via subagent: kudos `(difficulty_id ?? 0) + 1` per correct, 0 for wrong (mode='track' treated same as kiasu in KudosCalculator). Maxile via System B last-N-average across skill/track/field/user, no monotonic guards at any scope — confirmed matches documented intent. 3 worked examples + 1 edge case all pass. No code changes recommended.

### 99k-px RenderFlex overflow + TextStyle interpolation error (deferred Task #6, finally root-caused)

Intermittent on Submit and Next during track tests. Many attempts before root cause was found:

1. ❌ KeyedSubtree wrap on currentIndex — no effect
2. ❌ ConstrainedBox around Math.tex — capped size but didn't kill the TextStyle warning
3. ❌ RichText → Text.rich swap with explicit `rootSpanStyle` — partial improvement
4. ❌ DefaultTextStyle wrap around Math.tex with `inherit: false` — outer wrap didn't matter because Math.tex doesn't read ambient style
5. ✅ **Root cause**: the `textStyle` arg passed DIRECTLY to `Math.tex(textStyle: …)` had `inherit: true` (AppFontStyles default). flutter_math_fork internally uses `inherit: false` TextStyles. TextStyle.lerp asserts on mismatched `inherit`. Force `inherit: false` on the math style construction in `MathTextUtils.renderMathText` + `buildOptionText`.

Pamela hasn't yet confirmed whether the latest fix kills it. **If she still sees the warning after Ctrl+Shift+R + multiple Submit/Next interactions, the fix didn't take and another flutter_math_fork call site (e.g., inside the AGS modal's `_buildSteps`) needs the same `inherit: false` treatment.**

### Sentry (FE) noise disabled for local

- `main.dart`: `kSentryDsn` made overridable via `--dart-define=SENTRY_DSN=`; if empty, skip `SentryFlutter.init` entirely. Local runs are launched with `--dart-define=SENTRY_DSN=` so the stale-project "event submission rejected with_reason: ProjectId" warnings stop. Prod builds without that flag still get Sentry on the existing DSN.

### Other small things

- **`config/cors.php`** — pre-existing modification from a prior session, still uncommitted; allows localhost patterns when `APP_ENV=local`. Needed for the localhost:5050 → localhost:8000 dev loop.
- **`questions_per_test = 20`** (`configs` row) — kiasu test caps at 20 questions, batches of 5, level-laddered. Confirmed working via log inspection of test_id=3275.
- **`tmp-checkout-body.json`** — created during curl testing of the lives checkout endpoint. Should be deleted before commit (not sensitive, just clutter).

### Webhook events to subscribe in Stripe Dashboard (when registering live endpoint)

Per the 7-events list (matches `StripeWebhookController::handle` switch cases):
- `payment_intent.succeeded` (lives purchase + initial sub payment, mobile flow)
- `checkout.session.completed` (web flow — both lives + subscription)
- `customer.subscription.created`
- `customer.subscription.updated`
- `customer.subscription.deleted`
- `invoice.payment_succeeded`
- `invoice.payment_failed`

---

## Open items / next-step queue after this session

1. **Confirm 99k overflow fix held** — Pamela to re-test Submit/Next several times after Ctrl+Shift+R. If still showing, look for other Math.tex call sites inheriting AppFontStyles directly.
2. **PWA / Add-to-Home-Screen** — Already configured. `web/manifest.json` has `display: standalone`, name "AGS Math", theme/background colors, icons at 192 + 512 + maskable variants. Flutter web's build auto-generates the service worker. Mobile Chrome/Safari will show "Add to Home Screen" automatically once deployed at a public URL.
3. **Commit + push BE and FE** — neither repo has been committed since the AM session.
4. **Prod deploy** — Pamela asked, GATED on:
   - Restore `.env` Stripe keys to live (currently swapped to test)
   - Register live-mode webhook endpoint in Stripe Dashboard at `https://mathapi.allgifted.com/api/stripe/webhook` with the 7 events
   - Put the live webhook `whsec_` into prod `.env`
   - Run `php artisan migrate` on prod (the student-vetting migration will land there)
   - `php artisan route:cache && php artisan config:cache`
   - `php artisan queue:restart && systemctl restart apache2`
   - `chown -R www-data:www-data storage bootstrap/cache` (per `[[feedback_storage_chown_after_artisan]]`)
   - Smoke-test on prod with real test card before announcing
5. **Install Stripe CLI** — for proper local webhook testing. Today we worked around this with the verify-session endpoint, but the real webhook crediting path is still unverified end-to-end on local.
6. **Student vetting threshold review** — currently 1 helpful vote = student-vetted. Worth revisiting after a week of usage; may need to raise to 3 if low-effort first-clicks are noisy.

---

## 2026-05-26 AM session — kept for reference (pre-PM session)

### What shipped

### What shipped

1. **AI Math Tutor design doc — marked shipped** (BE `ae2b63a`).
   - `docs/sprints/ai-math-tutor-prototype-2026-05-25.md` rewritten from "awaiting sign-off" to "SHIPPED Days 1-6".
   - Added §0 commit map, marked §6 decisions RESOLVED, added §7 actual-vs-planned, filled in §8 success criteria with measured numbers, added §11.2 prod deploy checklist + §11.3 first-week monitoring.

2. **Lives correctness — login + subscription-status** (BE `b48d028`).
   - `app/Http/Controllers/OTPController.php::loginResponse` — calls `LiveService::regenerateLives()` then emits full snapshot (`lives, max_lives, unlimited, next_life_in_seconds, next_life_at, kudos`). Previously returned raw `$user->lives` column with no auto-restore.
   - `app/Http/Controllers/HomeController.php::subscriptionStatus` — same treatment.
   - `app/Http/Controllers/API/TrackController.php::postAnswers` — replaced `!$user->unlimited` predicate with `LiveService::hasUnlimitedLives($user)` so the deduct path + gate path share the canonical predicate.
   - Verified via tinker: `lives=1 → deductLife → lives=0`, gate predicate fires, response body has `{code: 205, lives: 0, can_answer: false}`.

3. **Lives sync + auto-flush — FE** (FE `1fcf081` on `rename/ags-math-brand`).
   - `lib/screens/auth/otp_verify_screen.dart` — persists `lives / max_lives / unlimited / next_life_in_seconds / is_subscriber / kudos / maxile_level / first_name` from verify-otp response. Previously only `token + user_id + kiasu_completed` were kept.
   - `lib/screens/home_screen.dart::loadFromStorage` — persists the full snapshot from `/api/user/subscription-status`, not just `lives`.
   - `lib/screens/question_screen.dart`:
     - New `_syncLivesFromResponse(result)` called from `_sendResults` — BE response overrides FE optimistic count on every batch.
     - Auto-flush at end of `_submitAnswer`: when a wrong-final answer would drop lives ≤ 0, schedule `_nextQuestion` 1.5s later so the gate appears without requiring a Next tap.
     - Idempotency guard at top of `_sendResults` (`_hasFlushed` bool) so the auto-flush timer and a manual Next tap can't double-POST.

### Diagnosis trail (so we don't relitigate)

- **Symptom Pamela reported:** after wrong answers FE batch sent to BE, gate didn't appear, BE kept sending more questions.
- **Audit (`php artisan tinker`):** user_id=2 today had 22 attempts across tests 3248 and 3254; only 2 were wrong (Q345 in test 3248 at 07:37:16, Q811 in test 3254 at 09:40:56). `lives=3`, `lives_restore_queue` had exactly 2 future timestamps (5h after each wrong). Internally consistent.
- **The specific Q599 submission Pamela flagged** (`answer: ["6", null, null, null]`) was **CORRECT** — Q599 is type=2 FIB with `answer0="6"`. BE correctly returned `code: 201` + 15 more questions and `lives: 3` unchanged.
- **Real root cause (her later clarification):** FE only flushed inside `_nextQuestion` (Next button) → trigger gap meant the gate didn't fire until the user tapped Next after their final wrong-life answer. Fixed by the auto-flush in `question_screen.dart`.

### Pushed

- BE: `feat/cascade-stripe-filament-2026-05-23` → `origin` ✅
  - PR URL: https://github.com/2ppaamm/capstoneapi/pull/new/feat/cascade-stripe-filament-2026-05-23
- FE: `rename/ags-math-brand` → `origin` ✅
  - PR URL: https://github.com/2ppaamm/flutterquiz/pull/new/rename/ags-math-brand

Both branches are ahead of `master`. No PRs opened yet.

### Uncommitted (intentionally left for Pamela)

- **BE: `config/cors.php`** — adds dev-only localhost `allowed_origins_patterns` gated by `APP_ENV`. From an earlier session. Safe to commit standalone with a `feat(cors): dev-only localhost patterns gated by APP_ENV` message.
- **FE: `lib/screens/auth/otp_request_screen.dart`** — switches OTP logo from web-conditional `registerOtpLogoView` to direct `Image.asset('assets/logo.png')`. Trim. Safe to commit standalone.

---

## Open items / next-step queue (priority order)

1. **Smoke-test the lives fix in the real app.** Tinker simulation passed but the FE has only been lint-verified. Test the full flow: login → home screen shows correct hearts → take a track test → get final-wrongs until heart counter hits 0 → confirm auto-flush fires within 1.5s and `OutOfLivesModal` appears.

2. **Open PRs** for both branches once smoke test passes. Use the PR URLs above. Recommend single PRs (not stacked) since each branch carries multiple concerns already.

3. **AI Math Tutor prod enablement** (from `ai-math-tutor-prototype-2026-05-25.md` §11.2). Gated on (a) lives fix landing on prod, (b) `ANTHROPIC_API_KEY` fingerprint verified on prod, (c) queue worker confirmed running. Then `AI_TUTOR_ENABLED=true` + `config:cache` + apache restart.

4. **Tune auto-flush delay if needed.** Currently `1500ms` so the user sees the wrong-answer feedback. If they want instant, drop to ~500ms; if they want longer reading time, push to 2500ms.

5. **Decide what to do with the two dangling commits** (cors.php, otp_request_screen.dart). Either commit them or revert.

---

## Earlier in this conversation (pre-compact)

This conversation began mid-thread after a context compact. Pre-compact work covered (per the summary):

- Cascade refactor + System B maxile rewrite (committed earlier — see git log on `feat/cascade-stripe-filament-2026-05-23`).
- Filament admin panel with QA cluster (committed).
- Stripe + Sentry hardening (committed).
- AGS Math Tutor v1 build Days 1-6 (committed — see commit map in `docs/sprints/ai-math-tutor-prototype-2026-05-25.md` §0).
- Branding migration to "AGS Math Tutor" (committed).

The detailed log is in `~/.claude/projects/C--allgifted-mathapi11v2/1227bf98-83bd-41d2-b110-d34fdd07c647.jsonl` if needed. Don't re-derive from it unless a specific decision is in dispute.

---

## Reference: project conventions to know upfront

These are codified in `CLAUDE.md` and `~/.claude/.../memory/MEMORY.md`. Read them first if you're a new CC instance:

- **API auth:** Sanctum guard, never default. `$this->user('sanctum')` / `auth('sanctum')->user()`. Bare default-guard calls return null for Bearer requests.
- **Mail config:** lives exclusively in `.env`, never `configs` table rows. `configs.mail_*` must stay NULL on every environment.
- **Admin login:** OTP-only, never password. Any new admin surface routes through the existing OTP flow.
- **Never view .env directly** via Read/cat/grep — exposes secrets to chat. Use fingerprint-only verification (head -c4 + tail -c4 + length).
- **Production server is git-read-only.** Allowed verbs: fetch / pull / log / status / diff / show. Never commit on prod.
- **After every prod `artisan` run as root:** `chown -R www-data:www-data storage bootstrap/cache`.
- **Brand name in user-facing copy:** "AGS Math Tutor". Internal class names stay generic (`MathTutorService` etc.).
- **Un-filled placeholders in prod scripts** (`PASTE_*`, `PUT_*`, `REPLACE_*`): stop and confirm before running.
- **System B maxile is the live formula** — last-N-average per skill, no monotonic guards at any scope (skill/track/field/user can decrease).
- **Per-tap idempotency:** `question_user.question_answered=1` is the durable replay guard in `AnswerGradingService` (Phase 1B).

---

## How to update this doc

When you (Claude Code, future session) make any of these changes, update the relevant section here BEFORE moving on:

- Shipped commit → add to "What shipped" with file paths and commit hash.
- Reproduced bug → add to "Diagnosis trail" with the smoking-gun line numbers.
- Product decision → add as a note under the affected feature.
- Pushed branch → update "Pushed" with branch name + URL.
- Uncommitted change deliberately left dangling → add to "Uncommitted" with a one-line reason.
- Open question raised → add to "Open items".

Keep it tight — one or two sentences per bullet. If a section gets long, archive the older content to a dated sprint doc under `docs/sprints/` and link from here.