diff --git a/bundles/AGENTS.md b/bundles/AGENTS.md
index 40ff949..2b339c8 100644
--- a/bundles/AGENTS.md
+++ b/bundles/AGENTS.md
@@ -56,12 +56,22 @@ bundles/<name>/
    [`groups/<axis>/<x>.py`](../groups/AGENTS.md) (preferred for shared
    bundles) or to the node's `bundles` list directly
    ([`nodes/AGENTS.md`](../nodes/AGENTS.md)).
-5. Verify, in this order:
-   - `bw test` — sanity (loaders + reactors).
-   - `bw items <node>` — confirm new items appear on a node that opts in.
-   - `bw hash <node>` — confirm the change is what you expected. See
-     [`docs/agents/commands.md`](../docs/agents/commands.md) and the
-     fork's hash-diff workflow.
+5. **Verify, in this order:**
+   - `bw test` — repo-wide parse + cross-cutting hooks. Loads every
+     bundle, but reactors don't fire for nodes that haven't opted into
+     the bundle yet — bugs in new reactors stay hidden here.
+   - **Attach the bundle to a node** (via the node's `bundles` list, or
+     a group it belongs to). Until you do, the next steps don't actually
+     exercise the bundle.
+   - `bw test <node>` — exercises every reactor and item-graph edge for
+     that node. This is where most new-bundle bugs surface.
+   - `bw items <node> --blame` — confirm items materialise with the
+     right paths, authored by the expected bundle.
+   - `bw metadata <node> -k <a/b>` — spot-check derived metadata.
+   - `bw hash <node>` — preview vs current host state.
+
+   See [`docs/agents/commands.md#bundle-validation-workflow`](../docs/agents/commands.md#bundle-validation-workflow)
+   for the rationale.
 6. Add a `bundles/<name>/README.md`. See "Per-bundle README" below
    for what to cover.
 
diff --git a/docs/agents/commands.md b/docs/agents/commands.md
index 37b1179..2225f31 100644
--- a/docs/agents/commands.md
+++ b/docs/agents/commands.md
@@ -73,3 +73,26 @@ selector grammar: bare node name, group name, `bundle:<name>`,
 `!bundle:<name>`, or `"lambda:node.metadata_get('foo/bar', 0) < 3"`.
 
 [fork]: https://github.com/CroneKorkN/bundlewrap/blob/main/AGENTS.md
+
+## Bundle-validation workflow
+
+`bw test` (no args) is a *parsing* gate, not a *behaviour* gate. It
+loads every bundle, but a bundle's reactors only resolve when a node's
+metadata is actually built — and that happens only for nodes that
+opt in. Until then, reactor bugs stay dormant. bw rejects reactors
+that don't read any metadata, but the rejection only fires once *some*
+node consumes the bundle.
+
+When developing a new bundle:
+
+1. Scaffold + `bw test` — confirms parsing.
+2. **Attach the bundle to one node** (or a stub node) by adding it to
+   `nodes/<n>.py`'s `bundles` list, or to a group the node is in.
+3. `bw test <node>` — now reactors fire. This is where bundle bugs
+   surface.
+4. `bw items <node> --blame` and `bw metadata <node> -k <key>` —
+   confirm items materialise and derived metadata looks right.
+5. `bw hash <node>` — preview against the live host.
+
+Step 2 is non-optional. A bundle that "passes `bw test`" with no
+consumer is proven only to parse.