diff --git a/bundles/AGENTS.md b/bundles/AGENTS.md
index 2b339c8..02c196a 100644
--- a/bundles/AGENTS.md
+++ b/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
 
diff --git a/nodes/AGENTS.md b/nodes/AGENTS.md
index 150ed45..d51c31d 100644
--- a/nodes/AGENTS.md
+++ b/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