From 0a9f3dae88175827d3e5a5242f246750bfb91abc Mon Sep 17 00:00:00 2001 From: CroneKorkN Date: Sun, 10 May 2026 20:26:27 +0200 Subject: [PATCH] agents/commands: read-only command cheat sheet Adds a flag-combinations table for bw test (selectors + the HIJKMSp/IJKMp default-flag split), bw metadata -k/-b/-f (with the -f sensitive-data warning), bw items --blame/-f, bw verify -o bundle:, bw hash -m/-d. Also documents the shared target- selector grammar. Surfaced by the left4me-integration session, where the agent relied on bare bw test / bw metadata / bw items invocations and missed leverage from the available flags. Co-Authored-By: Claude Opus 4.7 (1M context) --- docs/agents/commands.md | 25 +++++++++++++++++++++++++ 1 file changed, 25 insertions(+) diff --git a/docs/agents/commands.md b/docs/agents/commands.md index 2e78658..37b1179 100644 --- a/docs/agents/commands.md +++ b/docs/agents/commands.md @@ -48,3 +48,28 @@ instead. See [`conventions.md#secrets`](conventions.md#secrets) for the demagify magic-string list and the rule's full rationale. + +## Read-only commands — useful flag combinations + +The fork's [`AGENTS.md`][fork] documents the canonical safety envelope. +These are the flag combinations agents reach for most often in this repo: + +| Want to … | Run | +|---|---| +| Sanity-check the whole repo (parse + cross-cutting hooks) | `bw test` (defaults to `-HIJKMSp`) | +| Exercise reactors and item-graph for one node | `bw test ` (defaults to `-IJKMp`) | +| Same, but every node that has a given bundle | `bw test bundle:` | +| Print one metadata key for one node | `bw metadata -k ` (repeat `-k` for more) | +| Show where each metadata value comes from | `bw metadata -b` | +| Resolve Faults (vault values) into the dump | `bw metadata -f` — **may print secrets, avoid** | +| List a node's items, with the bundle that defines each | `bw items --blame` | +| Preview a rendered file's content | `bw items file: -f` | +| Verify against the live host, scoped to one bundle | `bw verify -o bundle:` | +| Hash metadata only (faster than full config hash) | `bw hash -m` | +| Inspect the data backing a hash | `bw hash -d` | + +`bw test`, `bw verify`, `bw nodes`, `bw metadata` all share a target- +selector grammar: bare node name, group name, `bundle:`, +`!bundle:`, or `"lambda:node.metadata_get('foo/bar', 0) < 3"`. + +[fork]: https://github.com/CroneKorkN/bundlewrap/blob/main/AGENTS.md