Feature request: add a non-mutating `buzz doctor` command

[MajorTal]

Motivation

The CLI has comprehensive command help, but --help cannot answer whether a Buzz environment is actually ready to use. Today, troubleshooting usually means running a real command and interpreting the first error it returns.

A single safe preflight would help humans, agents, automation, and support reports answer:

• Is the local configuration present and parseable?
• Which public identity will sign requests?
• Is the relay reachable and does it return valid NIP-11 metadata?
• Is authentication accepted?
• Is the identity a member of the selected community?

Buzz Desktop has a Doctor surface for managed ACP runtimes, but that has a different scope and is unavailable in headless environments, containers, and servers.

Proposed solution

Add a root-level buzz doctor command that runs independent checks, aggregates the results rather than failing at the first problem, and never publishes events or changes local or remote state.

A useful first slice could include:

Local checks, available even with --offline:

• CLI version/build information
• relay URL presence, syntax, and canonicalization
• BUZZ_PRIVATE_KEY presence and parseability, reporting only the derived public identity
• BUZZ_AUTH_TAG syntax and basic consistency, without ever printing the tag

Read-only remote checks:

• DNS/TLS/network reachability
• NIP-11 retrieval and basic compatibility
• authenticated read access
• community membership and available role/scope information
• WebSocket connection or subscription readiness, without publishing an event

The command should use the existing global relay, key, auth-tag, and output-format options. Default structured output could follow the existing CLI convention, for example:

{
  "status": "warning",
  "checks": [
    {
      "id": "identity",
      "status": "ok",
      "message": "Signing identity is available"
    },
    {
      "id": "relay",
      "status": "error",
      "message": "Relay is unreachable",
      "remediation": "Check the relay URL and network connectivity"
    }
  ]
}

Required behavior:

• Running with missing or invalid credentials reports those as check results instead of failing during CLI argument parsing.
• --offline runs only local checks and clearly marks remote checks as skipped.
• Remote probes are read-only.
• All applicable checks run so one invocation can reveal multiple problems.
• Output and error messages never expose private keys, auth tags, bearer values, or signed request material.
• Check identifiers and structured fields are stable enough for automation.
• Exit behavior distinguishes a failed required check from warnings while preserving structured output. I would welcome maintainer guidance on whether warnings should still exit zero and how this should map onto the existing exit-code categories.

Suggested coverage:

• unit tests for aggregation, redaction, skipped checks, and exit precedence
• mocked relay tests for unreachable, malformed NIP-11, unauthenticated, and non-member cases
• a CLI-definition test proving doctor --help remains available without credentials

For the initial version, local configuration plus NIP-11, read-only authentication, and membership checks may be enough; WebSocket readiness could follow separately if it adds too much scope.

Alternatives considered

• Run a harmless existing read command such as channels list: this fails fast, does not cover local configuration, and can blur network, authentication, and membership failures.
• Use the Desktop Doctor: it diagnoses managed agent runtimes rather than CLI-to-community readiness and is not available headlessly.
• Use shell scripts and curl: these duplicate Buzz signing/authentication behavior and make secret handling less reliable.
• Improve individual error messages only: useful, but it does not provide proactive, aggregated readiness information.

Additional context

• The prior Doctor issue, Add doctor section to settings to help with ACP setup #76, was specifically for the Desktop ACP setup surface and was completed by Add desktop settings shell and doctor panel #80.
• PR feat(cli): add buzz users me for external-agent identity #2933 proposes buzz users me with a whoami alias. A doctor command should reuse the same local identity derivation if that lands, not introduce a competing identity command.
• I searched open and closed issues and PRs for doctor, diagnostic, health check, preflight, and troubleshoot; I found no existing CLI diagnostics proposal.
• A local audit of current main found that --help succeeds across all exposed CLI command paths, so this proposal is about runtime readiness rather than help coverage.