fix: resolve 11 CLI help text consistency issues (#26047)

Author: Copilot

cmd/gh-aw/main.go

@@ -86,11 +86,12 @@ var rootCmd = &cobra.Command{
 
 Common Tasks:
   gh aw init                  # Set up a new repository
+  gh aw add-wizard            # Add workflows with interactive guided setup
   gh aw new my-workflow       # Create your first workflow
   gh aw compile               # Compile all workflows
   gh aw run my-workflow       # Execute a workflow
   gh aw logs my-workflow      # View execution logs
-  gh aw audit <run-id>        # Debug a failed run
+  gh aw audit <run-id-or-url> # Debug a failed run
 
 For detailed help on any command, use:
   gh aw [command] --help`,
@@ -163,19 +164,19 @@ Examples:
 }
 
 var removeCmd = &cobra.Command{
-	Use:   "remove [pattern]",
-	Short: "Remove agentic workflow files matching the given pattern",
-	Long: `Remove agentic workflow files matching the given workflow-id pattern.
+	Use:   "remove [filter]",
+	Short: "Remove agentic workflow files matching the given filter",
+	Long: `Remove agentic workflow files matching the given filter.
 
 The workflow-id is the basename of the Markdown file without the .md extension.
-You can provide a workflow-id prefix to remove multiple workflows, or a specific workflow-id.
+You can provide a substring to match multiple workflows, or a specific workflow-id.
 
 By default, this command also removes orphaned include files that are no longer referenced
 by any workflow. Use --keep-orphans to skip this cleanup.
 
 Examples:
   ` + string(constants.CLIExtensionPrefix) + ` remove my-workflow              # Remove specific workflow
-  ` + string(constants.CLIExtensionPrefix) + ` remove test-                    # Remove all workflows starting with 'test-'
+  ` + string(constants.CLIExtensionPrefix) + ` remove test-                    # Remove all workflows containing 'test-' in name
   ` + string(constants.CLIExtensionPrefix) + ` remove old- --keep-orphans      # Remove workflows but keep orphaned includes
   ` + string(constants.CLIExtensionPrefix) + ` remove my-workflow --dir .github/workflows/shared  # Remove from custom directory`,
 	RunE: func(cmd *cobra.Command, args []string) error {

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

@@ -14,10 +14,13 @@ The `gh aw` CLI extension enables developers to create, manage, and execute AI-p
 | [`gh aw init`](#init) | Set up your repository for agentic workflows |
 | [`gh aw add-wizard`](#add-wizard) | Add workflows with interactive guided setup |
 | [`gh aw add`](#add) | Add workflows from other repositories (non-interactive) |
+| [`gh aw new`](#new) | Create a new workflow from scratch |
 | [`gh aw compile`](#compile) | Convert markdown to GitHub Actions YAML |
 | [`gh aw list`](#list) | Quick listing of all workflows |
 | [`gh aw run`](#run) | Execute workflows immediately in GitHub Actions |
 | [`gh aw status`](#status) | Check current state of all workflows |
+| [`gh aw logs`](#logs) | Download and analyze workflow logs |
+| [`gh aw audit`](#audit) | Debug a failed workflow run |
 
 ## Installation
 

pkg/cli/audit.go

@@ -45,13 +45,6 @@ When a job URL is provided:
 - If no step number, finds and extracts the first failing step's output
 - Saves job logs to the output directory
 
-This command:
-- Downloads artifacts and logs for the specified run ID
-- Detects errors and warnings in the logs
-- Analyzes MCP tool usage statistics
-- Extracts missing tool reports
-- Generates a concise Markdown report
-
 Examples:
   ` + string(constants.CLIExtensionPrefix) + ` audit 1234567890     # Audit run with ID 1234567890
   ` + string(constants.CLIExtensionPrefix) + ` audit https://github.com/owner/repo/actions/runs/1234567890  # Audit from run URL

pkg/cli/list_workflows_command.go

@@ -72,7 +72,7 @@ Examples:
 	addJSONFlag(cmd)
 	cmd.Flags().String("label", "", "Filter workflows by label")
 	cmd.Flags().String("path", ".github/workflows", "Path to workflows directory in the remote repository (used with --repo)")
-	cmd.Flags().StringP("dir", "d", "", "Local workflow directory (overrides default .github/workflows; ignored when --repo is set)")
+	cmd.Flags().StringP("dir", "d", "", "Workflow directory (default: .github/workflows; ignored when --repo is set)")
 
 	// Register completions for list command
 	cmd.ValidArgsFunction = CompleteWorkflowNames

pkg/cli/logs_command.go

@@ -57,8 +57,8 @@ Examples:
   # Date filtering
   ` + string(constants.CLIExtensionPrefix) + ` logs --start-date 2024-01-01   # Download all runs after date
   ` + string(constants.CLIExtensionPrefix) + ` logs --end-date 2024-01-31     # Download all runs before date
-  ` + string(constants.CLIExtensionPrefix) + ` logs --start-date -1w          # Download all runs from last week
-  ` + string(constants.CLIExtensionPrefix) + ` logs --start-date -1w -c 5     # Download all runs from last week, show up to 5
+  ` + string(constants.CLIExtensionPrefix) + ` logs --start-date -1w          # Download up to 10 runs from last week
+  ` + string(constants.CLIExtensionPrefix) + ` logs --start-date -1w -c 5     # Download up to 5 runs from last week
   ` + string(constants.CLIExtensionPrefix) + ` logs --end-date -1d            # Download all runs until yesterday
   ` + string(constants.CLIExtensionPrefix) + ` logs --start-date -1mo         # Download all runs from last month
 
@@ -208,7 +208,7 @@ Examples:
 	addJSONFlag(logsCmd)
 	logsCmd.Flags().Int("timeout", 0, "Download timeout in minutes (0 = no timeout)")
 	logsCmd.Flags().String("summary-file", "summary.json", "Path to write the summary JSON file relative to output directory (use empty string to disable)")
-	logsCmd.Flags().Bool("train", false, "Train drain3 log template weights from downloaded runs and write drain3_weights.json to the output directory")
+	logsCmd.Flags().Bool("train", false, "Train Drain3 (log template mining) weights from downloaded runs and write drain3_weights.json to the output directory")
 	logsCmd.Flags().String("format", "", "Output format for cross-run audit report: markdown, pretty (generates security audit report instead of default metrics table)")
 	logsCmd.Flags().Int("last", 0, "Alias for --count: number of recent runs to download")
 	logsCmd.Flags().StringSlice("artifacts", nil, "Artifact sets to download (default: all). Valid sets: "+strings.Join(ValidArtifactSetNames(), ", "))

pkg/cli/remove_command.go

@@ -59,7 +59,7 @@ func RemoveWorkflows(pattern string, keepOrphans bool, workflowDir string) error
 				fmt.Fprintf(os.Stderr, "  %s\n", name)
 			}
 		}
-		fmt.Fprintln(os.Stderr, console.FormatInfoMessage(fmt.Sprintf("\nUsage: %s remove <pattern>", string(constants.CLIExtensionPrefix))))
+		fmt.Fprintln(os.Stderr, console.FormatInfoMessage(fmt.Sprintf("\nUsage: %s remove <filter>", string(constants.CLIExtensionPrefix))))
 		return nil
 	}
 

pkg/cli/tokens_bootstrap.go

@@ -24,12 +24,6 @@ func newSecretsBootstrapSubcommand() *cobra.Command {
 are required, check which ones are already configured, and interactively
 prompt for any missing required secrets.
 
-This command:
-- Discovers all workflow files in .github/workflows/
-- Analyzes required secrets for each workflow's engine
-- Checks which secrets already exist in the repository
-- Interactively prompts for missing required secrets (unless --non-interactive)
-
 Only required secrets are prompted for. Optional secrets are not shown.
 
 For full details, including precedence rules, see the GitHub Tokens

pkg/cli/trial_command.go

@@ -30,7 +30,7 @@ Workflows from different repositories:
   ` + string(constants.CLIExtensionPrefix) + ` trial githubnext/agentics/daily-plan myorg/myrepo/custom-workflow
 
 Repository mode examples:
-  ` + string(constants.CLIExtensionPrefix) + ` trial githubnext/agentics/my-workflow --host-repo myorg/myrepo         # Run directly in myorg/myrepo (no simulation)
+  ` + string(constants.CLIExtensionPrefix) + ` trial githubnext/agentics/my-workflow --host-repo myorg/myrepo         # Use myorg/myrepo as host for trial execution
   ` + string(constants.CLIExtensionPrefix) + ` trial githubnext/agentics/my-workflow --logical-repo myorg/myrepo  # Simulate running against myorg/myrepo
   ` + string(constants.CLIExtensionPrefix) + ` trial githubnext/agentics/my-workflow --clone-repo myorg/myrepo   # Clone myorg/myrepo contents into host
 
@@ -127,7 +127,7 @@ Trial results are saved both locally (in trials/ directory) and in the host repo
 	cmd.Flags().Bool("force-delete-host-repo-before", false, "Force delete the host repository before creation if it already exists")
 	cmd.Flags().BoolP("yes", "y", false, "Skip confirmation prompts")
 	cmd.Flags().Bool("dry-run", false, "Show what would be done without making any changes")
-	cmd.Flags().Int("timeout", 30, "Execution timeout in minutes (e.g., 30 for 30 minutes)")
+	cmd.Flags().Int("timeout", 30, "Execution timeout in minutes")
 	cmd.Flags().String("trigger-context", "", "Trigger context URL (e.g., GitHub issue URL) for issue-triggered workflows")
 	cmd.Flags().Int("repeat", 0, "Number of additional times to run after the initial execution (e.g., --repeat 3 runs 4 times total)")
 	cmd.Flags().Bool("auto-merge-prs", false, "Auto-merge any pull requests created during trial execution")

pkg/cli/upgrade_command.go

@@ -51,13 +51,6 @@ Use --audit to check dependency health without performing upgrades. This include
 
 The --audit flag skips the normal upgrade process.
 
-The upgrade process ensures:
-- Dispatcher agent is current (.github/agents/agentic-workflows.agent.md)
-- All workflows use the latest syntax and configuration options
-- Deprecated fields are automatically migrated across all workflows
-- GitHub Actions are pinned to the latest versions
-- All workflows are compiled and lock files are up-to-date
-
 This command always upgrades all Markdown files in .github/workflows.
 
 Examples: