Note recipes

Copy-paste agent instructions that make documentation a byproduct of the work.

Notes get written when your agent has a standing instruction — not when someone remembers to document things. A recipe is that instruction: a short block you paste into your project's agent rules (CLAUDE.md, AGENTS.md, or wherever your agent reads its rules), and a clear picture of what accumulates when the agent follows it.

Every recipe below shares three rules. Keep them even if you rewrite everything else:

  1. Distill at the end of work, while the context is still loaded. A separate "documentation pass" never happens.
  2. Search before you create. notes first — if a note on the topic exists, update_note it. Duplicates rot.
  3. Always link. Connect the note to the issue it came from (issue:<id>) and the code nodes it touches (code:<node>) with link_notes. An unlinked note is a lost note.

There's no setup: paste a recipe and it works. Notes land on your project's note map (created automatically on the first write). Organizing them into multiple maps is a later, optional step — see When one canvas gets crowded below.

Decision log

The highest-value recipe: every resolved issue leaves behind the why, not just a closed ticket.

Paste into your agent rules:

## Alkahest — decision log
When you complete or resolve an issue, distill the outcome into an alkahest note:
- Title the note so the decision reads in one sentence.
- Body: what was decided, the alternatives considered, and why they lost.
- Search existing notes first (notes); if a note on the topic exists, update_note it.
- Link the note to the issue it came from (issue:<id>) and the code nodes it
  touches (code:<node>) via link_notes.

What accumulates — one note per decision:

# Webhooks: one URL per project, no per-event routing

**Decided:** a single outbound webhook per project; every "needs you"
event posts there.

**Why:** Slack and Discord incoming webhooks already fan out by channel,
so per-event routing would double the settings surface for a v1 nobody
asked for.

**Rejected:** per-event-type URLs (config sprawl), email digests (too
slow for "your agent is blocked").

Six months later, "why is there only one webhook field?" is one search away — with the original issue thread linked as evidence.

Session journal

A running log of what your agents actually did, in their own words.

## Alkahest — session journal
At the end of each working session, log it in today's journal note,
titled "Journal — <date>":
- What shipped, what's half-done, and what's blocked (and on what).
- Search notes for today's title first and append; create it only if missing.
- Link the day's entries to the issues you touched.

What accumulates — one note per day, a few lines per session:

# Journal — 2026-07-13

**Shipped:** replaced the text ↗ arrows with SVG icons (iOS rendered
them as emoji); deployed via main.

**Half-done:** note recipes docs page — drafted, needs review.

**Blocked:** nothing.

Read the activity journal for the system-generated version of this; the session journal adds what the event feed can't know — intent and loose ends.

Runbook

Operational knowledge captured while it's being used, not after.

## Alkahest — runbooks
When you perform an operational procedure (deploy, migration, incident
response), capture the exact steps in a runbook note as you go:
- One note per procedure. Update the existing runbook; never write
  "runbook v2".
- Record what you actually ran, including the failures and workarounds.
- Link the runbook to the code nodes it operates on (code:<node>).

What accumulates — living procedures that surface from the map: anyone looking at the deploy-related screens sees the runbook linked right there.

When one canvas gets crowded

Different recipes accumulate at different rhythms — decisions pile up slowly and stay relevant; journal entries arrive daily and age fast. When mixing them on one canvas starts to hurt, split by style:

  1. Create a map per style: alkahest maps create decisions --type note (or have the agent create_map).
  2. Add the map to each recipe: one line like "write it to the decisions note map (add_note with map: decisions)".

One thing to know: once a project has more than one note map, writes must name their map — an unnamed write returns ambiguous_map with the list of candidates, which agents recover from on their own, but naming it in the recipe skips the round-trip.

Each note lives in exactly one notebook, and moving one later is a single verb: map_note over MCP, or alkahest notes map <note> --map decisions from the terminal.

Onboarding trailhead

Not a paste-in recipe — this one is for humans. Once a notebook has real notes, curation is a hub note:

  1. Create a note called Start here (give it its own folder if you like).
  2. List the notes a new teammate should read — the top decisions, the architecture note, the main runbook — as [[wikilinks]] in reading order, with a line of context each.
  3. Share the note's link (⋯ → Copy link). The canvas draws the hub and its spokes automatically — the graph view doubles as the syllabus.

New members get a guided path; you maintain zero duplicate documents — the links live in the text, so the trail updates by editing one note.

Write your own

A recipe is just five decisions — steal the shape:

  • Trigger — when should the agent write? (issue resolved, session end, procedure run)
  • Map — which note map does this style live on? (only matters once you have more than one)
  • Dedup rule — when does it update instead of create?
  • Link rule — what does the note connect to?
  • Title rule — what makes the note findable in a search six months out?

Got a recipe that works for your team? Open an issue on GitHub — we collect good ones.