Align CLI help text, shared flag usage, and setup docs

[Copilot]

This addresses a batch of CLI consistency issues across command help text, flag descriptions, and docs/src/content/docs/setup/cli.md. The main gaps were drift between CLI/docs, inconsistent wording across related commands, and duplicated engine flag usage strings.

• Root and command help alignment

  • normalized the root help header and common-task formatting
  • updated run examples to build from constants.CLIExtensionPrefix instead of hardcoded gh aw
  • standardized wording for version, disable, compile, and run help text
  • clarified compile action pinning language around --gh-aw-ref, --action-tag, --show-all, and safe-update approval text

• Shared flag usage

  • promoted engine override/filter help text to shared constants in pkg/cli/flags.go
  • switched new, compile, and run to consume the shared engine usage string instead of duplicating literal text

• Docs parity

  • added a missing doctor section under setup docs, including purpose, --repo, and representative usage
  • aligned docs wording for run --push and version
  • added doctor to the common command table so visible setup commands are documented where users expect them

• Command copy cleanup

  • tightened short descriptions for fix, project, experiments, env get, env update, and secrets bootstrap
  • aligned wording with actual command behavior and existing repository terminology

• Focused test updates

  • updated CLI consistency tests to match the revised help text and newly documented doctor command
  • adjusted project command expectations to reflect the new short description

Example of the run example cleanup:

Example: `  ` + string(constants.CLIExtensionPrefix) + ` run                          # Interactive mode
  ` + string(constants.CLIExtensionPrefix) + ` run daily-perf-improver --push  # Commit, push, and dispatch the workflow`,

[Copilot]

Pull request overview

This pull request improves consistency across gh aw CLI help text, shared flag usage strings, and the setup CLI documentation, with corresponding test updates to keep the CLI/docs contract stable.

Changes:

• Standardizes multiple command short/long descriptions and example blocks (including run, version, compile, and root help).
• Promotes --engine override/filter help text into shared constants and updates consumers/tests to use them.
• Updates setup docs to include doctor and aligns additional doc wording with current CLI output.

Show a summary per file

File	Description
pkg/cli/tokens_bootstrap.go	Updates secrets bootstrap short help text to reflect interactive configuration behavior.
pkg/cli/project_command.go	Expands project short help text to include management capabilities.
pkg/cli/project_command_test.go	Updates tests to match revised project short description.
pkg/cli/flags.go	Introduces shared engine flag usage constants and uses them in flag helpers.
pkg/cli/flags_test.go	Updates engine flag usage assertions to reference shared constants.
pkg/cli/fix_command.go	Refines fix short help text to better describe behavior/defaults.
pkg/cli/experiments_command.go	Clarifies experiments short help text to match branch-based behavior.
pkg/cli/env_command.go	Clarifies env get/update short help text as compiler-default variables.
pkg/cli/cli_consistency_help_test.go	Extends CLI/docs parity tests to include doctor and revised version wording.
docs/src/content/docs/setup/cli.md	Adds doctor documentation, updates run --push wording, and aligns version description.
cmd/gh-aw/main.go	Aligns root/command help text, uses shared engine usage text, and refines multiple flag descriptions/examples.
cmd/gh-aw/main_help_text_test.go	Adjusts help-text consistency tests for --approve and --show-all wording changes.

Review details

Tip

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

• Files reviewed: 12/12 changed files
• Comments generated: 3
• Review effort level: Low

[gh-aw-bot]

pr-sous-chef
@copilot please run the pr-finisher skill, address these unresolved review comments, and rerun checks once finished:

• Copilot: Align CLI help text, shared flag usage, and setup docs #45753 (comment)
• Copilot: Align CLI help text, shared flag usage, and setup docs #45753 (comment)
• Copilot: Align CLI help text, shared flag usage, and setup docs #45753 (comment)

Run: https://github.com/github/gh-aw/actions/runs/29430208879

Generated by 👨‍🍳 PR Sous Chef · 12.9 AIC · ⌖ 5.6 AIC · ⊞ 7.5K · ◷
_{Comment /souschef to run again}

[Copilot]

pr-sous-chef
@copilot please run the pr-finisher skill, address these unresolved review comments, and rerun checks once finished:

• Copilot: Align CLI help text, shared flag usage, and setup docs #45753 (comment)...

Addressed in cc94a1c. I fixed the three remaining review items: the root help examples now use constants.CLIExtensionPrefix, run --approve now says "safe update", and the doctor docs now match the actual flags/behavior. I also reran focused local validation for the touched areas plus PR validation on the pushed diff.

[github-actions]

🎉 This pull request is included in a new release.

Release: v0.82.10