Note recipes

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.

Prefer it packaged? Install the as-built preset

The recipes below are the DIY path. If you want a complete documentation workflow in one command, install the as-built docs preset:

alkahest docs init

One run sets up four things:

• Two skills on your account — alkahest/as-built-docs (a four-layer documentation convention: system / components / features / modules, with a tone guide and an update checklist) and alkahest/adr (when to write a decision record, and the template). Namespaced so they can never collide with a skill of your own; after install they're yours to edit or rename. Your agent reads them over MCP (skills) whenever it writes docs.
• A docs/ scaffold in the repo (nothing you already have is overwritten).
• A reference sync script that mirrors docs/ into two note maps — as-built and adr — using the docs-folder mirror. The script is yours after install; adapt it freely.
• An agent-rules snippet (opt-in append to your CLAUDE.md) that closes the loop: update docs after each change, then mirror.

The first run in an undocumented repo is the point: tell your agent "start documenting" and the skill's bootstrap protocol has it write a small first pass — one system map, two or three core modules, and ADR-001 as an architecture snapshot — then mirror and hand you the map link. From there, the standing rules keep it alive.

Everything the preset does rides the same public commands on this page — it installs a starting point, not a requirement. Skip it and write your own recipes below; you lose nothing.

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.

Capture now, write later

The recipes above fire while your agent is working. This one covers the other direction: a thought that arrives when no agent is running — on your phone, mid-conversation, halfway through something else — and shouldn't have to wait for you to open an editor.

A task can carry the intent to become a note. Set its note mode and the task stops being a to-do and becomes a standing instruction:

Mode	Means
(off)	An ordinary task. The default.
Keep	File this as-is — tidy it up and merge it, don't go looking for more.
Enrich	Research this first, then write it up. For a half-formed thought worth more than it says.

You can also name the target note. Naming one implies keep — choosing a destination is already the intent. Leave it on auto and the agent picks: an existing note on the topic if there is one, a new note if not.

Where you set it:

• On the web — the task detail's Note chip (next to Project / Due / Tags). Dotted means off; solid shows the target, and enrich wears a ✦.
• Over MCP — add_task / update_task take note_mode and note.
• From your phone — a capture shortcut can send note_mode in its body, so one home-screen icon files to-dos and a second files things to look into.

Nothing runs on its own

Alkahest stores the intent; it does not merge anything. An agent does the writing, next time one is working — which means it needs the standing instruction below. That's the honest shape of it: no scheduler, no background job, no queue that quietly drains.

## Alkahest — process note-mode tasks
At the start of a session, check list_tasks for open tasks with a note_mode.
For each one:
- Read its thread first (task_comments) — the source material usually lives there.
- keep: distill what's there. enrich: research it (web, code) first, then write.
- Target: the task's note if it names one; otherwise `search` for an existing note on
  the topic and update_note it. Only create when nothing fits.
- If the task names a skill, read it (skills) and follow it when writing.
- Report what you did with reply_task, then complete_task.
- Stuck — two plausible targets, or the note contradicts what you captured? ask_task
  and stop. Don't guess a merge.

The last rule is the one worth keeping. A wrong merge is expensive to find later; ask_task puts the question in your "waiting on you" list and the task stays open.

Reviewing what it wrote

Every merge is a note revision, so the note's ⋯ → History shows the diff — what the agent added, in your own note, before you trust it. Nothing else in this loop needs supervising: the task stays open until the merge lands, so an unprocessed capture is visible as an unfinished task rather than lost.

Writing style

Which conventions the agent follows when it writes is a skill — a named block of writing instructions on your account, managed at My skills. A task can name one (skill on add_task), and starring a skill there makes it the default for note-mode processing, so the recipe above doesn't have to repeat your house style. alkahest docs init installs two ready-made ones (see above).

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.