Meal-Planner/.agent/plan.md

Recovery Plan — MealPlanner

Goal: bring implementation back into alignment with Review/reviewconcensus.md. Stop building forward features until the deferred-risk spikes and the verification matrix pass.

Active sprint: Sprint 14 — Vitest for useOnboarding (Q4)

Owner: this agent. Status: starting. Tracking: Review/sprint14-verification.md (deploy + smoke), .agent/plan.md (checklist), .agent/context.md (decisions + open Qs).

Why now (Q4 rationale): Sprint 9 (F1 Onboarding Tour) shipped a hand-rolled ~420-line component, then immediately regressed in 1562929: onComplete was wired to useOnboarding().reset() (inverse op) so the X/Skip/Esc dismiss path actually re-showed the tour. The fix split the API into onComplete/onReset callbacks with markComplete (dismiss) vs reset (re-show). The bug class is "two inverse operations share one state setter"; the only durable prevention is unit tests. ~1 hr sprint, locks the seam.

Sprint 14 lifts the "no new npm deps" rule for testing-only. Runtime deps unchanged.

S8.1 — Migration: 0016_denial_decay_and_scope.py (NEW)

• Adds meal_plan_item.denial_expires_at TIMESTAMPTZ NULL.
• Adds meal_plan_vote.denial_scope VARCHAR(16) NULL.
• Partial index on meal_plan_item.denial_expires_at (postgresql_where IS NOT NULL) for the planner's soft-deny lookup.
• Downgrade reverses all three.

S8.2 — Model: app/models/__init__.py

• MealPlanItem.denial_expires_at column added.
• MealPlanVote.denial_scope column added.

S8.3 — Schema: app/schemas/__init__.py

• MealPlanItemResponse.denial_expires_at: Optional[datetime].
• VoteRequest.denial_scope: Optional[str] with pattern=^(this_week|never_again)$.
• VoteResponse.denial_scope: Optional[str].

S8.4 — Backend helpers: app/api/meals.py

• _apply_denial(db, item, scope) — single source of truth for the deny path. Returns {item, promoted_to_permanent, scope}. Commits.
• _ensure_never_suggest_recipe(db, family_id, recipe_id, reason) — idempotent NeverSuggest insert. Returns True if new, False if existing.
• _has_prior_active_soft_denial(db, family_id, recipe_id, current_item_id=None) — count query for the 2-denial check.
• DENIAL_DECAY_DAYS = 90 constant.

S8.5 — Backend endpoints: app/api/meals.py

• POST /api/meals/items/{id}/deny?scope=this_week|never_again (default this_week).
  • Returns {message, item, promoted_to_permanent, scope}.
  • swap_meal_item also clears denial_expires_at (defensive: a new recipe_id is a fresh start).
• POST /api/meals/vote/{id} extended: vote: "approve" | "deny" | "never_again".
  • Returns {status, item_status, denial_scope, promoted_to_permanent}.
  • The 2-denial auto-escalation runs server-side for both deny and never_again.
• GET /api/meals/vote/{id} HTML page renders 3 buttons. Supports one-click ?scope=... for the email's per-button links.

S8.6 — Email template: app/services/orchestrator/steps.py

• 3 direct-action links per recipe (Approve / Deny this week / Never again).
• Legacy "Vote on this meal" preserved as a secondary "Open vote page (all 3 options)" link.

S8.7 — Planner: app/services/planner/generate.py

• _load_blocklists returns 3 sets: (blocked_ingredients, blocked_recipes, soft_denied_recipes).
• soft_denied_recipes is the hard filter (per user decision: same as blocked_recipes).
• rejected_summary adds a soft_denied_recipe diagnostic bucket.

S8.8 — Frontend: Dashboard.tsx + api/index.ts

• api/index.ts:48-58 — meals.denyItem(itemId, { scope }).
• Dashboard.tsx:38-50, 385-410 — MealCard accepts scope-aware onDeny; renders 3 buttons (Approve / Deny this week / Never again) for pending items.
• handleDeny is scope-aware; toast reflects the server's promoted_to_permanent flag.
• "Never again" is gated by window.confirm to prevent accidental permanent blocks.
• Buttons only show on pending items (approved/denied items show the badge only).

S8.9 — Verify

• npm run build green for Sprint 8 (tsc 0 errors, vite 0 errors).
• Backend smoke: 21/21 planner tests pass (1 pre-existing test_filter_blocks_by_cost failure is not introduced by S8 — verified via git stash + re-run on a clean tree).
• Static checks: all 6 new modules import cleanly, helper logic verified via Python AST + import-test against backend/venv.
• Review/sprint8-verification.md written with deploy + 11-step browser smoke + 4 API curls + email-render procedure + rollback.
• Deploy verified on 100.108.224.12 — see verification log.
• No regression in Sprints 1-7.

S8.10 — Docs (all 6 running docs updated)

• Review/ui-nielsen-audit.md — Sprint 8 status block at the top (T2.1–T2.10).
• fix-ui-audit.md — Sprint 8 plan section (T2.1–T2.10).
• Review/handoff-ui-audit.md — "Active sprint" callout + bottom "Last updated" line.
• docs/HANDOFF.md — Sprint 7 + Sprint 8 sections before the 2026-06-03 session.
• .agent/plan.md — this section.
• .agent/context.md — Sprint 8 decisions, file:line references, verification gate.

Done when (Sprint 8)

• All 12 boxes above ticked.
• npm run build green.
• Review/sprint8-verification.md exists.
• All 6 doc files have a Sprint 8 status block.
• User commits + runs the deploy + runs the SQL + reports the smoke checklist.

Out of scope (Sprint 8)

