docs(plugin): flip CLI examples to v2 short form

CHANGELOG.md

@@ -5,13 +5,14 @@ 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.
+- CLI v2 short-form sweep — every plugin page, skill, and slash command now uses the flat `bb <cmd>` invocation instead of the deprecated `bb cli <cmd>` form. Renames applied: `portfolio` → `account` (absorbs `address convert/validate`, `lookup`, `alias`, `gen-list-id`), `config` → `settings`, `tools/tool` + `resources/docs/skills/gen-pub-key` moved under `dev`, `swap pools`/`swap asset-pairs` promoted to top-level `pools`/`pairs`, and `sign-with-browser` + `gen-tx-payload` folded into `bb deploy --browser` / `bb deploy --gen-payload`. The old `bb cli <cmd>` form still works for one release with a stderr deprecation banner (set `BB_QUIET=1` to suppress). Tracked under autopilot ticket #0399 and design doc `outputs/flagship-plans/cli-v2-design.md`.
+- `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 `bb <standard> list / show / status` as the preferred route over `bb 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 (`bb 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 `bb 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):
-  - `build` — meta-guide for constructing any token type. Routes Claude to `bitbadges-cli skills <id>` for canonical instructions and the per-field MCP tools for construction.
+  - `build` — meta-guide for constructing any token type. Routes Claude to `bb dev skills <id>` for canonical instructions and the per-field MCP tools for construction.
   - `review`, `simulate`, `explain` — pre-broadcast safety net.
   - `query`, `address`, `claim` — runtime ops.
   - `broadcast` — hard-railed live broadcast.
@@ -22,4 +23,4 @@ All notable changes to the BitBadges Claude Code plugin will be documented in th
 
 ### Design
 
-The plugin is intentionally **a thin harness, not a knowledge base**. Token-type-specific instructions live in the SDK at `bitbadgesjs-sdk/src/builder/resources/skillInstructions.ts` and are surfaced to Claude on demand via `bitbadges-cli skills <id>`, the `get_skill_instructions` MCP tool, and the Gitbook pages at https://docs.bitbadges.io/x-tokenization/examples/skills/. The plugin's job is to teach Claude where to find them and how to compose them — not to ship 22 routing wrappers that just point at the same content.
+The plugin is intentionally **a thin harness, not a knowledge base**. Token-type-specific instructions live in the SDK at `bitbadgesjs-sdk/src/builder/resources/skillInstructions.ts` and are surfaced to Claude on demand via `bb dev skills <id>`, the `get_skill_instructions` MCP tool, and the Gitbook pages at https://docs.bitbadges.io/x-tokenization/examples/skills/. The plugin's job is to teach Claude where to find them and how to compose them — not to ship 22 routing wrappers that just point at the same content.

README.md

@@ -14,22 +14,22 @@ curl -fsSL https://install.bitbadges.io | sh
 
 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
+## One binary, one flat surface
 
-There are two binaries on PATH after install, and the skills route to each one accordingly:
+After install, `bb` is the single user-facing name. Every SDK command lives at the top level — no `cli` infix needed. The plugin skills standardize on this short form:
 
 | 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. |
+| **`bb <subcmd>`** (preferred) | Everything. The full SDK surface — `build`, `deploy`, `api`, `auctions`, `crowdfunds`, `intents`, `auth`, `account`, `pools`, `pairs`, `dev`, `settings`, etc. — plus every Cosmos-native surface (`tx`, `query`, `keys`) on the same binary. | Every skill. |
+| **`bitbadges-cli <subcmd>`** (direct) | Same SDK surface as `bb <subcmd>`, just the underlying JS binary. Use only when the chain binary isn't on PATH or a script pins the JS-only entry. | Fallback only. |
+| **`bb cli <subcmd>`** (deprecated alias) | Same as `bb <subcmd>`. Kept for one release so existing scripts and demos keep working — emits a one-line deprecation banner to stderr. Set `BB_QUIET=1` to suppress. | Never — examples have all moved to `bb <subcmd>`. |
 
