Fix root help flags and command-specific usage hints

- show root-local flags like --version in custom root help
- use ExecuteC() so human usage errors know which command failed
- suggest <failed command> --help instead of always fizzy --help
- add regression tests for root help and usage hint behavior
- regenerate SURFACE.txt for Cobra default version flag

Author: robzolkos

SURFACE.txt

@@ -163,6 +163,7 @@ FLAG fizzy --quiet type=bool
 FLAG fizzy --styled type=bool
 FLAG fizzy --token type=string
 FLAG fizzy --verbose type=bool
+FLAG fizzy --version type=bool
 FLAG fizzy account --agent type=bool
 FLAG fizzy account --api-url type=string
 FLAG fizzy account --count type=bool

internal/commands/help.go

@@ -89,6 +89,9 @@ func renderHelp(cmd *cobra.Command, w io.Writer) {
 }
 
 func renderRootHelp(cmd *cobra.Command, w io.Writer) {
+	cmd.InitDefaultHelpFlag()
+	cmd.InitDefaultVersionFlag()
+
 	fmt.Fprintln(w, strings.TrimSpace(cmd.Long))
 	fmt.Fprintln(w)
 	fmt.Fprintln(w, "USAGE")
@@ -101,6 +104,12 @@ func renderRootHelp(cmd *cobra.Command, w io.Writer) {
 		printCommandList(w, group.Commands)
 	}
 
+	if flags := rootLocalFlags(cmd); len(flags) > 0 {
+		fmt.Fprintln(w)
+		fmt.Fprintln(w, "FLAGS")
+		printFlags(w, flags)
+	}
+
 	fmt.Fprintln(w)
 	fmt.Fprintln(w, "GLOBAL OUTPUT FLAGS")
 	printNamedFlags(w, cmd.PersistentFlags(), []string{"json", "quiet", "styled", "markdown", "ids-only", "count", "limit"})
@@ -122,6 +131,8 @@ func renderRootHelp(cmd *cobra.Command, w io.Writer) {
 }
 
 func renderCommandHelp(cmd *cobra.Command, w io.Writer) {
+	cmd.InitDefaultHelpFlag()
+
 	desc := strings.TrimSpace(cmd.Long)
 	if desc == "" {
 		desc = strings.TrimSpace(cmd.Short)
@@ -282,6 +293,24 @@ func printNamedFlags(w io.Writer, flags *pflag.FlagSet, names []string) {
 	printFlags(w, selected)
 }
 
+func rootLocalFlags(cmd *cobra.Command) []*pflag.Flag {
+	excluded := map[string]bool{
+		"agent": true, "api-url": true, "count": true, "ids-only": true,
+		"json": true, "limit": true, "markdown": true, "profile": true,
+		"quiet": true, "styled": true, "token": true, "verbose": true,
+	}
+
+	flags := visibleFlags(cmd.Flags())
+	result := make([]*pflag.Flag, 0, len(flags))
+	for _, f := range flags {
+		if excluded[f.Name] {
+			continue
+		}
+		result = append(result, f)
+	}
+	return result
+}
+
 func visibleFlags(flags *pflag.FlagSet) []*pflag.Flag {
 	var result []*pflag.Flag
 	flags.VisitAll(func(f *pflag.Flag) {

internal/commands/help_test.go

@@ -15,7 +15,7 @@ func TestRenderRootHelp(t *testing.T) {
 	renderHelp(rootCmd, &buf)
 	out := buf.String()
 
-	for _, want := range []string{"CORE COMMANDS", "GLOBAL OUTPUT FLAGS", "LEARN MORE"} {
+	for _, want := range []string{"CORE COMMANDS", "FLAGS", "--version", "GLOBAL OUTPUT FLAGS", "LEARN MORE"} {
 		if !strings.Contains(out, want) {
 			t.Fatalf("expected root help to contain %q, got:\n%s", want, out)
 		}

internal/commands/root.go

@@ -159,7 +159,8 @@ func Execute() {
 	// Default to Auto — PersistentPreRunE will re-resolve from parsed flags.
 	outWriter = os.Stdout
 	out = output.New(output.Options{Format: output.FormatAuto, Writer: os.Stdout})
-	if err := rootCmd.Execute(); err != nil {
+	cmd, err := rootCmd.ExecuteC()
+	if err != nil {
 		if format, formatErr := resolveFormat(); formatErr == nil {
 			out = output.New(output.Options{Format: format, Writer: os.Stdout})
 		}
@@ -170,7 +171,7 @@ func Execute() {
 			e = &output.Error{Code: output.CodeUsage, Message: err.Error()}
 		}
 		if isHumanOutput() {
-			printHumanError(e)
+			printHumanError(cmd, e)
 		} else {
 			_ = out.Err(e)
 		}
@@ -273,7 +274,7 @@ func requestedHumanOutput() bool {
 	return false
 }
 
-func printHumanError(err error) {
+func printHumanError(cmd *cobra.Command, err error) {
 	e := output.AsError(err)
 	msg := strings.TrimSpace(e.Message)
 	if msg != "" {
@@ -283,8 +284,19 @@ func printHumanError(err error) {
 		fmt.Fprintf(os.Stderr, "\nHint: %s\n", e.Hint)
 	}
 	if e.Code == output.CodeUsage && !strings.Contains(msg, "--help") {
-		fmt.Fprintln(os.Stderr, "\nRun `fizzy --help` for usage.")
+		fmt.Fprintf(os.Stderr, "\nRun `%s` for usage.\n", usageHelpCommand(cmd))
+	}
+}
+
+func usageHelpCommand(cmd *cobra.Command) string {
+	if cmd == nil {
+		return rootCmd.CommandPath() + " --help"
+	}
+	path := strings.TrimSpace(cmd.CommandPath())
+	if path == "" {
+		path = rootCmd.CommandPath()
 	}
+	return path + " --help"
 }
 
 func init() {

internal/commands/root_test.go

@@ -0,0 +1,73 @@
+package commands
+
+import (
+	"io"
+	"os"
+	"strings"
+	"testing"
+
+	"github.com/basecamp/cli/output"
+	"github.com/spf13/cobra"
+)
+
+func TestUsageHelpCommand(t *testing.T) {
+	tests := []struct {
+		name string
+		cmd  string
+		want string
+	}{
+		{name: "nil falls back to root", cmd: "", want: "fizzy --help"},
+		{name: "subcommand uses command path", cmd: "auth login", want: "fizzy auth login --help"},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			var cmd *cobra.Command
+			if tt.cmd != "" {
+				parts := strings.Split(tt.cmd, " ")
+				found, _, err := rootCmd.Find(parts)
+				if err != nil {
+					t.Fatalf("find command: %v", err)
+				}
+				cmd = found
+			}
+
+			if got := usageHelpCommand(cmd); got != tt.want {
+				t.Fatalf("expected %q, got %q", tt.want, got)
+			}
+		})
+	}
+}
+
+func TestPrintHumanErrorUsesCommandSpecificHelp(t *testing.T) {
+	oldStderr := os.Stderr
+	r, w, err := os.Pipe()
+	if err != nil {
+		t.Fatalf("pipe: %v", err)
+	}
+	os.Stderr = w
+	defer func() {
+		os.Stderr = oldStderr
+	}()
+
+	cmd, _, err := rootCmd.Find([]string{"auth", "login"})
+	if err != nil {
+		t.Fatalf("find command: %v", err)
+	}
+
+	printHumanError(cmd, &output.Error{Code: output.CodeUsage, Message: "accepts 1 arg(s), received 0"})
+	_ = w.Close()
+
+	body, err := io.ReadAll(r)
+	if err != nil {
+		t.Fatalf("read stderr: %v", err)
+	}
+
+	out := string(body)
+	if !strings.Contains(out, "Run `fizzy auth login --help` for usage.") {
+		t.Fatalf("expected command-specific usage hint, got:\n%s", out)
+	}
+	if strings.Contains(out, "Run `fizzy --help` for usage.") {
+		t.Fatalf("expected root usage hint to be omitted, got:\n%s", out)
+	}
+}

internal/commands/surface_test.go

@@ -58,6 +58,7 @@ func TestSurfaceSnapshot(t *testing.T) {
 func initAllHelpFlags(cmd *cobra.Command) {
 	cmd.InitDefaultHelpCmd()
 	cmd.InitDefaultHelpFlag()
+	cmd.InitDefaultVersionFlag()
 	for _, sub := range cmd.Commands() {
 		initAllHelpFlags(sub)
 	}