forge-openclaw-plugin 0.2.104 → 0.2.105

package/dist/openclaw/tools.js

@@ -270,10 +270,12 @@ const healthLinkInputSchema = () => Type.Object({
     relationshipType: Type.Optional(Type.String({ minLength: 1 }))
 });
 const nutritionMealItemInputSchema = () => Type.Object({
+    foodId: Type.Optional(optionalNullableString()),
     name: Type.String({ minLength: 1 }),
     brand: optionalNullableString(),
     quantity: Type.Number({ minimum: 0 }),
     unit: optionalNullableString(),
+    grams: Type.Optional(Type.Union([Type.Number(), Type.Null()])),
     caloriesKcal: Type.Optional(Type.Union([Type.Number(), Type.Null()])),
     proteinG: Type.Optional(Type.Union([Type.Number(), Type.Null()])),
     carbsG: Type.Optional(Type.Union([Type.Number(), Type.Null()])),
@@ -304,16 +306,17 @@ const nutritionFoodLogSchema = () => Type.Object({
     mealLabel: optionalNullableString(),
     source: Type.Optional(Type.Union([
         Type.Literal("manual"),
+        Type.Literal("search"),
         Type.Literal("barcode"),
         Type.Literal("chatgpt"),
         Type.Literal("photo"),
-        Type.Literal("import")
+        Type.Literal("saved_meal")
     ])),
     confirmationState: Type.Optional(Type.Union([
         Type.Literal("candidate"),
         Type.Literal("confirmed"),
-        Type.Literal("corrected"),
-        Type.Literal("rejected")
+        Type.Literal("needs_review"),
+        Type.Literal("discarded")
     ])),
     satietyScore: Type.Optional(Type.Union([Type.Number(), Type.Null()])),
     hungerBefore: Type.Optional(Type.Union([Type.Number(), Type.Null()])),
@@ -878,7 +881,7 @@ export function registerForgePluginTools(api, config) {
     api.registerTool({
         name: "forge_log_food",
         label: "Forge Log Food",
-        description: "Create a confirmed or candidate food log with explicit meal items, calories, macros, quality tags, hunger, satiety, cravings, and context.",
+        description: "Create a confirmed or candidate food log. Search first and pass foodId when reusing a catalog food; for custom foods without foodId, caloriesKcal, proteinG, carbsG, and fatG are required.",
         parameters: nutritionFoodLogSchema(),
         async execute(_toolCallId, params) {
             const typed = params;

package/dist/server/server/src/app.js

@@ -3416,6 +3416,7 @@ const AGENT_ONBOARDING_ENTITY_CONVERSATION_PLAYBOOKS = [
             "Ask whether the question is fat-loss pace, food intake, protein/fiber sufficiency, sport fuel, visual look, water retention, cravings, gut comfort, energy, or one meal reaction.",
             "Use forge_get_weight_loss_overview before asking the user to reconstruct recent food, weight, workouts, or subjective state from memory.",
             "Use forge_parse_food_log_with_chatgpt only for rough meal text or photo descriptions through Forge's configured openai-codex ChatGPT subscription connection, not a metered OpenAI Platform API path.",
+            "Before forge_log_food, search foods or barcode lookup first; reuse a matching result with item.foodId, and create custom/no-foodId items only with researched calories, protein, carbohydrate, and fat.",
             "Use the dedicated nutrition tools for food logs, body check-ins, appearance check-ins, subjective food effects, gut check-ins, nutrition patterns, and N-of-1 experiments instead of generic batch CRUD.",
             "Ask for the one outcome metric that would make a nutrition experiment interpretable before turning repeated observations into a hypothesis."
         ]
@@ -4051,7 +4052,7 @@ function enrichConversationPlaybookWithRouteInfo(playbook) {
         ...buildPlaybookRouteInfo(playbook.focus)
     };
 }
-const AGENT_ONBOARDING_TOOL_INPUT_CATALOG = [
+export const AGENT_ONBOARDING_TOOL_INPUT_CATALOG = [
     {
         toolName: "forge_get_user_directory",
         summary: "Read the live human/bot directory and directional relationship graph.",
@@ -4299,10 +4300,36 @@ const AGENT_ONBOARDING_TOOL_INPUT_CATALOG = [
         notes: [
             "The API path is /api/v1/health/weight-loss and the UI route is /weight-loss.",
             "Use the dedicated nutrition logging tools for food, body, appearance, subjective, gut, and experiment mutations.",
+            "Before logging a custom food, search the local/public nutrition catalog; if there is no match, research calories and macros from reliable internet nutrition sources before creating the custom item.",
             "Food parsing uses Forge's configured openai-codex ChatGPT subscription connection, not the metered OpenAI Platform API."
         ],
         example: '{"userIds":["user_operator"]}'
     },
+    {
+        toolName: "forge_search_foods | forge_search_nutrition_foods",
+        summary: "Search Forge's local custom/cache database plus Open Food Facts and USDA-backed public nutrition sources before logging a food item.",
+        whenToUse: "Use before forge_log_food whenever the user names a food, brand, meal component, or custom food that might already exist.",
+        inputShape: "{ query: string, limit?: number, userIds?: string[] }",
+        requiredFields: ["query"],
+        notes: [
+            "Reuse a returned food by passing its id as item.foodId to forge_log_food.",
+            "The local results include custom foods previously added to Forge, so this prevents duplicate custom-food records.",
+            "If no result is good enough, research nutrition facts on the internet before creating a custom item."
+        ],
+        example: '{"query":"Greek yogurt 2%","limit":5}'
+    },
+    {
+        toolName: "forge_lookup_nutrition_barcode",
+        summary: "Lookup a packaged food by barcode before logging it, using Forge's nutrition catalog adapters.",
+        whenToUse: "Use when the user gives a barcode or a packaged-food photo/label includes one.",
+        inputShape: "{ barcode: string, userIds?: string[] }",
+        requiredFields: ["barcode"],
+        notes: [
+            "Reuse the returned food by passing its id as item.foodId to forge_log_food.",
+            "If barcode lookup fails, search by name and brand before creating a custom food."
+        ],
+        example: '{"barcode":"737628064502"}'
+    },
     {
         toolName: "forge_parse_food_log_with_chatgpt",
         summary: "Parse natural-language food text or a photo description into a candidate Forge nutrition log through the openai-codex ChatGPT subscription connection.",
@@ -4320,13 +4347,16 @@ const AGENT_ONBOARDING_TOOL_INPUT_CATALOG = [
         toolName: "forge_log_food",
         summary: "Create a food log with explicit food items, calories, macros, quality tags, hunger, satiety, cravings, and context.",
         whenToUse: "Use for confirmed manual entries, search/barcode-selected foods, or corrected ChatGPT candidates.",
-        inputShape: "{ mealLabel?: string, loggedAt?: string, source?: string, confirmationState?: string, notes?: string, items: Array<{ name, quantity, unit?, caloriesKcal?, proteinG?, carbsG?, fatG?, fiberG?, tags? }>, userIds?: string[] }",
+        inputShape: "{ mealLabel?: string, loggedAt?: string, source?: string, confirmationState?: string, notes?: string, items: Array<{ foodId?, name, quantity, unit?, grams?, caloriesKcal?, proteinG?, carbsG?, fatG?, fiberG?, tags? }>, userIds?: string[] }",
         requiredFields: ["items"],
         notes: [
+            "Always call forge_search_foods/forge_search_nutrition_foods or barcode lookup first and pass item.foodId when there is a good match.",
+            "If item.foodId is omitted, Forge creates or reuses a local custom food. Custom foods must include caloriesKcal, proteinG, carbsG, and fatG; name-only custom foods are rejected.",
+            "If the user does not know those nutrition facts, look them up on the internet from a reliable source before calling forge_log_food, or log a candidate only after estimating all four required values.",
             "Prefer confirmed entries when the user gave concrete amounts.",
             "Use candidate entries for rough estimates that need later correction."
         ],
-        example: '{"mealLabel":"post-workout","items":[{"name":"Greek yogurt","quantity":250,"unit":"g","caloriesKcal":180,"proteinG":25}]}'
+        example: '{"mealLabel":"post-workout","items":[{"foodId":"food_123","name":"Greek yogurt","quantity":250,"unit":"g"}]}'
     },
     {
         toolName: "forge_log_body_checkin | forge_log_appearance_checkin | forge_log_subjective_food_effect | forge_log_gut_checkin",
@@ -4710,7 +4740,7 @@ function buildAgentOnboardingPayload(request) {
             movement: "Forge Movement is the first-class mobility surface. It is a timeline of stays and trips: stays capture time spent in the same place, and trips capture travel between places. Use it for time-in-place questions, travel-history review, specific stay or trip edits, selected-span aggregates, known places, and links to other Forge records rather than pretending stays and trips are normal batch CRUD entities.",
             lifeForce: "Life Force is Forge's energy-budget and fatigue model. Read it through the dedicated life-force state and update it through focused profile, weekday-template, and fatigue-signal routes rather than generic entity CRUD.",
             workbench: "Workbench is Forge's graph-flow execution system. Treat flows, runs, published outputs, node results, and latest-node-output reads as a dedicated API family instead of a normal entity-batch surface.",
-            weightLoss: "Weight Loss is Forge's nutrition, body-composition, sport-fueling, appearance, gut-comfort, craving, and subjective-energy surface. Read it through the health overview route and use the dedicated nutrition tools for food logs, body check-ins, appearance check-ins, subjective effects, gut check-ins, and N-of-1 experiments instead of inventing batch CRUD records.",
+            weightLoss: "Weight Loss is Forge's nutrition, body-composition, sport-fueling, appearance, gut-comfort, craving, and subjective-energy surface. Read it through the health overview route and use the dedicated nutrition tools for food logs, reusable searched/custom food catalog entries, body check-ins, appearance check-ins, subjective effects, gut check-ins, and N-of-1 experiments instead of inventing batch CRUD records.",
             psyche: "Forge Psyche is the reflective domain for values, patterns, behaviors, beliefs, modes, flashcards, and trigger reports. It is sensitive and should be handled deliberately."
         },
         psycheSubmoduleModel: {

package/dist/server/server/src/health-weight-loss.js

@@ -37,6 +37,7 @@ const mealItemInputSchema = z.preprocess((value) => {
     id: z.string().trim().min(1).optional(),
     foodId: z.string().trim().min(1).nullable().optional(),
     name: z.string().trim().min(1),
+    brand: z.string().trim().nullable().optional(),
     quantity: z.coerce.number().positive().default(1),
     unit: z.string().trim().min(1).default("serving"),
     grams: optionalNumberSchema,
@@ -54,6 +55,29 @@ const mealItemInputSchema = z.preprocess((value) => {
     nutrients: z.record(z.string(), z.unknown()).default({}),
     confidence: z.coerce.number().min(0).max(1).default(0.65)
 }));
+const requiredNutritionFields = [
+    "calories",
+    "proteinGrams",
+    "carbohydrateGrams",
+    "fatGrams"
+];
+function hasNutritionValue(value) {
+    return typeof value === "number" && Number.isFinite(value) && value >= 0;
+}
+function missingRequiredNutritionFields(input) {
+    return requiredNutritionFields.filter((field) => !hasNutritionValue(input[field]));
+}
+function nutritionRequirementError(path, name) {
+    return new z.ZodError([
+        {
+            code: z.ZodIssueCode.custom,
+            path,
+            message: `Food item "${name}" must include calories, proteinGrams, ` +
+                "carbohydrateGrams, and fatGrams. Search Forge/public nutrition " +
+                "sources first, or add a custom food only after researching those facts."
+        }
+    ]);
+}
 export const nutritionFoodSearchSchema = z.object({
     query: z.string().trim().min(1),
     limit: z.coerce.number().int().min(1).max(25).default(12)
@@ -575,6 +599,141 @@ function mapFood(row) {
         updatedAt: row.updated_at
     };
 }
+function getFoodCatalogById(foodId) {
+    const row = getDatabase()
+        .prepare(`SELECT * FROM nutrition_food_catalog WHERE id = ?`)
+        .get(foodId);
+    return row ? mapFood(row) : null;
+}
+function consumedGramQuantity(input) {
+    if (hasNutritionValue(input.grams) && input.grams > 0) {
+        return input.grams;
+    }
+    const unit = normalizeCustomFoodToken(input.unit);
+    if (hasNutritionValue(input.quantity) &&
+        input.quantity > 0 &&
+        ["g", "gram", "grams"].includes(unit)) {
+        return input.quantity;
+    }
+    return null;
+}
+function catalogScaleFactor(input, food) {
+    const consumedGrams = consumedGramQuantity(input);
+    if (consumedGrams != null &&
+        hasNutritionValue(food.servingGrams) &&
+        food.servingGrams > 0) {
+        return consumedGrams / food.servingGrams;
+    }
+    const unit = normalizeCustomFoodToken(input.unit);
+    if (hasNutritionValue(input.quantity) &&
+        input.quantity > 0 &&
+        (!unit || ["serving", "servings"].includes(unit))) {
+        return input.quantity;
+    }
+    return 1;
+}
+function scaledCatalogNutrition(value, scaleFactor) {
+    return hasNutritionValue(value) ? round(value * scaleFactor, 2) : undefined;
+}
+function normalizeCustomFoodToken(value) {
+    return (value ?? "")
+        .trim()
+        .toLowerCase()
+        .normalize("NFKD")
+        .replace(/[\u0300-\u036f]/g, "")
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "");
+}
+function customFoodServingKey(input) {
+    if (hasNutritionValue(input.grams) && input.grams > 0) {
+        return `${round(input.grams, 1)}g`;
+    }
+    return `${round(input.quantity, 3)}-${normalizeCustomFoodToken(input.unit) || "serving"}`;
+}
+function customFoodSourceId(input) {
+    const nameKey = normalizeCustomFoodToken(input.name);
+    const brandKey = normalizeCustomFoodToken(input.brand ?? "");
+    return [nameKey, brandKey, customFoodServingKey(input)]
+        .filter(Boolean)
+        .join(":");
+}
+function cacheCustomFood(input) {
+    return cacheFood({
+        source: "custom",
+        sourceId: customFoodSourceId(input),
+        name: input.name,
+        brand: input.brand ?? "",
+        servingLabel: input.unit && input.unit !== "serving"
+            ? `${input.quantity} ${input.unit}`
+            : "1 serving",
+        servingGrams: input.grams ?? null,
+        calories: input.calories,
+        proteinGrams: input.proteinGrams,
+        carbohydrateGrams: input.carbohydrateGrams,
+        fatGrams: input.fatGrams,
+        fiberGrams: input.fiberGrams ?? null,
+        sugarGrams: input.sugarGrams ?? null,
+        sodiumMg: input.sodiumMg ?? null,
+        potassiumMg: input.potassiumMg ?? null,
+        tags: Array.from(new Set(["custom", ...input.tags])),
+        nutrients: {
+            ...input.nutrients,
+            customFood: true,
+            nutritionBasis: "agent_or_user_supplied"
+        },
+        confidence: input.confidence
+    });
+}
+function resolveMealItemForInsert(input, options) {
+    let item = input;
+    if (input.foodId) {
+        const food = getFoodCatalogById(input.foodId);
+        if (!food) {
+            throw new z.ZodError([
+                {
+                    code: z.ZodIssueCode.custom,
+                    path: ["items", "foodId"],
+                    message: `Food catalog item ${input.foodId} was not found. Search foods again before logging.`
+                }
+            ]);
+        }
+        const scaleFactor = catalogScaleFactor(input, food);
+        item = {
+            ...input,
+            name: input.name || food.name,
+            calories: input.calories ?? scaledCatalogNutrition(food.calories, scaleFactor),
+            proteinGrams: input.proteinGrams ??
+                scaledCatalogNutrition(food.proteinGrams, scaleFactor),
+            carbohydrateGrams: input.carbohydrateGrams ??
+                scaledCatalogNutrition(food.carbohydrateGrams, scaleFactor),
+            fatGrams: input.fatGrams ?? scaledCatalogNutrition(food.fatGrams, scaleFactor),
+            fiberGrams: input.fiberGrams ??
+                scaledCatalogNutrition(food.fiberGrams, scaleFactor),
+            sugarGrams: input.sugarGrams ??
+                scaledCatalogNutrition(food.sugarGrams, scaleFactor),
+            sodiumMg: input.sodiumMg ?? scaledCatalogNutrition(food.sodiumMg, scaleFactor),
+            potassiumMg: input.potassiumMg ??
+                scaledCatalogNutrition(food.potassiumMg, scaleFactor),
+            caffeineMg: input.caffeineMg ??
+                scaledCatalogNutrition(food.caffeineMg, scaleFactor),
+            alcoholGrams: input.alcoholGrams ??
+                scaledCatalogNutrition(food.alcoholGrams, scaleFactor),
+            nutrients: Object.keys(input.nutrients).length > 0
+                ? input.nutrients
+                : food.nutrients,
+            confidence: input.confidence ?? food.confidence
+        };
+    }
+    const missing = missingRequiredNutritionFields(item);
+    if (missing.length > 0) {
+        throw nutritionRequirementError(["items"], item.name);
+    }
+    if (!item.foodId && options.cacheConfirmedCustomFood) {
+        const customFood = cacheCustomFood(item);
+        item = { ...item, foodId: customFood.id };
+    }
+    return item;
+}
 function mapItem(row) {
     return {
         id: row.id,
@@ -685,9 +844,10 @@ function listFoodLogs(userId, limit = 120) {
     const itemsByLog = readMealItems(rows.map((row) => row.id));
     return rows.map((row) => mapFoodLog(row, itemsByLog.get(row.id) ?? []));
 }
-function insertMealItem(logId, input) {
+function insertMealItem(logId, input, options) {
+    const item = resolveMealItemForInsert(input, options);
     const now = nowIso();
-    const id = input.id ?? newId("meal_item");
+    const id = item.id ?? newId("meal_item");
     getDatabase()
         .prepare(`INSERT INTO nutrition_meal_items (
         id, log_id, food_id, name, quantity, unit, grams, calories,
@@ -695,7 +855,41 @@ function insertMealItem(logId, input) {
         sodium_mg, potassium_mg, caffeine_mg, alcohol_grams, tags_json,
         nutrients_json, confidence, created_at, updated_at
       ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`)
-        .run(id, logId, input.foodId ?? null, input.name, input.quantity, input.unit, input.grams ?? null, input.calories ?? null, input.proteinGrams ?? null, input.carbohydrateGrams ?? null, input.fatGrams ?? null, input.fiberGrams ?? null, input.sugarGrams ?? null, input.sodiumMg ?? null, input.potassiumMg ?? null, input.caffeineMg ?? null, input.alcoholGrams ?? null, jsonString(input.tags), jsonString(input.nutrients), input.confidence, now, now);
+        .run(id, logId, item.foodId ?? null, item.name, item.quantity, item.unit, item.grams ?? null, item.calories ?? null, item.proteinGrams ?? null, item.carbohydrateGrams ?? null, item.fatGrams ?? null, item.fiberGrams ?? null, item.sugarGrams ?? null, item.sodiumMg ?? null, item.potassiumMg ?? null, item.caffeineMg ?? null, item.alcoholGrams ?? null, jsonString(item.tags), jsonString(item.nutrients), item.confidence, now, now);
+}
+function cacheConfirmedCustomMealItems(logId) {
+    const rows = readMealItems([logId]).get(logId) ?? [];
+    for (const row of rows) {
+        if (row.food_id) {
+            continue;
+        }
+        const item = resolveMealItemForInsert({
+            id: row.id,
+            foodId: null,
+            name: row.name,
+            quantity: row.quantity,
+            unit: row.unit,
+            grams: row.grams ?? undefined,
+            calories: row.calories ?? undefined,
+            proteinGrams: row.protein_grams ?? undefined,
+            carbohydrateGrams: row.carbohydrate_grams ?? undefined,
+            fatGrams: row.fat_grams ?? undefined,
+            fiberGrams: row.fiber_grams ?? undefined,
+            sugarGrams: row.sugar_grams ?? undefined,
+            sodiumMg: row.sodium_mg ?? undefined,
+            potassiumMg: row.potassium_mg ?? undefined,
+            caffeineMg: row.caffeine_mg ?? undefined,
+            alcoholGrams: row.alcohol_grams ?? undefined,
+            tags: parseJson(row.tags_json, []),
+            nutrients: parseJson(row.nutrients_json, {}),
+            confidence: row.confidence
+        }, { cacheConfirmedCustomFood: true });
+        getDatabase()
+            .prepare(`UPDATE nutrition_meal_items
+         SET food_id = ?, updated_at = ?
+         WHERE id = ?`)
+            .run(item.foodId ?? null, nowIso(), row.id);
+    }
 }
 export function createNutritionFoodLog(input) {
     const parsed = nutritionFoodLogCreateSchema.parse(input);
@@ -713,7 +907,9 @@ export function createNutritionFoodLog(input) {
         ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`)
             .run(id, userId, loggedAt, parsed.mealLabel, parsed.source, parsed.confirmationState, parsed.notes, parsed.placeId ?? null, parsed.stayId ?? null, parsed.workoutId ?? null, parsed.sleepId ?? null, logDayKey, jsonString(parsed.imageRefs), jsonString(parsed.parserProvenance), jsonString(parsed.links), now, now);
         for (const item of parsed.items) {
-            insertMealItem(id, item);
+            insertMealItem(id, item, {
+                cacheConfirmedCustomFood: parsed.confirmationState === "confirmed"
+            });
         }
     });
     return getNutritionFoodLogById(id);
@@ -726,6 +922,7 @@ export function patchNutritionFoodLog(logId, input) {
     }
     const nextLoggedAt = parsed.loggedAt ?? existing.loggedAt;
     const nextDayKey = normalizeDayKey(parsed.dayKey, nextLoggedAt);
+    const nextConfirmationState = parsed.confirmationState ?? existing.confirmationState;
     const now = nowIso();
     runInTransaction(() => {
         getDatabase()
@@ -735,15 +932,20 @@ export function patchNutritionFoodLog(logId, input) {
              day_key = ?, image_refs_json = ?, parser_provenance_json = ?,
              links_json = ?, updated_at = ?
          WHERE id = ?`)
-            .run(nextLoggedAt, parsed.mealLabel ?? existing.mealLabel, parsed.source ?? existing.source, parsed.confirmationState ?? existing.confirmationState, parsed.notes ?? existing.notes, parsed.placeId !== undefined ? parsed.placeId : existing.placeId, parsed.stayId !== undefined ? parsed.stayId : existing.stayId, parsed.workoutId !== undefined ? parsed.workoutId : existing.workoutId, parsed.sleepId !== undefined ? parsed.sleepId : existing.sleepId, nextDayKey, jsonString(parsed.imageRefs ?? existing.imageRefs), jsonString(parsed.parserProvenance ?? existing.parserProvenance), jsonString(parsed.links ?? existing.links), now, logId);
+            .run(nextLoggedAt, parsed.mealLabel ?? existing.mealLabel, parsed.source ?? existing.source, nextConfirmationState, parsed.notes ?? existing.notes, parsed.placeId !== undefined ? parsed.placeId : existing.placeId, parsed.stayId !== undefined ? parsed.stayId : existing.stayId, parsed.workoutId !== undefined ? parsed.workoutId : existing.workoutId, parsed.sleepId !== undefined ? parsed.sleepId : existing.sleepId, nextDayKey, jsonString(parsed.imageRefs ?? existing.imageRefs), jsonString(parsed.parserProvenance ?? existing.parserProvenance), jsonString(parsed.links ?? existing.links), now, logId);
         if (parsed.items) {
             getDatabase()
                 .prepare(`DELETE FROM nutrition_meal_items WHERE log_id = ?`)
                 .run(logId);
             for (const item of parsed.items) {
-                insertMealItem(logId, item);
+                insertMealItem(logId, item, {
+                    cacheConfirmedCustomFood: nextConfirmationState === "confirmed"
+                });
             }
         }
+        else if (nextConfirmationState === "confirmed") {
+            cacheConfirmedCustomMealItems(logId);
+        }
     });
     return getNutritionFoodLogById(logId);
 }

package/dist/server/server/src/openapi.js

@@ -5286,11 +5286,14 @@ export function buildOpenApiDocument() {
         type: "object",
         additionalProperties: false,
         required: ["name", "quantity"],
+        description: "Meal item input. Pass foodId from /foods/search or /foods/barcode when reusing a catalog food. If foodId is omitted, Forge treats the item as a custom food and requires calories, proteinGrams, carbohydrateGrams, and fatGrams.",
         properties: {
+            foodId: nullable({ type: "string" }),
             name: { type: "string" },
             brand: nullable({ type: "string" }),
             quantity: { type: "number" },
             unit: nullable({ type: "string" }),
+            grams: nullable({ type: "number" }),
             calories: nullable({ type: "number" }),
             proteinGrams: nullable({ type: "number" }),
             carbohydrateGrams: nullable({ type: "number" }),
@@ -5926,6 +5929,7 @@ export function buildOpenApiDocument() {
                 post: {
                     tags: ["Health"],
                     summary: "Search nutrition foods across local and public catalogs",
+                    description: "Searches Forge's local nutrition_food_catalog first, including custom foods, then public Open Food Facts and USDA-backed sources. Reuse returned ids as NutritionMealItemInput.foodId before creating a new custom food.",
                     requestBody: {
                         content: {
                             "application/json": {

package/openclaw.plugin.json

@@ -2,7 +2,7 @@
   "id": "forge-openclaw-plugin",
   "name": "Forge",
   "description": "Curated OpenClaw adapter for the Forge collaboration API, UI entrypoint, and localhost auto-start runtime.",
-  "version": "0.2.104",
+  "version": "0.2.105",
   "activation": {
     "onStartup": true,
     "onCapabilities": [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forge-openclaw-plugin",
-  "version": "0.2.104",
+  "version": "0.2.105",
   "description": "Curated OpenClaw adapter for the Forge collaboration API, UI entrypoint, and localhost auto-start runtime.",
   "type": "module",
   "license": "Apache-2.0",

package/skills/forge-openclaw/SKILL.md

@@ -208,6 +208,13 @@ Health rule:
   `forge_log_appearance_checkin`, `forge_log_subjective_food_effect`,
   `forge_log_gut_checkin`, `forge_get_nutrition_patterns`,
   `forge_start_nutrition_experiment`, and `forge_update_nutrition_experiment`.
+  Before logging food, search Forge's nutrition catalog first. If a result matches,
+  pass that result's `id` as `item.foodId` to `forge_log_food` so Forge reuses the
+  local/custom food database instead of creating a duplicate. If no result matches
+  and you are creating a custom food, look up nutrition facts on the internet or
+  another reliable public nutrition source before logging it. Custom/no-`foodId`
+  items must include at least calories plus protein, carbohydrate, and fat
+  (`caloriesKcal`, `proteinG`, `carbsG`, `fatG`); never save a name-only food.
   `forge_parse_food_log_with_chatgpt` must use Forge's configured `openai-codex`
   ChatGPT subscription connection, not a metered OpenAI Platform API path.
 - In `forge_get_agent_onboarding.entityRouteModel.readModelOnlySurfaces`, operator,
@@ -702,7 +709,7 @@ Use the health tools when the request is about sleep or sports review:
 - `forge_get_training_load_overview` to inspect cardiovascular load, HR zone balance, zone-time buckets, smart training modes, acute/chronic stress, high-intensity pressure, VO2max context, next-workout guidance, and training target fit
 - `forge_get_weight_loss_overview` to inspect calorie balance, protein/fiber targets, body trend, food quality, training fuel, subjective energy, gut comfort, aesthetic look, hypotheses, and experiments
 - `forge_parse_food_log_with_chatgpt` to convert rough meal text or a photo description into a candidate food log through the configured `openai-codex` ChatGPT subscription connection
-- `forge_log_food`, `forge_log_body_checkin`, `forge_log_appearance_checkin`, `forge_log_subjective_food_effect`, and `forge_log_gut_checkin` to preserve the user's food, body-composition, visual-look, energy/craving/performance, and gut-health evidence
+- `forge_log_food`, `forge_log_body_checkin`, `forge_log_appearance_checkin`, `forge_log_subjective_food_effect`, and `forge_log_gut_checkin` to preserve the user's food, body-composition, visual-look, energy/craving/performance, and gut-health evidence. For `forge_log_food`, search first and reuse `item.foodId`; custom/no-`foodId` items require calories plus protein, carbohydrate, and fat, researched before logging when the user does not provide them.
 - `forge_get_nutrition_patterns`, `forge_start_nutrition_experiment`, and `forge_update_nutrition_experiment` to turn repeated food/body observations into testable N-of-1 hypotheses
 - `forge_update_sleep_session` to add sleep-quality notes, tags, or links back to Forge entities after review
 - `forge_update_workout_session` to add subjective effort, mood, meaning, tags, or links on one workout after review

package/skills/forge-openclaw/entity_conversation_playbooks.md

@@ -415,7 +415,10 @@ still knowing the exact write/read family before it acts.
   hypotheses, or nutrition experiments. Use `forge_parse_food_log_with_chatgpt`
   for rough meal text/photo descriptions through the configured `openai-codex`
   ChatGPT subscription connection, then use `forge_log_food` and the body,
-  appearance, subjective, gut, and experiment tools for durable evidence.
+  appearance, subjective, gut, and experiment tools for durable evidence. Search
+  foods first and reuse returned `foodId` values. If a custom food is needed,
+  research calories plus protein, carbohydrate, and fat from reliable internet
+  nutrition sources before logging; name-only custom foods are invalid.
 - `movement`: specialized domain surface. Use the dedicated movement routes for day,
   month, all-time, timeline, places, trip detail, selection aggregates, manual
   overlays, and repair actions.
@@ -1598,7 +1601,11 @@ Arc:
 4. Use `forge_log_food`, `forge_log_body_checkin`,
    `forge_log_appearance_checkin`, `forge_log_subjective_food_effect`, and
    `forge_log_gut_checkin` to preserve the user's actual evidence.
-5. Use `forge_get_nutrition_patterns`, `forge_start_nutrition_experiment`, and
+5. For `forge_log_food`, call `forge_search_foods` or barcode lookup first. Reuse
+   a matching result through `item.foodId`. If there is no match, create a custom
+   food only after researching calories, protein, carbohydrate, and fat; include
+   `caloriesKcal`, `proteinG`, `carbsG`, and `fatG` in the item.
+6. Use `forge_get_nutrition_patterns`, `forge_start_nutrition_experiment`, and
    `forge_update_nutrition_experiment` when repeated observations should become
    an N-of-1 test instead of vague advice.
 
@@ -1607,6 +1614,8 @@ Helpful follow-up lanes:
 - whether the decision is weight trend, protein/fiber sufficiency, sport fuel,
   visual look, water retention, gut comfort, cravings, or energy
 - whether a meal should be confirmed precisely or logged as a candidate estimate
+- whether a searched/catalog food can be reused by `foodId` or whether a researched
+  custom food with calories and macros is needed
 - which outcome metric should define a nutrition experiment before interpreting it
 
 Route note:
@@ -1614,7 +1623,9 @@ Route note:
 - `weight_loss` is a health read model plus dedicated nutrition write workflow.
   Use `/api/v1/health/weight-loss` or `forge_get_weight_loss_overview` for the
   overview. Do not invent generic batch entities for food logs or body check-ins
-  when the dedicated tools exist.
+  when the dedicated tools exist. Food search reads Forge's local custom/cache
+  database plus public nutrition catalogs. `forge_log_food` rejects custom items
+  without calories, protein, carbohydrate, and fat.
 
 Ready to review when: