From 0ede23fdfef878489a1ae675cd6f2e9d039321a3 Mon Sep 17 00:00:00 2001
From: Mikkeli <mikkeli@novoyuuparosk.org>
Date: Fri, 21 Aug 2026 22:05:06 +0900
Subject: [PATCH] Scaffold the handbooks repo: scope, format convention,
 git-operations outline
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Sibling store to halogen-workstation-roadmap's skills/ — instance-agnostic
reference material meant for KB admission, not for loading into context.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01YKviBjJejufEUmryJ42tLT
---
 README.md         | 32 ++++++++++++++++++++++++++++++++
 git-operations.md | 34 ++++++++++++++++++++++++++++++++++
 2 files changed, 66 insertions(+)
 create mode 100644 README.md
 create mode 100644 git-operations.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..f062296
--- /dev/null
+++ b/README.md
@@ -0,0 +1,32 @@
+# 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
+  (`kb-engineering` for [halogen](https://pi5-16.local/mikkeli/halogen-workstation-roadmap)).
+- **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.
+
+## Status
+
+Started 2026-08-21. First handbook: general git operations.
diff --git a/git-operations.md b/git-operations.md
new file mode 100644
index 0000000..c250a6a
--- /dev/null
+++ b/git-operations.md
@@ -0,0 +1,34 @@
+# Git operations
+
+> Draft outline — 2026-08-21. General practice, not tied to any one project's Gitea/GitHub setup.
+
+## Scope
+
+General git operations a coding agent should get right without being told each time: branching,
+committing, merging vs. rebasing, and how to recover from the common ways each goes wrong. Anything
+specific to one project's hosting setup (branch protection, PR template, CI triggers) belongs in
+that project's own KB corpus instead — see this repo's README.
+
+## Outline
+
+- Branching
+  - naming conventions and when a new branch is warranted vs. not
+  - long-lived vs. short-lived branches
+- Committing
+  - what makes a commit atomic; when to split or squash
+  - message conventions and what a good message actually needs to say
+- Merging vs. rebasing
+  - when each is appropriate, and the history each produces
+  - conflict resolution — reading a conflict marker correctly, not guessing
+- Reverting and undoing
+  - revert vs. reset vs. checkout — what each does to shared history
+  - recovering from a bad rebase or reset (reflog)
+- Remotes and collaboration
+  - fetch vs. pull, and why the distinction matters under contention
+  - force-push: when it's ever appropriate, and how to do it without destroying someone else's work
+- Tags and releases
+  - lightweight vs. annotated tags
+  - what a tag should mean once it's pushed
+
+*(Fill in as it's composed. Each section should end up citable on its own — a chunk boundary, not
+just a heading.)*