feat(ui): Sprint 9 — F1 onboarding tour (4-step welcome)

Hand-rolled 4-step tour (no react-joyride) anchors to existing
[data-tour="<id>"] attributes. localStorage key
mealplanner:onboarding-complete is the source of truth; ?reset-tour=1
clears the key and re-shows.

Steps: Dashboard / Pantry / Recipes / Shopping List. Keyboard: 1-4 jump,
←/→ step, Esc dismiss. Off-route fallback renders a centered card with
an 'Open <page>' CTA. A11y: role=dialog, aria-modal=true, focus captured
on open and restored on close.

5 lines of code across 4 pages; 1 new component (~420 lines). No new
dependencies. No backend changes. No migration. Frontend-only deploy.

Tracking: Review/sprint9-verification.md (8-step browser smoke + a11y
check + reset-link test).

.agent/plan.md

@@ -121,3 +121,68 @@ Goal: bring implementation back into alignment with `Review/reviewconcensus.md`.
 
 - 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)
+
+- [x] Hand-rolled (no `react-joyride`) — keeps npm footprint flat.
+- [x] 4 steps: Dashboard / Pantry / Recipes / Shopping List.
+- [x] Anchors to `[data-tour="<id>"]` attributes on existing elements.
+- [x] Tooltip card pinned to anchor (top/bottom/center fallback for off-route steps).
+- [x] Anchor highlight = primary-400 ring + soft scrim; tooltip is a real `<div role="dialog" aria-modal="true">`.
+- [x] Step progress = 4 progress bars.
+- [x] Keyboard: `1`–`4` jump, `←/→` step, `Esc` dismiss, `Tab` order is `Skip → Back → Next`.
+- [x] `useOnboarding()` hook + `?reset-tour=1` re-trigger; localStorage key `mealplanner:onboarding-complete`.
+- [x] Focus captured on open (primary action), restored on close.
+- [x] All reads/writes to localStorage wrapped in try/catch (private mode safe).
+
+### S9.2 — Anchor points (5 lines of code total)
+
+- [x] `pages/Dashboard.tsx:602` — `<Card data-tour="dashboard">` on the Weekly Overview grid.
+- [x] `pages/Pantry.tsx:185` — `<div data-tour="pantry">` on the page header (always present).
+- [x] `pages/Pantry.tsx:208` — second anchor on the add-form `<Card>` (when the form is open).
+- [x] `pages/Recipes.tsx:124` — `<Button data-tour="recipes">` on the Filters button.
+- [x] `pages/ShoppingList.tsx:231` — `<div data-tour="shopping-list">` on the page header.
+
+### S9.3 — `App.tsx` mount
+
+- [x] `useOnboarding()` at App root, `isComplete` passed to `<OnboardingTour>`.
+- [x] `onComplete` mapped to `onboarding.reset()` (flips the flag so re-renders don't re-show).
+- [x] Mounted as sibling of `<ShortcutHelpBanner />` inside `<BrowserRouter>` (so `useLocation` / `useNavigate` work).
+
+### S9.4 — Verify
+
+- [x] `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.5 — Docs (all 6 running docs updated)
+
+- [x] `Review/ui-nielsen-audit.md` — Sprint 9 status block at the top.
+- [x] `fix-ui-audit.md` — Sprint 9 plan section (T3.1–T3.4).
+- [x] `Review/handoff-ui-audit.md` — Sprint 9 entry in the "How to take over" section + TL;DR row.
+- [x] `docs/HANDOFF.md` — Sprint 9 section.
+- [x] `.agent/plan.md` — this section.
+- [x] `.agent/context.md` — Sprint 9 decisions + file:line references.
+- [x] `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 — already drafted, awaiting user approval to execute.