Update to BetterMenu

{
  "description": "Use when the user wants US nutrition numbers or FDA food labelling with BetterMenu: an FDA Nutrition Facts label, or nutrition facts, calories and %DV per serving, for a recipe or batch they paste (in any units), link, want saved, or already have saved, with per-unit numbers for a yield (\"calories per bar if it makes 8\"); USDA nutrition for one food, branded products included (\"how many calories in an apple\", \"sugar in a granola bar\"); comparing two foods (\"butter vs margarine, more saturated fat\"); an amount in grams (\"how many grams is 2 cups of flour\"); the US FDA Daily Value for a nutrient (\"daily value for sodium\"); the FDA serving size for a food type (\"what serving size for cookies\"); and their saved recipes and custom ingredients. Not for inventing a recipe or method (\"give me a banana bread recipe\"), meal plans, diet advice, or explaining a term such as %DV.",
  "included_files": [
    {
      "relative_path": "references/custom-ingredients.md",
      "size_in_bytes": 2647
    },
    {
      "relative_path": "references/reading-a-recipe.md",
      "size_in_bytes": 4234
    },
    {
      "relative_path": "references/saving-a-recipe.md",
      "size_in_bytes": 5349
    }
  ],
  "name": "bettermenu",
  "skill_md_contents": "---\nname: bettermenu\ndescription: Use when the user wants US nutrition numbers or FDA food labelling with BetterMenu: an FDA Nutrition Facts label, or nutrition facts, calories and %DV per serving, for a recipe or batch they paste (in any units), link, want saved, or already have saved, with per-unit numbers for a yield (\"calories per bar if it makes 8\"); USDA nutrition for one food, branded products included (\"how many calories in an apple\", \"sugar in a granola bar\"); comparing two foods (\"butter vs margarine, more saturated fat\"); an amount in grams (\"how many grams is 2 cups of flour\"); the US FDA Daily Value for a nutrient (\"daily value for sodium\"); the FDA serving size for a food type (\"what serving size for cookies\"); and their saved recipes and custom ingredients. Not for inventing a recipe or method (\"give me a banana bread recipe\"), meal plans, diet advice, or explaining a term such as %DV.\n---\n\n# BetterMenu: US nutrition facts, FDA labels, food data\n\nBetterMenu computes nutrition from amounts, using USDA data and the user's own custom\ningredients, under US FDA rules (market `US`).\n\n## Read the recipe first\n\nBefore the first search, read the whole recipe: the ingredient table and every step. The\nrecipe is everything in both. Then send the user one message that covers all of these:\n\n- **Items only in the steps.** Finishing butter, egg wash, dusting flour, a side sauce\n  served \"in a ramekin\" or \"serve with\", a garnish. Name each one as an addition, with its\n  amount, or ask for the amount.\n- **Items only in the table** that no step uses. An item is table-only when no step names\n  it, even when you can guess where it goes. Name each one as table-only, even when you plan\n  to keep it, and ask whether it goes in the dish.\n- **Names that differ.** \"Chicken slice\" in the table and \"chicken pieces\" in a step are one\n  item. Say that you read them as one.\n- **Alternatives.** \"Rice or fries\", \"chicken or beef\", \"selected add-on\", \"choice of\" are\n  options, not additions. Never add the options together. Propose one recipe per guest\n  choice, or ask which one to label.\n- **Amounts that differ** between the table and the steps. Use the table amount and say so.\n  Ask only when the difference matters (see \"Go ahead, ask, or step away\").\n- **Household units** (\"1 scoop\", \"6 shakes\", \"150 ml\" of a sauce). Convert them with\n  `convert_ingredient_amounts_to_grams`, or state the weight you used and why.\n- **House-made items named like a generic food** (\"garlic butter blend\", \"house seasoning\n  salt\"). They are not plain butter or plain salt. Ask for the house recipe or the spec\n  sheet, or offer to make a custom ingredient (`references/custom-ingredients.md`). Use the\n  generic food only when the user says so, and say that you did.\n- **Raw or cooked** for every line (next section).\n\nOne message, not one question per line. When an item needs the user's answer (an item\nonly in the steps or only in the table, a garnish with no amount, alternatives, a\nhouse-made item, or a raw or cooked state the steps do not settle), send the message and\nwait for the reply before you save. Ask only about the items that need an answer; state\neverything else as a default with its size, and do not ask to confirm it. States the steps settle need no answer: state them and\ngo ahead. A clean recipe, where the table and the\nsteps agree, needs no extra questions. Worked examples are in `references/reading-a-recipe.md`.\n\n## Raw or cooked\n\nDecide for each line from what the steps do with it, then search for that state.\n\n- **Weighed, then cooked in the dish** (chicken grilled to order, rice simmered in the pot):\n  raw. Use the raw food.\n- **Weighed after cooking** (rice scooped from a warmer, beans ladled from a pot; \"cooked penne\n  230g\"): cooked. Search \"rice, cooked\", not \"rice\". A portioned grain is a cooked weight\n  even when the recipe never says \"cooked\".\n- **Not said, for grains, pasta, dried beans or meat:** ask.\n- **Give the size of the swing** for grains, pasta, dried beans and meat, for the line as\n  written: 200 g of cooked rice is about 260 kcal, and the same 200 g matched as raw rice is\n  about 730 (USDA: about 365 kcal per 100 g raw, 130 cooked). Cooked chicken breast entered\n  as raw loses about a quarter.\n- **A dry product the user requires, weighed cooked:** keep their product. Convert the\n  weight with the ratio of the dry and cooked USDA foods' calories per 100 g\n  (`get_ingredient_nutrition_facts`), and show the arithmetic: 230 g cooked penne × 158 /\n  371 ≈ 98 g dry. Say the conversion is your arithmetic, and say what the wrong weight\n  would do: 230 g of the dry product would overstate the line by about 135% (about 853 kcal\n  against 363).\n- **One serving is the whole plate or bowl:** set its weight to `reference_weight_grams`\n  from `get_recipe_total_nutrition`, the sum of the saved rows. A plated weight that differs\n  from that sum scales every number wrongly.\n- **Edible part only.** No bones, shells, peels or pits.\n\nBare words often rank raw or dry foods first. Check that each chosen hit's name says the state\nyou meant, and say why you chose raw or cooked for each line, with the swing for each\ngrain, pasta, dried bean or meat line.\n\n## Frying oil and marinade\n\nCount only what stays in the food: the oil it absorbs and the marinade it takes up or is\nserved with. Oil left in the fryer and marinade poured away are not in the dish. Ask the\nuser for those weights; weighing the oil before and after frying gives the uptake. Oil\nbrushed on a pan or plate with no amount: go ahead without it, and say it is not counted.\nAbsorbed oil is almost pure fat: every 10 g adds about 88 kcal and 10 g of fat. A brush of\noil on a plate is a gram or two.\n\n## Go ahead, ask, or step away\n\n- **Go ahead**, and state the assumption and about how much it moves the panel (\"about\n  5 kcal\"), when it moves the panel a little: salt to taste, a pinch of a dried spice, ml\n  read as g for a sauce (say that you assume it is about as dense as water), a small difference between the table and\n  the steps. A garnish with no amount is not dropped: name it in the read-back and ask for\n  its weight.\n- **Ask** before saving or exporting when an unknown could move calories or another\n  mandatory nutrient by more than about 20%. FDA's tolerance for calories is 20%\n  (21 CFR 101.9(g)(5)). Give the size of the swing in the question.\n- **Step away** when these tools cannot give a reliable panel. Say what they cannot do, and\n  what would:\n\n| Case | Why these tools cannot | What would |\n|---|---|---|\n| Deep-fried, oil uptake unknown | Uptake varies widely | Weigh the oil before and after frying, or a lab analysis |\n| Cooking loss that matters (a serving set by its cooked weight) | Numbers use raw ingredient weights; no allowance for water lost | A lab analysis, or a serving set as a share of the raw batch |\n| Dual-column label (`us.dual_column_not_supported`) | Not supported | Another labeling tool or a regulatory consultant |\n| Nutrient content claims (\"low fat\", \"high protein\") | Claims are not checked | A regulatory consultant |\n| Allergen statement (\"Contains: milk\") | No allergen data | The user's ingredient specs and a regulatory review |\n| Menu labeling (calories on a menu board) | Not covered | The menu labeling rules, or a consultant |\n| Labels for other countries | US only | That country's rules |\n\nThe user decides. If they still want the label, export it, and state the assumption with\nthe numbers. Never call a label \"FDA compliant\" or \"FDA approved\".\n\n## A recipe the user pasted → a label\n\n1. `find_saved_recipes` by name; if one matches, ask before creating a duplicate. Read the\n   recipe first (above).\n2. `search_ingredients_for_nutrition`: every ingredient in one call (up to 20\n   `queries`, each with its `position`), with its state in the query. Custom\n   ingredients rank above standard USDA ones. When a custom ingredient is the same food as\n   the line, use it without asking, say which one you used, and offer the USDA food after\n   you save. A brand the recipe does not name, or fewer nutrients than the USDA food, is not\n   a reason to ask or to switch: name any mandatory nutrients it lacks, which the export\n   will ask the user to confirm. A custom\n   ingredient that only shares a word with the line (almond butter for \"butter\") is not a\n   match; a brand or variety in its name (\"wildflower honey\") does not make it a different\n   food. Ask only when two close matches would move calories or another mandatory\n   nutrient by more than about 20%.\n3. `convert_ingredient_amounts_to_grams`: every amount in one call. It does not create\n   or change a recipe; an estimated weight (`allow_estimation`) uses a language model and\n   plan credits. `needs_resolution` means no exact conversion: estimate the weight\n   yourself, call again with `allow_estimation: true` when its `resolve_options` offers\n   that, or ask the user for the weight. Show each estimate with its reasoning so the user\n   can correct it: your own arithmetic written out, or for a `system_estimate` its\n   `gram_weight.estimate.explanation` with the `low_grams` to `high_grams` range. Put them\n   all in one message rather than one question per ingredient; a weight the user gives\n   replaces any estimate.\n4. Per-serving numbers and a label are computed for a **saved** recipe, so ask before\n   saving: `create_recipe_for_nutrition_label`, `set_recipe_ingredients`, then\n   `add_recipe_serving_size` with the yield (\"makes 8 bars\"); for a US label choose\n   `racc_guided` first (`find_fda_serving_size_category`), and `user_provided` only when no\n   category fits. The `demographic` behind %DV, the version token each write needs and what\n   to send for a resolved weight are in `references/saving-a-recipe.md`. Per-serving\n   numbers come from the raw ingredient weights, with no allowance for water lost in\n   cooking; for a cooked or baked food, say so once with the numbers.\n5. Added Sugars: `get_recipe_added_sugars`, ask the user about each open row, save their\n   answers with `patch_recipe_added_sugars_rows`, show them the report, and call\n   `confirm_recipe_added_sugars` with its `report_hash` only when they tell you to. Until\n   it is confirmed the label prints no Added Sugars line.\n6. `get_recipe_nutrition_facts_per_serving` for the numbers,\n   `get_recipe_nutrition_facts_label` for the label (its `readiness` and `findings` show\n   what would stop an export), `get_recipe_total_nutrition` for the batch,\n   `export_nutrition_facts_label_file` for a file (output may carry a DRAFT watermark\n   depending on the account's plan, which is managed in BetterMenu Studio; give the user\n   the `download_url`).\n\nWithout a save you can still give per-ingredient nutrition and gram weights, and say that\nthose are ingredient figures, not a label.\n\n## A recipe link\n\nBetterMenu does not fetch URLs; it takes ingredient lines, so follow the steps above with\nthe page's content. When you cannot read the page (JavaScript-rendered, paywalled, blocked), ask\nthe user to paste the ingredients rather than working from the URL's wording.\n\nTake the recipe's name, its ingredient lines and its yield. The page's other details, such\nas prep and cook times, are not ingredients.\n\nAsk for the yield if the page gives none, and say which yield you used when you give the\nnumbers: per-serving numbers computed against a guessed serving count are wrong in a way no\nlater check catches.\n\nWhen the page lists nutrition of its own and you compute numbers here, show where the two\ndiffer rather than quietly replacing one with the other.\n\n## One food, or two compared\n\n`search_ingredients_for_nutrition`, then `get_ingredient_nutrition_facts`; branded and\npackaged products are in there. Standard foods are `per_100g`, with `portions` giving\nhousehold weights (a medium apple, 182 g), so scale by `gram_weight` / 100; a custom\ningredient is `per_reference_serving`. Compare two foods at the same amount, converting\nwhen their `basis` differs.\n\n## Grams for an amount\n\n`search_ingredients_for_nutrition` for the food, then\n`convert_ingredient_amounts_to_grams` with the quantity and unit (\"2 cups\", \"1 tbsp\").\n\n## Daily Values and serving sizes\n\n`get_fda_daily_value` for one nutrient, `list_fda_daily_values` for the table\n(21 CFR 101.9); both need a `demographic`. `find_fda_serving_size_category` for the FDA\nreference amount (RACC) behind a food type's label serving size,\n`get_fda_serving_size_category` by id, `list_fda_serving_size_categories` for all.\n\n## Saved recipes and custom ingredients\n\n`find_saved_recipes` by name, `list_saved_recipes` to browse. From a recipe id:\n`get_recipe_ingredients`, and `list_recipe_serving_sizes` for the `serving_id` every\nper-serving, label and export tool needs plus the current `version_id`. Change one with\n`set_recipe_ingredients`, `update_recipe_serving_size` or `add_recipe_serving_size`.\n\nFor the user's own ingredients (`list_custom_ingredients`, `get_custom_ingredient`,\n`create_custom_ingredient`, `confirm_custom_ingredient`), see\n`references/custom-ingredients.md`: a panel's amounts are per `reference_quantity_g`\ngrams, and without that weight the ingredient adds nothing to a recipe.\n\n## Managing saved work\n\nEach write needs the current `version_id` (from `get_recipe`, `get_custom_ingredient` or the last change).\n\n- **Put aside or bring back:** `archive_recipe` and `archive_custom_ingredient` keep the\n  history and can be undone with `unarchive_recipe` and `unarchive_custom_ingredient`.\n  Before archiving an ingredient, `get_ingredient_usage` shows which recipes use it.\n- **Delete:** `delete_recipe` is permanent; `delete_custom_ingredient` works only on a draft\n  that was never confirmed and that no recipe uses; `delete_recipe_serving_size` removes one\n  serving. Ask before any of them.\n- **History:** `list_recipe_versions`, `get_recipe_version_changes` and\n  `get_recipe_audit_trail` (and the custom-ingredient equivalents `list_custom_ingredient_versions`,\n  `get_custom_ingredient_version`, `get_custom_ingredient_version_changes`,\n  `get_custom_ingredient_audit_trail`) answer what changed, who changed it and when.\n  `restore_recipe_version` and `restore_custom_ingredient_version` put the whole item back to\n  that version and drop what was added after it, so show the user the changes and ask first.\n- **Label settings:** `get_nutrition_label_settings` shows which nutrients the label prints;\n  `reset_nutrition_label_settings` removes every custom setting.\n- **Why a number is what it is:** `get_recipe_nutrition_analysis` (which ingredients drive\n  a nutrient), `get_recipe_serving_nutrition_analysis` (rounding and %DV for one serving),\n  `get_recipe_nutrition_facts_per_container` (the whole package), `get_recipe_serving_size`\n  (one serving's detail), `list_ingredients_used_in_recipes` (what the organization uses most).\n\n## Before the user prints\n\n- Say when a gram weight is an estimate (`system_estimate`), and when a number came from\n  your own arithmetic rather than these tools. An estimate the user never confirmed is\n  still an estimate at the moment it reaches a printed label, so name it again there.\n- `completeness.is_complete` false: name the `missing_mandatory` nutrients and say the\n  label must not be used until they are filled in.\n- Read `readiness.findings` and `findings` on the label before exporting. A blocking\n  finding needs a data fix. A stated zero (`review: true`) is the user's to confirm,\n  through `set_nutrition_label_settings` with `acknowledged_fills`. `us.sold_individually_unknown`\n  means asking the user whether the product is sold individually and resending the\n  `racc_guided` size with `sold_individually`. `us.dual_column_not_supported` cannot be\n  resolved here; say so, and do not switch to a manual size to get past it. Offer\n  `acknowledged_findings_hash` only when the user declines to confirm Added Sugars, and say\n  the label will then lack that line. Never confirm or acknowledge for the user.\n- `staleness.is_current` false: the numbers predate the last change to the ingredients or\n  the serving, so they need recomputing first: resend the same serving with\n  `update_recipe_serving_size`, or the ingredients with `set_recipe_ingredients`.\n\n- Repeat any assumption the user has not confirmed (an item left out, an amount read from\n  the table, oil not counted) when you hand over the label.\n\n## Outside these tools\n\nInventing a recipe, cooking advice, substitutions, meal plans, whether a food is healthy,\nnon-US labelling rules, and the cases under \"Step away\" above. The Daily Value tools return reference amounts, not a definition\nof what %DV means.\n"
}