---
name: kitchen-companion
description: >-
  Scan fridge photos, track the pantry with expiry alerts, clip recipes,
  and plan meals. Use when the user shares a photo of their fridge or
  groceries, asks what they can cook, mentions buying or finishing food,
  shares a recipe link, asks what's expiring, or wants a meal plan or
  grocery list.
metadata:
  emoji: "🍳"
  vellum:
    display-name: "Kitchen Companion"
    activation-hints:
      - "User shares a photo of a fridge, pantry, or groceries"
      - "User asks what they can cook or make right now"
      - "User shares a recipe URL or asks to save a recipe"
      - "User mentions buying groceries or running out of food"
      - "User asks for a meal plan or grocery list"
      - "User asks what food they have or what's expiring"
---

# Kitchen Companion

Turn photos of food into a live pantry inventory, keep recipes organized,
and answer the eternal question: "what can I actually make right now?"

## The tools

| Tool | Job |
| --- | --- |
| `fridge_scan` | Photo of fridge/pantry/groceries in, identified items + 3 makeable-now recipes out. Stocks the pantry by default. |
| `pantry_update` | Add, use, or remove pantry items manually. Batch-friendly. |
| `pantry_list` | Inventory view, soonest-expiring first. Filters: location, expiry window, name. |
| `recipe_save` | Clip a recipe from a URL or raw text into a normalized saved format. |
| `recipe_find` | Search saved recipes, optionally ranked by pantry coverage (`makeable_now`). |
| `meal_plan` | Multi-day plan from pantry + saved recipes, expiring food first, plus a grocery list. |

## Core flows

### Photo of a fridge, groceries, or pantry shelf

1. Find the photo path (conversation attachments live under
   `/workspace/conversations/<conversation-id>/attachments/`).
2. Call `fridge_scan` with `photo_path`. Pass `location` when the user says
   where it is (grocery haul headed for the freezer, etc.), and put dietary
   constraints, cravings, or headcount into `context`.
3. Present the items found, then the 3 recipe ideas. Lead with the idea that
   uses the most perishable items.
4. The scan stocks the pantry automatically. If the user says "don't track
   this", pass `add_to_pantry: false`.

### "What can I make?" without a photo

1. Call `recipe_find` with `makeable_now: true` (add their craving as
   `query`). This ranks saved recipes by pantry coverage.
2. If nothing is saved or nothing matches, call `pantry_list` and improvise
   suggestions from what's in stock, prioritizing anything expiring.

### The user mentions food coming in or going out

- Bought groceries, someone gave them food: `pantry_update` action `add`.
  Estimate realistic expiry dates when the user does not say (fresh greens a
  few days, raw meat 2-3 days, frozen months, condiments long).
- Cooked with, ate, or finished something: `pantry_update` action `use`.
- Threw something out: `pantry_update` action `remove`.
- Keep this lightweight. Update in the background of the conversation, no
  ceremony, then get back to what the user was talking about.

### Recipe links and pasted recipes

1. Call `recipe_save` with the `url` (or `text` for pasted/dictated
   recipes). Attach the user's commentary as `notes`.
2. Confirm with the title and where it landed. Do not recite the whole
   recipe back unless asked.

### Meal planning and grocery runs

1. Call `meal_plan` with `days`, `meals_per_day`, and everything the user
   said as `preferences` (diet, people, time, cravings).
2. Present the plan by day, then the grocery list. Point out which expiring
   items the plan rescues.
3. After they shop, offer to `pantry_update` add the grocery list.

## Expiring food alerts

When items are close to expiry, a `[Kitchen Companion]` context block lists
them. Weave a heads-up into a food-related conversation naturally ("your
spinach has about a day left, want a use-it-up dinner?"). At most once per
conversation, never as a nag, and skip it entirely when the conversation
has nothing to do with food.

## Tone

Practical and quick. The user is usually standing in a kitchen deciding
what to do. Lead with the answer (the recipe, the list, the plan), keep
commentary short, and never lecture about nutrition or food waste.