handbooks/README.md

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.

Ingesting a handbook

Markdown needs no conversion and no extraction verifier — admit it straight from this repo:

index.py admit ~/dev/handbooks/git-operations.md --corpus engineering \
  --vouch mikkeli --title 'Git operations' --collection dev-practice \
  --version "$(git -C ~/dev/handbooks rev-parse --short HEAD)"

Without --title the document is titled by its filename, which is what a retrieval hit then shows. --collection is a flat cluster tag; getting it wrong costs recall and nothing else.

⚠ --version is this repo's commit, and it is the one that matters. Re-admitting replaces a document outright with no version history, so the pin is the only record of which revision a chunk reflects.

⚠ Editing a file here does not update the corpus. Re-admission is deliberate, because the vouch is a claim about a specific version of a document.

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.