From ba534cb8644152f0f71b599d6802f297050537b9 Mon Sep 17 00:00:00 2001
From: OpenClaw Bot <openclaw-bot@friborg.uk>
Date: Mon, 11 May 2026 23:15:15 +0200
Subject: [PATCH] docs: document native meal planning patch

---
 docs/MEAL_PLANNING_NATIVE_PATCH.md | 95 ++++++++++++++++++++++++++++++
 1 file changed, 95 insertions(+)
 create mode 100644 docs/MEAL_PLANNING_NATIVE_PATCH.md

diff --git a/docs/MEAL_PLANNING_NATIVE_PATCH.md b/docs/MEAL_PLANNING_NATIVE_PATCH.md
new file mode 100644
index 0000000..50ef31f
--- /dev/null
+++ b/docs/MEAL_PLANNING_NATIVE_PATCH.md
@@ -0,0 +1,95 @@
+# 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:
+
+```bash
+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.