Handbooks

Instance-agnostic reference material for coding agents — the verbose, citable kind that belongs in a retrieval store, not in a skill.

What goes here

• Public standards, style guides, and conventions that apply regardless of which box or project is running — general git operations, language style guides, CERT/MISRA-style rulebooks.
• Long-form and specific. A handbook can be as detailed as it needs to be; nothing here is loaded into a model's context wholesale, so length carries no per-turn tax.

What does not go here

• Anything specific to one machine or one project. A local Gitea's branch-naming rule, this box's PR checklist — that's instance-bound and belongs in that project's own KB corpus instead (the engineering corpus, for halogen).
• Short, prescriptive procedures achievable within a context window or two. That's a skill, not a handbook — it gets loaded, not retrieved. See skills/ in the halogen-workstation-roadmap repo for the sibling convention.
• The retrieval store itself. This repo holds the source-of-truth markdown a human has vouched for. The chunked, embedded index built from it is derived and rebuildable state — it lives beside whichever KB is consuming it, never committed here.

Format

One markdown file per topic at the repo root. Each file should stand as a single admittable document — the same shape a human vouches for at KB admission time.

Each file opens with a small flat YAML frontmatter block — title and collections only, no nested structure, so it stays greppable without a YAML dependency (same reasoning index.py itself gives for hand-parsing corpora.yaml):

---
title: Git operations
collections: [handbooks, dev-practice]
---

title and collections are the two ingest-time values that are actually about the document, so they live with it instead of being retyped by hand at admission time — that's what let --collection dev-practice and an actual admission of handbooks drift apart on 2026-08-22, silently, until it was noticed by inspection rather than by anything catching it.

version is deliberately not a frontmatter field — a file can't contain the hash of the commit that writes it, the same self-reference problem any __COMMIT__ build stamp runs into. It stays a value computed at admission time, same as before, just scoped to the file rather than the whole repo.

Ingesting a handbook

Markdown needs no conversion and no extraction verifier — admit it straight from this repo, reading title/collections from the frontmatter instead of retyping them:

F=~/dev/handbooks/git-operations.md
TITLE=$(sed -n '/^---$/,/^---$/{/^title:/s/^title:[[:space:]]*//p}' "$F")
COLLECTIONS=$(sed -n '/^---$/,/^---$/{/^collections:/s/^collections:[[:space:]]*//p}' "$F" \
  | tr -d '[]' | tr ',' '\n' | sed 's/^ *//;s/ *$//')
VERSION=$(git -C ~/dev/handbooks log -1 --format=%h -- "$F")

index.py admit "$F" --corpus engineering --vouch mikkeli \
  --title "$TITLE" --version "$VERSION" \
  $(for c in $COLLECTIONS; do printf -- '--collection %s ' "$c"; done)

⚠ --version is the last commit that touched this file, not the repo's HEAD. A whole-repo HEAD pin would bump every handbook's recorded version on any unrelated edit, even one that never touched this document — the per-file form is what actually answers "which revision does this chunk reflect."

⚠ Re-admitting replaces a document outright, with no version history kept. The --version pin is the only record of which revision a chunk reflects, which is also why editing a file here does not by itself update the corpus — re-admission is deliberate, a fresh claim about a specific version of a document, not something that should happen automatically on every commit.

Status

Started 2026-08-21. First handbook, git-operations.md, composed 2026-08-21 – 2026-08-22: branching, committing, merging vs. rebasing, reverting and undoing, remotes and collaboration, tags and releases. Confirmed ingestible 2026-08-22 — 30 chunks, heading paths intact, retrieved correctly.

Second handbook, failure-handling.md, composed 2026-08-22: input contract discipline, failure- propagation discipline. Environment/verification parity was scoped out of it deliberately — a different axis (how confidence is established, not how code behaves), queued as a handbook of its own rather than folded in.

Frontmatter (title, collections) added to both 2026-08-22, after --collection dev-practice in this file's own recipe was found to have drifted from handbooks, the value actually used at admission — the two ingest-time values that describe the document now live with it instead of being retyped by hand.