Refine root and commands UX

[robzolkos]

Summary

• make bare fizzy behave more like basecamp, with concise TTY help and quick-start JSON for non-TTY use
• move the full catalog to fizzy commands, with grouped TTY output and filtered detail on demand
• keep the animated banner in interactive setup/signup flows instead of showing it on bare root

Testing

• go test ./internal/commands/...
• make build

---

Summary by cubic

Refines the root UX and command catalog. Bare fizzy shows concise help in TTY and returns a quick‑start JSON for non‑TTY. The full catalog lives under fizzy commands with grouping, filtering, action hints, and JSON category.

• New Features

  • fizzy commands [filter] (alias cmds): grouped, styled TTY catalog; when filtered, shows subcommand actions; --json returns a structured catalog with category; filter matches names/paths/descriptions and sorts items.
  • Bare fizzy (non‑TTY): quick‑start JSON with version, auth status/profile/account, board context, suggested commands, and breadcrumbs; TTY shows concise help.

• Refactors

  • Removed the root banner from help flows (kept in interactive setup/signup); deleted the unused banner helper.
  • Root help reorganized: new groups (Core, Collaboration, Getting Started, Discover), a single FLAGS block (--json, --jq, --quiet, --profile, --verbose), and clearer guidance to use fizzy commands; added cmds and its flags to the public surface.
  • Simplified quick‑start auth profile handling by removing a redundant assignment.

^{Written for commit acc3975. Summary will update on new commits.}

[github-actions]

⚠️ Potential breaking changes detected:

• The addition of a new alias 'cmds' for the 'commands' CLI command may potentially break scripts that rely on strict argument handling or explicit use of the primary command name 'commands'.
• The removal of the 'completion' command from the root command group effectively changes its availability and categorization, which may affect users who relied on its previous organization.
• The removal of the 'banner.go' file eliminates the 'printBanner' function usage, which previously printed a banner during the root and help commands, potentially breaking automation or tests that relied on its presence.

Review carefully before merging. Consider a major version bump.

[cubic-dev-ai]

No issues found across 8 files

[Copilot]

Pull request overview

This PR refines the root command and fizzy commands UX to provide a more concise root help while maintaining a comprehensive command catalog. When running bare fizzy, the CLI now returns concise TTY help or quick-start JSON for non-TTY environments, similar to the Basecamp CLI. The full command catalog has been moved to fizzy commands (with cmds alias) with grouped display, filtering support, and optional action detail views.

Changes:

• Bare fizzy invocation now returns concise help for TTY or quick-start JSON for non-TTY (no banner on root)
• fizzy commands command now supports filtering by name/description, with categorized display and action lists
• Root help reorganized into four categories (core, collaboration, getting-started, discover) instead of all commands
• Full command catalog (fizzy commands --json) maintains comprehensive organization (core, collaboration, admin, utilities)
• Animated banner moved to interactive setup/signup flows only

Reviewed changes

Copilot reviewed 9 out of 9 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
internal/commands/root.go	Added RunE handler (runRootDefault) to bare root command
internal/commands/quickstart.go	New file with quick-start JSON response structure and logic
internal/commands/help.go	Removed banner from root help, simplified root command groups, added "LEARN MORE" reference to full catalog
internal/commands/help_test.go	Updated root help test to verify new section headings and content
internal/commands/commands.go	Added filter support, human-readable catalog rendering, category assignments, and cmds alias
internal/commands/commands_test.go	Updated and added tests for catalog rendering and filtering
internal/commands/format_test.go	Added test for bare root non-TTY JSON response
SURFACE.txt	Added cmds command/alias and filter argument references

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.