# Handbooks Instance-agnostic reference material for coding agents, in two shapes: long-form **handbooks** meant for a retrieval store, and short **redirect-skills** meant to be deployed into an agent's own skill directory. Both are authored and version-controlled here; neither is consumed directly *from* here — a handbook isn't live until admitted to a KB, a skill isn't live until deployed to wherever it actually runs. ## What goes here - **Handbooks: 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; nothing here is loaded into a model's context wholesale, so length carries no per-turn tax. - **Redirect-skills: short, prescriptive, and specifically pointer-shaped** — their entire job is telling an agent to verify against a live or handbook source rather than trust its own recall, for domains that churn too fast for a stored answer to stay correct (`gdext-verify-live-docs` is the first: gdext is pre-1.0, so the skill points at `docs.rs/gdext` and the `godot-rust` book instead of encoding any API surface as text). **Not** a home for full procedural skills that encode real workflow knowledge of their own (a debugging methodology, a review checklist) — those still belong wherever they're consumed, authored there directly. ## 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](https://git.novoyuuparosk.org/mikkeli/halogen-workstation-roadmap)). - **Full procedural skills that aren't redirect-shaped.** Genuine workflow knowledge — a debugging methodology, a review checklist, anything that *is* the content rather than pointing at it — still belongs where it's consumed: the shared, git-tracked `skills/` at halogen-workstation-roadmap's root (OpenCode, Codex, Claude Code, via `--link`), or authored directly by an agent into its own runtime skill directory (hermes' per-profile home isn't git-tracked at all). - **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. - **The deployed copy of a skill.** This repo holds the authored source; the running copy lives wherever the consuming agent actually reads skills from, deployed by copy (never symlink — an agent may write back to its own skill files, which a symlink would corrupt at the source). Deployment tooling lives with the consumer, not here. ## Format **Handbooks:** one markdown file per topic under `handbooks/`. Each file should stand as a single admittable document — the same shape a human vouches for at KB admission time. (Redirect-skills live under `skills/` instead, with their own format — see below.) 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`): ```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: ```bash F=~/dev/handbooks/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. ## Redirect-skills Live under `skills//SKILL.md` — the same `skills//SKILL.md` shape every consuming agent already expects, so a skill here copies straight across with no reshaping. Frontmatter is `name` + `description` (the Agent Skills standard, not this repo's `title`/`collections`): `description` is what a consuming agent's own trigger-matching reads to decide relevance, so it needs to name the concrete situation the skill applies to, not just summarize the body. A redirect-skill's body should contain no cacheable domain knowledge — only what to check, where, and under what condition to suspect staleness over a code error. If a skill here starts accumulating API details "for next time," that's the sign it's stopped being a redirect and started being the exact stale cache it exists to avoid. **Deploying one is out of scope for this repo** — copy the file into wherever the consuming agent reads skills from, never symlink (an agent may write back to its own skill files over time, which a symlink would corrupt at the vendor source). The deployment tooling itself lives with the consumer. ## 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. Scope widened 2026-08-22, superseding the same-day note above: this repo now also houses **redirect-skills** (`skills//SKILL.md`) — short, pointer-shaped skills whose job is verifying against a live or handbook source rather than caching an answer that would go stale. First one: `gdext-verify-live-docs`, for `gdext` (Rust bindings for Godot 4, pre-1.0, no existing skill or MCP tool anywhere). Full procedural skills — genuine workflow knowledge, not a pointer — still don't belong here; they're authored where they're consumed, same as before. Handbooks moved from the repo root into `handbooks/` the same day, for symmetry with `skills/` — each content shape gets its own directory rather than handbooks implicitly owning the root.