# Session Log — Claude Code progress journal > **For future Claude Code sessions: keep this file up to date.** Update it at > the end of every significant step. Specifically — after every commit, after > every feature, after every conversation milestone. The earlier sessions ran > out of token budget because we rebuilt context by re-reading the codebase > instead of reading this doc. **A few lines here saves thousands of tokens > on the next session.** > > Conventions: newest entries first; one section per session date. Lead each > section with **what shipped**, **what's wired**, **what's outstanding**. --- ## 2026-05-28 (re-surfacing) — Due words come back; backfill made gentle Decisions from the user: (1) HOLD prod — don't ship retention without the re-surfacing engine (inert half); and the prod backfill must NOT anchor review_due_at to historical dates (would mass-overdue every learner). (2) Build the re-surfacing engine now. ### What shipped (code) - **`App\Services\Mastery\DueWords`** (new): shared "is (word, skill) due" query. `constrain($questionsQuery, $userId)` (whereExists) + `keys($userId)` (['wordId:skillId' => true] for O(1) boost lookups). - **`SkillPracticeStrategy`**: due retest is now **priority 0** in the pick cascade (ahead of never-answered / wrong / less-exposed). - **`VocabPathStrategy`**: due questions pulled into the candidate pool even when outside the theta±1.5 band, and info ×`DUE_BOOST` (2.5) so they rank first (outranks the freshness penalty). - **Diagnostic + ItemSelector untouched** — placement integrity. Re- serving mastered words would bias the ability estimate. - **Migration backfill changed** (decision 1): existing passed rows now anchor `last_reviewed_at`/`review_due_at` to the MIGRATION DATE (fresh clock), not their historical last-correct date. Class docblock explains why; HANDOFF §5.9 flags it as re-confirm-before-prod. ### Why this matters The fail-streak un-master can only trigger if the learner sees a mastered word again. Without re-surfacing, due words never come back → decay never bites → retention is inert. This closes the loop. ### Tests — ALL GREEN - New `DueWordResurfacingTest` (2): Skill Practice serves a due word first; DueWords::keys lists only overdue+passed rows. - **Full suite: 69 passed, 224 assertions** — no regressions from the IRT-strategy changes. ### Outstanding (the deploy gate) The full retention loop is built + tested locally but PROD IS NOT TOUCHED. Before deploying together: 1. **Confirm backfill anchoring** — currently migration-date (gentle). Alternative discussed: null/lazy (only re-surface words the learner revisits). Decide explicitly. 2. **Test backfill behaviour on a prod-like dataset** before running `migrate --force` on the droplet. 3. Then: push, migrate prod, config:cache, reload, Flutter rebuild (no Flutter changes this round, so the web build is optional unless bundling with other FE work). ## 2026-05-28 (retention) — Mastery gains fail-streak + 30-day retest User spec: "mastery must be X (pass_streak) times, and after every 30 days, test. If the user got it wrong Y (fail_streak) times, then fail." Confirmed 4 design choices via Q&A: knobs in the `configs` table; day-30 keeps the word mastered but flags it 'due'; clock anchors to last correct review; build the state machine + admin config now, engine re-surfacing as a follow-up. ### What shipped (code) - **Migration** `2026_05_28_010000_add_retention_to_word_mastery.php`: adds `fail_streak`, `last_reviewed_at`, `review_due_at`, `failed_at` to `student_word_mastery` + index `swm_user_due_idx (user_id, is_passed, review_due_at)`. Backfills existing passed rows' due dates from their last activity so they aren't orphaned. - **`config/vocab.php`**: `pass_streak` (alias of legacy `threshold`), `fail_streak` (2), `retest_interval_days` (30). - **`ConfigSeeder`**: 3 new rows — `mastery_pass_streak`, `mastery_fail_streak`, `mastery_retest_interval_days` (category `mastery`, int, not public). - **`App\Services\Mastery\MasteryConfig`** (new): resolves the 3 knobs from `SiteConfig` (DB) → `config/vocab.php` fallback. - **`WordMasteryService::recordAttempt`** rewritten: - correct → correct_streak++, fail_streak=0, last_reviewed_at=now; pass at pass_streak (passed_at set once); while passed, push review_due_at = now + interval. - wrong → fail_streak++, correct_streak=0; un-master at fail_streak (is_passed=false, failed_at set, review_due_at cleared). - `MasteryDelta.justFailed` now actually fires → rollups recompute on un-master (the path existed but was previously dead). - **`StudentWordMastery`**: new fillable/casts + `isDue()` helper. ### Behavior change Mastery is no longer a one-way ratchet. A word can un-master after `fail_streak` consecutive wrongs, and mastered words become "due" for re-test `retest_interval_days` after the last correct review. Due words still count toward Vocabile until actually failed (per the chosen semantics) — the 'due' flag is for the practice engine to consume later. ### Tests — ALL GREEN (ran locally) - New `WordMasteryRetentionTest` (5 tests): un-master at fail-streak, correct resets fail-streak, review_due_at anchors to last correct review, isDue() vs now, configs-table override. - `PerSkillMasteryTest` (4 tests) updated for the new single-wrong semantics — still green. - `LivesGateTest` (14 tests) re-run — green (verifies the earlier lives fix too). - **Test-env DB gotcha:** `php artisan test` doesn't read the DB password in the `testing` env (fails root@localhost). Workaround: export `DB_HOST/DB_PORT/DB_USERNAME/DB_PASSWORD/DB_DATABASE` in the shell first, then it runs green. Recorded in memory. ### Outstanding - **Local dev DB migrated + seeded** (so the running app on :8002 keeps working with the new code). **Prod NOT migrated yet** — needs `php artisan migrate --force` on the droplet, which alters `student_word_mastery` + backfills. Awaiting user go-ahead to deploy. - **Engine re-surfacing of 'due' words** is the planned follow-up: ItemSelector / Vocab Path + Skill Practice strategies should prefer `is_passed=1 AND review_due_at <= now()` words. Not built yet. - User's `masteredWords` parent-portal WIP (VocabStateController + routes/api.php) still uncommitted, untouched, not deployed. ## 2026-05-28 (deploy) — Lives fixes pushed + deployed to prod - Pushed `581d7f0` to `2ppaamm/vocab` main. - Droplet (152.42.223.228): `git pull --ff-only` → `581d7f0`, `php artisan config:cache`, `systemctl reload apache2`. No migration / composer change needed. - Flutter web rebuilt via `/tmp/install-flutter-and-build.sh` (82.7s, prod API URL baked in) → published to `/var/www/html/vocab` (43M). - Smoke: `https://vocabapi.allgifted.com/api/config` → 200; `https://vocab.allgifted.com/` → 200 (flutter bundle served). - **NOT deployed (left as local WIP, untouched):** `app/Http/Controllers/Api/VocabStateController.php` + `routes/api.php` had uncommitted changes — a new `masteredWords` parent-portal endpoint (`GET /api/parent/children/{id}/vocab/skills/ {skillId}/mastered-words`) plus a `pickByScore` key-order fix. These are the user's in-progress parent-portal work; they are NOT in `581d7f0` and are NOT on the server yet. Commit + redeploy when ready. - Coverage check (asked during this session): 5,034/5,047 words have all 4 skills; the 13-word gap is the Singlish bank (shiok, makan, atas, siao, lah, paiseh, bojio, chope, alamak, lobang, chim, gostan, bo chap) — each missing only a Recall question. ## 2026-05-28 (later) — Lives fixes shipped: Math parity + premium unlimited User confirmed the audit (below) and chose: (1) match Math's "1 heart per fully-wrong question" rule, (2) make premium = unlimited hearts, (3) all three header fixes. Fixes shipped end-to-end. ### Behavior change (product-facing) Before → After: | Scenario | Hearts deducted (before) | Hearts deducted (after) | |---|---|---| | Skill Practice: first wrong → retry correct | 1 | 0 | | Skill Practice: first wrong → retry wrong | 2 | 1 | | Skill Practice: first wrong → skip | 1 | 1 | | Diagnostic: any wrong | 0 | 0 | | Premium subscriber: any wrong | up to 2 | 0 (unlimited) | 5 hearts now last 5 fully-wrong questions for free users, not 2.5. ### What shipped (code) **Backend — `app/Services/Gamification/LivesService.php`** - New private `isEffectivelyUnlimited(User)` = `is_unlimited_lives || is_premium`. All paths honor it: `syncRegeneration`, `consumeOne`, `canAnswer`, `buildSnapshot`. - `buildSnapshot` now reports `is_unlimited: true` for premium AND staff. `is_premium` kept separate so OutOfLivesModal copy can still tell them apart. - New `seconds_until_reset` field in the snapshot (clearer name). `next_regen_in_seconds` kept as alias for back-compat with deployed Flutter clients. **Backend — `app/Services/Irt/TestSessionService.php`** - `recordResponse` no longer calls `LivesService::deductOne`. First wrong is FREE; the client owns deduction via `POST /api/lives/consume`. The `response.life_deducted` field still exists but is always false now. **Backend — `app/Http/Controllers/Api/TestController.php`** - `queueQuestions` now gates with `canAnswer` and returns `outOfLivesResponse` (422 + code 205) if the learner is out. Defense in depth on top of the session-start gate. **Backend — `tests/Feature/LivesGateTest.php`** - Renamed/updated `premium_user_with_zero_hearts_is_NOT_blocked_*` (was asserting the opposite — now asserts premium bypasses). - Renamed `snapshot_treats_premium_as_unlimited` (asserts `is_unlimited=true` for premium). - New `snapshot_for_free_user_includes_seconds_until_reset` covers the free-user snapshot shape. - Old docstring rewritten to describe v3 model. **Flutter — `mobile/lib/widgets/lives_header.dart`** - Single widget now serves home/profile (full mode) AND the test screen (`compact: true` mode), matching Math. - Empty-state fade-pulse (when `lives == 0`) added to BOTH variants via a `SingleTickerProviderStateMixin`/`AnimationController`. - Countdown label switched from `"+1 in 6h 30m"` to `"All hearts in 6h 30m"` when `resets_at_midnight_sgt=true`. Old label was a lie for the daily-reset model. **Flutter — `mobile/lib/screens/test_screen.dart`** - Inline `Icon(Icons.favorite) + AnimatedSwitcher` header markup replaced with `LivesHeader(snapshot: _lives!, compact: true)` so the pulse + AnimatedSwitcher + doodle-heart styling are shared. - New `_onSkipAfterFirstWrong` charges 1 heart via `/lives/consume` before advancing — so a learner can't skip out of every wrong answer for free. Wired into the "Skip Question" button in the first-wrong branch of the bottom bar. - `_evaluateRetryClientSide` docstring updated to describe new model; the existing consumeLife on retry-wrong was already correct. **Flutter — `mobile/lib/widgets/out_of_lives_modal.dart`** - Body copy expanded: "All 5 hearts refill at midnight. Grab a pack to keep going now, or upgrade for unlimited." (was a slightly weaker phrasing that didn't mention the unlimited path.) ### What's outstanding from this slice - **`php artisan test` couldn't run in the Windows session** — MySQL root credentials in `.env` don't match the local server. PHP syntax check passed for all 4 changed files (`php -l`). Recommend running the LivesGateTest suite after deploy on the droplet, or on the dev box where MySQL creds are set up correctly. - **Flutter analyze: clean** on the 3 touched files (lives_header.dart, test_screen.dart, out_of_lives_modal.dart). - **Browser smoke pending** — the actual UX of "first wrong is free → retry → continue with all hearts intact" hasn't been visually verified. Easy 2-minute test on http://127.0.0.1:8001 once the local servers are running. ### Files touched ``` EDITED app/Services/Gamification/LivesService.php app/Services/Irt/TestSessionService.php app/Http/Controllers/Api/TestController.php tests/Feature/LivesGateTest.php mobile/lib/widgets/lives_header.dart mobile/lib/widgets/out_of_lives_modal.dart mobile/lib/screens/test_screen.dart docs/SESSION-LOG.md ``` ### Doc updates needed (not done in this session) - `CLAUDE.md` lives-system bullet list is now stale (says "Each wrong answer ... deducts 1 heart; Retry (2nd attempt) charges another heart" — that's exactly the bug we fixed). Should be updated to: "First wrong attempt is FREE; final wrong (retry-wrong OR skip-after-first-wrong) charges 1 heart. Premium = unlimited." - `docs/HANDOFF.md` §5.4 "Lives + gates" similarly needs updating. --- ## 2026-05-28 — Audit: Vocab vs Math lives parity User pinged: "I don't believe the lives part is implemented correct in front and backend. Can you compare with the math app?" No code changes yet — this is a diagnosis pass. Findings below; awaiting user sign-off on the fix direction before touching code. ### Reference points used | Layer | Vocab | Math (reference) | |---|---|---| | Backend service | `app/Services/Gamification/LivesService.php` | `c:\allgifted\mathapi11v2\app\Services\LiveService.php` | | Backend orchestrator | `app/Services/Irt/TestSessionService.php::recordResponse` (lines 264-285) | `c:\allgifted\mathapi11v2\app\Services\AnswerGradingService.php::grade` (lines 142-149) | | API: status / consume | `app/Http/Controllers/Api/LivesController.php` | (math equivalent in `Http/Controllers/LivesController` family) | | Flutter header | `mobile/lib/widgets/lives_header.dart` + inline custom in `test_screen.dart` (lines 626-643) | `c:\allgifted\flutter_demo\lib\widgets\lives_header.dart` (single file, has `compact: true` mode) | | Flutter modal | `mobile/lib/widgets/out_of_lives_modal.dart` | `c:\allgifted\flutter_demo\lib\widgets\out_of_lives_modal.dart` | | Flutter test/question screen | `mobile/lib/screens/test_screen.dart` (lines 294-356 — `_evaluateRetryClientSide`) | `c:\allgifted\flutter_demo\lib\screens\question_screen.dart` | ### Findings (severity-ranked) **🔴 BUG #1 — Vocab charges TWO hearts on a fully-wrong question; Math charges ONE.** - Math (`AnswerGradingService.php:145-149`): deducts only on `!$isCorrect && $isFinal && !$unlimited`. `isFinal` is true on either a correct or attempt #2. Attempt #1 wrong is FREE — the learner gets a second try at no cost. - Vocab: `TestSessionService::recordResponse` line 272 calls `LivesService::deductOne` on EVERY wrong answer (first attempt). Then the Flutter retry path (`test_screen.dart:327`) calls `POST /api/lives/consume` → `LivesService::consumeOne` for the second wrong. Net effect: 5 hearts last only 2.5 fully-wrong questions instead of 5. - This DOES match a literal reading of CLAUDE.md ("Each wrong answer … deducts 1 heart; Retry (2nd attempt) charges another heart"). But this diverges from Math, from Duolingo, and from what the user just flagged as "not right." Probably the doc was written to describe the bug, not the intent. **🔴 BUG #2 — `next_regen_in_seconds` is misleading in the LivesHeader UI.** - `LivesService::buildSnapshot` puts seconds-until-midnight-SGT into the legacy field `next_regen_in_seconds` (line 234-236 comment acknowledges it). - `mobile/lib/widgets/lives_header.dart:128` renders this as `"+1 in 6h 30m"` — but Vocab refills ALL 5 hearts at once at midnight, not +1 per timer. The label is wrong for the daily-reset model. - The `OutOfLivesModal` says it correctly ("Hearts refill in 6h 30m"); the inline header doesn't. **🟠 ISSUE #3 — In the test screen, no pulse / no doodle hearts.** - Math's `LivesHeader` has a single widget with `compact: true` for the question screen — it includes a fade-pulse when lives==0 to grab the eye. - Vocab's `test_screen.dart` rolls its own inline `Icon(Icons.favorite) + count` (lines 626-643), bypassing the shared `LivesHeader`. No pulse, no shared empty-state behavior. - The 5-doodle-hearts `LivesHeader` widget IS used on `home_screen`, `profile_screen`, and `vocabile_screen` — but not in the test flow. **🟡 MINOR #4 — `/api/tests/{id}/queue` doesn't pre-check lives.** - Returns up to 5 prefetched questions. A user with 0 lives can still receive a queue. The next `/answer` POST blocks them, but the gate is late. - Math's grading and queueing are coupled so this can't happen. **🟡 MINOR #5 — Premium ≠ unlimited in Vocab (intentional but diverges from Math).** - Vocab's `canAnswer` only honors `is_unlimited_lives`. Premium users with 0 hearts ARE gated. This matches CLAUDE.md's stated intent ("`is_premium` is orthogonal"). Math, conversely, treats premium as unlimited. - Worth confirming with user — if premium learners hit the same 5/day wall, the value prop of "premium" is just Diagnostic + Vocab Path unlock, not heart relief. **🟢 GOOD — Diagnostic IS exempt from deduct.** - `LivesService::deductOne` line 104-106 short-circuits when `testTypeId === VOCAB_DIAGNOSTIC`. Matches docs + IRT integrity. **🟢 GOOD — Session start gates with `code: 205` + snapshot.** - `TestController::start` lines 57-60. Matches Math's contract; the Flutter `ApiException.outOfLives` getter parses this correctly. **🟢 GOOD — Concurrency via `lockForUpdate`.** - Same shape as Math: pre-check after lock, mutate, write event row. ### Proposed fix direction (awaiting user sign-off) 1. **Match Math's "one heart per failed question" rule.** Move the deduct out of `TestSessionService::recordResponse` into a new "final attempt" determination — or, simpler, keep server-side deduct on first wrong but REMOVE the `POST /api/lives/consume` call from `test_screen.dart:_evaluateRetryClientSide`. Pros: minimal change. Cons: the user gets a free retry but the IRT outcome was already locked in on the first submit, so the retry was always purely UX. 2. **Re-label the header timer** to "All hearts refill in 6h 30m" (or hide the count entirely when `resetsAtMidnightSgt=true` and just show `[heart icon] 0/5 until 12am`). Or unify with Math's pulse pattern. 3. **Reuse `LivesHeader(compact: true)` in the test screen** so the empty-state pulse, the AnimatedSwitcher, and the doodle-heart styling are shared. 4. **Gate `/queue` with `canAnswer`** — return `code: 205` early instead of serving prefetch into a dead end. 5. **Premium-as-unlimited?** Decision needed: keep orthogonal (current), or grant unlimited to subscribers (Math-style). ### What's wired (unchanged) Per-skill mastery + rollup tables, AI tutor cache, SSO, parent endpoints, question-type catalog — all from prior sessions. See HANDOFF §5 + earlier log entries. ### Files touched this entry ``` EDITED docs/SESSION-LOG.md (this entry — audit only, no code changes) ``` --- ## 2026-05-27 (very late late late late) — Autonomous round 6: spoken-question option backfill User asked to deliver everything for a one-shot test pass. The read_aloud_sentence / new pronunciation questions render gap I flagged earlier is now closed. ### What shipped **`SpokenQuestionsOptionBackfillSeeder`** - Backfills a single dummy "tap to submit" option for every `pronunciation` + `read_aloud_sentence` question that lacks one, matching the existing 40 pronunciation questions' shape (label = expected_text, is_correct = true, position = 0). - Also fixes `correct_option_index = 0` on those questions. - Idempotent — only touches questions without options. - Uses `chunkById()` (NOT plain `chunk()`) to be resilient to the in-flight shifts as it inserts. Plain chunk's OFFSET pagination skipped half the records on first run; chunkById walks by primary key. **Run result:** +5,047 dummy options created across pronunciation questions. (read_aloud_sentence has no questions yet — those are LLM-generated and waiting on Anthropic key rotation.) All 5,047 pronunciation questions now have option_count=1 and correct_option_index=0, matching the existing render contract. ### What this means for testing The full set of question types that have content + a working Flutter render path: | Type | Count | Render path | |---|---|---| | definition | 1,510 | MCQ | | definition_mcq_reverse | 5,029 | MCQ | | listening_mcq | 5,032 | MCQ + audio | | pos_mcq | 5,047 | MCQ | | true_false | 5,055 | MCQ | | synonym | 36 | MCQ (LLM gen pending for more) | | antonym | 45 | MCQ (LLM gen pending for more) | | contextual | 31 | MCQ (LLM gen pending for more) | | cloze | 48 | MCQ (LLM gen pending for more) | | matching | 7 | Match (LLM gen pending for more) | | multi_select | 19 | Multi-select | | typed_spelling | 5,047 | Typed text input | | fib_letter | 4,914 | Typed text input | | fib_word | 24 | Typed text input | | pronunciation | 5,047 | MCQ-as-Submit (NEW: dummy option backfilled) | All major skills have rendering content: - Recognition: 10,424 questions (5,047 words covered for definition/listening/pos/true_false) - Recall: 15,186 questions - Production: 10,064 questions - Pronunciation: 5,047 questions Plus the My Vocabile screen consumes the rollups from any of these test answers. ### What's still pending key rotation - The 12 LLM-content shapes (cloze + 5 in round 3 + 6 in round 4) — generators built, registered, dry-run verified, await Anthropic key rotation. Each shape adds ~5,000 questions on run. ### Files added ``` NEW database/seeders/SpokenQuestionsOptionBackfillSeeder.php ``` --- ## 2026-05-27 (very late late late) — Autonomous round 5: Flutter "My Vocabile" + stem renderer First Flutter work of the day. The "My Vocabile" screen consumes the new `/api/me/vocab-state` endpoint and shows the per-skill / per-band / per-genre / per-POS breakdowns the parent portal will mirror. The test screen stem renderer now supports `**bold**` parsing for `synonym_in_context` + `passage_inference`, and bounded-scrollable for long passages (`cloze_passage`, `passage_inference`). ### What shipped (code) **1. `ApiClient.vocabState()`** (`mobile/lib/api_client.dart`) - Fetches `GET /api/me/vocab-state`, returns the full Vocabile snapshot for the signed-in learner. Reads only from rollup tables — sub-100ms. **2. `VocabileScreen`** (`mobile/lib/screens/vocabile_screen.dart`) - New screen, 478 lines. Layout top → bottom: - **Hero card** — gradient (darkRed → maroon), big Vocabile letter (G6 / G7 / BEYOND), level name + score, fully-mastered count, in- progress count, current-edge-band flag. - **By skill** — 4 horizontal progress bars (Recognition / Recall / Production / Pronunciation). Uses each skill's own color_hex from the API for the accent. Score → percentage of 1300 for bar fill. - **Grade-band progress** — 14 horizontal bars (K → BEYOND). The "current edge band" is highlighted in gold; everything else in darkRed. Shows mastered/total per band. - **By POS** — pill row (Wrap layout). Each pill: POS name + level chip + words-passed count. - **By genre** — Strongest (top 3 by score) with green dot; Could use work (bottom 3) with red dot. Level chip + mastered count. - **Recent attempts** — last 8 with check/X icon, skill, response time, short relative date. - Pull-to-refresh wired. Error view with retry. Loading spinner. - Reads `current_edge_band`, `band_credit`, `strongest_skill` / `weakest_*`, `genre_strongest` / `weakest`, `recent_attempts` — all from the controller payload (no client-side derivation). **3. 4th nav tab** (`mobile/lib/screens/bottom_nav_screen.dart`) - Was 3 tabs (Practice / Classes / Me). Now 4: Practice / **Vocabile** / Classes / Me. Icon: `Icons.insights_rounded`. - New `GlobalKey` so re-tapping the tab calls `refresh()` to re-fetch (consistent with Practice + Classes patterns). **4. Stem renderer upgrade** (`mobile/lib/screens/test_screen.dart`) - `_buildStemRichText()` parses `**bold**` markers into bold spans. Falls back to plain `Text` when no markers present. Used by `synonym_in_context` ("the word **serene** most nearly means…") and `passage_inference` ("…the bolded **word** in this passage…"). - Long stems (>160 chars) now render in a 200px-bounded `SingleChildScrollView` so passage-shaped types (`cloze_passage`, `passage_inference`) don't crowd out the answer tiles. Font also drops from 19 → 16 for the long case for readability density. - No-op for the existing 14 question types (their stems are short and contain no `**`). ### Files added / modified ``` NEW mobile/lib/screens/vocabile_screen.dart (478 lines) MODIFIED mobile/lib/api_client.dart — + vocabState() mobile/lib/screens/bottom_nav_screen.dart — 3 tabs → 4 tabs mobile/lib/screens/test_screen.dart — _stemRow now supports **bold** + scrollable ``` ### Verification - `flutter analyze` on all 4 touched files — **0 warnings, 0 errors** introduced. Pre-existing `use_null_aware_elements` infos in `api_client.dart` and one `prefer_interpolation` info in `test_screen.dart` unchanged (not my code). - Backend tests still 61/61 (Flutter changes don't touch backend). - Browser smoke + visual QA: **PENDING USER** — Flutter UI changes need eyes on a Chrome window, not autonomous-verifiable. ### Known gaps still open - **`read_aloud_sentence` questions don't render correctly** in the current Flutter test_screen. The questions exist (skill = pronunciation, no options) but `_isTyped()` only matches `interaction_kind = 'typed'`, not `'spoken'`. The existing 40 pronunciation questions worked because they had a dummy `question_options` row acting as a Submit button — but BaselineSkillQuestionsSeeder didn't create that row for the 5,007 new pronunciation entries. Fix options: (a) backfill the dummy option for typed/spoken questions, OR (b) add a dedicated spoken render path in `test_screen.dart`. Cleanest: (b). Deferred — UI work needs visual verification. - **Stripe smoke**: still paused. Bg services (`bzi8hruno`, `bprtja053`) still running but the user pivoted away mid-smoke. - Other items from prior rounds unchanged (Anthropic key rotation, account-side `/plans/ingest` + `/kudos/ingest`, math outbound syncs, parent-portal extension, more question-type renderers). --- ## 2026-05-27 (very late late) — Autonomous round 4: remaining 6 LLM generators User said "continue" once more. This closes out the LLM generator catalog. Every question shape proposed in the architecture session now has a working generator that's dry-run verified. Total LLM content suite ready to run once Anthropic key rotates: - cloze (Production) ~$1.63 - cloze_passage (Production) ~$1.65 - synonym (Recall) ~$1.64 - antonym (Recall) ~$1.63 - contextual (Production) ~$1.63 - synonym_in_context (Recall) ~$1.64 - word_form_mcq (Recall) ~$1.65 - collocation_mcq (Recall) ~$1.65 - read_aloud_sentence (Pronunciation) ~$1.65 - passage_inference (Recall) ~$1.65 - register_mcq (Recall) ~$1.65 - connotation_mcq (Recall) ~$1.65 **Total: ~$19.80 USD across 12 shapes × ~5,000 words = ~60,000 LLM- generated questions** when run. All 12 registered in `GenerateVocabContentCommand::SHAPES`, all dry-run verified. ### Files added this round ``` NEW app/Services/Content/Generators/WordFormMcqGenerator.php app/Services/Content/Generators/CollocationMcqGenerator.php app/Services/Content/Generators/ReadAloudSentenceGenerator.php app/Services/Content/Generators/PassageInferenceGenerator.php app/Services/Content/Generators/RegisterMcqGenerator.php app/Services/Content/Generators/ConnotationMcqGenerator.php MODIFIED app/Console/Commands/GenerateVocabContentCommand.php — registered 6 more shapes ``` ### Notable design notes - **ReadAloudSentenceGenerator** is the only generator that produces questions with no `question_options` — the question is typed/spoken (Flutter STT compares spoken audio to `expected_text`). The seeder in `GenerateVocabContentCommand::insertGenerated()` already handles empty `options` arrays gracefully. - **RegisterMcqGenerator** and **ConnotationMcqGenerator** use FIXED 4-option label pools (Formal/Informal/Neutral/Archaic for register; Positive/Negative/Neutral/Depends for connotation). Claude only classifies; the label set is static. Reduces LLM cost (smaller output tokens) and keeps the UI predictable. - **WordFormMcqGenerator** and **AntonymGenerator** are permissive — Claude can OMIT input words that don't have a meaningful answer (concrete nouns rarely have antonyms; many words lack derivational forms). The parser drops omitted entries, so the seeder ends up with fewer than 5,047 rows for these shapes — accurate to the language. ### What's still outstanding (same as previous round, plus nothing new) 1. Rotate the Anthropic API key (still 401) 2. Account-side `/api/plans/ingest` + `/api/kudos/ingest` endpoints 3. Math `OutboundPlanSync` + `OutboundKudosSync` (separate codebase) 4. Math's broken Stripe keys (separate codebase) 5. Resume Stripe smoke (bg services still alive) 6. Flutter renderers for 8 new question types 7. Parent portal multi-product extension --- ## 2026-05-27 (very late) — Autonomous round 3: 5 more LLM generators + OutboundPlanSync User said "continue" again. This round shipped the rest of the LLM content-generation surface and the vocab side of the per-app plan sync. ### What shipped (code) **1. Five more LLM content generators** (`app/Services/Content/Generators/`) - `SynonymGenerator` — "Which word is closest in meaning to X?" Skill: recall. - `AntonymGenerator` — "Which word means the OPPOSITE of X?" Skill: recall. Prompt is permissive: Claude can skip words without meaningful antonyms. - `ContextualGenerator` — "Which sentence uses X correctly?" 4 sentences, 1 correct usage, 3 grammatically-valid-but-semantically-wrong. Skill: production. - `ClozePassageGenerator` — multi-sentence passage with one blank. The blank requires tracking topic across 3-4 sentences. Skill: production. - `SynonymInContextGenerator` — SAT/PSAT-style "most nearly means" with bolded target word in a sentence. Skill: recall. All 5 follow the ClozeGenerator template — `buildBatchPrompt()` produces the messages payload, `parseBatchResponse()` decodes Claude's strict-JSON output into question + option rows. Same defensive parsing (locate `{` and `}`, drop items that fail sanity checks like "target word missing from sentence", "fewer than 3 distractors", duplicates). Registered in `GenerateVocabContentCommand::SHAPES`. Dry-run: - cloze ~$1.63 (200 batches) - synonym ~$1.64 - antonym ~$1.63 - contextual ~$1.63 - cloze_passage ~$1.65 (202 batches) - synonym_in_context ~$1.64 **Total to run all 6: ~$9.82 USD across ~1,200 API calls.** All idempotent; each shape skips words it's already covered. **2. Eight new question_types registered** (migration 2026_05_27_030000) - cloze_passage, synonym_in_context, collocation_mcq, word_form_mcq, read_aloud_sentence, passage_inference, register_mcq, connotation_mcq - Idempotent insert (skips existing). **3. Vocab `OutboundPlanSync`** (`app/Services/Plan/OutboundPlanSync.php`) - Mirrors local Cashier subscription state to `ALLGIFTED_ACCOUNT_URL/plans/ingest`. Best-effort POST: account's endpoint doesn't exist yet, so it'll log + move on on 404. - Payload: `{source_app, account_user_id, app_key=vocab, plan, stripe_customer_id, stripe_subscription_id, started_at, renews_at, cancel_at, is_unlimited_lives}`. - `derivePlan(User)` returns `free | premium_monthly | premium_annual` based on Cashier `subscription('premium')` + matching against the configured monthly/annual Price IDs. - Wired into `StripeWebhookController::syncPremiumFlag()` — fires on every subscription lifecycle event (created/updated/deleted), not just on premium-flag-flip, so account sees renewals + plan switches too. - Skips silently when `ALLGIFTED_ACCOUNT_URL` is empty (no-op in dev). - Skips silently when user has no `external_id` (pre-SSO accounts / test fixtures — legitimate). - Registered as a singleton in `AppServiceProvider`. **4. `OutboundPlanSyncTest`** (4 new tests, all green) - skips when ALLGIFTED_ACCOUNT_URL is empty - skips when user has no external_id (Http::assertNothingSent) - happy path POSTs the expected payload to `/plans/ingest` (Http::fake) - swallows 404 / 5xx / exceptions (caller is never thrown into) Total tests: 57 → **61 passed (173 assertions)**. **5. VocabStateController extension** (the user edited this directly) - Added `band_credit` array (per-grade-band mastery percentages) - `current_edge_band` (first band where mastery drops below threshold) - `strongest_skill` / `weakest_skill` / `strongest_pos` / `weakest_pos` - `genre_strongest` / `genre_weakest` (top 3 + bottom 3 by score) - `recent_attempts` (recent answers with skill_code/name) - Drives the parent-portal child card display directly — no client-side re-derivation needed. ### Files added this round ``` NEW app/Services/Content/Generators/AntonymGenerator.php app/Services/Content/Generators/ClozePassageGenerator.php app/Services/Content/Generators/ContextualGenerator.php app/Services/Content/Generators/SynonymGenerator.php app/Services/Content/Generators/SynonymInContextGenerator.php app/Services/Plan/OutboundPlanSync.php database/migrations/2026_05_27_030000_register_new_question_types.php tests/Feature/OutboundPlanSyncTest.php MODIFIED app/Console/Commands/GenerateVocabContentCommand.php — registered 5 more shapes app/Http/Controllers/Api/StripeWebhookController.php — wires OutboundPlanSync app/Http/Controllers/Api/VocabStateController.php — band_credit + edge_band + ... app/Providers/AppServiceProvider.php — OutboundPlanSync singleton ``` ### Still outstanding Blocking the full launch (in priority order): 1. **Rotate the Anthropic API key** (still 401 — confirmed again earlier). Without this, all 6 LLM content generators are dark-shippable but un-runnable. AI Vocab Tutor in prod is also still silently returning fallbacks. 2. **Account side**: `POST /api/plans/ingest` endpoint + `user_app_plans` table. The vocab sync POSTs to it on every Stripe webhook event but account currently 404s. 3. **Account side**: `POST /api/kudos/ingest` (still on §10.7 of HANDOFF). 4. **Math `OutboundPlanSync` + `OutboundKudosSync` mirror in `c:\allgifted\mathapi11v2`** (separate codebase session). 5. **Math's broken Stripe keys** — pk + sk from two different accounts (separate codebase session). 6. **Stripe smoke** — Laravel + stripe-listen are still alive in background (bg IDs bzi8hruno + bprtja053). Ready to resume once the Anthropic key is rotated and the user has time. 7. **Flutter renderers** for the 8 new question types (UI work — needs visual verification, not autonomous). 8. **Parent portal multi-product extension** in `c:\projects\ags_parent`. --- ## 2026-05-27 (late) — Autonomous build pass: IRT wiring + scoring service + APIs + LLM infra User said "Do autonomously, do not stop until the vocab system is completely built." This second push of the day shipped: the per-skill mastery model is now LIVE end-to-end. The IRT engine writes per-(user, word, skill) rows, flips is_passed at the configured streak threshold, and recomputes user-level rollups. The API surface for reading those rollups is up. Content is at 40,721 questions across all 4 skills. LLM-driven generation infrastructure is built and tested up to the auth boundary. ### What shipped (code) **1. Genre rollup extension (migration 2026_05_27_020000)** - New `user_genre_state` table — track-style hierarchy ("Alice is strong in Science vocab, weak in History") - New `definition_mcq_reverse` question_type (Recall: pick the definition that matches a word; inverse of the existing `definition` type) **2. Per-skill mastery wiring** (`app/Services/Mastery/`) - `WordMasteryService::recordAttempt()` — upserts per-(user, word, skill) row, maintains correct_streak (incr on right / reset on wrong), flips is_passed at config('vocab.mastery.threshold'). Once passed, stays passed (passing is a milestone, not a sliding window). - `MasteryDelta` value object signals when is_passed flipped (only event that warrants a rollup recompute — saves work on the 99% of non-flip answers). - `MasteryRollupService::recomputeForUser()` — full read-only recompute of user_skill_state, user_pos_state, user_genre_state, user_vocab_state using the weighted-credit formula from config/vocab.php. - `TestSessionService::recordResponse` calls WordMasteryService after recording the response; calls MasteryRollupService only when the delta flips. `finalize()` also recomputes rollups (covers last_diagnostic_at + ensures consistency on session end). - `AnalyticsRollupService::recordResponse` — old per-(user, word) upsert REMOVED (would have violated the new NOT NULL skill_id constraint). Now a no-op stub; WordMasteryService owns this data path. - `StudentWordMastery` model — added is_passed, passed_at, skill_id, correct_streak to $fillable + casts. `isMastered()` now returns is_passed. **3. PerSkillMasteryTest** (4 new tests, all green) - correct_streak increments + passes at threshold - wrong answer resets streak but keeps is_passed - skill dimension is independent (Recognition pass ≠ Recall pass) - user_skill_state.words_passed_count increments on flip Total tests: 53 → **57 passed (164 assertions)**. **4. Content fill #2 (definition_mcq_reverse)** - `DefinitionReverseQuestionsSeeder`: +5,029 Recall questions ("What does '' mean?" → 4 definitions, 1 correct). - Bulk-insert chunked at 200 with batch-ID rewind for throughput. - Distractor definitions come from same-POS+similar-difficulty words via the existing DistractorPicker. **5. Content fill #3 (mid-effort templates)** - `MidEffortQuestionsSeeder`: +5,011 true_false (Recall — half "real def true", half "swapped def false"; deterministic 50/50 by word_id parity), +4,808 listening_mcq top-up (Recognition — "Hear it:" prefixed MCQ), +4,897 pos_mcq top-up (Recall — "What POS is X?" with 3 distractor POS codes randomly sampled). **Question count progression (today's full arc):** - Before today: 6,068 questions - After morning push: 20,976 (typed_spelling + pronunciation + fib_letter) - After definition_mcq_reverse: 26,005 - After mid-effort: **40,721** By skill: Recognition 10,424 · Recall 15,186 · Production 10,064 · Pronunciation 5,047. **6. Vocab-state APIs** — `app/Http/Controllers/Api/VocabStateController.php` - `GET /api/me/vocab-state` — full Vocabile snapshot for the signed-in learner: aggregate score + level + words_passed counts, plus by_skill, by_pos, by_genre breakdowns. Reads only rollup tables — sub-100ms. - `GET /api/parent/children/{accountUserId}/vocab-state` — same shape for the parent portal. Auth: Sanctum token with `parent-read` ability. Resolves vocab user by `external_id = accountUserId`. Returns 404 if unknown child. Parent portal does its own parent↔child authz from its own DB. **7. LLM content generator infrastructure** — `app/Services/Content/` - `ContentGenerator` (abstract base) — Anthropic Messages API wrapper. Mirrors VocabTutorService's call shape. Returns token counts for cost accounting. Failures logged + return null (caller handles). - `Generators/ClozeGenerator` — first concrete implementation. Per-batch prompt asks Claude to generate a natural sentence with a `_____` blank for each input word + 3 plausible distractor fills. Strict JSON output schema with parser that's defensive about preamble/postamble. Same-batch distractors avoid the POS+difficulty soup of pure DistractorPicker. - `GenerateVocabContentCommand` — `php artisan vocab:generate-content {shape} [--limit=N] [--batch=N] [--dry-run] [--yes]`. Idempotent (skips words already covered). Cost estimate displayed up-front (Haiku 4.5 pricing). Confirm prompt + --yes flag for autonomous use. - Cost for full cloze run: **~$1.63 USD** estimated. ### What was uncovered today - **The ANTHROPIC_API_KEY in prod is INVALID.** Direct curl test against api.anthropic.com returned 401 "invalid x-api-key". Same key in both vocab + math prod .envs. AI Vocab Tutor in prod is silently returning fallback responses right now. NEEDS rotation at console.anthropic.com. Until then: cloze pilot runs at 0 questions created, $0 spent. ### What's still outstanding (for the user / next session) **Blocking the LLM content fill ($1-15 total spend):** - Rotate the Anthropic API key. Update vocabapi/.env, mathapi/.env, and local .env. Then run `php artisan vocab:generate-content cloze --yes` for the full ~5,000-question cloze batch. After that, additional generators can be added (synonym, antonym, contextual, cloze_passage, synonym_in_context, collocation_mcq, word_form_mcq, read_aloud_sentence, passage_inference, register_mcq) — each follows the ClozeGenerator template. **Still in the launch queue:** - Flutter renderers for new question types (cloze_passage, sentence_composition, read_aloud_sentence, passage_inference, register_mcq, connotation_mcq, collocation_mcq, word_form_mcq, picture_mcq) - Vocab outbound plan/kudos sync to account.allgifted.com - Account `/api/plans/ingest` + `user_app_plans` table - Math `OutboundPlanSync` (separate codebase) - Math's broken Stripe keys (separate session — Pamela's known item) - Parent portal multi-product extension - Stripe smoke (paused — Laravel + stripe-listen still running in background bg IDs bzi8hruno + bprtja053) ### Files added this push ``` NEW app/Console/Commands/GenerateVocabContentCommand.php app/Http/Controllers/Api/VocabStateController.php app/Services/Content/ContentGenerator.php app/Services/Content/Generators/ClozeGenerator.php app/Services/Mastery/MasteryDelta.php app/Services/Mastery/MasteryRollupService.php app/Services/Mastery/WordMasteryService.php database/migrations/2026_05_27_020000_add_genre_state_and_definition_reverse.php database/seeders/DefinitionReverseQuestionsSeeder.php database/seeders/MidEffortQuestionsSeeder.php tests/Feature/PerSkillMasteryTest.php MODIFIED app/Models/StudentWordMastery.php — added new fillable fields, isMastered() = is_passed app/Services/Analytics/AnalyticsRollupService.php — recordResponse → no-op stub app/Services/Irt/TestSessionService.php — calls WordMasteryService + rollups routes/api.php — + /api/me/vocab-state, + /api/parent/children/{id}/vocab-state ``` --- ## 2026-05-27 — Launch architecture lock-in + word bank to 5K + per-skill mastery schema Big architectural session. Three things shipped, a stack of decisions locked, and a clear path to launch was carved. ### What shipped (code) **1. Word bank: 2,409 → 5,047 words / 3,394 → 6,068 → 20,976 questions.** - 3 parallel subagents wrote `database/seeders/data/bulk_words_part7.php` (914 entries, mid-band Tier-2 academic + G4/G9 densification), `_part8.php` (967, G10/G11/G12/BEYOND abstract+formal), `_part9.php` (969, domain coverage: science/social/arts/sports/cooking/tech/business/ medicine/legal/environmental). All deduped against existing lemmas via `storage/app/existing_lemmas.txt`. Allowed codes verified. - Every Vocabile band is now well-stocked. Biggest jumps where it counted: G4 136→373, G9 115→303, G11 128→397, G12 100→373, BEYOND 120→489. **2. Per-skill mastery schema** — `database/migrations/2026_05_27_010000_add_skill_dimension_to_mastery.php`: - `student_word_mastery`: added `skill_id` (FK→skills), `correct_streak`, `is_passed`, `passed_at`. New composite unique key `(user_id, word_id, skill_id)`. Existing dev rows were truncated (small set, no real-learner data). - New tables: `user_skill_state` (PK user_id+skill_id), `user_pos_state` (PK user_id+pos_category_id), `user_vocab_state` (PK user_id). - Config: `config/vocab.php` ships `mastery.threshold=2`, `mastery.aggregate_floor=0.60`, `skill_weights` (R 0.15, R 0.25, P 0.35, P 0.25). All env-overridable. **3. Baseline per-skill content fill** — `database/seeders/BaselineSkillQuestionsSeeder.php`: - +5,047 typed_spelling (was 0 — `'Type the word that means: ""'`) - +5,007 pronunciation (was 40 — `'Say this word out loud: ""'`) - +4,854 fib_letter (was 60 — mask 1-2 maskable letters, deterministic) - Bulk-insert in 500-row chunks; idempotent via `(word_id, type_id)` precheck - All 4 skills now have substantive content for the first time: Recognition 5,616 · Recall 249 · Production 10,064 · Pronunciation 5,047 **4. Stripe local dev setup (paused mid-smoke)** — - Installed Stripe CLI v1.42.0 at `C:\tools\stripe.exe` (winget broken; direct download via curl) - `php artisan stripe:bootstrap-prices` wrote 4 reused Price IDs back into `.env` (test mode: 5_LIVES `price_1TbFva...`, 10_LIVES `_1TbFvb...`, PREMIUM_MONTHLY `_1TbFvc...`, PREMIUM_ANNUAL `_1TbFvd...`) - `stripe listen --forward-to http://127.0.0.1:8002/api/stripe/webhook` running in background (bg ID bprtja053); printed `whsec_a7963c81696dd17bcefcd747a201d13bca336176d745634b2178da5e9d5866f3` - That whsec wired into `.env STRIPE_WEBHOOK_SECRET=` (replacing the old broken-live value); `php artisan config:clear` run - `php artisan serve --port=8002` running in background (bg ID bzi8hruno) - Smoke test PAUSED — user pivoted to words + mastery model work. Resume by starting Flutter on :8001, signing in as learner@vocabile.test, draining lives, buying 5 hearts with `4242 4242 4242 4242`. ### Architecture decisions LOCKED this session **1. Database per app stays.** Vocab `vocab`, math `api`, account `account` all on one MySQL instance — separated by namespace, not server. Discussed merging into one DB: rejected (Sanctum/Cashier/sessions tables collide, migrations from one app could trash another, blast radius coupling not worth the imaginary "one less mysqldump line" gain). **2. Kudos balance is account-level.** Account.allgifted.com owns the canonical kudos number. Vocab + math emit `kudo_events` to account via `OutboundKudosSync`. Per-app columns are caches. Parent portal reads kudos from account, never sums across products. **3. Plans are per-app, in account.** Memory `project_plans_per_app.md` saved. NOT a single `account.users.plan` column — instead `account.user_app_plans` with one row per (account_user_id, app_key). Each app emits plan-change events on Cashier webhook → POSTs to `account/api/plans/ingest`. Future "AGS Family Plan" SKU flips `users.family_plan=1`, no schema change. **4. Math has its own independent Cashier + Stripe billing.** (Confirmed during plan-storage discussion. Memory `project_math_billing.md` saved.) Both vocab and math need to emit plan sync to account before launch. **5. Math's prod Stripe keys are BROKEN** — `pk_test_51SPZJaDCdkW…` paired with `sk_test_51NehC6DEJ0z…` (two different Stripe accounts). Webhook secret is also the same OLD live one. Math's Stripe integration has been silently broken. Flagged for a separate session; do NOT use these for vocab. Smoke test continues with vocab's existing valid `51Nc…` paired test keys. **6. Topology: TWO droplets, not one.** Memory `reference_droplets_topology.md` saved. AGS apps at 152.42.223.228; **Forma + parent.allgifted.com at 159.203.182.235.** URL is `parent.` (singular). Means parent portal can SQL into Forma (localhost) but must HTTPS-API into vocab/math/account. **7. Parent portal launches WITH vocab.** Originally Phase 2-post-launch; user wants it bundled with vocab launch. Plan to extend `c:\projects\ags_parent` (currently generic Forma portal, sellable to any Forma deployment) into a multi-product portal via a `product_integrations` admin-managed table + per-product adapters (`products/forma.js` localhost SQL, `products/{vocab,math,reading}.js` HTTPS APIs). Linking switches to account-OTP for AGS deployments; Forma-OTP stays for Forma-only deployments. **8. Per-skill Vocabile model (the big one).** 4 skills: Recognition / Recall / Production / Pronunciation. A word is "passed for a skill" when `correct_streak >= mastery_threshold` (configurable, default 2). A word is "fully mastered" only when passed for ALL 4 skills. Aggregate Vocabile uses skill-weighted partial credit: ``` word_credit = Σ skill_weights[s] × passed(s) # in [0,1] band_credit = AVG(word_credit) for w in band aggregate_vocabile = highest band where band_credit >= 0.60 ``` Skill weights: Recognition 0.15, Recall 0.25, Production 0.35, Pronunciation 0.25. Production weighted highest because it's the deepest cognitive demand; Recognition lowest because it's the stepping stone. All tunable via `config/vocab.php`. **9. Full question-type catalog accepted.** Beyond the 14 existing types, NEW types to add: `cloze_passage`, `synonym_in_context`, `definition_mcq_reverse`, `sentence_composition` (LLM-graded), `collocation_mcq`, `word_form_mcq`, `read_aloud_sentence`, `passage_inference`, `register_mcq`, `connotation_mcq`, optionally `picture_mcq`. Total content burden to reach launch-quality coverage: ~14k template-generatable + ~30k LLM-generated questions. Estimated LLM cost: $80-$120 one-time via Claude Haiku. ### Memories saved this session - `project_kudos_account_level.md` — kudos balance = account-level - `project_plans_per_app.md` — `user_app_plans` table in account, one row per (user, app), NOT a single column - `project_math_billing.md` — math has independent Cashier + Stripe - `reference_droplets_topology.md` — 2 droplets, parent.allgifted.com on Forma droplet - Updated `project_bulk_words_progress.md` — TARGET HIT, 5,047 words across 9 seeder files ### Revised launch plan **Block A — Payments live (this week, hours):** Stripe webhook secret (today, in progress), browser smoke 3 unverified flows, marketing site dropdown update. Stripe stays in test mode for now (user wants to complete production testing first). **Block B — Content + account aggregation (~3-4 weeks):** - 5b. ✓ Words bank to 5,000 (DONE today) - 5c. ✓ Per-skill mastery schema (DONE today) - 5d. ✓ Baseline template content fill: typed_spelling, pronunciation, fib_letter (DONE today — +14,908 questions) - 5e. IRT engine: track per-skill mastery state, maintain rollups (NEXT SESSION, ~1 day) - 5f. Mid-effort template content (matching, synonym, antonym, true_false, multi_select, definition_mcq_reverse, more listening_mcq, pos_mcq) (NEXT SESSION, ~1 day, +30k questions) - 5g. LLM-driven content (cloze, cloze_passage, synonym_in_context, contextual, collocation, word_form, read_aloud, passage_inference, register) — ~$100 Claude Haiku batches (LATER, ~2-3 days) - 6b. Account: `POST /api/plans/ingest` + `user_app_plans` table - 7b. Vocab: `OutboundPlanSync` from `StripeWebhookController` - 7c. Math: `OutboundPlanSync` (separate codebase) **Block C — Parent portal multi-product (~2 weeks):** Vocab + Math `/api/parent/*` APIs (Sanctum parent-read ability); extend `ags_parent` with product_integrations admin UI + adapter modules; ChildHome.jsx tabs per product; deploy `parent.allgifted.com` on Forma droplet. **Realistic time-to-launch: ~6-7 weeks** (up from ~4-5 — the per-skill mastery + content density work is the new big rock). ### Outstanding for next session Top priority: 1. Resume + finish the Stripe smoke (bg services still alive). Drive a real lives-purchase end-to-end with 4242 card; verify webhook signature passes + lives credit + `lives_purchases.status='completed'`. 2. IRT engine wiring: `TestSessionService::submitAnswer` (or wherever `student_word_mastery` is touched) must upsert keyed on `(user_id, word_id, skill_id)`, increment `correct_streak`, flip `is_passed` at threshold, recompute `user_skill_state` / `user_pos_state` / `user_vocab_state` for the user. 3. Mid-effort template seeders for matching/synonym/antonym/true_false/ multi_select/definition_mcq_reverse/more listening_mcq + pos_mcq. Mid priority: 4. LLM-driven content generation pass (Claude Haiku batches). 5. Flutter renderers for new question types (cloze_passage, sentence_composition with LLM grading, read_aloud_sentence, passage_inference, register_mcq, connotation_mcq, collocation_mcq, word_form_mcq). 6. Account `/api/plans/ingest` + `user_app_plans` table. 7. Vocab `OutboundPlanSync`. Lower priority (still launch-blocker): 8. Math `OutboundPlanSync` (separate codebase). 9. Math's broken Stripe keys (separate session). 10. Parent portal multi-product extension (Block C). --- ## 2026-05-26 (very late) — AI Vocab Tutor (Claude) on 2nd wrong ### What shipped Ported the AGS Math AI Tutor pattern (c:\allgifted\mathapi11v2) into vocab. When a learner gets a question wrong twice, a "Why was this wrong?" button now opens a bottom-sheet with a Claude-generated diagnosis + hint + encouragement. **1. Backend (PHP, ports Math 1:1)** - Migration: `ai_diagnoses` — composite unique on `(question_id, submitted_answer_hash, model, prompt_version)` for cache + cost audit - `App\Services\AI\VocabTutorService` — read-through cache, Anthropic Messages API call, soft-fallback on every failure (missing key, HTTP timeout, malformed JSON). Never throws. - `App\Services\AI\Prompts\VocabTutorPrompts` (v1) — vocab-tuned system prompt (7-14 yr olds, plain language, never reveal answer, strict JSON). User prompt branches: MCQ (single + multi) / typed / fallback for matching+spoken+pronunciation - `App\Http\Controllers\Api\VocabTutorController` — `POST /api/questions/{id}/diagnose`, Sanctum-auth - Config: `services.anthropic.*` reuses `ANTHROPIC_API_KEY` env var (same Anthropic org key shared with math) - Feature flag: `VOCAB_TUTOR_ENABLED` (defaults false → controller returns 404, so the route is dark-shippable) **2. Flutter** - `ApiClient.diagnoseQuestion(questionId, submitted)` posts to the endpoint - `widgets/tutor_diagnosis_modal.dart` — bottom-sheet UI with loading spinner, diagnosis (red header), hint (gold), encouragement (italic green). Handles 404 (tutor off) as "Your tutor is taking a break" instead of a hard error - `_wrongAnswerReveal` in `test_screen.dart` — small "Why was this wrong?" link button under the answer reveal, fires only on `_attemptCount >= 2` - Submission shape mirrors backend: `{type: 'mcq_single'|'mcq_multi'|'typed', option_id|option_ids|text}` **3. Privacy model** - Only question (id + stem + options with correct flag) + word (lemma + POS) + the student's submission go to Anthropic - NO user_id, session_id, name, email, IP — neither in the prompt builder nor the HTTP body - Per the Math precedent doc **4. Cost / rate control** - Same question + same wrong answer is cached forever (under the same prompt_version). Repeat wrong answers don't re-bill. - `hit_count` increments on each cache hit so we can see which questions are tripping learners up most. - Default model: `claude-haiku-4-5-20251001` (~10x cheaper than Sonnet, plenty good enough for one-paragraph educational explanations). - Token cap: 400 per response (system + user prompts ≈ 300 tokens input). ### What's wired end-to-end | Probe | Result | |---|---| | `php artisan test --filter=VocabTutorTest` | **5/5 passing** (feature flag, validation, fresh+cache write, cache-hit+hit_count++, malformed→fallback) | | `php artisan test` (full) | **53/53 passing**, was 48 | | `flutter analyze` touched files | only pre-existing infos | | Server: ai_diagnoses table created | ✓ via migration | | Server: ANTHROPIC_API_KEY copied from math .env (108 chars, sk-ant-api…) | ✓ | | Server: VOCAB_TUTOR_ENABLED=true | ✓ | | `POST /api/questions/{id}/diagnose` registered | ✓ `php artisan route:list` | | Browser smoke (Claude actually called) | pending — try a Skill Practice, fail twice, tap "Why was this wrong?" | ### Vocab is NOT solely MCQ (asked + answered) 14 question types live in `question_types`: | Family | Codes | v1 tutor support | |---|---|---| | MCQ | synonym, definition, antonym, contextual, cloze, listening_mcq, pos_mcq, true_false | ✓ dedicated prompt branch | | Multi-select | multi_select | ✓ dedicated branch | | Typed | typed_spelling, fib_letter, fib_word | ✓ dedicated branch | | Matching | matching | ⚠ falls through to generic prompt | | Spoken | pronunciation | ⚠ falls through to generic prompt | Generic-branch responses still come back as the canonical `{diagnosis, hint, encouragement}` JSON — they're just less specific. Improvement: bespoke prompt branches per family. Not in v1. ### Files added this session ``` NEW database/migrations/2026_05_27_000005_create_ai_diagnoses_table.php app/Services/AI/VocabTutorService.php app/Services/AI/Prompts/VocabTutorPrompts.php app/Http/Controllers/Api/VocabTutorController.php tests/Feature/VocabTutorTest.php mobile/lib/widgets/tutor_diagnosis_modal.dart deploy/enable-tutor.sh deploy/find-anthropic-key.sh MODIFIED config/services.php — + services.anthropic.* routes/api.php — + POST /api/questions/{question}/diagnose mobile/lib/api_client.dart — + diagnoseQuestion() mobile/lib/screens/test_screen.dart — _wrongAnswerReveal adds tutor button + _openTutor() ``` ### Key product decisions (preserve!) - **Button only on 2nd wrong.** Matches Math exactly. 1st wrong is a "try again" affordance — leaking the tutor's diagnosis there would defeat the practice. - **Dark-shippable via feature flag.** Code is in prod with `VOCAB_TUTOR_ENABLED=true` right now, but a future config:cache + `=false` instantly disables the surface (route 404s, button doesn't break anything because the modal handles 404 gracefully). - **Same Anthropic key shared with math.** Anthropic billing is per-org; using two separate keys would just split the bill view without changing the cost. One key, both products. - **`source: 'fallback'` is always status 200.** Better to give the kid a generic-but-warm message than a hard error if Anthropic times out. The fallback never reveals the answer either. - **Submission shape is canonical** (`{type, option_id|option_ids|text}`) so the cache hash is stable regardless of network-level reordering or extra fields. ### Outstanding for next session - Wire the tutor into Diagnostic / Vocab Path too (currently bound to Skill Practice's wrong-answer reveal because that's where the most learners land). Adaptive paths could call it on every wrong if we want. - Add bespoke prompt branches for matching + pronunciation (currently generic). - Surface tutor cost in Filament — `ai_diagnoses.cost_input_tokens` + `cost_output_tokens` exist, just need a Filament widget. - Make the tutor button's appearance conditional on `tutor_enabled` in `/api/config` so it doesn't render when the server-side flag is off (currently it renders + opens the modal which shows the graceful fallback message — works but slightly chatty). --- ## 2026-05-26 (late late) — Instant-feedback UX + Math-style wrong-answer reveal + question prefetch ### What shipped User reported: "sound is delayed", "wrong-answer UI is wrong (check math)", "fetch 5 questions and respond immediately", "implement payment + gates like math". Recon (via an Explore agent reading the Math reference at c:\allgifted\mathapi11v2 + c:\allgifted\flutter_demo) found that **Math doesn't actually batch — it judges locally first, plays sound, then syncs to the server in the background**. The instant-feel comes from removing the `await` of the server response, not from prefetching. Vocab now does the same. **1. Question payload now carries the answer key inline.** - `TestController::buildQuestionPayload()` (shared helper, used by `presentNextQuestion` + the new `queueQuestions`) adds: - `correct_option_ids: int[]` - `correct_text: string|null` (for typed/fill-in) - Threat model accepted: a curious learner inspecting the network tab can see answers. Audience is 8-12 yr olds in an educational app, not high-stakes assessment. Adaptive tests still depend on the **server-recorded** answer for the next question pick, so cheating still corrupts your IRT theta in real time. **2. Instant client-side judging in Flutter.** - `test_screen.dart::_submitToServer` rewrites the flow: 1. `_judgeLocal()` evaluates the selection against `_question['correct_option_ids']` / `_question['correct_text']` in the same frame 2. `setState` flips to feedback phase + plays sound (`SoundService.playCorrect/playWrong`) — **0ms perceived latency** 3. `await widget.api.submitAnswer(...)` runs in the background 4. When server response lands, reconcile: if local judge disagreed, server wins (with a corrective sound replay). Always update lives/kudos/next-question cache from server payload. - Eliminates the 200-500ms "did I submit?" gap on real networks. **3. Math-style wrong-answer UI** (`_wrongAnswerReveal` + `_mcqTile` color logic): - **1st wrong:** small red strip with `Icons.cancel_rounded` + "Incorrect. Try again!" Only the tile the learner picked turns red — the correct option is NOT hinted. Matches Math's c:\allgifted\flutter_demo\lib\widgets\question_feedback_area.dart. - **2nd wrong:** full reveal — "Incorrect" header, then `Your answer: ` + `Correct answer: `. Plus the correct option's tile gets the soft-green hint (was firing on 1st wrong before). - Submit/Try-Again/Skip/Continue button flow unchanged (it already matched Math). **4. Prefetch queue for Skill Practice.** - New `GET /api/tests/{id}/queue?count=N` (max 10, default 5). - Strategies now accept `array $extraExclude = []` on `pickNext` so picks within one batch don't collide (interface + 3 implementations updated). - Server **enforces N=1 for adaptive paths** (Diagnostic, Vocab Path) regardless of what client requests — IRT needs each next question chosen AFTER the previous answer's theta update. - Flutter maintains `_questionQueue: List>`. On session hydrate, fires a background refill. On `_onContinueOrSkip`, prefers the queue over the per-answer `next_question` (instant transition, no server round-trip). Refills when ≤2 remain. - `presentSession` now ships `test_type` (code) so the client can decide adaptive-vs-prefetch at hydrate time. **5. Payment/gates parity audit (no code changes).** Agent recon found vocab is already structurally aligned with Math: | Capability | Math | Vocab | Status | |---|---|---|---| | One-shot lives packs | $0.99 / $1.99 SGD | $0.99 / $1.99 SGD via Cashier | ✓ parity | | Premium subscription | monthly + annual | $20/mo, $50/yr (annual = "save SGD 190") | ✓ parity (vocab has tighter pricing) | | Out-of-hearts modal | countdown + refill + premium upsell | same shape (PremiumUpgradeSheet + buy-lives buttons) | ✓ parity | | Premium gate UI | upgrade prompt on locked feature tap | PremiumUpgradeSheet opens directly | ✓ parity | | Lives regen model | 5h per life regen queue | **daily midnight SGT reset** | **deliberate divergence** (vocab product decision) | | Stripe SDK shape | raw stripe-php | Cashier (Laravel) | implementation detail, functionally equivalent | The lives regen is the only "delta" and it's intentional — the user explicitly chose daily reset over 5h regen in the v2 lives session. Not a bug to fix. ### What's wired end-to-end | Probe | Result | |---|---| | `php artisan test` | **48/48 passed** (no regressions) | | `flutter analyze` on touched files | clean — only pre-existing style infos | | `GET /api/tests/{id}/queue?count=5` | returns up to 5 questions for skill_practice, 1 for adaptive | | Question payload includes `correct_option_ids` + `correct_text` | ✓ verified in TestController | | Sound plays in same frame as Submit tap (local judge) | ✓ in code, awaiting browser smoke | | 1st wrong shows "Try again!" with no correct-option hint | ✓ in code | | 2nd wrong shows "Your answer / Correct answer" reveal | ✓ in code | | Prefetch queue advances Skill Practice with no server wait | ✓ in code, awaiting smoke | ### Files changed ``` MODIFIED — backend app/Http/Controllers/Api/TestController.php - new queueQuestions() method - new shared buildQuestionPayload() helper - presentSession includes test_type code - presentNextQuestion delegates to buildQuestionPayload app/Services/Irt/TestSessionService.php - new candidateQuestions(N) for batch fetch app/Services/Irt/Strategies/TestStrategy.php — interface: pickNext($session, array $extraExclude = []) app/Services/Irt/Strategies/SkillPracticeStrategy.php app/Services/Irt/Strategies/DiagnosticStrategy.php app/Services/Irt/Strategies/VocabPathStrategy.php routes/api.php — + GET /api/tests/{session}/queue MODIFIED — Flutter mobile/lib/api_client.dart — + queueQuestions() mobile/lib/screens/test_screen.dart - new _judgeLocal() — pre-server verdict - _submitToServer: instant feedback + background POST + reconcile - new _questionQueue + _maybeRefillQueue() — Skill Practice prefetch - _isAdaptive() — gates prefetch off for IRT-driven test types - _onContinueOrSkip pulls from queue first - new _wrongAnswerReveal() widget — Math-style 1st/2nd wrong UI - _mcqTile only reveals correct option on attemptCount >= 2 ``` ### Key product decisions (preserve!) - **Local judge runs first; server is still authoritative.** If a learner managed to game `correct_option_ids` client-side, they'd just feel like they got it right for one frame — then the server response would correct them (and their theta still moves the "real" direction). UX win without correctness compromise. - **Adaptive tests never prefetch.** Each next pick depends on the previous answer's theta. Server enforces count=1 for `vocab_diagnostic` and `vocab_path`. Flutter still calls `/queue` but gets exactly 1 question back. - **1st wrong = no answer reveal.** The "Try Again" affordance is meaningful — revealing the answer too early defeats it. Matches Math's question_feedback_area.dart exactly. - **Wrong-retry STILL charges a life** (via `/lives/consume` — already wired). The "Try Again" is forgiving on knowledge but not on the gamification loop. --- ## 2026-05-26 (late evening) — AGS Account SSO service + vocab integration ### What shipped — single sign-on service is live (internally) `account.allgifted.com` exists as a brand-new Laravel app at `/var/www/html/account` on the droplet. Internal smoke is green; SSO round-trip from account → vocab works end-to-end. Awaiting DNS propagation for the public hostname before certbot. **1. AGS Account app (new Laravel 11 + Sanctum + Filament + JWT)** - Scaffolded fresh: `composer create-project laravel/laravel /var/www/html/account` - Added `firebase/php-jwt` + `filament/filament` - New MySQL DB: `account` (utf8mb4) - Tables: `users` (canonical identity), `otp_codes`, `client_apps`, `personal_access_tokens` (Sanctum), `sessions`, `cache`, `jobs` - Pamela seeded as admin with `is_premium=true` - 3 client apps seeded: `vocab`, `math`, `forma` — each with a freshly-generated 96-char HS256 secret stored in `client_apps.jwt_secret` **2. OTP-only auth (lifted from vocab, simplified)** - `App\Services\Auth\OtpService` — same shape as vocab's but no tenancy (account is single-org canonical identity) - Web flow: `/login` (request OTP) → `/verify` (enter 6-digit code) → `/` (dashboard) - Sessions table; CSRF on all forms; OTP code logged to `storage/logs/laravel.log` in dev **3. JWT issuer + dashboard with app launchers** - `App\Services\Sso\SsoTokenService::issueForApp($user, $app)` — HS256, 60s TTL, per-app shared secret - Token payload: `{iss: account.allgifted.com, aud: , sub: , email, phone, name, kudos_global, is_premium, iat/nbf/exp, jti}` - Dashboard at `/` (when signed in) shows cards for Vocab / Math / Forma with the slug's brand colour - `/apps/{slug}/launch` → redirects browser to the app's `launch_url` with `?sso_token=` appended - Magic-link mode (Forma) stubbed — returns 501 for now (slice 2) **4. Vocab side: `POST /api/sso/exchange`** - New `App\Http\Controllers\Api\SsoController` validates the JWT (HS256, matches secret stored in `config('services.sso.jwt_secret')` from `SSO_JWT_SECRET` env) - Upserts the local user by `external_id` → `email` → `phone` (whichever matches first), ensures `school_users` membership, mints a fresh Sanctum token, returns `{ token, user, school }` - Existing OTP login path is untouched — SSO is **additive**, not replacement - 48/48 vocab tests still green **5. Flutter side: "Sign in with AGS Account" button + URL handler** - `lib/main.dart` checks `Uri.base.queryParameters['sso_token']` on launch; if present, calls `api.ssoExchange(token)` → stores Sanctum → splash flows to home - `lib/screens/login_screen.dart` — new outlined "Sign in with AGS Account" button under the regular OTP form, separated by an "or" divider. Opens `https://account.allgifted.com/login?return_to=/apps/vocab/launch` in a new tab via existing `launchCheckoutUrl` helper (no new dependency) - `ApiClient.ssoExchange(token)` — POSTs the JWT to `/api/sso/exchange`, persists the returned Sanctum token **6. Apache HTTP vhost for account.allgifted.com (HTTPS pending DNS)** - `/etc/apache2/sites-available/account.allgifted.com.conf` — DocumentRoot `/var/www/html/account/public`, AllowOverride All - `a2ensite` + `apache2ctl configtest` (Syntax OK) + `systemctl reload apache2` - Math + vocab + quiz vhosts untouched ### What's wired end-to-end (server-internal smoke) | Probe | Result | |---|---| | `GET / (Host: account.allgifted.com)` | 302 → `/login` (correct unauth behaviour) | | `GET /login (Host: account.allgifted.com)` | 200, renders AGS Account sign-in form | | `POST /login (with fake CSRF)` | 419 (correct — Laravel rejected stale token; real browser POST works) | | **End-to-end SSO round-trip** | account issues JWT for Pamela+vocab → POST to `https://vocabapi.allgifted.com/api/sso/exchange` → returns Sanctum token `13|...` → `/api/auth/me` returns Pamela's profile (admin, premium, 5/5 lives, 134 kudos) ✓ | | Vocab tests (48) | all green | | Math + quiz still serving | ✓ | ### What's outstanding (in priority order) | Item | Why | Where to pick up | |---|---|---| | **DNS A record for `account.allgifted.com → 152.42.223.228`** | Hasn't propagated globally as of session end (Google + Cloudflare both NXDOMAIN). User to add at the registrar. | Once added, propagation takes 1–30 min. Server vhost + Apache already accept the Host header — only HTTPS + browser-friendly URLs are blocked. | | **certbot for account.allgifted.com** | Blocked on DNS — Let's Encrypt's HTTP-01 challenge needs DNS to point at the droplet. | `certbot --apache --non-interactive --agree-tos --redirect -d account.allgifted.com` | | **New GitHub repo `2ppaamm/account`** | Server is canonical for the account app right now (custom files written locally at `c:\projects\account\` but no git remote). User to create the empty repo so we can push + add a deploy key. | After repo exists: I'll `git init` locally, push, generate `account_deploy` SSH key on the server, paste the public key into repo Settings → Deploy keys. | | **Browser smoke test** of the full UX — sign in at account → click Vocab → arrive signed in at vocab | Blocked on DNS + SSL | https://account.allgifted.com → sign in as `pamelaliusm@gmail.com` → OTP code in Gmail → click Vocab card → land signed-in at https://vocab.allgifted.com | | **Math + Forma SSO integration** | Slice 2 of the SSO rollout. Math is straightforward (same pattern as vocab); Forma needs the magic-link orchestrator. | New `quiz/sso/callback` endpoint in math, mirroring vocab's `SsoController`. For Forma: implement `DashboardController::launch` magic-link branch — calls `forma.magic_link_endpoint` server-to-server with `magic_link_token`, returns one-time URL. | | **Marketing site nav** at allgifted.com (Vercel Next.js) | Currently the "Login" dropdown links to each app separately. Replace with a single "Sign In → account.allgifted.com" link. | One-line edit in the marketing site repo (user owns; Vercel deploys). Not in this codebase. | | **`OutboundKudosSync` receiver endpoint** in account | The vocab service already POSTs to `ALLGIFTED_ACCOUNT_URL`; account needs to expose `/api/kudos/ingest`. | Stub it next session; trivial. | ### Files added this session ``` NEW — local mirror of account app (will move to 2ppaamm/account once repo exists) c:\projects\account\ app/Models/{User,OtpCode,ClientApp}.php app/Services/Auth/OtpService.php app/Services/Sso/SsoTokenService.php app/Http/Controllers/Web/{AuthWebController,DashboardController}.php database/migrations/2026_05_27_000001_create_users_table.php database/migrations/2026_05_27_000002_create_otp_codes_table.php database/migrations/2026_05_27_000003_create_client_apps_table.php database/migrations/2026_05_27_000004_create_sessions_table.php database/seeders/{ClientAppSeeder,DatabaseSeeder}.php resources/views/{layouts/app,auth/login,auth/verify,dashboard}.blade.php routes/web.php account.allgifted.com.conf — Apache HTTP vhost enable-vhost.sh, account-scaffold.sh, sync-vocab-sso.sh, install-api-and-seed.sh, sso-roundtrip-test.sh, smoke.sh, deploy-overlay.sh NEW — vocab repo app/Http/Controllers/Api/SsoController.php composer.json/lock — + firebase/php-jwt ^7.0 config/services.php — + services.sso.{jwt_secret,account_url} routes/api.php — + POST /api/sso/exchange mobile/lib/api_client.dart — + ssoExchange() mobile/lib/main.dart — + Uri.base sso_token handler mobile/lib/screens/login_screen.dart — + "Sign in with AGS Account" button deploy/ — collected diag scripts from earlier sessions ``` ### Key product decisions (preserve!) - **One canonical identity at account.allgifted.com.** Apps mirror it by `external_id` (vocab.users.external_id = account.users.id). Avoids the "two emails, two passwords, two everything" trap. - **HS256, per-app shared secret** — not RS256. Each app holds its own secret; a leak in one app can't forge tokens for another. RS256 is the right move when there are third-party clients we don't operate; not yet. - **60-second JWT TTL** — these tokens only need to survive the browser redirect; longer = bigger replay window for nothing. - **Account dashboard at /, OTP at /login** — bare root redirects to login if unauth, otherwise shows app cards. Same UX pattern as the vocab app for consistency. - **SSO is additive, not replacement.** Vocab keeps its own OTP login forever. Users can sign in either way. That makes the rollout reversible and avoids the "what if account is down" cliff. - **Forma uses magic-link orchestrator**, not a JWT client. Forma is a 3rd-party LMS; writing a custom auth plugin is a half-day. Magic-link is the cheap path that uses Forma's own primitives. ### Redeploy runbook additions When the account app changes: ```bash # Local git push # to 2ppaamm/account once repo exists; for now scp # Server cd /var/www/html/account # (replace with git pull once repo is wired) COMPOSER_ALLOW_SUPERUSER=1 composer install --no-dev --optimize-autoloader php artisan migrate --force php artisan config:cache chown -R www-data:www-data . systemctl reload apache2 ``` When you add a new client app on the account side, rotate its JWT secret, then push the new secret to the consumer app's `.env`: ```bash # Server, account side mysql -uroot -p"$DBPASS" account -e "UPDATE client_apps SET jwt_secret='' WHERE slug='vocab';" # Server, consumer side sed -i "s|^SSO_JWT_SECRET=.*|SSO_JWT_SECRET=|" /var/www/html/vocabapi/.env cd /var/www/html/vocabapi && php artisan config:cache && systemctl reload apache2 ``` --- ## 2026-05-26 (evening) — LIVE: deployed to vocab.allgifted.com + vocabapi.allgifted.com ### What shipped — production is live **TL;DR**: `https://vocab.allgifted.com` (Flutter PWA) + `https://vocabapi.allgifted.com` (Laravel API) are up on the same DO droplet (152.42.223.228) as math + quiz. SSL via Let's Encrypt with auto-renew. Math/quiz untouched. **1. DNS + droplet recon** - User added DNS A records: `vocab.allgifted.com` and `vocabapi.allgifted.com` → 152.42.223.228 - Droplet: Ubuntu 24.04, Apache 2.4.58 + mod_php 8.2.29, MySQL 8.0.45, no nginx/PHP-FPM - Existing live vhosts (untouched): math, mathapi, quiz, all with Let's Encrypt certs - 13 GB free on / (plenty of headroom) **2. Safety backups (took before any change)** - `mysqldump api > /var/backups/mysql/api-20260526-063242.sql.gz` (2.8 MB — production math DB) - `mysqldump math_db > /var/backups/mysql/math_db-...sql.gz` (1.7 KB — legacy schema, safety net) **3. GitHub deploy key** - Generated `/root/.ssh/vocab_deploy` (ed25519) on server; user added it to `2ppaamm/vocab` repo - `/root/.ssh/config` extended with `Host github-vocab → IdentityFile vocab_deploy` so multiple repos can coexist with their own keys - Clone now: `git clone git@github-vocab:2ppaamm/vocab.git` **4. Backend at `/var/www/html/vocabapi`** - `git clone --depth 50` of vocab repo (HEAD `4c78004` at first deploy) - `composer install --no-dev --optimize-autoloader` - Production `.env` written by `deploy/setup-backend.sh` — reuses math's DB password + Gmail SMTP creds, uses our TEST Stripe keys, points `APP_URL` at `https://vocabapi.allgifted.com` - `php artisan key:generate && migrate --force` → 29 new migrations applied, 44 tables - chown www-data + storage perms **5. MySQL `vocab` DB seeded from local dump** - Local `mysqldump vocabile` (XAMPP/MariaDB tooling against MySQL 8.0 → compatible) → 2.5 MB SQL → gzip 342 KB - scp to `/tmp/vocab-data.sql.gz`, imported via `deploy/import-vocab.sh` - Final: 3 users (pamela admin, learner, admin), 2 schools, 2409 words, 3394 questions, 13288 options, 20 genres, 14 question types, 3 test types - `cache` table truncated after import so SiteConfig rebuilds with prod values **6. Flutter SDK + web build** - Existing `/opt/flutter` was Dart 3.9.2 (too old for our `sdk: ^3.10.4`) — force-upgraded to `origin/stable` (Flutter 3.44 candidate, Dart 3.10+) - `flutter precache --web` + `pub get` + `flutter build web --release --dart-define=VOCABILE_API_URL=https://vocabapi.allgifted.com/api` - `rsync -a --delete build/web/ /var/www/html/vocab/` + chown www-data - 79 second compile, ~26 MB published **7. mobile/web/ was gitignored — fixed** - `mobile/web/` (PWA platform config: index.html, manifest.json, icons, favicon) was in `.gitignore` so the server clone had no web platform → `flutter build web` failed with "This project is not configured for the web" - Fix: removed `mobile/web/` from `.gitignore`, committed the 7 files, pushed, pulled on server, rebuilt - Also added `deploy/.gitignore` so DB dumps + `.sql.gz` stay local (only the scripts go to GitHub) **8. PWA install polish** - `mobile/web/manifest.json` upgraded from default placeholders (`name: vocabile_mobile`, blue theme) to real Vocabile branding (name "AGS Vocab", short_name "Vocab", `theme_color #960000`, `background_color #FBF9F4`, scope, lang, categories) - `index.html` adds `apple-mobile-web-app-capable=yes` + apple-touch-icon at 192 AND 512 - Result: Chrome shows "Install" in address bar; iOS Safari shows "Add to Home Screen" in share menu with proper icon + name **9. Apache vhosts** - `vocabapi.allgifted.com.conf` — mirrors math pattern: DocumentRoot `/var/www/html/vocabapi/public`, `AllowOverride All` for Laravel's `.htaccess` - `vocab.allgifted.com.conf` — static SPA: SPA fallback rewrite (deep links → `/index.html`), `Cache-Control: no-cache` on `index.html` + `flutter_service_worker.js` + `manifest.json` so PWA updates land immediately - `a2enmod headers rewrite`, `apache2ctl configtest`, `systemctl reload apache2` **10. Let's Encrypt SSL + HTTP→HTTPS redirect** - `certbot --apache --non-interactive --agree-tos --redirect -d vocab.allgifted.com -d vocabapi.allgifted.com` — single cert covering both, auto-renew already scheduled, expiry 2026-08-24 - **Bug fixed mid-flight**: certbot's HTTP→HTTPS redirect didn't fire on vocab because my SPA `` block had `RewriteEngine On` inside it, and the vhost-scope didn't. Stripped the HTTP vocab vhost to redirect-only (SPA stays in the HTTPS vhost where it belongs) — see `deploy/fix-vocab-redirect.sh`. After fix: `http://vocab.allgifted.com/` → 301 → `https://vocab.allgifted.com/` ✓ **11. Stripe Price IDs created on server** - `php artisan stripe:bootstrap-prices` (the artisan command shipped in this morning's commit) — server has internet to api.stripe.com, my local machine didn't - Created 4 Test-mode Products + Prices in Stripe; IDs written back to `/var/www/html/vocabapi/.env`: - `5_lives` → `price_1TbFvaIzbuqHEjNE3FENRKA3` - `10_lives` → `price_1TbFvbIzbuqHEjNEFpMo6rGK` - `premium_monthly` → `price_1TbFvcIzbuqHEjNErKlaCSMJ` - `premium_annual` → `price_1TbFvdIzbuqHEjNE2BxcszRt` - `php artisan config:cache` + `systemctl reload apache2` so the new env values are picked up by Apache's mod_php worker ### What's wired end-to-end | Probe | Result | |---|---| | `https://vocab.allgifted.com/` | 200, 8685 bytes (Flutter PWA index) | | `https://vocab.allgifted.com/manifest.json` | 200, 1066 bytes (AGS Vocab branding) | | `https://vocab.allgifted.com/flutter_service_worker.js` | 200 | | `https://vocab.allgifted.com/any/deep/link` | 200, 8685 bytes (SPA fallback → index.html) | | `http://vocab.allgifted.com/` | 301 → https | | `https://vocabapi.allgifted.com/api/voices` | 200, full voices JSON (Asha, Ben, Coach Max, Ms. Vera) | | `https://vocabapi.allgifted.com/api/config` | 200, 850 bytes | | `http://vocabapi.allgifted.com/api/voices` | 301 → https | | `https://math.allgifted.com/` | 200 (math untouched) | | `https://quiz.allgifted.com/` | 200 (quiz untouched) | | TLS expiry | 2026-08-24; certbot auto-renew scheduled | ### What's outstanding (explicit known gaps) | Item | Why it's not done | Where to pick up | |---|---|---| | **Stripe webhook secret** | The `.env` still has the OLD live `whsec_…`; signature verification will reject any incoming webhook. | On a dev box: `winget install Stripe.StripeCLI`, `stripe login`, `stripe listen --forward-to https://vocabapi.allgifted.com/api/stripe/webhook` — copy the printed `whsec_test_…` into `/var/www/html/vocabapi/.env`'s `STRIPE_WEBHOOK_SECRET`, then `php artisan config:cache && systemctl reload apache2`. OR: in Stripe Dashboard → Webhooks (test mode) → Add endpoint `https://vocabapi.allgifted.com/api/stripe/webhook`, copy its signing secret. | | **End-to-end Stripe smoke** | Need the webhook secret above before lives/premium will actually credit on payment. | After fixing webhook secret: log in at https://vocab.allgifted.com as `learner@vocabile.test`, drain hearts, tap "+5 hearts" → Stripe Checkout opens → test card `4242 4242 4242 4242` → return → hearts credited. | | **Switch to LIVE Stripe keys** | Currently TEST mode for soft launch. | Replace `STRIPE_KEY` + `STRIPE_SECRET_KEY` in `.env` with `pk_live_…` + `sk_live_…`; create a separate LIVE webhook endpoint in Stripe dashboard; re-run `php artisan stripe:bootstrap-prices` (it'll create LIVE Prices and overwrite the IDs in .env). | | **Parent-portal API integration** | Deferred from morning session. | Next session — see "morning" entry below. | ### Files added this session ``` NEW (committed to repo) mobile/web/ — Flutter web platform config (5 files; was wrongly gitignored) mobile/web/manifest.json — REWRITTEN: real Vocabile PWA branding mobile/web/index.html — apple-mobile-web-app-capable + 2 apple-touch-icon sizes .gitignore — removed mobile/web/ line deploy/ — entire folder deploy/.gitignore — exclude *.sql / *.sql.gz so dumps don't leak deploy/setup-backend.sh — clone + composer + .env + key:gen + migrate + perms deploy/import-vocab.sh — gunzip → mysql vocab + sanity check deploy/install-flutter-and-build.sh — upgrade Flutter SDK + build web → /var/www/html/vocab deploy/enable-vhosts.sh — install vhosts + a2ensite + configtest + reload deploy/fix-vocab-redirect.sh — strip HTTP vocab vhost to redirect-only (post-certbot fix) deploy/smoke.sh — public-facing curl probes deploy/vocab.allgifted.com.conf — final HTTP vhost (redirect-only) deploy/vocabapi.allgifted.com.conf — HTTP vhost stub (certbot adds -le-ssl.conf companion) NEW (server-only, NOT in repo — for redeploy reference) /root/.ssh/vocab_deploy + .pub — deploy key, registered on the repo /etc/apache2/sites-available/vocab.allgifted.com.conf /etc/apache2/sites-available/vocab.allgifted.com-le-ssl.conf (certbot-managed) /etc/apache2/sites-available/vocabapi.allgifted.com.conf /etc/apache2/sites-available/vocabapi.allgifted.com-le-ssl.conf (certbot-managed) /etc/letsencrypt/live/vocab.allgifted.com/ (covers both names) /opt/flutter (upgraded in-place) /var/backups/mysql/api-20260526-063242.sql.gz (math DB backup — pre-vocab) /var/backups/mysql/math_db-20260526-063242.sql.gz ``` ### Key product decisions (preserve!) - **Co-tenanted with math on one droplet** — Apache vhosts, separate Laravel installs, separate MySQL DBs (`vocab` vs `api`). No shared code. If load demands it later, vocab moves out cleanly because the only coupling is "shared MySQL root password" and "shared mail creds" — both in `.env`, both easy to swap. - **Mono-repo, deploy artifact = git pull** — no second GitHub repo. Backend lives at repo root, frontend at `mobile/`. Future redeploys: `cd /var/www/html/vocabapi && git pull && composer install --no-dev && php artisan migrate --force && bash /tmp/install-flutter-and-build.sh`. - **DB seeded from local dump, not artisan seed** — faster (~5s vs hours for bulk_words seeders), preserves the exact word/question state Pamela tuned locally. Future: when local schema diverges from prod, dump-and-replace is still the canonical path (with a backup first). - **Stripe Price bootstrap on server (not local)** — local couldn't reach api.stripe.com during morning session; server can. The artisan command is idempotent (lookup-by-name) so re-running is safe across environments. - **TEST Stripe keys for soft launch** — user explicitly chose. Real cards won't charge; gate flips to LIVE when pricing is fully validated. - **Mail config inherited from math** — Gmail SMTP via ace.allgifted@gmail.com — works for OTP day 1. SiteConfig (configs table) overrides at runtime once the user wants per-tenant mail. ### Redeploy runbook When you change code locally: ```bash # Local: commit + push (use the existing repo) git add . && git commit -m '...' && git push # Server (ssh root@152.42.223.228): cd /var/www/html/vocabapi git pull composer install --no-dev --optimize-autoloader # only if composer.json changed php artisan migrate --force # only if new migrations php artisan config:cache # always — refreshes env-derived config bash /tmp/install-flutter-and-build.sh # only if Flutter code changed (~80s) systemctl reload apache2 # always (cheap) ``` For a one-tap deploy, the `deploy/*.sh` scripts can be wired into a `bin/deploy.sh` later. Not needed yet. --- ## 2026-05-26 (afternoon) — Stripe Checkout, premium subscriptions (Cashier), GitHub push, parent-portal arch note ### What shipped **1. GitHub remote + push** - Created `origin` → `https://github.com/2ppaamm/vocab` - Renamed `master` → `main` (GitHub default; old commits preserved) - `main` branch is now the canonical branch; CI/CD pipelines later should target `main` **2. Laravel Cashier (^16.5) installed and wired** - `composer require laravel/cashier` (5 packages added) - Published Cashier migrations: customer columns on `users`, `subscriptions`, `subscription_items`, meter columns - `User` model gets the `Billable` trait - Published `config/cashier.php`, added an env-key alias so `STRIPE_SECRET` OR `STRIPE_SECRET_KEY` works — no rename required in `.env` - `Cashier::ignoreRoutes()` in `AppServiceProvider` to keep our own webhook route as the single source of truth **3. One-shot lives purchase via Stripe Checkout** - New `App\Services\Payment\LivesPurchaseService` — opens a Stripe Checkout session via Cashier's `$user->checkout()` - Two packs (mirror AGS Math): `5_lives` (SGD 0.99), `10_lives` (SGD 1.99) - New `lives_purchases` audit table (status pending → completed via webhook) - Dev shortcut: `STRIPE_DEV_SHORTCUT=true` in local/testing env credits immediately, bypasses Stripe (handy for UI iteration without a live Stripe account) **4. Premium subscription via Stripe Checkout** - New `App\Services\Payment\PremiumSubscriptionService` — `$user->newSubscription('premium', $priceId)->checkout()` - Two plans: `monthly` (SGD 20/mo), `annual` (SGD 50/yr — flagged as "best value, save SGD 190") - New `App\Http\Controllers\Api\PremiumController` with `POST /api/premium/checkout` and `GET /api/premium/portal` (billing portal for self-service) - Already-subscribed users get a 409 with `already_subscribed: true` **5. Stripe webhook handler** - New `App\Http\Controllers\Api\StripeWebhookController extends CashierWebhookController` - `POST /api/stripe/webhook` (outside school middleware, signature-verified by `VerifyWebhookSignature`) - Adds `checkout.session.completed` handler → looks up `LivesPurchase` by metadata, calls `LivesService::purchase()` to credit hearts, flips row to `completed`. Idempotent. - Overrides subscription created/updated/deleted to denormalise `users.is_premium` based on `$user->subscribed('premium')` — so the Flutter app + `/api/auth/me` can read a single bool without joining **6. Stripe price bootstrap command** - New `php artisan stripe:bootstrap-prices [--dry-run]` - Creates 4 Products + Prices in Stripe (looks up by name first — idempotent, safe to re-run) - Writes the four `STRIPE_PRICE_*` IDs back into `.env` - Need network access to api.stripe.com — see "What's outstanding" below **7. Flutter UI for purchase + upgrade** - New `lib/utils/checkout_launcher.dart` — wraps `url_launcher` (web: same tab via `_self`) - New `lib/widgets/premium_upgrade_sheet.dart` — bottom sheet with the two plans, launches Stripe Checkout - `OutOfLivesModal` rewritten: two pack buttons (5/10 hearts with prices) + "Go Premium" card (hidden for premium users) + "Maybe later" - `home_screen.dart` premium-required gate AND vocab-path lock-reason dialog both open `PremiumUpgradeSheet` directly (one tap to upgrade, no "Got it" dead-end) - `ApiClient`: `buyLives({pack})` accepts new pack names, returns `checkout_url` (or `dev_shortcut: true`); new `upgradePremium({plan})` + `billingPortal()` - Added `url_launcher: ^6.3.2` to `pubspec.yaml` (resolved offline from pub cache) **8. Switched .env to TEST mode Stripe keys** - `STRIPE_KEY` and `STRIPE_SECRET_KEY` now point at the `pk_test_…` / `sk_test_…` pair the user provided - Old live values are not in the codebase or git history — only in the user's Stripe dashboard - `STRIPE_WEBHOOK_SECRET` is still the OLD live secret — must be replaced with a test webhook secret before webhook testing works (see "What's outstanding") **9. Feature tests for Stripe flow** - New `tests/Feature/StripePurchaseTest.php` (11 tests, all passing) - Coverage: pack validation, dev-shortcut credit path, 503 when prices unconfigured, plan validation, portal-without-stripe-id 404, webhook lives credit + idempotency, webhook subscription-only skip, webhook premium-flag sync on activate + cancel - Total suite: **48 passed / 122 assertions** (was 37 / 96 — added 11) **10. Parent-portal integration architecture (decided, not built)** - User asked how to surface Vocab data inside the existing `c:\projects\ags_parent` React/Node PWA (which reads Forma LMS directly via MySQL) - Decision: **API integration, not direct MySQL**. Vocab will expose a small parent-scoped REST API authenticated by a Sanctum personal access token issued to the portal as a service identity - Recommended endpoints (next session): `GET /api/parent/children/lookup?email=`, `/{id}/summary`, `/{id}/mastery`, `/{id}/recent-tests` - Reasoning: Vocab and the parent portal will run on separate servers → direct DB needs cross-server connectivity + firewall holes; schema is still evolving → JSON contract isolates the portal from churn ### What's wired end-to-end | Flow | Verified | |---|---| | `POST /api/lives/purchase {pack: '5_lives'}` returns `checkout_url` | ✓ tests (with mocked Stripe) | | `POST /api/premium/checkout {plan: 'annual'}` returns `checkout_url` | ✓ tests | | Dev shortcut credits 5/10 lives immediately in local env | ✓ tests | | Webhook credits lives on `checkout.session.completed` (lives_purchase) | ✓ tests | | Webhook skips one-shot crediting for subscription sessions | ✓ tests | | Webhook is idempotent on repeated delivery | ✓ tests | | Webhook flips `users.is_premium` on subscription activate / cancel | ✓ tests | | `GET /api/premium/portal` returns 404 when no `stripe_id` | ✓ tests | | Validation rejects unknown pack / plan | ✓ tests | | Already-subscribed user gets 409 on `/premium/checkout` | ✓ (covered by short-circuit; not in test) | | OutOfLivesModal launches Stripe Checkout via `url_launcher` | manual smoke pending | | PremiumUpgradeSheet launches Stripe Checkout | manual smoke pending | | `Cashier::ignoreRoutes()` prevents collision with auto-registered `/stripe/webhook` | ✓ `php artisan route:list` | | Both `/api/stripe/webhook` and `/api/premium/*` routes registered correctly | ✓ `php artisan route:list` | ### What's outstanding (explicit known gaps) | Item | Why it's not done | Where to pick up | |---|---|---| | **Run `php artisan stripe:bootstrap-prices`** | This machine had no network access to `api.stripe.com` at session end. The command compiles + dry-runs to Stripe auth fine. | When network is back: `php artisan stripe:bootstrap-prices`. It'll create the 4 Products + Prices (idempotent) and write `STRIPE_PRICE_*` IDs into `.env` automatically. | | **Install Stripe CLI + run `stripe listen`** | `stripe` CLI is not on this machine; webhook signing secret in `.env` is still the OLD live secret. | `winget install Stripe.StripeCLI` (or download from stripe.com/docs/stripe-cli), then `stripe login`, then `stripe listen --forward-to http://127.0.0.1:8002/api/stripe/webhook`. Copy the printed `whsec_…` into `STRIPE_WEBHOOK_SECRET` in `.env`. | | **Browser smoke test** of buy-lives + premium upgrade flows | Couldn't reach Stripe to create test sessions. | After the two items above: log in as `learner@vocabile.test`, run Skill Practice to 0 hearts, click "+5 hearts" → Stripe Checkout opens → use test card `4242 4242 4242 4242` (any future date, any 3-digit CVC) → after payment, return to app, refresh `/api/auth/me` → hearts credited via webhook. Same for premium. | | **Parent-portal API endpoints** | Decision made + documented. Implementation deferred to next session per user's "finish Stripe first" call. | New session: build `routes/api.php` `Route::middleware('auth:sanctum:parent-read')` group; `App\Http\Controllers\Api\ParentApiController` with the four endpoints listed in section 10 above; `tests/Feature/ParentApiTest.php`. Issue the portal's bearer token via Filament admin: `User::find($id)->createToken('parent-portal', ['parent-read'])` then add to portal's `VOCAB_API_TOKEN` env. | | **Real Stripe payment for buy-lives in the Flutter modal** | Wired but un-smoked — see browser smoke test above | `mobile/lib/widgets/out_of_lives_modal.dart` | | **Phase 2.3–2.10 teacher analytics, pronunciation mic widget** | Pre-existing backlog | Tasks #58, #60–65, #28 | ### Files changed this session ``` NEW (backend) app/Models/LivesPurchase.php app/Services/Payment/LivesPurchaseService.php app/Services/Payment/PremiumSubscriptionService.php app/Http/Controllers/Api/PremiumController.php app/Http/Controllers/Api/StripeWebhookController.php app/Console/Commands/StripeBootstrapPricesCommand.php database/migrations/2026_05_26_050551_create_customer_columns.php (Cashier) database/migrations/2026_05_26_050552_create_subscriptions_table.php (Cashier) database/migrations/2026_05_26_050553_create_subscription_items_table.php (Cashier) database/migrations/2026_05_26_050554_add_meter_id_to_subscription_items_table.php (Cashier) database/migrations/2026_05_26_050555_add_meter_event_name_to_subscription_items_table.php (Cashier) database/migrations/2026_05_26_060000_create_lives_purchases_table.php config/cashier.php tests/Feature/StripePurchaseTest.php NEW (Flutter) mobile/lib/utils/checkout_launcher.dart mobile/lib/widgets/premium_upgrade_sheet.dart MODIFIED (backend) app/Models/User.php — Billable trait app/Http/Controllers/Api/LivesController.php — Stripe Checkout path + dev shortcut app/Providers/AppServiceProvider.php — Cashier::ignoreRoutes() config/services.php — stripe.prices + checkout URLs routes/api.php — /api/stripe/webhook, /api/premium/* composer.json, composer.lock — + laravel/cashier ^16.5 .env — switched to TEST keys + Price ID placeholders + DEV_SHORTCUT .env.example — documented all new Stripe vars MODIFIED (Flutter) mobile/pubspec.yaml, mobile/pubspec.lock — + url_launcher ^6.3.2 mobile/lib/api_client.dart — new buyLives shape, upgradePremium, billingPortal mobile/lib/widgets/out_of_lives_modal.dart — pack picker + premium upsell + URL launcher mobile/lib/screens/home_screen.dart — both gates open PremiumUpgradeSheet directly ``` ### Verifications | Check | Result | |---|---| | `php artisan test` | **48/48 passed**, 122 assertions, 22s (was 37 / 96) | | `php artisan migrate` | 6 new migrations applied (5 Cashier + 1 lives_purchases) | | `php artisan route:list` | `/api/stripe/webhook`, `/api/premium/checkout`, `/api/premium/portal`, `/api/lives/purchase` all registered | | `php artisan stripe:bootstrap-prices --dry-run` | command resolves, Stripe SDK loads, hits a network error on `api.stripe.com` — proves auth path works | | `flutter analyze` (touched files) | 0 errors, 7 pre-existing style infos in `api_client.dart` (use_null_aware_elements) | | `flutter pub get --offline` | resolved url_launcher + 7 sub-packages from pub cache | | Webhook signature middleware | Wired via `->middleware(VerifyWebhookSignature::class)` on the route | ### Key product decisions (preserve!) - **Annual @ SGD 50 / Monthly @ SGD 20** — annual is the "commit and save SGD 190" anchor; monthly is the "stop anytime" entry. Both unlock the same feature set (Diagnostic + Vocab Path), both subject to the 5/day heart limit - **Cashier (not raw stripe-php) for subscriptions** — gives us dunning, period tracking, billing portal, and webhook scaffolding for free. One library, one webhook handler, covers both lives + premium - **Denormalised `users.is_premium` boolean** synced from `subscribed('premium')` on every relevant webhook event. Source of truth is Cashier's `subscriptions` table; the boolean is the read optimisation. Don't try to invert this — Flutter would have to join tables it doesn't see - **Stripe Checkout (hosted), not embedded** — works on web + mobile with one code path, zero PCI scope, Stripe maintains the form - **`Cashier::ignoreRoutes()`** — we own the webhook route at `/api/stripe/webhook` so it lives next to our other API routes (and `routes/api.php` is already CSRF-free) - **Webhook is idempotent on `lives_purchases.stripe_checkout_session_id`** — Stripe retries on 5xx; our handler short-circuits on `status='completed'` - **`STRIPE_DEV_SHORTCUT=true` only bypasses the Stripe call for one-shot LIVES** — premium subscriptions always go through Stripe (the "happy path" cost of testing premium is having `stripe listen` running) - **Renamed `master` → `main`** to align with GitHub default. All history preserved; the old branch ref no longer exists locally or remotely ### Quick reference (newly added) | Endpoint | What it does | |---|---| | `POST /api/lives/purchase {pack}` | Start Stripe Checkout for `5_lives` or `10_lives` | | `POST /api/premium/checkout {plan}` | Start Stripe Checkout subscription for `monthly` or `annual` | | `GET /api/premium/portal` | Billing portal URL for self-service | | `POST /api/stripe/webhook` | Stripe webhook receiver (signature-verified) | | `php artisan stripe:bootstrap-prices [--dry-run]` | Create/reuse Stripe Products + Prices, write IDs to .env | | .env knob | Purpose | |---|---| | `STRIPE_KEY`, `STRIPE_SECRET_KEY`, `STRIPE_WEBHOOK_SECRET` | Stripe API access + webhook signing | | `STRIPE_PRICE_5_LIVES`, `STRIPE_PRICE_10_LIVES` | Price IDs for the lives packs | | `STRIPE_PRICE_PREMIUM_MONTHLY`, `STRIPE_PRICE_PREMIUM_ANNUAL` | Price IDs for the subscription plans | | `STRIPE_DEV_SHORTCUT=true` | Local-only: credit lives without calling Stripe | | `STRIPE_SUCCESS_URL`, `STRIPE_CANCEL_URL` | Where Stripe Checkout returns the user | | `CASHIER_CURRENCY=sgd` | Default currency for Cashier helpers | --- ## 2026-05-26 — Lives v2, premium tier, 2-tries-per-question, distractor rebalance, listening-MCQ stem rename ### What shipped **1. Lives system v2 — daily midnight reset (Singapore TZ)** - 5 hearts/day, reset at midnight Singapore (lazy on-access, not cron) - Removed the old 5h-per-life regen queue - New column: `users.lives_last_reset_date` (date) - New column: `users.is_premium` (boolean) - Each wrong attempt deducts 1 heart, including the SECOND attempt of a 2-try retry - Vocab Diagnostic NEVER deducts (IRT integrity) but IS still gated by lives - `is_unlimited_lives` (staff/test fixture) bypasses every gate **2. Premium tier — feature gate** - Free users → Skill Practice only - Premium users → Skill Practice + Vocab Diagnostic + Vocab Path (same 5/day limit) - API: free user trying Diagnostic/Vocab Path gets `422` with `{code: 402, gate: 'premium_required'}` - Flutter: home screen pops an "Premium feature" dialog - Pamela (`pamelaliusm@gmail.com`) seeded as premium - Filament admin form has Toggle for `is_premium` + `is_unlimited_lives` **3. 2 tries per question (AGS Math style retry)** - 1st submit → `POST /tests/{id}/answer` records IRT + deducts heart if wrong - Wrong → "Try Again!" (red) + "Skip Question" (peach) - 2nd submit → client-side compare against cached `correct_option_ids` - Wrong retry → calls new `POST /api/lives/consume` to charge another heart (NO duplicate IRT row) - 0 hearts mid-question → OutOfLivesModal pops with payment option + midnight countdown - Heart counter at the top of the test screen rerenders immediately after every deduction **4. Distractor rebalance — POS + difficulty matching** - New `App\Services\Seeding\DistractorPicker` — picks layered fallbacks: same POS + same difficulty → same POS + adjacent → same POS + any → any POS + same difficulty - New artisan command: `php artisan vocab:rebalance-distractors [--question=ID] [--dry-run]` - Rebalanced all 2666 definition questions; 100% POS-match in 500-sample audit - `BulkWordsSeeder` now uses the same picker for future seeds **5. Listening MCQ stem renamed** - `"Listen to the word. What does it mean? (lemma)"` → `" means"` - All 224 existing rows in DB rewritten - `SampleQuestionsSeeder.php:466` updated for future seeds **6. Question UI polish (test_screen.dart rewrite)** - 2×2 grid for short labels (every option ≤24 chars and exactly 4 options) - Explicit Submit button for all interaction kinds (single MCQ, multi-select, typed) - Selected tile feedback: green (correct) + red (wrong) + hint outline on the correct one - Mascot + speaker + read-aloud highlight matches AGS Math `question_layout.dart` - Multi-select questions now actually work (was the bug that kicked off the rewrite) ### What's wired end-to-end | Flow | Verified | |---|---| | Free user → Skill Practice → answer wrong twice → 2 hearts lost → counter updates | ✓ tests + analyze | | Free user → tries Diagnostic → 422 + premium dialog | ✓ tests | | Free user → tries Vocab Path → 422 + premium dialog | ✓ tests | | Premium user → Diagnostic works, no heart deducted on wrong | ✓ tests | | Premium user → all 3 test types work, still subject to 5/day | ✓ tests | | 0 hearts mid-question → OutOfLivesModal appears with "Hearts refill in Xh Ym" | client-side, manual smoke pending | | 0 hearts on test start → OutOfLivesModal appears on home screen | ✓ tests | | Daily reset at SGT midnight, lazy on access | ✓ tests | | `is_unlimited_lives` bypass for all gates | ✓ tests | | Filament admin can toggle `is_premium` and `is_unlimited_lives` per user | ✓ form | | `/api/auth/me` and `/api/auth/verify-otp` return `is_premium` on user object | ✓ | | Listening MCQ stems show "<lemma> means" | ✓ smoke | | All 2666 definition questions have POS-matched distractors | ✓ tinker audit | ### What's outstanding (explicit known gaps) | Item | Why it's not done | Where to pick up | |---|---|---| | **Real Stripe payment** for "Buy lives" / "Upgrade to Premium" | Out of scope for this session; dev shortcut credits lives immediately in `local`/`testing` env. | `app/Http/Controllers/Api/LivesController::purchase` + Math reference at `c:\allgifted\mathapi11v2\app\Services\LivesPurchaseService.php`. New endpoints for premium subscription (vs one-shot lives refill). | | **Premium subscription tier UI in Flutter** (upgrade card in OutOfLivesModal) | Needs payment provider first | `mobile/lib/widgets/out_of_lives_modal.dart` — add card matching `c:\allgifted\flutter_demo\lib\widgets\out_of_lives_modal.dart` "Unlimited Lives" path | | **`gh repo create` + push** | No git remote configured yet; **initial commit was made** (see Git state below). | Run `gh repo create allgifted/vocabile --private --source=. --remote=origin --push` (or whatever org/name they want) | | **Browser smoke test** of the full retry-with-deduction loop | Skipped to save tokens; all 37 PHP tests pass, Flutter analyze clean, build green. | Manual: hard-refresh `http://127.0.0.1:8001`, log in as `learner@vocabile.test`, do Skill Practice, intentionally fail twice on a Q, watch hearts go from 5→3 | | **Phase 2.3–2.10 teacher analytics** | Pre-existing backlog from earlier sessions; not in this session's scope. | Tasks #58, #60–65 in TaskList | | **Pronunciation skill mic widget** | Long-standing | Task #28 | ### Files changed this session ``` NEW app/Services/Seeding/DistractorPicker.php app/Console/Commands/RebalanceDistractorsCommand.php database/migrations/2026_05_25_110615_add_daily_reset_and_premium_to_users.php tests/Feature/LivesGateTest.php (13 tests, all passing) docs/SESSION-LOG.md (this file) MODIFIED — backend app/Services/Gamification/LivesService.php — daily reset, consumeOne, lockForUpdate app/Http/Controllers/Api/LivesController.php — + consume() action app/Http/Controllers/Api/TestController.php — premium gate (402) + lives gate (205) + correct_option_ids in response app/Http/Controllers/Api/AuthController.php — + is_premium on user payload app/Models/User.php — + is_premium, lives_last_reset_date fillable + casts routes/api.php — + POST /lives/consume database/seeders/BulkWordsSeeder.php — uses DistractorPicker database/seeders/SampleQuestionsSeeder.php — listening MCQ stem renamed app/Filament/Admin/Resources/Users/Schemas/UserForm.php — + is_premium + is_unlimited_lives toggles MODIFIED — Flutter mobile/lib/screens/test_screen.dart — full rewrite for AGS Math question_layout, 2-tries flow, deduction wiring mobile/lib/screens/home_screen.dart — out-of-lives + premium-required gate handlers mobile/lib/widgets/lives_header.dart — hours-aware timer format mobile/lib/widgets/out_of_lives_modal.dart — copy: "Hearts refill in …" + premium-aware text mobile/lib/models/gamification.dart — + isPremium, resetsAtMidnightSgt on LivesSnapshot mobile/lib/api_client.dart — + consumeLife(), + ApiException.premiumRequired, + outOfLives getters ``` ### Verifications | Check | Result | |---|---| | `php artisan test` | **37/37 passed**, 96 assertions, 21s | | `flutter analyze` on changed files | 0 errors, 8 style-info lints | | `flutter build web --release` (with `VOCABILE_API_URL=http://127.0.0.1:8002/api`) | 56.4s, green | | Migrations | `lives_last_reset_date`, `is_premium` applied to `users` | | Pamela.is_premium | true (manually set) | | Q#622 ("provide") distractors | `display / intend / balance / provide` — all 4 verbs | | Listening MCQ stems | renamed across 224 rows | ### Key product decisions (preserve!) - **Hard-coded `Asia/Singapore` for the midnight reset** — move to `schools.timezone` if multi-region SaaS becomes real - **Diagnostic does not deduct lives** — IRT integrity wins over uniformity; the gate keeps free-farming attacks closed - **"5 hearts for everyone, premium = feature unlock"** — both tiers subject to the daily limit - **Lazy daily reset on access** instead of cron — every snapshot/canAnswer call checks `lives_last_reset_date` vs today SGT and tops up. Simpler than scheduling; learner never sees stale hearts. If a nightly cron is later needed (analytics, push notifications), add separately — don't replace the lazy path - **Client-side retry, server-side authoritative grading** — 2nd attempt does NOT re-hit `/answer` (would create a duplicate IRT row); it does call `/lives/consume` to charge the heart - **`is_unlimited_lives` is the staff/test bypass**, NOT a premium synonym. Two separate flags. Filament exposes both as toggles ### Git state at end of session - Branch: `master` - HEAD: `a038e6b` — `Initial commit: AGS Vocab — adaptive IRT vocab testing platform` - Remote: **none configured**. `gh` CLI not installed on this machine. - Files in initial commit: ~917 (excludes `vendor/`, `node_modules/`, `mobile/build/`, `storage/backups/*.sql`, `.env*` — all in `.gitignore`) **To push to a new GitHub repo** (run these from `c:\projects\vocabile`): ```powershell # Option A — install gh, then create + push in one shot winget install --id GitHub.cli gh auth login gh repo create vocabile --private --source=. --remote=origin --push # Option B — create the repo in the GitHub web UI first, then git remote add origin git@github.com:/vocabile.git git push -u origin master ``` The commit message has the full session summary so a fresh clone + read of `docs/SESSION-LOG.md` is enough to onboard the next session. ### Dev environment quick reference | Service | URL | |---|---| | Vocab Laravel API | `http://127.0.0.1:8002` | | Vocab Flutter web | `http://127.0.0.1:8001` | | Filament admin | `http://127.0.0.1:8002/admin/{school-slug}/...` | | AGS Math (reference) | `http://127.0.0.1:8000` | | Account | Email | Tier | |---|---|---| | Admin / staff | `pamelaliusm@gmail.com` | `is_premium=true` | | Test learner | `learner@vocabile.test` | `is_premium=false` | | Credentials (do NOT commit) | | |---|---| | MySQL root | `16M@tl0ckRise` | | Mail SMTP | `mail.privateemail.com:465` SSL, `pam@allgifted.com` | | Pre-tenancy DB backup | `storage/backups/pre-tenancy-20260524-201545.sql` | ### Reference paths (for future Claude Code to read INSTEAD of grepping) - AGS Math backend (lives system reference) — `c:\allgifted\mathapi11v2\app\Services\LiveService.php` - AGS Math Flutter (UI reference) — `c:\allgifted\flutter_demo\lib\widgets\lives_header.dart`, `c:\allgifted\flutter_demo\lib\widgets\out_of_lives_modal.dart` - AGS Math palette + brand — `c:\allgifted\flutter_demo\AGS_MATH_PALETTE.md`, `c:\allgifted\allgifted-web\CLAUDE-brand.md` --- ## How to maintain this log 1. **Add a new section at the top** for each session (newest first). 2. Use the same three sub-headings every time: - **What shipped** — concrete deliverables, one bullet each - **What's wired end-to-end** — tabulated, so it's obvious what works - **What's outstanding** — known gaps + WHERE to pick up 3. **List every file changed.** Group by NEW / MODIFIED-backend / MODIFIED-flutter. 4. **Record key product decisions** — the *why*, not the *what*. The code shows what was done; this section captures the reasoning that would otherwise vanish. 5. **Update at every commit**, not at session end. If the session is interrupted, the doc still reflects reality. 6. **Don't paste full code** — paths + a one-line description are enough. The point is to know where to look, not to duplicate the codebase.