Skip to content

fix(docs): correct CLI gotcha and test credential setup in AGENTS.md and TESTING.md - #6012

Open
santhiprakash wants to merge 1 commit into
block:mainfrom
santhiprakash:fix/agents-docs-cli-gotchas
Open

fix(docs): correct CLI gotcha and test credential setup in AGENTS.md and TESTING.md#6012
santhiprakash wants to merge 1 commit into
block:mainfrom
santhiprakash:fix/agents-docs-cli-gotchas

Conversation

@santhiprakash

Copy link
Copy Markdown

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.

  1. AGENTS.md Common Gotchas item 3 says messages search requires
    --kinds, but the flag does not exist on that subcommand.
    cmd_search_messages hardcodes kinds [9, 40002, 45001, 45003] and
    never trips the p-gate.
  2. crates/buzz-cli/TESTING.md § 4 tells you to run
    buzz-admin mint-token, which does not exist. The actual auth flow is
    generate-keyadd-member → export BUZZ_PRIVATE_KEY.

Refs #5663

Triage / Root cause

  • MessagesCmd::Search (crates/buzz-cli/src/lib.rs) takes
    --query, --author, --since, --limit only. The --kinds
    flag belongs to messages get, not messages search.
  • buzz-admin's Command enum (crates/buzz-admin/src/main.rs)
    has generate-key and add-member, not mint-token. Scoped API
    tokens exist in the schema but have no CLI or relay surface.

Fix

  • Rewrote AGENTS.md gotcha feat: add desktop app #3 to state that messages search already
    scopes kinds internally and to use messages get --kinds for explicit
    filtering.
  • Replaced TESTING.md § 4 mint-token flow with the real
    generate-key + add-member bootstrap. Replaced the phantom
    scope-reference table with the actual pubkey + membership auth model.

Verification

  • Read crates/buzz-cli/src/lib.rs to confirm MessagesCmd::Search fields
    and MessagesCmd::Get fields (including --kinds).
  • Read crates/buzz-cli/src/commands/messages.rs to confirm
    cmd_search hardcodes kinds.
  • Read crates/buzz-admin/src/main.rs to confirm available subcommands.
  • Docs-only change; no code or test modifications.

@santhiprakash
santhiprakash requested a review from a team as a code owner August 16, 2026 05:08
…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
santhiprakash force-pushed the fix/agents-docs-cli-gotchas branch from 6aa0e43 to 28c49d8 Compare August 16, 2026 15:55
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant