Field Notes Guide

Field notes are user-submitted learnings that augment these docs. The docs describe how kilter is supposed to work; field notes capture what actually happened in real projects — the gotcha the docs didn't mention, the error message that meant something unexpected, the workaround that unblocked a team. Approved notes appear in Field Notes panels on relevant doc pages and in semantic search, and the best ones get merged into the docs themselves.

What makes a good note

A good field note is something a future reader can act on:

• Concrete. Name the command, the error text, the version. "Auth was broken" helps nobody; "kilter db restore without --include kilter_kratos left logins 500ing until I rolled the Ory pods" helps everyone.
• Reproducible. Say what state you started from and what triggered the problem, so the next person can recognize they're in the same situation.
• Says what actually worked. Include the fix you verified — not the three things you tried first, unless the failed attempts are themselves the lesson.
• Scoped. One learning per note. Two problems means two notes, each of which can be tagged to the right doc page.

A rough shape that works: situation → symptom → what fixed it → why (if you know). Markdown is supported; short is fine — a three-line note with an exact error string beats a page of narrative.

Lifecycle

1. Submit

Two routes in:

• Web form at /notes/new — quickest for a one-off.
• kilter share "description" from a project directory — attaches project context and kilter version automatically. The command posts to the Share API; see Share API for the contract and a curl fallback while the CLI command ships.

You can suggest doc pages your note relates to (suggested_docs), but tagging is ultimately the moderator's call.

2. Moderation queue

Every submission lands in a queue as pending — nothing is published automatically. Admins review at /admin/queue and approve, reject, or hold. Rejection is usually about fit (duplicate, too vague to act on, project-specific with no general lesson), not quality of writing.

3. Approval and tagging

On approval, the admin tags the note to one or more doc pages. From that moment the note:

• appears in the Field Notes panel on each tagged page, alongside the official content, and
• is indexed for semantic search, so it surfaces even for readers who never open the tagged page.

4. Optional: merge into the docs

Notes that repeatedly prove useful — or that plug a real hole in a page — can graduate into the documentation itself. An admin triggers an LLM-assisted merge: the system drafts an edit to the target page incorporating the note, and opens a pull request. A human reviews and lands the PR like any other doc change; nothing is merged into the docs without admin review. The note's status moves to merged.

Statuses at a glance