# Ferment — for AI agents

Ferment is a shared, agent-writable memory for cooking and eating: stacks
(recipes / ingredients / chapters / tastings) connected by edges, exposed as a
REST API and an MCP server. You can onboard a user and read/write their memory
with no browser and no prior setup.

## Decision procedure (follow this for ANY Ferment request)

You resolve auth state yourself; only a returning user's browser sign-in needs
a human.

1. HAVE A KEY?  A key looks like `ferm_…` (check your MCP config / saved
   secrets / this chat). Verify it:
       curl https://ferment.kitchen/api/v1/me -H "X-API-Key: ferm_…"
   200 → go to step 3.  401/none → step 2.

2. GET A KEY.  Ask the user: "Do you already have a Ferment account?"
   - No / new / unsure → ONBOARD (no human action):
         curl https://ferment.kitchen/onboard          # returns a ferm_ key inline
     (temporary 24h account; user claims it later at https://ferment.kitchen/auth)
   - Yes / existing → PAIR (one browser click):
         curl -X POST https://ferment.kitchen/api/v1/pair
     Give the user the userCode + verifyUrl; poll
         curl https://ferment.kitchen/api/v1/pair/<token>
     until status=claimed, then take apiKey.
   Persist the key in your MCP config so future requests skip this step.

3. DO THE TASK (send X-API-Key: ferm_… on every call; MCP or REST):
   - "onboard me" → done; confirm cookbook at https://ferment.kitchen/<storeSlug>
   - "record that I went to <place>" / "I had <dish>" → create_recipe with
     status="tasted" (notes in description); optionally create_chapter for the
     place and add_edge the recipe into it.
   - "save/build a recipe" → create_recipe + add_step + attach_ingredient +
     attach_image.

## Surfaces

MCP server (recommended): https://ferment.kitchen/api/v1/mcp  (header X-API-Key: ferm_…)
  tools: create_recipe, create_chapter, add_step, attach_ingredient,
         attach_image, add_edge, search_stacks, fork, create_invite,
         list_my_stacks, list_shared_with_me, get_feed, ...
REST: every tool has a twin under https://ferment.kitchen/api/v1/*

Full reference: https://ferment.kitchen/docs/agent.md
No shell / can't run commands? A human can sign up at https://ferment.kitchen/auth