docs: scaffold agent-friendly entry points (Phase 1)

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>

2026-05-10 15:44:45 +02:00

2.3 KiB

Raw Blame History

data/

What's here

Out-of-bundle data assets consumed by one or more bundles. Each subdir maps to a consumer:

data/
├── apt/keys/                   # binary GPG keys for apt sources
├── grafana/rows/               # Mako-templated dashboard panels (Python)
├── nginx/                      # nginx snippets shared across vhosts
├── homeassistant/, mailman/, nextcloud/, ...
└── network.py                  # repo-wide network metadata (one-off file)

Two distinct content models

Same directory shape, different content kinds. When you add a new data/<x>/ subdir, declare which model it follows:

Model	Example	Consumer
Binary / static	`data/apt/keys/*.{asc,gpg}`	`bundles/apt` reads files at apply time
Python module / template	`data/grafana/rows/.py`, `data/routeros-monitoring/.py`	bundle `import`s and renders

If a data asset is read by exactly one bundle, prefer bundles/<x>/files/ instead of data/<x>/. data/ is for shared / multi-consumer artifacts. Single-instance evidence: commit 78a8abc moved mikrotik.mib out of data/ into the bundle for this reason.

Conventions

One subdir per consumer. Subdir name = consumer bundle name (data/apt/, data/nextcloud/).
network.py exception. A single file at data/network.py holds repo-wide network metadata; it doesn't belong to one bundle. Treat it as cross-cutting infrastructure metadata.

How to add data

Decide the content model (binary or Python).
mkdir data/<consumer>/.
Drop assets in.
The consumer bundle (bundles/<consumer>/items.py or metadata.py) reads them via repo.path + os.path.join or similar.

Pitfalls

Apt keys trigger an offline-verify rule before they're committed. See commands.md#apt-key-changes-need-offline-verification.
Mako-templated Python data evaluates at bundle render time. Side effects in those modules slow the whole repo (same caveat as libs/).

2.3 KiB Raw Blame History