[cli-consistency] Normalize CLI help text and setup docs across run/upgrade/secrets/mcp-server

cmd/gh-aw/main.go

@@ -362,7 +362,7 @@ var runCmd = &cobra.Command{
 	Short: "Run one or more agentic workflows on GitHub Actions",
 	Long: `Run one or more agentic workflows on GitHub Actions using the workflow_dispatch trigger.
 
-When called without workflow arguments, enters interactive mode with:
+When called without workflow arguments, this command enters interactive mode and shows:
 - List of workflows that support workflow_dispatch
 - Display of required and optional inputs
 - Input collection with validation
@@ -735,7 +735,7 @@ Use "` + string(constants.CLIExtensionPrefix) + ` help all" to show help for all
 	runCmd.Flags().Bool("push", false, "Commit and push workflow files (including transitive imports) before running")
 	runCmd.Flags().Bool("dry-run", false, "Validate workflow without actually triggering execution on GitHub Actions")
 	runCmd.Flags().BoolP("json", "j", false, "Output results in JSON format")
-	runCmd.Flags().Bool("approve", false, "Approve all safe update changes during compilation (skip safe update enforcement)")
+	runCmd.Flags().Bool("approve", false, "Approve all safe update changes. When strict mode is active (the default), the compiler emits warnings for new restricted secrets or unapproved action additions/removals not present in the existing gh-aw-manifest. Use this flag to approve and skip safe update enforcement")
 	// Register completions for run command
 	runCmd.ValidArgsFunction = cli.CompleteWorkflowNames
 	cli.RegisterEngineFlagCompletion(runCmd)

cmd/gh-aw/main_help_text_test.go

@@ -0,0 +1,20 @@
+//go:build !integration
+
+package main
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestRunCommandHelpTextConsistency(t *testing.T) {
+	assert.Contains(t, runCmd.Long, "this command enters interactive mode and shows", "run command interactive mode text should be explicit")
+
+	runApprove := runCmd.Flags().Lookup("approve")
+	compileApprove := compileCmd.Flags().Lookup("approve")
+	require.NotNil(t, runApprove, "run command should define --approve")
+	require.NotNil(t, compileApprove, "compile command should define --approve")
+	assert.Equal(t, compileApprove.Usage, runApprove.Usage, "run and compile should share the same --approve description")
+}

docs/src/content/docs/setup/cli.md

@@ -220,7 +220,7 @@ gh aw secrets bootstrap --engine copilot                 # Check only Copilot se
 gh aw secrets bootstrap --non-interactive                # Display missing secrets without prompting
 ```
 
-**Options:** `--engine` (copilot, claude, codex), `--non-interactive`, `--repo`
+**Options:** `--engine` (copilot, claude, codex, gemini), `--non-interactive`, `--repo`
 
 See [Authentication](/gh-aw/reference/auth/) for details.
 
@@ -603,7 +603,7 @@ gh aw mcp-server --validate-actor     # Enable actor validation
 
 **Options:** `--port` (HTTP server port), `--cmd` (custom subprocess command), `--validate-actor` (enforce actor validation for logs and audit tools)
 
-**Available Tools:** status, compile, logs, audit, mcp-inspect, add, update, fix
+**Available Tools:** status, compile, logs, audit, checks, mcp-inspect, add, update, fix
 
 When `--validate-actor` is enabled, logs and audit tools require write+ repository access via GitHub API (permissions cached for 1 hour). See [MCP Server Guide](/gh-aw/reference/gh-aw-as-mcp-server/).
 

pkg/cli/mcp_add.go

@@ -361,7 +361,7 @@ Registry URL defaults to: https://api.mcp.github.com/v0.1`,
 	}
 
 	cmd.Flags().StringVar(&registryURL, "registry", "", "MCP registry URL (default: https://api.mcp.github.com/v0.1)")
-	cmd.Flags().StringVar(&transportType, "transport", "", "Preferred transport type (stdio, http, docker)")
+	cmd.Flags().StringVar(&transportType, "transport", "", "Preferred transport type (stdio, http, Docker)")
 	cmd.Flags().StringVar(&customToolID, "tool-id", "", "Custom tool ID to use in the workflow (default: uses server ID)")
 
 	return cmd

pkg/cli/mcp_add_test.go

@@ -157,6 +157,18 @@ This is a test workflow.
 	}
 }
 
