Merge pull request #123 from basecamp/feature/fizzy-doctor

Add doctor and config diagnostics commands

Author: robzolkos

README.md

@@ -29,7 +29,16 @@ curl -fsSL https://raw.githubusercontent.com/basecamp/fizzy-cli/master/scripts/i
 fizzy setup
 ```
 
-That's it. The installer detects your platform and architecture, downloads the right binary, and verifies checksums. The setup wizard then walks you through configuring your token, selecting your account, and optionally setting a default board. Try `fizzy board list` to verify everything is working.
+That's it. The installer detects your platform and architecture, downloads the right binary, and verifies checksums. The setup wizard then walks you through configuring your token, selecting your account, and optionally setting a default board.
+
+Recommended first checks:
+
+```bash
+fizzy doctor
+fizzy board list
+```
+
+Use `fizzy doctor` any time you want a full health check of your install, config, auth, API connectivity, board context, and agent setup.
 
 <details>
 <summary>Other installation methods</summary>
@@ -121,6 +130,8 @@ Breadcrumbs suggest next commands, making it easy for humans and agents to navig
 
 **Agent discovery:** Every command supports `--help --agent` for structured help output. Use `fizzy commands --json` for the full command catalog.
 
+**Troubleshooting:** Run `fizzy doctor` for a read-only health check with remediation hints and next steps.
+
 ## Configuration
 
 ```
@@ -141,6 +152,37 @@ Configuration priority (highest to lowest):
 
 `FIZZY_ACCOUNT` is accepted as a deprecated alias for `FIZZY_PROFILE`.
 
