From 26bcb872e16e05777bc09fb138ca620df39de953 Mon Sep 17 00:00:00 2001 From: Joakim Persson Date: Wed, 20 May 2026 23:12:07 +0200 Subject: [PATCH] AGENTS.md: documentation-drift sweep as explicit pre-commit step Companion to the same addition in the cloud-init and ansible repos. Caught real drift in those repos in a recent session only because the user explicitly asked. Codify the sweep with concrete, repo- specific drift hotspots rather than a vague 'watch for drift' rule that gets ignored. Each AGENTS.md addition lists the doc files most likely to fall behind code changes here, plus a quick-triage one-liner using 'git diff --name-only HEAD | xargs grep -l ...' so the rule is actionable not aspirational. --- AGENTS.md | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index 7be5c88..b60cca0 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -195,3 +195,14 @@ future pi-option: a container built with mempalace off should still be able to install a functional pi, and that dependency asymmetry is cleanest when pi's own config lives in its own repo. Mirrors the 2026-05-05 split of `opencode-toolkit` out of the same parent. + +## Documentation drift sweep + +Before committing any non-trivial change, check that prose still matches code. Drift hotspots in this repo: + +- `README.md` — install instructions, the file/artifact table, the testing recipe. The installer's behaviour and the README's description of it must stay in lockstep — the README is what users follow. +- `AGENTS.md` (this file) — the `Conventions` section codifies symlink-vs-cp-vs-template decisions per artifact; if you change how an artifact is installed, update the conventions too. +- `install.sh` — contains its own usage block at the top; keep the `--help` output and the README in sync. +- `settings.example.json` — the canonical template for pi settings; if pi adds a new top-level setting that this toolkit blesses with defaults, update the example here. + +Quick triage: `git diff --name-only HEAD | xargs -I{} grep -l 'thing-you-changed' README.md AGENTS.md install.sh`.