+func TestMCPAddTransportFlagDescriptionUsesDockerCapitalization(t *testing.T) {
+	cmd := NewMCPAddSubcommand()
+	transportFlag := cmd.Flags().Lookup("transport")
+	if transportFlag == nil {
+		t.Fatal("expected --transport flag to exist")
+	}
+
+	if !strings.Contains(transportFlag.Usage, "Docker") {
+		t.Fatalf("expected --transport usage to include Docker, got: %s", transportFlag.Usage)
+	}
+}
+
 func TestAddMCPTool_WorkflowNotFound(t *testing.T) {
 	// Create a temporary directory for testing
 	tempDir, err := os.MkdirTemp("", "gh-aw-test-*")

pkg/cli/secrets_command_test.go

@@ -5,6 +5,7 @@ package cli
 import (
 	"testing"
 
+	"github.com/spf13/cobra"
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
 )
@@ -66,3 +67,21 @@ func TestSecretsCommandStructure(t *testing.T) {
 		})
 	}
 }
+
+func TestSecretsBootstrapEngineFlagIncludesGemini(t *testing.T) {
+	cmd := NewSecretsCommand()
+
+	var bootstrapCmd *cobra.Command
+	for _, subcmd := range cmd.Commands() {
+		if subcmd.Name() == "bootstrap" {
+			bootstrapCmd = subcmd
+			break
+		}
+	}
+
+	require.NotNil(t, bootstrapCmd, "bootstrap subcommand should exist")
+
+	engineFlag := bootstrapCmd.Flags().Lookup("engine")
+	require.NotNil(t, engineFlag, "--engine flag should exist on bootstrap")
+	assert.Contains(t, engineFlag.Usage, "gemini", "--engine help should include gemini engine")
+}

pkg/cli/tokens_bootstrap.go

@@ -40,7 +40,7 @@ Examples:
 	}
 
 	cmd.Flags().BoolVar(&nonInteractiveFlag, "non-interactive", false, "Check secrets without prompting (display-only mode)")
-	cmd.Flags().StringVarP(&engineFlag, "engine", "e", "", "Check tokens for specific engine (copilot, claude, codex)")
+	cmd.Flags().StringVarP(&engineFlag, "engine", "e", "", "Check tokens for specific engine (copilot, claude, codex, gemini)")
 	addRepoFlag(cmd)
 
 	return cmd

pkg/cli/upgrade_command.go

@@ -34,7 +34,7 @@ func NewUpgradeCommand() *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "upgrade",
 		Short: "Upgrade repository with latest agent files and apply codemods to all workflows",
-		Long: `Upgrade the repository for the latest version of agentic workflows.
+		Long: `Upgrade the repository to the latest version of agentic workflows.
 
 This command:
   1. Updates the dispatcher agent file to the latest template (like 'init' command)
@@ -111,7 +111,7 @@ Examples:
 	cmd.Flags().Bool("pr", false, "Alias for --create-pull-request")
 	_ = cmd.Flags().MarkHidden("pr") // Hide the short alias from help output
 	cmd.Flags().Bool("audit", false, "Check dependency health without performing upgrades")
-	cmd.Flags().Bool("approve", false, "Approve all safe update changes during compilation (skip safe update enforcement)")
+	cmd.Flags().Bool("approve", false, "Approve all safe update changes. When strict mode is active (the default), the compiler emits warnings for new restricted secrets or unapproved action additions/removals not present in the existing gh-aw-manifest. Use this flag to approve and skip safe update enforcement")
 	cmd.Flags().Bool("skip-extension-upgrade", false, "Skip automatic extension upgrade (used internally to prevent recursion after upgrade)")
 	_ = cmd.Flags().MarkHidden("skip-extension-upgrade")
 	addJSONFlag(cmd)

pkg/cli/upgrade_command_test.go

@@ -0,0 +1,21 @@
+//go:build !integration
+
+package cli
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestUpgradeCommandHelpTextConsistency(t *testing.T) {
+	cmd := NewUpgradeCommand()
+	require.NotNil(t, cmd, "upgrade command should be created")
+
+	assert.Contains(t, cmd.Long, "Upgrade the repository to the latest version of agentic workflows.", "long description should use correct grammar")
+
+	approveFlag := cmd.Flags().Lookup("approve")
+	require.NotNil(t, approveFlag, "--approve flag should exist")
+	assert.Contains(t, approveFlag.Usage, "When strict mode is active", "--approve description should match compile semantics")
+}