agents: nodes carry only node-specific metadata

When the left4me bundle was first integrated, ovh.left4me's node
file carried ~40 lines of left4me-related metadata (git_url,
secret_key, full nginx vhost, monitoring, backups, nftables
rules). The maintainer pushed back: per-node metadata should be
only what genuinely varies per host. Refactor brought it down to
{'domain': 'left4.me'} with everything else in bundle defaults
or in a reactor deriving from the domain.

Add the rule to bundles/AGENTS.md from the bundle-author angle
(use defaults / vault-keyed-on-node for secrets, cite left4me
and postgresql for the established pattern). Add the reviewer's
form to nodes/AGENTS.md Pitfalls.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

bundles/AGENTS.md

@@ -41,6 +41,16 @@ bundles/<name>/
   more than one bundle. Don't duplicate logic across bundles.
 - **Custom item types** (e.g. `download:`) live in
   [`items/`](../items/AGENTS.md), not per-bundle.
+- **Bundles own application-wide knowledge; nodes carry only the few
+  per-host knobs the bundle actually needs.** When designing a bundle,
+  identify the per-node knobs (e.g. domain, uplink interface, a
+  vault-id suffix) and put everything else in `defaults`, or in a
+  reactor that derives from those knobs. Per-node random secrets
+  belong in `defaults` via `repo.vault.random_bytes_as_base64_for(...)`
+  keyed on the node — not in the node file. See
+  `bundles/left4me/metadata.py:10` (`secret_key` derived in defaults)
+  and `bundles/postgresql/metadata.py:4` (vault-derived `password_for`
+  at module scope).
 
 ## How to add a new bundle
 

nodes/AGENTS.md

@@ -81,6 +81,12 @@ This loader shape has consequences:
   These are intentional parks/buffers, not bugs.
 - **`id` must be unique.** A pre-apply hook (`hooks/unique_node_ids.py`)
   enforces this; duplicate IDs fail `bw test` and `bw apply`.
+- **Bloated per-node metadata is usually a bundle smell.** If a
+  bundle's metadata block in the node file has more than 3-5 keys,
+  the bundle is probably under-using `defaults` / reactors. Push the
+  contribution into the bundle (see
+  [`bundles/AGENTS.md`](../bundles/AGENTS.md#conventions)) rather than
+  growing the node file.
 
 ## See also