+Inspect the effective config and precedence:
+
+```bash
+fizzy config show
+fizzy config explain
+fizzy config explain --profile acme
+```
+
+## Troubleshooting
+
+```bash
+fizzy doctor                 # Full install/config/auth/API/agent health check
+fizzy doctor --profile acme  # Check one saved profile explicitly
+fizzy doctor --all-profiles  # Sweep every saved profile
+fizzy doctor --verbose       # Include effective config details and timings
+fizzy doctor --json          # Structured output for scripts and support
+```
+
+Common follow-up commands:
+
+```bash
+fizzy auth status
+fizzy config show
+fizzy config explain
+fizzy identity show
+fizzy board list
+fizzy setup
+fizzy setup claude
+fizzy skill install
+```
+
 ## Development
 
 ```bash

SURFACE.txt

@@ -11,6 +11,7 @@ ARG fizzy comment attachments download 00 [ATTACHMENT_INDEX]
 ARG fizzy comment attachments help 00 [command]
 ARG fizzy comment help 00 [command]
 ARG fizzy completion 00 [bash|zsh|fish|powershell]
+ARG fizzy config help 00 [command]
 ARG fizzy help 00 [command]
 ARG fizzy identity help 00 [command]
 ARG fizzy migrate help 00 [command]
@@ -126,6 +127,12 @@ CMD fizzy comment show
 CMD fizzy comment update
 CMD fizzy comment view
 CMD fizzy completion
+CMD fizzy config
+CMD fizzy config explain
+CMD fizzy config help
+CMD fizzy config show
+CMD fizzy config view
+CMD fizzy doctor
 CMD fizzy help
 CMD fizzy identity
 CMD fizzy identity help
@@ -1728,6 +1735,91 @@ FLAG fizzy completion --quiet type=bool
 FLAG fizzy completion --styled type=bool
 FLAG fizzy completion --token type=string
 FLAG fizzy completion --verbose type=bool
+FLAG fizzy config --agent type=bool
+FLAG fizzy config --api-url type=string
+FLAG fizzy config --count type=bool
+FLAG fizzy config --help type=bool
+FLAG fizzy config --ids-only type=bool
+FLAG fizzy config --jq type=string
+FLAG fizzy config --json type=bool
+FLAG fizzy config --limit type=int
+FLAG fizzy config --markdown type=bool
+FLAG fizzy config --profile type=string
+FLAG fizzy config --quiet type=bool
+FLAG fizzy config --styled type=bool
+FLAG fizzy config --token type=string
+FLAG fizzy config --verbose type=bool
+FLAG fizzy config explain --agent type=bool
+FLAG fizzy config explain --api-url type=string
+FLAG fizzy config explain --count type=bool
+FLAG fizzy config explain --help type=bool
+FLAG fizzy config explain --ids-only type=bool
+FLAG fizzy config explain --jq type=string
+FLAG fizzy config explain --json type=bool
+FLAG fizzy config explain --limit type=int
+FLAG fizzy config explain --markdown type=bool
+FLAG fizzy config explain --profile type=string
+FLAG fizzy config explain --quiet type=bool
+FLAG fizzy config explain --styled type=bool
+FLAG fizzy config explain --token type=string
+FLAG fizzy config explain --verbose type=bool
+FLAG fizzy config help --agent type=bool
+FLAG fizzy config help --api-url type=string
+FLAG fizzy config help --count type=bool
+FLAG fizzy config help --help type=bool
+FLAG fizzy config help --ids-only type=bool
+FLAG fizzy config help --jq type=string
+FLAG fizzy config help --json type=bool
+FLAG fizzy config help --limit type=int
+FLAG fizzy config help --markdown type=bool
+FLAG fizzy config help --profile type=string
+FLAG fizzy config help --quiet type=bool
+FLAG fizzy config help --styled type=bool
+FLAG fizzy config help --token type=string
+FLAG fizzy config help --verbose type=bool
+FLAG fizzy config show --agent type=bool
+FLAG fizzy config show --api-url type=string
+FLAG fizzy config show --count type=bool
+FLAG fizzy config show --help type=bool
+FLAG fizzy config show --ids-only type=bool
+FLAG fizzy config show --jq type=string
+FLAG fizzy config show --json type=bool
+FLAG fizzy config show --limit type=int
+FLAG fizzy config show --markdown type=bool
+FLAG fizzy config show --profile type=string
+FLAG fizzy config show --quiet type=bool
+FLAG fizzy config show --styled type=bool
+FLAG fizzy config show --token type=string
+FLAG fizzy config show --verbose type=bool
+FLAG fizzy config view --agent type=bool
+FLAG fizzy config view --api-url type=string
+FLAG fizzy config view --count type=bool
+FLAG fizzy config view --help type=bool
+FLAG fizzy config view --ids-only type=bool
+FLAG fizzy config view --jq type=string
+FLAG fizzy config view --json type=bool
+FLAG fizzy config view --limit type=int
+FLAG fizzy config view --markdown type=bool
+FLAG fizzy config view --profile type=string
+FLAG fizzy config view --quiet type=bool
+FLAG fizzy config view --styled type=bool
+FLAG fizzy config view --token type=string
+FLAG fizzy config view --verbose type=bool
+FLAG fizzy doctor --agent type=bool
+FLAG fizzy doctor --all-profiles type=bool
+FLAG fizzy doctor --api-url type=string
+FLAG fizzy doctor --count type=bool
+FLAG fizzy doctor --help type=bool
+FLAG fizzy doctor --ids-only type=bool
+FLAG fizzy doctor --jq type=string
+FLAG fizzy doctor --json type=bool
+FLAG fizzy doctor --limit type=int
+FLAG fizzy doctor --markdown type=bool
+FLAG fizzy doctor --profile type=string
+FLAG fizzy doctor --quiet type=bool
+FLAG fizzy doctor --styled type=bool
+FLAG fizzy doctor --token type=string
+FLAG fizzy doctor --verbose type=bool
 FLAG fizzy help --agent type=bool
 FLAG fizzy help --api-url type=string
 FLAG fizzy help --count type=bool
@@ -3058,6 +3150,12 @@ SUB fizzy comment show
 SUB fizzy comment update
 SUB fizzy comment view
 SUB fizzy completion
+SUB fizzy config
+SUB fizzy config explain
+SUB fizzy config help
+SUB fizzy config show
+SUB fizzy config view
+SUB fizzy doctor
 SUB fizzy help
 SUB fizzy identity
 SUB fizzy identity help

internal/commands/commands.go

@@ -34,7 +34,7 @@ var commandCatalogGroups = map[string][]string{
 	"core":          {"board", "card", "column", "comment", "search", "step"},
 	"collaboration": {"notification", "pin", "reaction", "tag", "user"},
 	"admin":         {"auth", "account", "identity", "webhook", "upload", "migrate"},
-	"utilities":     {"setup", "signup", "completion", "skill", "commands", "version"},
+	"utilities":     {"setup", "signup", "completion", "doctor", "config", "skill", "commands", "version"},
 }
 
 var commandCatalogCategory = func() map[string]string {