oikos/docs/MEAL_PLANNING_ROADMAP.md

Oikos Meal Planning — Combined Roadmap

Status: active Friborg branch roadmap. This merges the older Assist plan, native meal-planning patch notes, structured taxonomy work, Playwright E2E plan, and upstream-readiness backlog into one source of truth.

North Star

Meal planning should be a native Oikos kitchen workflow, not a chatbot shortcut. Assist can suggest and prefill, but the family reviews and edits in a dedicated Kitchen surface before anything is written.

Current Verified Live Baseline

• Public app: https://home.friborg.uk
• Core branch: friborg/native-meal-planning
• Latest verified core commit: 58a76ee (feat: structure meal planning taxonomy and favorites)
• Latest verified Assist/Studio commit: 062211f (chore: remove legacy meal plan add path)
• Live core image: oikos-structured-mealflow:20260512-170557
• DB schema: migration 41
• Latest live E2E: OIKOS_E2E_MUTATE=1 npm run test:e2e:oikos-flow -- --project=chromium-desktop → 2/2 passed, cleanup zero

Completed Plan Threads

Studio-first Assist handoff

• Meal-plan prompts return a structured studioPlan instead of text-only drafts.
• Assist action card opens the page-level Kitchen Studio.
• Direct legacy text-plan add path removed from the widget.
• Studio lives on /meals as a Kitchen module.
• Confirming the Studio writes native meals through explicit user action.

Native meal-planning data

• Native /api/v1/meal-planning/* endpoints for rules, recipe signals, variation metadata, cook assignments, feedback, and kids cookbooks.
• Native /api/v1/meals accepts and returns cook assignments.
• Meal/recipe taxonomy promoted into core fields: meal_category, protein, style, recipe tags_json.
• Leftovers are first-class via leftover_from_meal_id.
• source_plan_id preserves Studio provenance.

Family preference and learning loop

• Likes/dislikes/favorite/can-cook/can-help/modified-ok/adult-only signals.
• Meal modal and recipe cards can save person-specific signals.
• Family profile cards report favorite and can-cook counts.
• Accept/reject/edit/swap/confirm feedback is recorded.
• Learning summary panel exposes signal counts.

Planning quality

• Planner considers family rules, cook assignments, preferences, weather/activity/season context.
• Generation modulators are explicit in Studio plans: season, weather, easy/busy days, guests, no-kids/adult-only context, family favorites/likes/dislikes, child age, child can-cook/can-help signals, and variety counters.
• Planner tracks category/protein/style diversity.
• Adjacent category repeats are penalized/avoided.
• Swap alternatives are ordered to preserve diversity constraints.
• Leftovers are dedicated linked slots, not note text.

Kids flow

• Kids board with large category cards.
• Drag/tap meal card assignment to days.
• Kid cookbook preview and saved cookbook storage.

Verification and safety

• Playwright smoke covers Kitchen open + Assist handoff.
• Mutating E2E covers swap/edit/confirm/native readback/cook assignments/cleanup.
• Structural E2E asserts categories, diversity, linked leftovers, favorite-signal UI, profile count reflection, and cleanup.
• Structural E2E asserts Studio plans expose modulator labels and active signal types, so planning context is not hidden in opaque AI text.
• Playwright artifacts are opt-in to reduce credential leak risk.

Context-aware family logistics engine

• Added deterministic meal-fit service for the next planning slice: day context, energy, guests, cleanup, interruption tolerance, concrete inventory/leftover use, preferences/allergies, recency, and grocery delta all affect ranking before AI gets involved.
• Added /api/v1/meal-planning/suggestions as a thin native API boundary returning ranked suggestions plus optional generated grocery output.
• Added test:meal-fit acceptance coverage proving busy/low-energy days, guest days, allergy blocks, dislike/repetition, concrete inventory matching, and grocery dedupe change outputs materially.

Remaining Combined Plan

P0 — Upstream/Core polish before PR

• Make OpenAPI more explicit for meal-planning request/response bodies instead of broad object bodies.
• Update product spec data model to include native meal-planning tables and structured meal/recipe taxonomy.
• Keep Friborg-specific deployment details out of upstream docs/PR copy.
• Rebase friborg/native-meal-planning onto current upstream main and resolve conflicts.
• Prepare small upstreamable PR slices rather than one giant Friborg branch.

P1 — Reduce sidecar ownership

• Keep moving UI state from injected Assist widget toward native Kitchen components.
• Preserve Assist as suggestion/provider layer, not system-of-record.
• Add native Studio API boundaries where useful before porting the full Studio UI.
• Keep Settings → Assist limited to provider/model plumbing.

P1 — UX polish

• Localize new structured meal fields and preference labels fully (currently several labels are English in Danish/German UI surfaces).
• Make leftovers source selector easier to scan by week/date/category.
• Add small visual category chips consistently across meals, recipes, and Studio.
• Add dedicated Studio controls for one-off guests/no-kids/easy-day overrides instead of relying only on activity/event text detection.
• Improve mobile layout for Studio slots and kids board after the data model has stabilized.

P2 — Platform modularization

• Module registry for routes/navigation/capabilities.
• Locale registry so supported locales, picker labels, and service worker precache come from one source.
• Extension/overlay mechanism for deployment-specific customizations without patching core.

Implementation Rule

Continue in verified slices:

1. make the smallest meaningful change,
2. run syntax/unit gates,
3. deploy only when needed,
4. run live smoke/E2E when the public flow changes,
5. verify cleanup/data health,
6. commit and push to Gitea,
7. update this roadmap if scope or status changes.