fix(docs): correct CLI gotcha and test credential setup in AGENTS.md and TESTING.md - #6012
Open
santhiprakash wants to merge 1 commit into
Open
fix(docs): correct CLI gotcha and test credential setup in AGENTS.md and TESTING.md#6012santhiprakash wants to merge 1 commit into
santhiprakash wants to merge 1 commit into
Conversation
…and TESTING.md - Problem: AGENTS.md Common Gotchas item 3 says `messages search` requires `--kinds`, but the flag does not exist on that subcommand and cmd_search hardcodes its own kind filter. TESTING.md § 4 instructs `buzz-admin mint-token`, which does not exist. - Fix: Rewrite gotcha block#3 to state that messages search already scopes kinds internally and point to messages get --kinds for explicit filtering. Replace TESTING.md § 4 mint-token flow with the real generate-key + add-member bootstrap, and replace the phantom scope reference table with the actual pubkey-based auth model. - Verification: Verified against upstream main crates/buzz-cli/src/lib.rs (MessagesCmd::Search struct takes --query/--author/--since/--limit; messages get takes --kinds) and crates/buzz-admin/src/main.rs (Command enum has generate-key and add-member, not mint-token). Signed-off-by: Santhi Prakash <b.santhiprakash@gmail.com>
santhiprakash
force-pushed
the
fix/agents-docs-cli-gotchas
branch
from
August 16, 2026 15:55
6aa0e43 to
28c49d8
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Problem
Two contributor-facing docs instruct running commands the binaries do not have,
blocking the onboarding path for new contributors and agents following
AGENTS.md.messages searchrequires--kinds, but the flag does not exist on that subcommand.cmd_search_messageshardcodes kinds[9, 40002, 45001, 45003]andnever trips the p-gate.
crates/buzz-cli/TESTING.md§ 4 tells you to runbuzz-admin mint-token, which does not exist. The actual auth flow isgenerate-key→add-member→ exportBUZZ_PRIVATE_KEY.Refs #5663
Triage / Root cause
MessagesCmd::Search(crates/buzz-cli/src/lib.rs) takes--query,--author,--since,--limitonly. The--kindsflag belongs to
messages get, notmessages search.buzz-admin'sCommandenum (crates/buzz-admin/src/main.rs)has
generate-keyandadd-member, notmint-token. Scoped APItokens exist in the schema but have no CLI or relay surface.
Fix
messages searchalreadyscopes kinds internally and to use
messages get --kindsfor explicitfiltering.
mint-tokenflow with the realgenerate-key+add-memberbootstrap. Replaced the phantomscope-reference table with the actual pubkey + membership auth model.
Verification
crates/buzz-cli/src/lib.rsto confirmMessagesCmd::Searchfieldsand
MessagesCmd::Getfields (including--kinds).crates/buzz-cli/src/commands/messages.rsto confirmcmd_searchhardcodes kinds.crates/buzz-admin/src/main.rsto confirm available subcommands.