BitBadges · trevormil · May 14, 2026 · May 14, 2026 · May 14, 2026
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -4,6 +4,10 @@ All notable changes to the BitBadges Claude Code plugin will be documented in th
 
 ## [Unreleased]
 
+### Changed
+- `query/SKILL.md` — description now lists the standards surface (auctions, crowdfunds, payment-requests, intents, smart-tokens, etc) alongside the raw API routes. Added a "Standards shortcuts" section pointing Claude at `bitbadges-cli <standard> list / show / status` as the preferred route over `bitbadges-cli api ...` when the user asks about a standard by name. API route count bumped from 104 → 106 (SDK #223 + #228 added 27+ indexer routes including consolidated `/swap/*` and gamm queries).
+- `broadcast/SKILL.md` — added a fifth signing path (`deploy --with-keyring --from <key>`) for headless CLI-only flows that already have a key in the chain binary's keyring; the CLI prints + runs the equivalent `bitbadgeschaind tx ...` so users see what's being signed. Added a top-level note about `--wait-for-indexer [timeout-ms]` for agent scripts that immediately need to query the newly-created entity.
+
 ### Added
 - Initial scaffolding: plugin manifest, MCP server registration, README, LICENSE.
 - 8 skills, all hand-written as routing guides on top of the CLI / MCP / docs (no duplicated SDK content):

diff --git a/README.md b/README.md
@@ -12,12 +12,24 @@ The BitBadges chain binary + CLI are the canonical way to interact with BitBadge
 curl -fsSL https://install.bitbadges.io | sh
 ```
 
-This installs `bitbadgeschaind` (the chain binary) and `bitbadges-cli` (the JS CLI that exposes 104+ API routes plus the `bitbadges-builder` MCP server). This plugin is a Claude Code convenience layer on top of those — it does not replace them.
+This installs `bitbadgeschaind` (the chain binary), `bitbadges-cli` (the JS SDK CLI that exposes 106+ API routes plus the `bitbadges-builder` MCP server), and a friendly `bb` alias that wraps `bitbadgeschaind`. This plugin is a Claude Code convenience layer on top of those — it does not replace them.
+
+## Two entrypoints — when to use which
+
+There are two binaries on PATH after install, and the skills route to each one accordingly:
+
+| Form | What it covers | When skills use it |
+|---|---|---|
+| **`bb cli <subcmd>`** (preferred) | The full Node SDK CLI surface — `build`, `deploy`, `api`, `auctions`, `crowdfunds`, `intents`, `auth`, etc. `bb cli` is `bitbadgeschaind cli` is `bitbadges-cli` — same code, friendlier alias. | Almost all skills (`build`, `query`, `simulate`, `explain`, `review`, `claim`, `address`, most of `broadcast`). |
+| **`bitbadgeschaind tx \| query \| keys`** (no `cli` forwarder) | Native Cosmos chain-binary surface — keyring management, signing, on-chain queries. NOT forwarded through `bitbadges-cli`. | `broadcast` skill's "chain binary" path (`bitbadgeschaind tx <module> <action>`). Address skill's keyring lookups. |
+| **`bitbadges-cli <subcmd>`** (direct) | Same as `bb cli <subcmd>` — the underlying JS binary, no chain-binary wrapper. Use when the chain binary isn't on PATH or scripts pin the JS-only entry. | Fallback only — examples in the skills standardize on `bb cli` for terseness. |
+
+**Rule of thumb**: when in doubt, use `bb cli <subcmd>`. The only time you must use `bitbadgeschaind` directly is for the Cosmos-native surface (`tx`, `query`, `keys`) — those don't have a `bb cli` equivalent because they're not part of the JS SDK.
 
 Get an API key at [bitbadges.io/developer](https://bitbadges.io/developer) and configure it once:
 
 ```sh
-bitbadges-cli config set apiKey YOUR_KEY
+bb cli config set apiKey YOUR_KEY
 ```
 
 ## Install the plugin

diff --git a/skills/broadcast/SKILL.md b/skills/broadcast/SKILL.md
@@ -8,17 +8,29 @@ This is the only skill that touches money. Treat it as on-rails, not LLM-discove
 
 ## Pick a path
 
-There are four signing paths. Choose based on what the user actually has — not what's most convenient for you.
+There are five signing paths. Choose based on what the user actually has — not what's most convenient for you.
 
 | What the user has | Use |
 |---|---|
-| A bb1 key in `bitbadgeschaind keys` (or a hardware wallet that signs ADR-36) | **Chain binary** — `bitbadgeschaind tx ...` |
+| A bb1 key in `bitbadgeschaind keys` and a CLI workflow | **`deploy --with-keyring --from <key>`** — the CLI prints the equivalent `bitbadgeschaind tx ...` command, runs it, returns the response. Best for headless scripts. |
+| Same but driving the chain binary directly | **Chain binary** — `bitbadgeschaind tx ...` |
 | Just a browser wallet (Keplr, MetaMask, Phantom) | **Browser bridge** — `bitbadges-cli deploy --browser` |
 | Want zero wallet setup for a one-shot create-collection | **Burner** — `bitbadges-cli deploy --burner` |
 | A programmatic signer (cosmjs / ethers / viem / hardware that takes raw bytes) | **gen-tx-payload** — produces SignDoc bytes, user signs in their own code |
 
 If the user can't tell you which they have, ask. Don't guess. The simulator and review steps are identical regardless of path.
 
+## Useful flag on every `deploy` path: `--wait-for-indexer`
+
+After broadcast succeeds, the indexer is eventually-consistent — querying the new collection / dynamic store immediately can 404 for a few seconds. Add `--wait-for-indexer [timeout-ms]` (default 30000) to any `deploy` invocation to poll until the entity appears, so the next step in an agent script can rely on it. The CLI returns a `waited: { entity, id, attempts, elapsedMs, ok }` field on the response envelope.
+
+```bash
+bitbadges-cli deploy --burner --msg-stdin --manager bb1... \
+  --wait-for-indexer
+```
+
+Skip the flag when you don't need to query the entity immediately afterwards.
+
 ## Hard requirements (universal)
 
 - The transaction has been **simulated and reviewed** in the same session.
@@ -43,6 +55,18 @@ Network flags:
 - Mainnet (default): no flag
 - Testnet: `--node https://rpc-testnet.bitbadges.io --chain-id bitbadges-1-testnet`
 
+## Path 1b — CLI keyring shortcut (`deploy --with-keyring --from <key>`)
+
+Same outcome as Path 1, but you stay inside `bitbadges-cli`. The CLI inspects the msg JSON, prints the equivalent `bitbadgeschaind tx ...` command (so users see exactly what's being signed), executes it, and returns the chain response. Best when you've already piped a `build` output and don't want to context-switch:
+
+```bash
+bitbadges-cli build vault --name … \
+  | bitbadges-cli deploy --with-keyring --from mykey --msg-stdin \
+      --keyring-backend test --manager bb1…
+```
+
+The msg is unrestricted — works for any tokenization msg, not just create-collection.
+
 ## Path 2 — Browser bridge (`deploy --browser`)
 
 For users whose wallet only lives in a browser extension (Keplr, MetaMask, Phantom, WalletConnect). The CLI opens `/sign` on bitbadges.io, the user reviews + signs in their wallet, the tx hash comes back to the terminal.

diff --git a/skills/query/SKILL.md b/skills/query/SKILL.md
@@ -1,5 +1,5 @@
 ---
-description: Query BitBadges collections, balances, accounts, claims, addresses, and any of the 104+ API routes. Discovers routes via --help-json instead of guessing.
+description: Query BitBadges collections, balances, accounts, claims, addresses, standards (auctions / crowdfunds / payment-requests / intents / smart-tokens / ...), and any of the 106+ API routes. Discovers routes via --help-json instead of guessing.
 ---
 
 # Query
@@ -29,6 +29,28 @@ The `--help-json` output is the source of truth for routes and parameters. Read
 
 Or use the MCP fast-paths: `query_collection`, `query_balance`, `verify_ownership`.
 
+## Standards shortcuts (preferred over raw API)
+
+For every BitBadges standard the CLI exposes a typed list / show / status surface that's friendlier than the raw indexer routes. Reach for these BEFORE `api ...` when the user asks about a standard by name:
+
+```bash
+bitbadges-cli auctions list                       # browse active auctions
+bitbadges-cli auctions show 42                    # one auction
+bitbadges-cli auctions status 42                  # bidding | accepting | sold | expired
+
+bitbadges-cli crowdfunds list                     # crowdfund campaigns
+bitbadges-cli pay-requests list --mine bb1...     # payment requests TO me
+bitbadges-cli intents list --pay-denom uusdc      # intent-exchange offers
+bitbadges-cli prediction-markets list --open      # active prediction markets
+bitbadges-cli credit-tokens show <id>             # one credit-token collection
+bitbadges-cli smart-tokens status <id>            # one smart token
+bitbadges-cli subscriptions status <id> <addr>    # subscription tier status
+bitbadges-cli swap assets / chains / balances     # cross-chain swap surface
+bitbadges-cli dynamic-stores list-values <id>     # on-chain key→bool map
+```
+
+Every standard supports `--mine <addr>` (or equivalent) to scope to a specific user. Add `--testnet` / `--local` for non-mainnet. Output is structured JSON. The full surface lives at the docs Standards Commands reference.
+
 ## Networks
 
 Add `--testnet` to any command to hit testnet. Add `--local` for `http://localhost:3001`. Default is mainnet.