The one call to make when the user says 'run agent chef' (or run the app / plan dinner / do the weekly thing). Returns the operating manual plus the checklist of tool calls that are due right now. Execute them in order, then call next_actions again until it returns no actions. Stop before any checkout.

Call after creating (or changing) the recurring 'Run Agent Chef.' task in your own scheduler, with a one-line description, e.g. 'Claude scheduled task, daily 9:00 and 18:00 America/Los_Angeles'. Lets the app stop reminding you and shows the owner that the loop is automated.

Hides the 'Get set up' card on the household dashboard (e.g. when the owner says they don't need it). Pass show=true to bring it back.

Agents connected to this household via OAuth sign-in (Claude, ChatGPT…), with when they connected and last used. API keys are separate.

Revoke an OAuth-connected agent's access (client_id from get_connected_agents). It must sign in again to reconnect.

START HERE. Returns the current phase and an ordered checklist of tool calls that are due right now (propose, send ballot, remind non-voters, add options for feedback, lock in, shop), with why and the arguments/message text to use. Execute them, then call again until empty. Idempotent and time-aware; safe to call on a schedule.

The full operating manual for agents: the run loop, phases, how to write recipes, messaging and safety rules. Read once per session.

Household name, recipe preferences prompt (diet, allergies, dislikes, cuisines, time budget), shopping preferences prompt (brands, organic, store quirks) plus settings: plan_day, servings, grocery_store, recipes_per_week, votes_per_member.

Update any subset of the preferences prompt and settings. Omitted fields are unchanged.

List household members with contact info and their personal vote links.

Add a household member or update phone/email. Name is the key (case-insensitive).

Remove a household member by name (their votes and ratings stay attached to past weeks). The owner can't be removed.

Pantry/fridge/spice inventory the household already has. Used to trim the shopping list.

Add/refresh items (upsert by name), remove items, or replace the whole inventory.

Recipes marked as household favorites, with ratings. Good candidates to re-propose by recipe_id.

Mark (or unmark) a recipe as a household favorite.

Full details for one recipe: ingredients, steps, servings, source, tags, ratings, comments, how often it's been cooked, and a link to its page.

Every recipe the household has ever had proposed, with ratings and cook counts. Filter by text, favorites, or tag. Use recipe_id from here with propose_recipes to re-propose.

Edit a stored recipe: fix an ingredient, add steps, change servings, tags, image or source. Only provided fields change.

Fetch a recipe page (most cooking sites) and save it to the library with its real photo, ingredients, and steps. Returns the recipe; pass its recipe_id to propose_recipes or add_candidates to put it on a ballot.

Every recipe selected for a past week, newest first, with week, status, and ratings/comments. Use to avoid repeats and learn what landed.

Where the cycle stands: latest week + status (voting/selected/ordered/done), candidates with tallies, who has/hasn't voted, selected recipes, pending_feedback. Call this first.

Start a weekly cycle: store the candidate recipes (normally 10) and return numbered candidates, a ballot_text (with a {vote_link} placeholder for message_group), and each member's vote link. Re-calling for the same week_start replaces the candidates.

Append extra recipes to the current voting ballot (positions continue after the existing ones; votes are kept; 15 max). Use in response to ballot_feedback from get_current_week; open feedback is marked addressed. Follow up with message_group so voters know new options are up.

Record a member's comment about the current ballot (optionally about one candidate), e.g. relayed from a text message. Members can also do this themselves on their vote page.

Send SMS/MMS or email to household members. '{vote_link}' in the message becomes each member's personal voting link. Channel 'auto' texts members with a phone and emails the rest. Providers now: {"sms":"dry-run","email":"dry-run"} (dry-run = logged only).

Record one member's votes for the current week (replaces their earlier votes). Accepts recipe_ids or ballot positions. Unknown member names are created.

Historical ballots: per week, every candidate with vote count, voters, and whether it was selected.

Lock in the winners. With no recipe_ids, picks the top N (recipes_per_week) by votes, ties broken by ballot order. Moves the week to 'selected' and returns the shopping list.

Undo set_this_weeks_recipes: clears the winners and returns the week to 'voting'. Existing votes are kept. Use if winners were locked in too early.

One-off override of when the current ballot closes: an ISO timestamp, or extend_hours from the current deadline. Normally the deadline comes from the household schedule (vote_close_day/time); changing those via update_recipe_preferences re-syncs the current week.

Record post-cook feedback (1-5 + comment) for a member. When every selected recipe of that week has feedback the week becomes 'done'.

Shopping list for the selected recipes minus ingredients on hand, grouped by item with quantities and which recipe needs it, plus the preferred store. Drive the browser to fill the cart; stop before checkout for approval; then call record_grocery_order.

Log the placed order and (by default) add purchased items to ingredients on hand. Moves the week to 'ordered'.