oikos/docs/MEAL_PLANNING_NATIVE_PATCH.md

Native Meal Planning Signals Patch

Status: local patch series, not deployed and not pushed upstream.

This patch series turns the Oikos Assist meal-planning sidecar concepts into a first native Oikos shape. The intent is to make meal-planning data belong to Oikos core while Assist remains a suggestion/prepare-action layer.

Patch series

• 7c11806 — feat: add native meal planning signal api
• 0b6603b — test: cover native meal planning schema
• 5099155 — feat: expose meal cook assignments on meals
• cf099bb — feat: add native meal cook selector

Schema

Migration v39 adds these tables:

• meal_cooking_rules — recurring cook rules by user, weekday, and meal type.
• recipe_family_preferences — per-user recipe preferences and capability signals.
• recipe_variation_meta — recipe protein/style/kid-suitability metadata.
• planned_meal_cooks — assigned cook for a planned/saved meal.
• meal_plan_feedback — accept/reject/edit/swap/confirm/cookbook feedback events.
• kids_cookbooks — saved kid-readable cookbook previews.

API surface

New route namespace: /api/v1/meal-planning.

Endpoints added:

• GET /cooking-rules
• PUT /cooking-rules
• GET /recipe-signals
• PUT /recipe-signals/:recipeId
• GET /variation-meta
• PUT /variation-meta/:recipeId
• GET /cook-assignments
• PUT /cook-assignments/:mealId
• GET /feedback
• POST /feedback
• GET /kids-cookbooks
• POST /kids-cookbooks

OpenAPI path entries are included for the new namespace.

Native meals integration

/api/v1/meals now exposes cook assignments directly:

• Weekly GET /api/v1/meals returns cook_assignment per meal.
• POST /api/v1/meals accepts cook_user_id / cookUserId and optional source_plan_id / sourcePlanId.
• PUT /api/v1/meals/:id accepts the same fields and can clear with cook_user_id: null.
• Moving a meal without explicitly changing cook syncs the assignment date/type to the new slot.

Native UI integration

public/pages/meals.js now:

• loads /family/members,
• displays assigned cook on meal cards,
• adds a cook selector to the meal create/edit modal,
• sends cook_user_id through native meal create/edit calls.

Locale keys added in English and German:

• meals.cookLabel
• meals.cookNone

Verification run

Passed locally:

node --check server/routes/meal-planning.js
node --check server/routes/meals.js
node --check server/index.js
node --check server/openapi.js
node --check public/pages/meals.js
node -e "JSON.parse(require('fs').readFileSync('public/locales/en.json','utf8')); JSON.parse(require('fs').readFileSync('public/locales/de.json','utf8'))"
npm run test:meal-planning
npm run test:meals

Focused test results:

• test:meal-planning: 15/15 passing
• test:meals: 22/22 passing

Known caveats before upstream PR

• The route currently supports the needed native shape, but should be reviewed for upstream naming conventions.
• The OpenAPI entries are intentionally broad (jsonBody(null)) and should be expanded with formal schemas before a polished PR.
• Only English/German locale keys were added in this patch. Other locales fall back, but a full upstream PR should update all supported locales or accept fallback behavior.
• This patch does not include AI generation. That remains outside Oikos core; Assist should call these native endpoints once this lands.
• The local working tree has unrelated Danish translation edits that are intentionally not part of this patch series.