Docs: two setup-path instructions that don't exist in the binaries (messages search --kinds, buzz-admin mint-token)
- Dominant language
- Rust
- Stars
- 32.7k
- Forks
- 4.3k
- Avg merge
- 1d 13h
- Merged PRs (30d)
- 253
Description
## Summary
Two contributor-facing docs instruct you to run things the binaries do not have. Both fail at argv parsing, so nothing is silently wrong — but both are on the setup path, where a new contributor (or an agent following `AGENTS.md`) has no way to tell a broken instruction from a broken environment.
## 1. `AGENTS.md` says `messages search` needs `--kinds`. There is no such flag.
`AGENTS.md` § Common Gotchas, item 3:
> **`messages search` must include `--kinds`** — an open-ended search (no kinds) hits the relay p-gate and returns 403. Pass at least `--kinds 9,45001,45003` to scope the query.
`MessagesCmd::Search` (`crates/buzz-cli/src/lib.rs:502-516`) takes only `--query`, `--author`, `--since`, `--limit`. Following the gotcha gets you:
```console
$ buzz messages search --query foo --kinds 9,45001,45003
error: unexpected argument '--kinds' found
```
The advice is also unnecessary: `cmd_search_messages` sets its own kind filter, so an open-ended search never trips the p-gate in the first place —
```rust
// crates/buzz-cli/src/commands/messages.rs:451
"kinds": [9, 40002, 45001, 45003],
```
The gotcha inverts the actual situation. `messages get --channel --kinds 9` (`lib.rs:466-482`) is the subcommand that takes kinds — worth naming, because "did event X land in this channel with kind Y" is exactly the question that sends people to `search` first.
## 2. `crates/buzz-cli/TESTING.md` § 4 tells you to mint a token with a subcommand that doesn't exist.
`TESTING.md:66`:
```bash
cargo run -p buzz-admin -- mint-token \
--name "cli-test" \
--scopes "messages:read,messages:write,…,admin:channels"
```
`buzz-admin`'s `Command` enum (`crates/buzz-admin/src/main.rs:42-97`) is `add-member`, `remove-member`, `list-members`, `generate-key`, `migrate`, `product-feedback`, `reconcile-channels`. No `mint-token`. It is the first credential step in the CLI testing runbook, so it blocks the whole document.
Nor is there another way to get one. Scoped API tokens exist in the schema and the data layer (`crates/buzz-db/src/api_token.rs`, `create_api_token` at `:15`), but `grep -rn create_api_token --include='*.rs' crates/ | grep -v crates/buzz-db/` returns **nothing** — no relay route and no admin command calls it. So the "Scope reference" table below it, which promises nine self-mintable scopes, describes a credential no stock deployment can issue.
What actually authorizes a CLI identity is pubkey plus membership role: the relay authenticates the event's key (NIP-42 over WebSocket, NIP-98 over HTTP) and authorizes against the relay-membership and per-channel role. The working setup is `generate-key` → `add-member` → export `BUZZ_PRIVATE_KEY`. Without that key every relay command exits **3** (`CliError::Auth` → `3`, `crates/buzz-cli/src/error.rs:101`).
## Fix
I have both corrections written and verified locally against the tree (AGENTS.md gotcha rewritten; TESTING.md § 4 replaced with the identity + membership flow, and the scope table replaced with what genuinely needs owner/admin standing). I don't have push access to this repo, so I can't open the PR from a branch here — happy to send it however maintainers prefer.
Contributor guide
Research direction
Start with the cited sections of AGENTS.md and crates/buzz-cli/TESTING.md, then compare their commands with MessagesCmd in crates/buzz-cli/src/lib.rs, cmd_search_messages in crates/buzz-cli/src/commands/messages.rs, and Command in crates/buzz-admin/src/main.rs. Done means both setup paths use commands and credential steps present in the repository, with the scope guidance matching what a stock deployment can issue.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- rust
- Domain
- cli, documentation
- Issue type
- Documentation
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Activity status
- Quiet
- Clarity
- Clearly specified
- Newbie friendliness
- 76/100