-**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.
+**Rule of thumb**: when in doubt, use `bb <subcmd>`. Chain-native surfaces (`tx`, `query`, `keys`) live there too — `bb --help` groups them as "Chain operations" so you can tell at a glance which side of the binary owns each command.
 
 Get an API key at [bitbadges.io/developer](https://bitbadges.io/developer) and configure it once:
 
 ```sh
-bb cli config set apiKey YOUR_KEY
+bb settings set apiKey YOUR_KEY
 ```
 
 ## Install the plugin
@@ -47,10 +47,10 @@ Then run `/bitbadges:setup` once to verify everything is wired and `/bitbadges:s
 
 - **MCP tools** — `bitbadges-builder` registered automatically (no separate `claude mcp add` step). Exposes 50+ session-based per-field token construction tools, queries, validation, review, and simulation.
 - **8 skills** — guides that route Claude to the right CLI command, MCP tool, or docs page for each common BitBadges workflow:
-  - `build` — meta-guide for building any token type. Discovers via `bitbadges-cli skills`, loads canonical instructions from the SDK, constructs via per-field MCP tools.
-  - `review`, `simulate`, `explain` — pre-broadcast safety net. Wraps `bitbadges-cli check`, MCP `simulate_transaction`, and `bitbadges-cli explain`.
+  - `build` — meta-guide for building any token type. Discovers via `bb dev skills`, loads canonical instructions from the SDK, constructs via per-field MCP tools.
+  - `review`, `simulate`, `explain` — pre-broadcast safety net. Wraps `bb check`, MCP `simulate_transaction`, and `bb explain`.
   - `query`, `address`, `claim` — runtime ops. Wraps the API routes, address derivations, and claim builder respectively.
-  - `broadcast` — hard-railed signer. Picks one of four signing paths based on what wallet the user has (chain binary, browser bridge via `/sign`, throwaway burner, or programmatic `gen-tx-payload`). Dry-run by default, explicit confirmation for live.
+  - `broadcast` — hard-railed signer. Picks one of four signing paths based on what wallet the user has (chain binary, browser bridge via `/sign`, throwaway burner, or programmatic `bb deploy --gen-payload`). Dry-run by default, explicit confirmation for live.
 - **2 slash commands** — `/bitbadges:setup` (one-time prereq check + API key wiring) and `/bitbadges:status` (health check).
 - **`bitbadges-builder` subagent** for focused builder loops.
 - **SessionStart pre-warm** so the first MCP-tool call doesn't pay npx download latency.

agents/bitbadges-builder.md

@@ -9,9 +9,9 @@ You are a BitBadges builder subagent. Your job is to take a token-creation or tr
 ## Tool preference
 
 1. **MCP tools first.** The `bitbadges-builder` MCP server exposes 50+ tools for session management, token construction, review, simulation, and queries. Use `set_standards`, `set_invariants`, `add_approval`, `validate_transaction`, `review_collection`, `simulate_transaction`, `get_skill_instructions`, etc. directly — don't shell out unless MCP is unavailable.
-2. **CLI fallback.** If an MCP tool isn't available or the user is doing something off the happy path (custom queries, address derivations not exposed via MCP), fall back to `bitbadges-cli` subcommands: `sdk`, `api`, `builder`, `config`.
-3. **Chain binary** (`bitbadgeschaind`) for key management and live broadcasts when the user has a bb1 key in the keyring. Default to dry-run; require explicit user confirmation for live broadcasts.
-4. **Browser bridge / programmatic helpers** (`bitbadges-cli deploy --browser`, `gen-tx-payload`, `gen-pub-key`) when the user has a browser wallet, no wallet at all, or a custom signer. See the `broadcast` skill for the four-path decision matrix.
+2. **CLI fallback.** If an MCP tool isn't available or the user is doing something off the happy path (custom queries, address derivations not exposed via MCP), fall back to `bb` subcommands: `sdk`, `api`, `builder`, `settings`.
+3. **Chain binary** (`bb tx`, `bb keys`) for key management and live broadcasts when the user has a bb1 key in the keyring. Default to dry-run; require explicit user confirmation for live broadcasts.
+4. **Browser bridge / programmatic helpers** (`bb deploy --browser`, `bb deploy --gen-payload`, `bb dev gen-pub-key`) when the user has a browser wallet, no wallet at all, or a custom signer. See the `broadcast` skill for the four-path decision matrix.
 
 ## Workflow on a creation task
 
@@ -22,10 +22,10 @@ You are a BitBadges builder subagent. Your job is to take a token-creation or tr
 5. `simulate_transaction` to dry-run.
 6. Show the user the simulator output and ask explicitly before broadcasting.
 7. Route the broadcast based on what the user actually has. Pick one — don't guess if you don't know:
-   - **Chain binary** (`bitbadgeschaind tx ...`): bb1 key in keyring, hardware wallet via ADR-36.
-   - **Browser bridge** (`bitbadges-cli deploy --browser`): user has only a browser wallet (Keplr / MetaMask / Phantom). CLI opens `/sign` on bitbadges.io, user reviews + signs, hash comes back to terminal. Add `--sign-only` to skip broadcast and return signed bytes for caller-controlled submission.
-   - **Burner** (`bitbadges-cli deploy --burner --manager bb1...`): zero-wallet one-shot create-collection. Throwaway signer, faucet-funded, discarded. CREATE-only.
-   - **Programmatic** (`bitbadges-cli gen-tx-payload --from bb1...` or `0x...`): for custom signers — cosmjs, ethers/viem, hardware that takes raw bytes, custodial. Returns the full SignDoc envelope (signDirect + legacyAmino + evmTx) plus pre-resolved account state. Pair with `bitbadges-cli gen-pub-key` if the account is fresh and the indexer has no pubkey on file. See the `broadcast` skill for path-by-path failure modes.
+   - **Chain binary** (`bb tx ...`): bb1 key in keyring, hardware wallet via ADR-36.
+   - **Browser bridge** (`bb deploy --browser`): user has only a browser wallet (Keplr / MetaMask / Phantom). CLI opens `/sign` on bitbadges.io, user reviews + signs, hash comes back to terminal. Add `--sign-only` to skip broadcast and return signed bytes for caller-controlled submission.
+   - **Burner** (`bb deploy --burner --manager bb1...`): zero-wallet one-shot create-collection. Throwaway signer, faucet-funded, discarded. CREATE-only.
+   - **Programmatic** (`bb deploy --gen-payload --from bb1...` or `0x...`): for custom signers — cosmjs, ethers/viem, hardware that takes raw bytes, custodial. Returns the full SignDoc envelope (signDirect + legacyAmino + evmTx) plus pre-resolved account state. Pair with `bb dev gen-pub-key` if the account is fresh and the indexer has no pubkey on file. See the `broadcast` skill for path-by-path failure modes.
 
 ## Always
 

commands/setup.md

@@ -13,7 +13,7 @@ The chain + CLI install is **the** entrypoint. The plugin's `npx`-based MCP fall
 
 1. **Chain binary check (required).** If `bitbadgeschaind` is on PATH, print the version. If not, print the install one-liner (`curl -fsSL https://install.bitbadges.io | sh`) and ask for explicit consent before running it. Never auto-pipe `curl ... | sh` — show the command, wait for "yes".
 2. **CLI check (required).** Same flow — if `bitbadges-cli` is on PATH, OK; otherwise the same one-liner installs both binaries together. The presence of `bitbadges-cli` globally also means the `bitbadges-builder` MCP bin is on PATH, which is faster and more reliable than the plugin's npx fallback.
-3. **API key (required).** If `~/.bitbadges/config.json` already has an `apiKey`, use it — no prompt. The CLI config is canonical; both the CLI and the plugin read from there. Otherwise prompt for the key and write via `bitbadges-cli config set apiKey <KEY>`. Source: https://bitbadges.io/developer.
+3. **API key (required).** If `~/.bitbadges/config.json` already has an `apiKey`, use it — no prompt. The CLI config is canonical; both the CLI and the plugin read from there. Otherwise prompt for the key and write via `bb settings set apiKey <KEY>`. Source: https://bitbadges.io/developer.
 4. **Migration check (optional).** If the user previously ran `claude mcp add bitbadges-builder ...` manually (user scope), that registration coexists with the plugin's `.mcp.json` entry and produces duplicate MCP servers. Detect it (`claude mcp list | grep bitbadges-builder`) and offer to run `claude mcp remove bitbadges-builder` to clean up.
 
 ## Behavior summary for Claude

commands/status.md

@@ -7,14 +7,14 @@ argument-hint: (no arguments)
 
 A one-shot diagnostic. Runs `${CLAUDE_PLUGIN_ROOT}/scripts/doctor.sh` and reports:
 
-- `bitbadgeschaind` version (or "not installed").
-- `bitbadges-cli` version (resolved via `npx bitbadges --version`).
+- `bb` chain binary version (or "not installed").
+- `bb` SDK version (resolved via `bb --version`).
 - Active network (mainnet / testnet / local).
-- API connectivity (`bitbadges-cli doctor`).
+- API connectivity (`bb doctor`).
 - API key configured (yes/no, masked).
 - MCP server `bitbadges-builder` is reachable.
 
-Output is human-readable by default; the underlying `bitbadges-cli doctor` always emits the universal `{ok, data, warnings, error}` envelope to stdout with the colored scorecard on stderr. Slash commands surface the human form.
+Output is human-readable by default; the underlying `bb doctor` always emits the universal `{ok, data, warnings, error}` envelope to stdout with the colored scorecard on stderr. Slash commands surface the human form.
 
 ## When to use
 

skills/address/SKILL.md

@@ -9,8 +9,8 @@ BitBadges runs on a Cosmos chain with EVM compatibility, so addresses come in tw
 ## Conversion
 
 ```bash
-bitbadges-cli address convert <address> --to <bb1|0x>
-bitbadges-cli address validate <address>
+bb account convert <address> --to <bb1|0x>
+bb account validate <address>
 ```
 
 `bb1...` ↔ `0x...` is deterministic — same key, two encodings. The CLI handles the bech32/hex math.
@@ -19,9 +19,9 @@ bitbadges-cli address validate <address>
 
 | Need | Command |
 |---|---|
-| Backing address for an IBC denom (smart-token deposits) | `bitbadges-cli alias for-ibc-backing <denom>` |
-| Wrapper address for a collection | `bitbadges-cli alias for-wrapper <collection-id>` |
-| Mint-escrow address for a collection | `bitbadges-cli alias for-mint-escrow <collection-id>` |
+| Backing address for an IBC denom (smart-token deposits) | `bb account alias for-ibc-backing <denom>` |
+| Wrapper address for a collection | `bb account alias for-wrapper <collection-id>` |
+| Mint-escrow address for a collection | `bb account alias for-mint-escrow <collection-id>` |
 
 These are protocol-controlled addresses with auto-set approvals. Don't try to write to them directly — use the corresponding flow (IBC backing, mint, etc.).