From 9e1bb2ac45e4ffed7d5b9f05ce686666122f7731 Mon Sep 17 00:00:00 2001 From: CroneKorkN Date: Sun, 10 May 2026 16:02:24 +0200 Subject: [PATCH] docs: per-bundle docs are README.md, not AGENTS.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit drops the per-bundle AGENTS.md convention and the rigid template that went with it. each bundle has (or gets) one README.md that serves humans and agents both. bundles/AGENTS.md now has a "Per-bundle README" section pointing at the more substantial existing READMEs (flask, dm-crypt, apt, nextcloud) for orientation, plus loose guidance on what to cover and what to skip. no required structure — match the bundle's actual surface. removes bundles/AGENTS.template.md; the template was prescriptive in a way that wouldn't survive contact with this repo's actual bundles, where READMEs range from one-paragraph balanced docs to operational scratchpads. phase-2 seed-bundle work stays deferred and will land as plain README updates when bundles are materially edited. Co-Authored-By: Claude Opus 4.7 (1M context) --- bundles/AGENTS.md | 78 +++++++++++++++++++++++++++----------- bundles/AGENTS.template.md | 61 ----------------------------- 2 files changed, 55 insertions(+), 84 deletions(-) delete mode 100644 bundles/AGENTS.template.md diff --git a/bundles/AGENTS.md b/bundles/AGENTS.md index c4d0b73..40ff949 100644 --- a/bundles/AGENTS.md +++ b/bundles/AGENTS.md @@ -22,8 +22,7 @@ bundles// ├── items.py # the items this bundle creates (files, services, packages, …) ├── metadata.py # `defaults` + `@metadata_reactor` functions ├── files/ # static or templated file payloads referenced from items.py -├── AGENTS.md # this bundle's doc (template at AGENTS.template.md) -└── README.md # legacy; being phased out (see "Documentation transition" below) +└── README.md # one doc per bundle, for humans and agents (see "Per-bundle README" below) ``` ## Conventions @@ -63,10 +62,8 @@ bundles// - `bw hash ` — confirm the change is what you expected. See [`docs/agents/commands.md`](../docs/agents/commands.md) and the fork's hash-diff workflow. -6. Create `bundles//AGENTS.md` from - [`AGENTS.template.md`](AGENTS.template.md). For a brand-new bundle - without consumers yet, leave `Depends on` and `Produces` empty or - marked TBD; fill them in after the first verify run. +6. Add a `bundles//README.md`. See "Per-bundle README" below + for what to cover. ## How to remove a bundle @@ -88,31 +85,66 @@ bundles// - **Reactors writing across namespaces.** Some bundles' reactors write into other bundles' metadata namespaces (e.g. `nextcloud` writes into `apt.packages`, `archive.paths`). When you change such a bundle, - every consumer's metadata changes too. Per-bundle docs declare these - in an optional `## Writes into` section — read it before assuming the - blast radius is local. + every consumer's metadata changes too. The bundle's `README.md` + often calls these out — but the authoritative source is `metadata.py` + itself; grep `'':` in the reactors when in doubt. - **`bw hash` doesn't accept selectors.** Use `bw hash ` per literal name; see the fork's runbook. -## Documentation transition +## Per-bundle README -This repo is migrating from bundle `README.md` files to per-bundle -`AGENTS.md` files (one balanced doc per bundle, agents + humans). +Each bundle has (or should have) a `README.md`. One doc per bundle, +written for humans and agents both. There's no fixed structure — +match the bundle's actual surface, write what helps a future reader +(or future you) avoid trial-and-error. -- Where both exist, **`AGENTS.md` is canonical**; the `README.md` is - being phased out. -- ~28 bundle READMEs survive after the seed migration (the seed PR - folds in 5–10 of them; the rest are addressed lazily on the next - material edit — Phase 3 leave-as-you-go). -- Phase-3 rule: any time you (or any agent) materially edits a bundle, - top-up its `AGENTS.md` or create one from - [`AGENTS.template.md`](AGENTS.template.md). If a stale `README.md` - is still around in the bundle, fold it in and remove it in the same - commit. +The existing READMEs vary in quality and shape. For orientation, +look at the bigger ones, not the two-line ones: + +- [`bundles/flask/README.md`](flask/README.md) — title + one-sentence + purpose, a metadata example as a Python dict, then the contract + the consuming git repo has to satisfy + a logging pitfall. The + closest thing to a "balanced doc" in tree. +- [`bundles/dm-crypt/README.md`](dm-crypt/README.md) — same shape, + shorter: purpose + metadata example + one sentence on effect. +- [`bundles/apt/README.md`](apt/README.md) — relevant upstream URLs + at the top, then a Python metadata example with rich inline + comments (type / optionality / where keys come from). +- [`bundles/nextcloud/README.md`](nextcloud/README.md) — operational + scratchpad: iPhone-import recipe, preview-generator commands, + reset queries. Captures muscle-memory the maintainer would + otherwise re-learn each time. + +Useful things to include, when relevant: + +- A sentence or two on what the bundle does and when you'd attach it. +- A metadata example as a Python dict literal, with `#` comments + on each key (type, required vs default, units, where it comes + from). This is the cleanest way to communicate the schema and + matches how `metadata.py` actually looks. +- Anything non-obvious about wiring it up — required keys without + defaults, group-membership expectations, manual one-time steps. +- Cross-namespace metadata writes, when this bundle's reactors + populate another bundle's namespace. Easy to miss, cheap to flag. +- Gotchas, debug recipes, failure modes you've actually hit. + +What to skip: + +- An exhaustive item list — `items.py` is shorter and more accurate. +- Anything that would just rot — version numbers, "TODO" lists, + change notes. Use git history. + +If a single paragraph is enough to say what's worth saying, write a +single paragraph. Verbosity isn't a goal. + +Convention going forward is leave-as-you-go: any time you materially +edit a bundle, top up its README (or write one if it's missing). +Don't burn a session bulk-reformatting the existing ones — uneven +quality is part of what we accept in exchange for not blocking other +work. ## See also -- [`AGENTS.template.md`](AGENTS.template.md) — per-bundle doc template. - [`docs/agents/conventions.md`](../docs/agents/conventions.md) — repo idioms (vault, demagify, naming, do-not-touch list). - [`docs/agents/commands.md`](../docs/agents/commands.md) — repo-specific diff --git a/bundles/AGENTS.template.md b/bundles/AGENTS.template.md deleted file mode 100644 index 79cc611..0000000 --- a/bundles/AGENTS.template.md +++ /dev/null @@ -1,61 +0,0 @@ -# - - - -<1–3 sentences: what this bundle does and when you'd use it.> - -## Usage - - - -## Metadata - -Keys read from `node.metadata`: - -```python -{ - '': { - 'key': 'value', # str, required — short note - 'flag': True, # bool, default True - 'list': [], # list[str], default [] — short note - 'nested': { - 'subkey': 0, # int, default 0 - }, - }, -} -``` - -## Produces - - - -## Depends on - - - -## Writes into - - - -## Gotchas - -