CroneKorkN
04558a9189
introduces a balanced set of agent + human docs: - root AGENTS.md (with CLAUDE.md symlink) — 5-rule quickstart, layout map, mental model, use-case keyed example pointers. - docs/agents/conventions.md — vault/demagify, eval-loader constraints, group inheritance, naming, do-not-touch list, suspension idioms, working-style notes. - docs/agents/commands.md — repo-specific deltas to the fork's bw runbook (apt-key offline-verify, *.py_ suspended-node visibility, vault-echo rule). - per-area AGENTS.md for bundles/, nodes/, groups/, libs/, hooks/, data/, items/, bin/ — mechanism-focused, no enumeration. - bundles/AGENTS.template.md — per-bundle doc template with optional `## Writes into` section for cross-namespace reactors. bundlewrap-language reference (item types, dep keywords, reactors, runbook, three-tier safety envelope) is not duplicated here; we link out to the fork's AGENTS.md instead. bw test still green. all internal links resolve. Phase 0 invariants preserved (libs/hooks docstrings, bin/* # purpose: headers). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
61 lines
1.7 KiB
Markdown
61 lines
1.7 KiB
Markdown
# <bundle-name>
|
||
|
||
<!--
|
||
Per-bundle doc template. Copy to `bundles/<name>/AGENTS.md` and fill in.
|
||
|
||
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.
|
||
|
||
Skip the `## Gotchas` section if there are no real gotchas — empty
|
||
"Gotchas: none" sections are noise.
|
||
|
||
Skip the `## Writes into` section unless this bundle's `defaults` or
|
||
reactors write into other bundles' metadata namespaces. Most don't.
|
||
-->
|
||
|
||
<1–3 sentences: what this bundle does and when you'd use it.>
|
||
|
||
## Usage
|
||
|
||
<How to apply: which group(s) typically include it, or how a node opts
|
||
in. Minimal example of node metadata if any keys are required.>
|
||
|
||
## Metadata
|
||
|
||
Keys read from `node.metadata`:
|
||
|
||
```python
|
||
{
|
||
'<bundle>': {
|
||
'key': 'value', # str, required — short note
|
||
'flag': True, # bool, default True
|
||
'list': [], # list[str], default [] — short note
|
||
'nested': {
|
||
'subkey': 0, # int, default 0
|
||
},
|
||
},
|
||
}
|
||
```
|
||
|
||
## Produces
|
||
|
||
<Items created: files, services, packages, users, etc. One line each.
|
||
Skip if trivially obvious from items.py.>
|
||
|
||
## Depends on
|
||
|
||
<Other bundles required, or "none". Note ordering quirks if any.>
|
||
|
||
## Writes into
|
||
|
||
<!-- Optional. Most bundles don't write cross-namespace; skip the
|
||
section if this bundle doesn't either. List the foreign metadata
|
||
namespaces this bundle's `defaults` or reactors populate (e.g.
|
||
`apt.packages`, `archive.paths`). Cross-namespace writes are the
|
||
single most surprising blast-radius source in this repo — call them
|
||
out explicitly. -->
|
||
|
||
## Gotchas
|
||
|
||
<Non-obvious behavior, manual one-time steps, known pitfalls. Omit
|
||
the section if there are none.>
|