• Thread 3: §Future backlog (F1 onboarding, F8/F9 proposals, dead Generate Meal Plan CTA at Dashboard.tsx:415).
• "Unblock" UI on the webui. The NeverSuggest API exists; no UI to remove a row. User can use the API directly.
• Decay-sweep cron. The 90-day filter is at read time; expired rows just become invisible. No cleanup needed.
• Pre-existing denied row (2026-05-15 day-2 Roasted Sweet Potato and Chickpea Bowl) — left untouched. denial_expires_at stays NULL; the recipe is effectively forgotten after 90d from now (today is 2026-06-05, so it'll be eligible again ~2026-09-03). If the user wants it remembered permanently, they can re-trigger the soft-deny cycle by clicking "Deny this week" on the next plan that includes it.

---

Phase R1 — Stabilize (parallel-safe)

• R1-A: Verification harness. Add backend/tests/ with pytest config, a conftest.py with a transactional DB fixture, and smoke tests covering: app import, /health, /health/db, every router's GET list endpoint, Alembic upgrade head round-trip on a throwaway DB. Add .github/workflows/ci.yml running lint + pytest + frontend npm run build.
• R1-B: Auth dependencies on existing routers. Implement an app.security module with: (1) require_admin dep — bearer token compared to settings.ADMIN_TOKEN, applied to ALL /api/admin/* routes; (2) require_session dep — signed-cookie session (itsdangerous, key = SECRET_KEY) for profile/pantry/recipes/meals/shopping-list mutations; reads stay open inside the trusted network. Per-voter approval token flow stays as-is. Update .env.example with ADMIN_TOKEN. Document the model in docs/SECURITY.md.
• R1-C: Make /api/admin/scrape async. Convert the endpoint to enqueue a background job (FastAPI BackgroundTasks for now; APScheduler later). Endpoint returns 202 + scrape_log_id; status polled via /api/admin/logs/{id}. ScraperService must open its own DB session inside the task (the request-scoped db is gone by then).

Phase R2 — De-risk deferred work (parallel-safe, must run BEFORE further feature work per review §2.4)

• R2-A: Live-scrape spike. Run LuckyCaliforniaScraper against https://luckysupermarkets.com once, capture the raw HTML/PNG to backend/tests/fixtures/lucky_ca/, write a unit test that parses the captured fixture (no live network in CI). Document selector decisions in .agent/context.md. If the page can't be parsed, file the schema impact before going further.
• R2-B: Email + approval round-trip spike. Implement minimal SendGrid sender (app/services/email.py), an app/services/approval.py that issues per-voter signed tokens (TTL, single-use), the GET confirmation page + POST submit handler (the routes already exist as stubs in meals.py), and a CLI script scripts/send_test_approval.py that creates a fake meal plan, emails one voter, and verifies the click→POST→DB write path end to end against a sandboxed inbox or MAIL_BACKEND=console. Goal: prove the schema (family_member, approval_token tables) survives one full round trip BEFORE building Phase 4/5/9.

Phase R3 — Resume feature work (sequential, only after R1+R2 green)

• R3-A: Phase 4 Recipe Engine — search, tagging, never-suggest filter.
• R3-B: Phase 9 Meal Planner generation algorithm.
• R3-C: Phase 6 SendGrid templated emails (proposal, reminder, confirmation).
• R3-D: Phase 8 Feedback UI.
• R3-E: APScheduler with --workers 1 for weekly scrape + plan generation + email send.
• R3-F: Phase 10 image strategy.

Halt conditions

• R2 spikes fail → stop, propose schema/spec change, await approval.
• Verification matrix in Review/reviewconcensus.md §6 not green → no R3 work begins.

---

Sprint 9 — F1 Onboarding Tour (H10)

Owner: this agent. Status: code complete, npm run build green, awaiting user commit + deploy. Tracking: Review/sprint9-verification.md.

User policy decision (2026-06-05, exact): "Proceed with the next phase in the redesign." Selected Sprint 9 = F1 (the only §Future item with a clear UI scope). F8 (Spoonacular) and F9 (Ollama) are full backend proposals; the dead Generate Meal Plan CTA is a separate follow-up.

S9.1 — New OnboardingTour.tsx component (NEW)

• Hand-rolled (no react-joyride) — keeps npm footprint flat.
• 4 steps: Dashboard / Pantry / Recipes / Shopping List.
• Anchors to [data-tour="<id>"] attributes on existing elements.
• Tooltip card pinned to anchor (top/bottom/center fallback for off-route steps).
• Anchor highlight = primary-400 ring + soft scrim; tooltip is a real <div role="dialog" aria-modal="true">.
• Step progress = 4 progress bars.
• Keyboard: 1–4 jump, ←/→ step, Esc dismiss, Tab order is Skip → Back → Next.
• useOnboarding() hook + ?reset-tour=1 re-trigger; localStorage key mealplanner:onboarding-complete.
• Focus captured on open (primary action), restored on close.
• All reads/writes to localStorage wrapped in try/catch (private mode safe).

S9.2 — Anchor points (5 lines of code total)

• pages/Dashboard.tsx:602 — <Card data-tour="dashboard"> on the Weekly Overview grid.
• pages/Pantry.tsx:185 — <div data-tour="pantry"> on the page header (always present).
• pages/Pantry.tsx:208 — second anchor on the add-form <Card> (when the form is open).
• pages/Recipes.tsx:124 — <Button data-tour="recipes"> on the Filters button.
• pages/ShoppingList.tsx:231 — <div data-tour="shopping-list"> on the page header.

S9.3 — App.tsx mount

• useOnboarding() at App root, isComplete passed to <OnboardingTour>.
• onComplete mapped to onboarding.reset() (flips the flag so re-renders don't re-show).
• Mounted as sibling of <ShortcutHelpBanner /> inside <BrowserRouter> (so useLocation / useNavigate work).

S9.4 — Verify

• npm run build green (tsc 0 errors, vite 0 errors).
• Browser smoke (8 steps) on http://100.108.208.56:8082/ per Review/sprint9-verification.md.
• No regression in Sprints 1–8 (keyboard shortcuts, error toast, 3-button vote row, WeekRangeNav, bulk pantry add).

S9.4.1 — Post-deploy fix (2026-06-05)

User reported post-deploy: "The tour window looks great, but Clicking the X nor skip tour do anything. I cannot exit the tour." Build was green but the dismiss path was broken.

• Root cause identified (systematic-debugging Phase 4): useOnboarding().reset() was wired to the dismiss handler at App.tsx:104-109. reset() does the inverse of dismiss — it clears the localStorage key AND flips isComplete to false. So clicking X wrote the key, but the App-level flag flipped in the wrong direction, the tour's if (isComplete || !currentStep) return null early-return never fired, and the dialog stayed visible.
• Fix committed (1562929): split the dismiss and reset paths into two distinct callbacks.
  • useOnboarding now exposes markComplete() (state flip to true) in addition to reset() (state flip to false).
  • OnboardingTour takes two props: onComplete (dismiss) and onReset (re-show).
  • App.tsx wires onComplete → onboarding.markComplete() and onReset → onboarding.reset().
  • Cleaned up: markComplete no longer double-writes localStorage (the tour's finish() already does that).
• npm run build green on docker-willester after the fix (495.64 kB, no size change).
• User confirmed post-deploy smoke test passes (2026-06-05).
• Anchors + URL effect re-verified: 5/5 data-tour anchors present at Dashboard.tsx:602, Pantry.tsx:185, 208, Recipes.tsx:131, ShoppingList.tsx:231; ?reset-tour=1 effect calls onReset() correctly.

S9.5 — Docs (all 6 running docs updated)

• Review/ui-nielsen-audit.md — Sprint 9 status block at the top.
• fix-ui-audit.md — Sprint 9 plan section (T3.1–T3.4).
• Review/handoff-ui-audit.md — Sprint 9 entry in the "How to take over" section + TL;DR row.
• docs/HANDOFF.md — Sprint 9 section.
• .agent/plan.md — this section.
• .agent/context.md — Sprint 9 decisions + file:line references.
• Review/sprint9-verification.md — written (8-step browser smoke + a11y check + reset-link test).

Done when (Sprint 9)

• All boxes above ticked.
• npm run build green.
• Review/sprint9-verification.md exists.
• All 6 doc files have a Sprint 9 status block.

Out of scope (Sprint 9)

• Thread 3 follow-ups: F8 (Spoonacular), F9 (Ollama), dead Generate Meal Plan CTA at Dashboard.tsx:415.
• Per-page deep tutorials, video demos, hover tooltips.
• A user-facing "Show tour" link in the footer (operator uses ?reset-tour=1; a footer link is a 5-line follow-up if requested).
• Sprint 10 — "Deny Forever" on Recipes — committed 2026-06-05, awaiting user deploy.

---

Sprint 10 — "Deny Forever" on Recipes (user-driven)

Owner: this agent. Status: code complete, npm run build green, 21/21 planner tests pass, awaiting user commit + deploy. Tracking: Review/sprint10-verification.md.

User direction (2026-06-05, exact): "Proceed with the next phase in the redesign. Also add a phase to include a 'Deny Forever' button in the Recipes endpoint." Sprint 10 ships the Deny Forever button on both the Recipes page (card overlay) and the RecipeDetail page (top bar).

S10.1 — Backend: POST /api/never-suggest (public)

• New endpoint in app/api/never_suggest.py:60-86. Family-facing (uses require_session).
• Body: {family_profile_id, recipe_id, reason: "allergy"|"dislike", notes?}.
• Idempotent on (family_profile_id, recipe_id, ingredient_id, reason).
• Returns the row joined with recipe_name.

S10.2 — Backend: DELETE /api/never-suggest/{ns_id} (public)

• New endpoint in app/api/never_suggest.py:89-111. Family-facing.
• Row-level ownership check: 403 if family_profile_id doesn't match the session.
• 404 if the row doesn't exist.

S10.3 — Backend: NeverSuggestRead.recipe_name + .ingredient_name

• New fields in app/schemas/never_suggest.py:31-33.
• Server-side JOIN helper _attach_names() in app/api/never_suggest.py:33-58. One LEFT OUTER JOIN per kind, then merge into response dicts.
• Falls back to None if the recipe/ingredient was deleted (FK is ON DELETE CASCADE).

S10.4 — Frontend: API client

• mealPlannerApi.neverSuggest.list(familyProfileId) — frontend/src/api/index.ts:75-86.
• mealPlannerApi.neverSuggest.add({...}) — POST.
• mealPlannerApi.neverSuggest.remove(nsId) — DELETE.

S10.5 — Frontend: NeverSuggestButton component (NEW)

• frontend/src/components/NeverSuggestButton.tsx (~290 lines).
• Two variants: card (overlay on RecipeCard) and detail (text buttons in RecipeDetail top bar).
• Popover with two reasons: Allergy (red, requires window.confirm) and Dislike (neutral, no confirm).
• Undo toast via showToast.undo() (Sprint 3 B12 pattern, 6s window).
• Pre-existing block detection: shows a "Blocked" state with an "Unblock" path.
• Query invalidations: ['neverSuggest', familyId], ['recipes'], ['recommendedRecipes', familyId], ['mealPlan'].
• A11y: aria-label, aria-expanded, aria-haspopup="menu", role="menu", Esc dismisses, outside click dismisses.

S10.6 — Frontend: Recipes.tsx overlay

• RecipeCard now has position: relative so the overlay anchors correctly.
• Button is opacity-0 group-hover:opacity-100 (visible on hover or focus).
• e.preventDefault() + e.stopPropagation() on the click — doesn't navigate to the detail page.

S10.7 — Frontend: RecipeDetail.tsx top bar

• New "Deny forever" button group to the left of "Add to Plan".
• Same popover + confirm/undo semantics as the card overlay.

S10.8 — Verify

• npm run build green (tsc 0 errors, vite 0 errors). Bundle: 487 → 495 kB.
• Backend imports clean; routes registered.
• 21/21 planner tests pass (1 pre-existing failure deselected).
• Browser smoke (9 steps) on http://100.108.208.56:8082/ per Review/sprint10-verification.md.
• No regression in Sprints 1-9.

S10.9 — Docs (all 6 running docs updated)

• Review/ui-nielsen-audit.md — Sprint 10 status block at the top.
• fix-ui-audit.md — Sprint 10 plan section (T4.1–T4.9).
• Review/handoff-ui-audit.md — Sprint 10 entry in the "How to take over" section + TL;DR row.
• docs/HANDOFF.md — Sprint 10 section.
• .agent/plan.md — this section.
• .agent/context.md — Sprint 10 decisions, file:line references, verification gate.
• Review/sprint10-verification.md — written (deploy + 9-step browser smoke + 5 API curls + undo test + a11y check).

Done when (Sprint 10)

• All boxes above ticked.
• npm run build green.
• Review/sprint10-verification.md exists.
• All 6 doc files have a Sprint 10 status block.

Out of scope (Sprint 10)

• A "Manage blocked recipes" page.
• Bulk unblock.
• Touch-device gesture for the card overlay (the focus state already surfaces the button on tap).

---

Sprint 11 — Wire the dead "Generate Meal Plan" CTA (Dashboard.tsx:499-504)

User direction (2026-06-05): "Proceed." Selected from the question menu as the smallest §Future item. F1 (Sprint 9) is shipped, F8 (Spoonacular) + F9 (Ollama) are full backend proposals, and the dead Generate Meal Plan CTA at Dashboard.tsx:503 is the final remaining item. The button is rendered with onClick: () => {} — clicking it does nothing. Wired to existing endpoints, no backend changes, no new dependencies.

Root cause: the user lands on the Dashboard with no meal plan and sees a "Generate Meal Plan" button. Clicking it does nothing. The backend already has the two endpoints needed (POST /api/meals to create a plan + POST /api/meals/{id}/fill-empty-slots to fill it from the recipe library), and the fillEmptySlots partial-success report pattern is already in production for the existing Plan Week menu (handlePlanWeek at Dashboard.tsx:366-392). The wiring is a 25-line client-side glue function that calls both in sequence.

S11.1 — handleGenerateFirstPlan() in Dashboard.tsx

• Add a new handler next to handlePlanWeek (line 366) that:
  1. Reads weekStart (already in scope).
  2. POST /api/meals with { week_start_date: weekStart, status: 'draft' } to create an empty plan.
  3. On success, POST /api/meals/{newId}/fill-empty-slots with { meal_types: ['breakfast', 'lunch', 'dinner'] }.
  4. Invalidate ['mealPlan', weekStart].
  5. Toast: reuse the same partial-success pattern as handlePlanWeek ("Planned N of M meals — K failed").
• Wire onClick of the EmptyState.action (line 503) to call handleGenerateFirstPlan().
• Track a generatingFirstPlan state for the loading spinner; swap the button label to "Generating…" while in-flight.
• Handle the "Meal plan for this week already exists" 400 from meals.create (race condition with another tab) by calling fillEmptySlots directly with the existing plan's id — refetch the plan from getPlanned(weekStart) to get the id.

S11.2 — Verify

• npm run build green (tsc 0 errors, vite 0 errors).
• Browser smoke (4 steps) on http://100.108.208.56:8082/:
  1. Log in as a family with no meal plan for the current week. Land on /.
  2. Confirm EmptyState shows "Generate Meal Plan" button.
  3. Click the button. Confirm: button label flips to "Generating…", toast appears with "Planned N of M meals", empty state disappears, plan grid renders.
  4. Refresh the page. Confirm the plan persists.
• Race test: open two tabs, both click "Generate Meal Plan" at the same moment. Second tab should still succeed (handled by the meals.create 400 → fall-through to fillEmptySlots path).
• No regression in Sprints 1-10.

S11.3 — Docs (all 6 running docs updated)

• Review/ui-nielsen-audit.md — Sprint 11 status block at the top.
• fix-ui-audit.md — Sprint 11 plan section (T5.1-T5.3).
• Review/handoff-ui-audit.md — Sprint 11 entry in the "How to take over" section + TL;DR row.
• docs/HANDOFF.md — Sprint 11 section.
• .agent/plan.md — this section.
• .agent/context.md — Sprint 11 decisions + file:line references.
• Review/sprint11-verification.md — written (4-step browser smoke + race test).

Done when (Sprint 11)

• All boxes above ticked.
• npm run build green.
• Review/sprint11-verification.md exists.
• All 6 doc files have a Sprint 11 status block.

Out of scope (Sprint 11)

• LLM-powered generation (F8 Spoonacular, F9 Ollama) — separate backend proposals, future sprints. Sprint 11 only wires the existing recipe-library-based fill.
• A "what would you like for dinner?" prompt before generation — the existing flow generates from the library with no user input.
• A "regenerate" button after the plan exists — the existing Plan Week menu at Dashboard.tsx:366-392 already handles this case.

---

Sprint 12 — F8 Spoonacular search (§Future H10) — DRAFTED, awaiting user approval

User direction (2026-06-05): "Proceed." Selected from the question menu. F8 is the smallest remaining §Future item: search-by-name on a public API, brings external recipe data into the system. F9 (Ollama) remains a separate full-backend proposal.

Root cause: the user can browse ~150 local recipes on /recipes (admin seeds them) but has no path to find new ones without leaving the app. F8 adds a "Search the web" toggle that hits the Spoonacular complexSearch API and lets the user import a result into the local library in one click.

Pre-existing infrastructure to reuse (not recreate):

• backend/app/services/recipe_discovery.py (226 lines) — full RecipeDiscoveryService with _search_spoonacular(), _fetch_recipe_info(), _normalize_spoonacular(). Reads SPOONACULAR_API_KEY via getattr(settings, ...). Cites 150/day free quota.
• backend/app/api/ingredients.py:58-103 — public POST /api/ingredients is idempotent on name_lower + aliases. The ingredient-resolution helper for the import flow.
• scripts/enrich_recipes_spoonacular.py (76 lines) — standalone one-shot script, reference for the env + URL pattern.

Pre-existing WIP (NOT touched by Sprint 12):

• backend/app/api/recipes.py (352 lines, not registered in main.py)
• backend/app/schemas/recipe.py (93 lines, has RecipeCreate + RecipeIngredientRef)
• nginx/nginx.conf

S12.1 — Backend: GET /api/recipes/search (public, webui-facing)

• NEW backend/app/api/recipe_search.py — 2 endpoints + a thin search_spoonacular_summary(q, limit) wrapper. Reuses the existing requests.get(SPOONACULAR_SEARCH_URL, params={...}) pattern.
  • GET /recipes/search?q=&limit= — public, require_session. Calls complexSearch with addRecipeInformation=true, fillIngredients=true, instructionsRequired=true, number=limit. Returns normalized RecipeSearchHit[]. No info endpoint call (saves 1 point per result; search summary is enough for browsing).
  • POST /recipes/import — public, require_session. Body {external_id, external_source: "spoonacular"}. Fetches /recipes/{id}/information (1 point), normalizes, upserts ingredients via idempotent POST /api/ingredients, creates a local Recipe with external_source+external_id+is_manually_added=true. Returns the new Recipe.
• MODIFIED backend/app/schemas/__init__.py — add RecipeSearchHit and RecipeImportRequest Pydantic models. Mirror the ExternalRecipe dataclass shape from recipe_discovery.py:28-44 (but with Pydantic).
• MODIFIED backend/app/config.py — add SPOONACULAR_API_KEY: Optional[str] = None to Settings for schema consistency. (Currently read via getattr because extra="ignore". Adding it surfaces it in .env.example and tools.)
• MODIFIED backend/app/main.py — register the new router. Reuses the app.include_router pattern at line 44-50.
• Process-wide _points_used counter (module-level singleton in recipe_search.py). 503 with detail: "spoonacular daily quota reached" when over 140. Logged on every call.
• 503 with detail: "SPOONACULAR_API_KEY not configured" when env var unset. Logged once at startup.

S12.2 — Backend: tests

• NEW backend/tests/test_recipe_search.py — 4 tests, mock the Spoonacular requests.get calls.
  1. GET /api/recipes/search?q=chicken returns 200 + 1 normalized hit (mock summary).
  2. GET /api/recipes/search?q= returns 422 (empty query).
  3. POST /api/recipes/import happy path: mock info call + idempotent ingredient upsert + 201 with the new Recipe id.
  4. POST /api/recipes/import duplicate external_id → 409.

S12.3 — Frontend: API client + Recipes page

• MODIFIED frontend/src/api/index.ts:27-33 — add recipes.search(q, limit) and recipes.import(data).
• MODIFIED frontend/src/pages/Recipes.tsx — add a "Search the web" toggle next to the search bar (small button + Sparkles icon from lucide). When ON, the existing useQuery switches from recipes.list(params) to recipes.search({q: debouncedQ, limit: 10}). Renders results in a separate panel above the local list. Each result card has an "Import" button + the existing NeverSuggestButton removed (since these are not-yet-imported Spoonacular results, not local recipes).
  • Toggle defaults to OFF so the existing UX is preserved.
  • Toggle is a real <button> with aria-pressed={searchWeb}.
  • Debounced 300ms, same as the local search (reuse handleSearch from line 77-81).
  • Panel has aria-busy={isLoading} while fetching.

S12.4 — Verify

• cd backend && python -m pytest tests/test_recipe_search.py -v → 4/4 green.
• cd frontend && npm run build → green (tsc 0 errors, vite 0 errors).
• Manual API smoke: curl -sS 'http://100.108.208.56:8082/api/recipes/search?q=chicken&limit=5' -b session.txt → 200 JSON array.
• Manual UI smoke (4 steps):
  1. Open /recipes in incognito. Confirm "Search the web" toggle is OFF, only the local list shows.
  2. Click the toggle. Confirm the panel header changes to "Search the web — Spoonacular" and a debounced search bar appears.
  3. Type "pasta" with 300ms debounce. Confirm 5-10 results render with name + image + cuisine tags.
  4. Click "Import" on a result. Confirm: toast "Imported!" + result card shows "Already imported" + toggle closes + the local list re-fetches and now contains the imported recipe.
• Quota test: hit search 50 times in a row, confirm _points_used increments. The 51st within the budget returns 503.
• No regression in Sprints 1-11.

S12.5 — Docs (all 6 running docs updated)

• Review/ui-nielsen-audit.md — Sprint 12 status block (T6.1–T6.4) at the top.
• fix-ui-audit.md — Sprint 12 plan section (T6.1–T6.5).
• Review/handoff-ui-audit.md — Batch H + Sprint 12 entry + TL;DR row 12.
• docs/HANDOFF.md — Sprint 12 section.
• .agent/plan.md — this section.
• .agent/context.md — Sprint 12 decisions + file:line references.
• Review/sprint12-verification.md — written (4-step browser smoke + 2 API curls + quota test + a11y check).

Done when (Sprint 12)

• All boxes above ticked.
• npm run build green.
• pytest tests/test_recipe_search.py green (4/4).
• Review/sprint12-verification.md exists.
• All 6 doc files have a Sprint 12 status block.

Out of scope (Sprint 12)

• F9 — Ollama local LLM. Different backend proposal (model pull + ollama-py + /api/llm/plan endpoint). Separate sprint.
• Image generation. AI_IMAGE_ENABLED env gate already exists; not enabled. Sprint 12 imports the Spoonacular image as-is.
• Auto-enriching existing recipes with macros (would require nutrition endpoint = 1 pt per recipe; out of free quota).
• Modifying the pre-existing WIP backend/app/api/recipes.py / schemas/recipe.py / nginx/nginx.conf — untouched.
• F8 Spoonacular + F9 Ollama + dead Generate Meal Plan CTA — separate.

---

Sprint 13 — F9-lite (Ollama Cloud free-text plan synthesis) — DRAFTED, awaiting user approval

User direction (2026-06-05): "Proceed." F9-lite reuses the pre-existing OLLAMA_* config (config.py:36-38: OLLAMA_BASE_URL=https://ollama.com/v1, OLLAMA_API_KEY, OLLAMA_MODEL=kimi-k2.6:cloud). Avoids the local model pull (F9-full would be 4 GB on disk + a separate uvicorn process). Cloud LLM — costs apply per call (operator's existing OLLAMA billing).

Pre-existing infrastructure to reuse (not recreate):

• backend/app/services/llm_matcher.py:97-144 — _ask_ollama(ingredient_name, candidates) helper. The exact call pattern Sprint 13 mirrors: POST ${OLLAMA_BASE_URL}/chat/completions with Authorization: Bearer ${OLLAMA_API_KEY}, model: settings.OLLAMA_MODEL, max_tokens: 500, temperature: 0, parse choices[0].message.content, strip `` blocks.
• backend/app/services/recipe_enrichment.py — parallel LLM helper for recipes (different prompt shape; not reused).
• backend/app/config.py:36-38 — OLLAMA config.

Pre-existing WIP (NOT touched): same as Sprint 12.

S13.1 — Backend: POST /api/llm/plan (public, webui-facing)

• NEW backend/app/api/llm_plan.py — single endpoint + a thin _ask_llm(prompt) helper. The endpoint:
  1. Validates the request body (prompt: str 1-500 chars, week_start: date).
  2. Reads the local recipe library (Recipe table, filtered by family_profile_id); serializes a compact list {id, name, cuisine_tags, dietary_tags, protein_type, total_time_minutes, dietary preferences}.
  3. Builds a prompt: "You are planning a 7-day meal plan (Mon-Sun). The user wants: ''. Pick up to 21 meals (7 breakfasts + 7 lunches + 7 dinners) from the recipe library. Return JSON: [{"day_of_week": 1-7, "meal_type": "breakfast|lunch|dinner", "recipe_id": "<uuid>"}]. If a slot has no good match, omit it. Use only recipe_ids from the list. Reply with JSON only — no commentary."
  4. Calls _ask_llm(prompt) (mirrors _ask_ollama from llm_matcher.py:97-144).
  5. Parses the JSON response (try json.loads, fall back to re.search(r"\[.*\]", content) to handle markdown code fences).
  6. Validates each entry: recipe_id is a UUID, day_of_week in 1-7, meal_type in {breakfast, lunch, dinner}. Drop invalid entries.
  7. Creates an empty plan via meals.create (Sprint 6+ endpoint), then bulk-inserts the LLM-picked items + calls fillEmptySlots for the slots the LLM didn't cover.
  8. Returns {plan_id, picked_count, filled_count, failed_count, reasoning: <LLM raw text if non-empty>}.
• MODIFIED backend/app/schemas/__init__.py — add LLMPlanRequest + LLMPlanResponse Pydantic models.
• MODIFIED backend/app/main.py — register the new router at /api/llm.
• 503 with clear detail: "OLLAMA_API_KEY not configured" when env var unset.
• 422 on empty / oversized prompt.
• Cap on library size sent to the LLM: 200 recipes max (alphabetical by name). Larger libraries would exceed prompt tokens.

S13.2 — Frontend: free-text prompt in the Sprint 11 flow

• MODIFIED frontend/src/pages/Dashboard.tsx — turn the Sprint 11 handleGenerateFirstPlan into a 2-step:
  1. New MealPlanPromptModal component (inline in Dashboard.tsx, ~40 lines, reuse Card/Button/Input from components/ui/*): a small modal with a textarea (max 500 chars, char counter) + two radio options: "Use the recipe library" (default) and "Ask the LLM". On submit, calls one of two API methods.
  2. Library path (default): keep Sprint 11's meals.create + fillEmptySlots exactly as-is.
  3. LLM path (new): mealPlannerApi.llm.plan({prompt, week_start}). On success, invalidate ['mealPlan', weekStart] and toast "Planned N meals (LLM picked N, library filled the rest)".
• MODIFIED frontend/src/api/index.ts — add llm.plan(data).
• A11y: modal has role="dialog", aria-modal="true", focus trapped on the textarea on open, restored to the CTA button on close. Esc dismisses. Tab cycles within the modal.

S13.3 — Verify

• cd frontend && npm run build → green (tsc 0 errors, vite 0 errors).
• Backend AST clean.
• Manual API smoke:
  • curl -X POST /api/llm/plan -d '{"prompt": "easy weeknight dinners, no fish", "week_start": "2026-06-08"}' → 200 with {plan_id, picked_count: 7+, filled_count: 14-, ...}. (Requires OLLAMA_API_KEY set on the host.)
  • With OLLAMA_API_KEY unset → 503.
  • Empty prompt → 422.
• Manual UI smoke (3 steps):
  1. Land on / with no plan. Click "Generate Meal Plan". Modal opens with the textarea + the two radio options.
  2. Type "Italian-inspired, vegetarian" + select "Ask the LLM" + click submit. Confirm: button label flips to "Asking LLM…", modal shows a small spinner, ~5-15s later the modal closes, plan grid renders, toast shows the picked/filled split.
  3. Refresh the page. Confirm the plan persists.
• No regression in Sprints 1-12.

S13.4 — Docs (all 6 running docs updated)

• Review/ui-nielsen-audit.md — Sprint 13 status block.
• fix-ui-audit.md — Sprint 13 plan section (T7.1-T7.4).
• Review/handoff-ui-audit.md — Batch I + Sprint 13 entry + TL;DR row 13.
• docs/HANDOFF.md — Sprint 13 section.
• .agent/plan.md — this section.
• .agent/context.md — Sprint 13 decisions + file:line references.
• Review/sprint13-verification.md — written.

Done when (Sprint 13)

• All boxes above ticked.
• npm run build green.
• Review/sprint13-verification.md exists.
• All 6 doc files have a Sprint 13 status block.

Out of scope (Sprint 13)

• F9-full — local Ollama model pull on the host. Would require pulling Mistral 7B or Llama 3 8B (~4 GB) + a separate ollama serve process + a different config (OLLAMA_BASE_URL=http://localhost:11434). F9-lite uses the cloud tier. Future sprint if the cloud costs become painful.
• Prompt engineering / quality iteration. The prompt is a first cut. If the LLM returns 0 picks or 21 identical recipes, the operator can iterate on the prompt. Out of scope for the initial ship.
• Multi-week plans. One week at a time.
• Save the prompt as a template for reuse. Future sprint.

---

Active sprint: Sprint 14 — Vitest for useOnboarding (Q4)

S14.1 — Dependencies (devDeps only)

• Add vitest@^1.6.0 — the runner.
• Add happy-dom@^14.7.0 — DOM env (lighter than jsdom, faster startup; 7x smaller).
• Add @testing-library/react@^14.2.0 — render + assert helper.
• Add @testing-library/jest-dom@^6.4.0 — .toBeInTheDocument() etc.
• All four go under devDependencies. Lifts the "no new npm deps" rule for testing-only.

S14.2 — Config

• frontend/vitest.config.ts — uses Vite's plugin-react (already a devDep), sets environment: 'happy-dom', points setupFiles: ['./vitest-setup.ts'], reuses tsconfig.json paths.
• frontend/vitest-setup.ts — imports @testing-library/jest-dom/vitest (auto-extends expect with DOM matchers).
• package.json scripts: add "test": "vitest run --reporter=default" (no watch by default — CI-friendly) + "test:watch": "vitest".

S14.3 — Tests for useOnboarding (the S9 bug class)

• frontend/src/components/OnboardingTour.test.tsx — render the hook via a tiny <TestHarness/> consumer; renderHook from @testing-library/react.
• Case 1 — clean init: clear localStorage; isComplete === false.
• Case 2 — persisted init: localStorage.setItem('mealplanner:onboarding-complete', '1'); isComplete === true on mount.
• Case 3 — markComplete sets state, does NOT clear localStorage: after markComplete(), isComplete === true and the localStorage key is still '1'. This is the S9 bug lock.
• Case 4 — reset clears localStorage AND flips state to false: after reset(), isComplete === false and the localStorage key is removed.
• Case 5 — show is a mirror of reset: after show(), same assertions as Case 4.
• Case 6 — localStorage throw is silently swallowed: stub localStorage.getItem to throw; hook still returns isComplete: false, does not crash.

S14.4 — Verify + commit

• cd frontend && npm test runs all 6 cases green.
• npm run build still green (vitest's types shouldn't conflict with vite's).
• Review/sprint14-verification.md written.
• All 6 running docs updated with the Sprint 14 status block.
• Commit on host + push.

Done when (Sprint 14)

• All boxes above ticked.
• npm test shows 6 passing in <5 s.
• npm run build still green.
• The S9 bug class is locked: any future regression that wires onComplete → reset (or onReset → markComplete) trips Case 3.

Out of scope (Sprint 14)

• Component-level tests for <OnboardingTour/> itself (the dialog, focus management, arrow-key navigation). The hook covers the S9 bug class; component tests are a different scope. Future sprint.
• Tests for recipes API client or useOnboarding callers. Not the S9 bug class. Future sprint.
• Tests for the backend. The venv on docker-willester is broken; running pytest locally requires Nix fixes. Out of scope.
• F9-full (local Ollama model pull). Opt-in based on cloud-billing feedback only. _ask_llm is the single seam — F9-full only needs to swap the URL + model name.

---

Active sprint: Sprint 15 — Seed 50 family-friendly recipes for 4-week planning (content op)

S15.1 — Recipe target list (50 queries, family default)

Distribution: 5 cuisines × 10 recipes each = 50. Each cuisine gets a mix of cooking methods (sheet-pan, skillet, slow-cooker, one-pot, 30-min) so the LLM has variety. Each query is a free-text Spoonacular complexSearch query.

• Italian (10): "chicken parmesan", "spaghetti carbonara", "lasagna", "minestrone soup", "pesto pasta", "chicken piccata", "mushroom risotto", "caprese salad", "italian wedding soup", "eggplant parmesan"
• Mexican (10): "chicken tacos", "beef enchiladas", "black bean burritos", "shrimp fajitas", "chicken quesadilla", "taco salad", "sopa de tortilla", "carnitas", "chicken tortilla soup", "huevos rancheros"
• Asian (10): "chicken stir fry", "beef and broccoli", "pad thai", "fried rice", "teriyaki salmon", "tofu curry", "chow mein", "spring rolls", "pho", "kung pao chicken"
• American (10): "chili", "meatloaf", "mac and cheese", "BBQ chicken", "pot roast", "shepherd's pie", "chicken pot pie", "beef stew", "burgers", "pulled pork"
• Mediterranean/Middle Eastern (10): "chicken shawarma", "falafel", "hummus bowl", "greek salad", "lamb kebabs", "tabbouleh", "roasted vegetable wrap", "couscous", "stuffed peppers", "baked falafel"

Dietary tags inferred from title+ingredients: _infer_protein_simple in recipe_search.py:151-170 (Sprint 12). Vegetarian entries: caprese, minestrone, pesto pasta, mushroom risotto, black bean burritos, taco salad, sopa de tortilla, huevos rancheros, fried rice, tofu curry, spring rolls, mac and cheese, falafel, hummus bowl, greek salad, tabbouleh, roasted vegetable wrap, couscous, stuffed peppers, baked falafel. That's ~20/50 = 40% vegetarian, which is the "vegetarian-heavy" target.

S15.2 — Import script (one-shot Python)

• scripts/seed_recipes.py (NEW) — reads the 50-query list, calls GET /api/recipes/search?q=...&limit=5, picks the top hit per query, calls POST /api/recipes/import with {external_id, external_source: "spoonacular"}. Idempotent: 409 on duplicate → skip.
• Uses the existing SESSION_PASSWORD=test-family-password for require_session auth. POST body is JSON. Runs in a single Python process.
• 1-2 sec sleep between queries to stay well below the 1-pt + 0.01 × 5 hits = 1.05 pts/search rate. No race with the frontend's quota counter — process-local, single-threaded.
• Logs per-query result: external_id, name, points_used_so_far, quota_status.

S15.3 — Verify

• SELECT count(*) FROM recipe WHERE external_source='spoonacular'; returns ~50 (give or take the 5-10 that fail to return hits).
• Spot-check 5 random recipes in the UI: /recipes page shows them with the right image, ingredients, prep time.
• mealPlannerApi.llm.plan({prompt: 'Italian, vegetarian', week_start}) returns picked_count > 0 and uses the new recipes.
• 4-week plan generation: meals.fillEmptySlots should pull from a richer library, fewer "no recipe available" failures.

S15.4 — Docs (all 6 running docs updated)

• Review/sprint15-verification.md (NEW) — the 50-query list + the script + the curl flow + the expected counts.
• .agent/plan.md — Sprint 15 section (S15.1-S15.4 + Done when + Out of scope).
• .agent/context.md — Sprint 15 decisions (D1-D6), open Q1-Q2, file:line references.
• Review/ui-nielsen-audit.md — Sprint 15 status block.
• fix-ui-audit.md — Sprint 15 section.
• Review/handoff-ui-audit.md — Batch K, TL;DR, last-updated.
• docs/HANDOFF.md — Sprint 15 section + last-updated footer.

Done when (Sprint 15)

• All boxes above ticked.
• 50 (or close to 50) Spoonacular recipes in the local recipe table.
• _points_used counter ends at ~105-130 pts (under the 140 cap).
• All 6 doc files have a Sprint 15 status block.

Out of scope (Sprint 15)

• No new feature work, no schema changes, no UI changes. This is a content op. Any change to the import endpoint, the search endpoint, or the recipe model is out of scope.
• No tuning of the quota counter or the inference logic. Sprint 12's _infer_protein_simple is good enough.
• No re-running of previous sprints' verification flows. Sprint 15 is additive.
• F9-full (local Ollama model pull). Still opt-in based on cloud-billing feedback.

Sprint 15 — Round 2 (2026-06-07): +18 recipes, library at 67 total

User direction (2026-06-07): "please add more meals to the potential list" / "Pull in more recipes so we have a larger sample to generate from."

Round 1 (Sprint 15) imported 18 recipes before hitting the 50-pt/day free-tier cap. The user wanted more. Round 2 uses a fresh quota (cap rolled over) and a different query list focused on cuisines and meal types the round 1 list didn't cover.

S15R2.1 — Round 2 query list (50 queries, gap-filling)

• Indian (8): chicken tikka masala, butter chicken, palak paneer, chana masala, biryani, dal, samosa, naan
• Thai (6): green curry, massaman curry, tom yum soup, mango sticky rice, papaya salad, thai basil chicken
• Chinese regional (6): mapo tofu, hot and sour soup, scallion pancakes, soup dumplings, beef noodle soup, dan dan noodles
• Soups & stews (6): french onion soup, clam chowder, chicken noodle soup, tomato soup, lentil soup, butternut squash soup
• Salads (6): caesar salad, cobb salad, nicoise salad, wedge salad, pasta salad, quinoa salad
• Sandwiches/wraps (5): banh mi, reuben sandwich, club sandwich, french dip, gyro wrap
• Breakfast (5): eggs benedict, pancakes, french toast, omelette, breakfast burrito
• German/European (4): schnitzel, spaetzle, sauerbraten, beef rouladen
• French (4): coq au vin, ratatouille, beef bourguignon, quiche lorraine

50 queries = 8+6+6+6+6+5+5+4+4.

S15R2.2 — Round 2 import script

• scripts/seed_recipes_round2.py (NEW, ~120 lines) — same shape as round 1, different query list. Hits Spoonacular's complexSearch directly, POSTs top hits to backend's /api/recipes/import. Idempotent (409 on duplicate). 1.5 sec sleep. Stops on 402.

S15R2.3 — Round 2 result

• 18 recipes imported today (queries 1, 2, 3, 5, 6, 7, 8, 10, 17, 19, 21, 22, 23, 24, 25, 27, 28, 29). 12 queries returned no hits from Spoonacular's free-tier index (e.g. "chana masala", "thai basil chicken", "dan dan noodles"). 1 query hit 402 mid-import ("wedge salad", HTTP 502 from /api/recipes/import).
• DB went 49 → 67 total recipes (37 Spoonacular + 30 manual).
• LLM test (Sprint 13, week 2026-07-20, prompt "variety, mix of cuisines, family-friendly, no repeats"): picked_count=0 / filled_count=21 / failed_count=0. Library now covers all 21 slots of a week (was 19/21 + 2 failed in round 1).

S15R2.4 — Round 2 follow-up

• Q2 — Run a round 3? Quota resets every 24h. A round 3 could add 30 more recipes (using round 1's script, which is idempotent and will skip the 37 already imported). Trajectory: 67 → 80-100 total.
• Q3 — Lower _DAILY_LIMIT=140 to 45 to match the real 50-pt free tier. Surface in the next sprint that touches recipe_search.py.

Done when (Round 2)

• 18 recipes imported today (from 50 queries).
• DB went 49 → 67.
• LLM test: 21/21 slots filled, 0 failed.
• All 6 running docs updated with round 2 status.

Out of scope (Round 2)

• Same as round 1. No feature work, no schema changes, no UI changes.