fix: resolve 7 CLI consistency issues from automated inspection

cmd/gh-aw/main.go

@@ -234,7 +234,7 @@ The --dependabot flag generates dependency manifests when dependencies are detec
 
 Examples:
   ` + string(constants.CLIExtensionPrefix) + ` compile                    # Compile all Markdown files
-  ` + string(constants.CLIExtensionPrefix) + ` compile ci-doctor    # Compile a specific workflow
+  ` + string(constants.CLIExtensionPrefix) + ` compile ci-doctor          # Compile a specific workflow
   ` + string(constants.CLIExtensionPrefix) + ` compile ci-doctor daily-plan  # Compile multiple workflows
   ` + string(constants.CLIExtensionPrefix) + ` compile workflow.md        # Compile by file path
   ` + string(constants.CLIExtensionPrefix) + ` compile --dir custom/workflows  # Compile from custom directory
@@ -416,6 +416,10 @@ Examples:
 var versionCmd = &cobra.Command{
 	Use:   "version",
 	Short: "Show gh aw extension version information",
+	Long: `Show the installed version of the gh aw extension.
+
+Examples:
+  ` + string(constants.CLIExtensionPrefix) + ` version   # Print the current version`,
 	RunE: func(cmd *cobra.Command, args []string) error {
 		fmt.Fprintf(os.Stderr, "%s version %s\n", string(constants.CLIExtensionPrefix), version)
 		return nil
@@ -466,6 +470,18 @@ func init() {
 	// Set version template to match the version subcommand format
 	rootCmd.SetVersionTemplate(string(constants.CLIExtensionPrefix) + " version {{.Version}}\n")
 
+	// Cobra generates flag descriptions using c.Name() which returns the first
+	// word of Use ("gh" from "gh aw"), producing "help for gh" and "version for
+	// gh". Explicitly initialize and override these flags so they display "gh aw".
+	rootCmd.InitDefaultHelpFlag()
+	if f := rootCmd.Flags().Lookup("help"); f != nil {
+		f.Usage = "Show help for " + string(constants.CLIExtensionPrefix)
+	}
+	rootCmd.InitDefaultVersionFlag()
+	if f := rootCmd.Flags().Lookup("version"); f != nil {
+		f.Usage = "Show version for " + string(constants.CLIExtensionPrefix)
+	}
+
 	// Fix usage lines so subcommands show "gh aw <cmd>" instead of "gh <cmd>".
 	// Cobra derives the root name from the first word of Use ("gh" from "gh aw"),
 	// so CommandPath() for subcommands omits "aw". We use SetUsageFunc to

pkg/cli/fix_command.go

@@ -46,10 +46,13 @@ The command will:
   1. Scan workflow files for deprecated fields
   2. Apply relevant codemods to fix issues
   3. Report what was changed in each file
-  4. Write updated files back to disk (with --write flag)
+
+Without --write (dry-run mode), no files are modified. With --write, the command performs
+all steps and additionally:
+  4. Write updated files back to disk
   5. Delete deprecated .github/aw/schemas/agentic-workflow.json file if it exists
-  6. Delete old template files from pkg/cli/templates/ (with --write flag)
-  7. Delete old workflow-specific .agent.md files from .github/agents/ (with --write flag)
+  6. Delete old template files from pkg/cli/templates/ if present
+  7. Delete old workflow-specific .agent.md files from .github/agents/ if present
 
 ` + WorkflowIDExplanation + `
 

pkg/cli/project_command.go

@@ -65,7 +65,7 @@ The project can optionally be linked to a specific repository.
 
 Authentication Requirements:
   The default GITHUB_TOKEN cannot create projects. You must use additional authentication.
-  See https://github.github.com/gh-aw/reference/auth/.
+  See https://github.github.com/gh-aw/reference/auth-projects/.
 
 Project Setup:
   Use --with-project-setup to automatically create:

pkg/cli/status.go

@@ -19,7 +19,7 @@ The optional pattern argument filters workflows by name (case-insensitive substr
 
 Examples:
   ` + string(constants.CLIExtensionPrefix) + ` status                          # Show all workflow status
-  ` + string(constants.CLIExtensionPrefix) + ` status ci-                       # Show workflows with 'ci-' in name
+  ` + string(constants.CLIExtensionPrefix) + ` status ci-                      # Show workflows with 'ci-' in name
   ` + string(constants.CLIExtensionPrefix) + ` status --json                    # Output in JSON format
   ` + string(constants.CLIExtensionPrefix) + ` status --ref main                # Show latest run status for main branch
   ` + string(constants.CLIExtensionPrefix) + ` status --label automation        # Show workflows with 'automation' label

pkg/cli/tokens_bootstrap.go

@@ -33,8 +33,10 @@ This command:
 Only required secrets are prompted for. Optional secrets are not shown.
 
 For full details, including precedence rules, see the GitHub Tokens
-reference in the documentation.`,
-		Example: `  gh aw secrets bootstrap                        # Check and set up all required secrets
+reference in the documentation.
+
+Examples:
+  gh aw secrets bootstrap                        # Check and set up all required secrets
   gh aw secrets bootstrap --non-interactive      # Display missing secrets without prompting
   gh aw secrets bootstrap --engine copilot       # Check secrets for a specific engine`,
 		RunE: func(cmd *cobra.Command, args []string) error {

pkg/cli/trial_command.go

@@ -110,7 +110,7 @@ Advanced examples:
 Repository modes:
 - Default mode (no flags): Creates a temporary trial repository and simulates execution as if running against the current repository (github.repository context points to current repo)
 - --logical-repo REPO: Simulates execution against a specified repository (github.repository context points to REPO while actually running in a temporary trial repository)
-- --repo REPO: Runs directly in the specified repository (no simulation, workflows installed and executed in REPO)
+- --host-repo REPO (or --repo REPO): Uses the specified repository as the host for trial execution instead of creating a temporary one
 - --clone-repo REPO: Clones the specified repository's contents into the trial repository before execution (useful for testing against actual repository state)
 
 All workflows must support workflow_dispatch trigger to be used in trial mode.