From 7935ec418badc5e0e31de29af2d43e3e69888408 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Fri, 12 Jun 2026 21:54:19 +0000
Subject: [PATCH 1/4] Initial plan


From df3411438b6863dc551a702e546275ebf33dc2ef Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Fri, 12 Jun 2026 22:26:46 +0000
Subject: [PATCH 2/4] Migrate cobra command Examples from Long: prose to
 Example: field

Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>
---
 pkg/cli/add_command.go            | 27 +++++++++++++--------------
 pkg/cli/add_wizard_command.go     | 21 ++++++++++-----------
 pkg/cli/audit.go                  |  6 ++----
 pkg/cli/audit_diff_command.go     |  6 ++----
 pkg/cli/checks_command.go         |  6 ++----
 pkg/cli/completion_command.go     | 18 ++++++------------
 pkg/cli/deploy_command.go         |  6 ++----
 pkg/cli/domains_command.go        |  6 ++----
 pkg/cli/experiments_command.go    | 18 ++++++------------
 pkg/cli/fix_command.go            |  6 ++----
 pkg/cli/forecast_command.go       |  6 ++----
 pkg/cli/hash_command.go           |  6 ++----
 pkg/cli/health_command.go         |  6 ++----
 pkg/cli/init_command.go           |  6 ++----
 pkg/cli/lint_command.go           |  6 ++----
 pkg/cli/list_workflows_command.go |  6 ++----
 pkg/cli/logs_command.go           |  6 ++----
 pkg/cli/mcp.go                    |  6 ++----
 pkg/cli/mcp_add.go                | 13 ++++++-------
 pkg/cli/mcp_inspect.go            | 17 ++++++++---------
 pkg/cli/mcp_list.go               | 11 +++++------
 pkg/cli/mcp_list_tools.go         | 11 +++++------
 pkg/cli/mcp_server_command.go     |  6 ++----
 pkg/cli/outcomes_command.go       |  6 ++----
 pkg/cli/outcomes_history.go       |  6 ++----
 pkg/cli/pr_command.go             | 12 ++++--------
 pkg/cli/project_command.go        | 12 ++++--------
 pkg/cli/secret_set_command.go     |  6 ++----
 pkg/cli/secrets_command.go        |  6 ++----
 pkg/cli/status.go                 |  6 ++----
 pkg/cli/tokens_bootstrap.go       |  6 ++----
 pkg/cli/trial_command.go          | 23 +++++++++++------------
 pkg/cli/update_command.go         |  6 ++----
 pkg/cli/upgrade_command.go        |  6 ++----
 pkg/cli/validate_command.go       |  6 ++----
 pkg/cli/view_command.go           |  6 ++----
 36 files changed, 128 insertions(+), 205 deletions(-)

diff --git a/pkg/cli/add_command.go b/pkg/cli/add_command.go
index 1a288dbe7a0..d746b50428e 100644
--- a/pkg/cli/add_command.go
+++ b/pkg/cli/add_command.go
@@ -59,20 +59,6 @@ func NewAddCommand(validateEngine func(string) error) *cobra.Command {
 This command adds workflows directly without interactive prompts. Use 'add-wizard'
 for a guided setup that configures secrets, creates a pull request, and more.
 
-Examples:
-  ` + string(constants.CLIExtensionPrefix) + ` add githubnext/agentics/daily-repo-status        # Add workflow directly
-  ` + string(constants.CLIExtensionPrefix) + ` add githubnext/agentics/repo-assist              # Add package from repository root aw.yml
-  ` + string(constants.CLIExtensionPrefix) + ` add githubnext/agentics/packages/repo-assist     # Add package from nested aw.yml
-  ` + string(constants.CLIExtensionPrefix) + ` add githubnext/agentics/ci-doctor@v1.0.0         # Add with version
-  ` + string(constants.CLIExtensionPrefix) + ` add githubnext/agentics/workflows/ci-doctor.md@main
-  ` + string(constants.CLIExtensionPrefix) + ` add https://github.com/githubnext/agentics/blob/main/workflows/ci-doctor.md
-  ` + string(constants.CLIExtensionPrefix) + ` add https://example.com/my-workflow.md           # Add workflow from any HTTPS URL
-  ` + string(constants.CLIExtensionPrefix) + ` add https://example.com/workflow.json            # Import JSON workflow definition
-  ` + string(constants.CLIExtensionPrefix) + ` add githubnext/agentics/ci-doctor --create-pull-request --force
-  ` + string(constants.CLIExtensionPrefix) + ` add ./my-workflow.md                             # Add local workflow
-  ` + string(constants.CLIExtensionPrefix) + ` add ./*.md                                       # Add all local workflows
-  ` + string(constants.CLIExtensionPrefix) + ` add githubnext/agentics/ci-doctor --dir .github/workflows/shared   # Add to .github/workflows/shared/
-
 Workflow specifications:
   - Two parts: "owner/repo[@version]" (loads repository-root aw.yml package)
   - Three+ parts without .md: "owner/repo/folder[@version]" (loads nested aw.yml package when present)
@@ -96,6 +82,19 @@ Note: In GitHub Enterprise repos, shorthand source specs resolve on your enterpr
       Use full https://github.com/... source URLs for other public github.com workflows.
 Note: To create a new workflow from scratch, use the 'new' command instead.
 Note: For guided interactive setup, use the 'add-wizard' command instead.`,
+		Example: `  ` + string(constants.CLIExtensionPrefix) + ` add githubnext/agentics/daily-repo-status        # Add workflow directly
+  ` + string(constants.CLIExtensionPrefix) + ` add githubnext/agentics/repo-assist              # Add package from repository root aw.yml
+  ` + string(constants.CLIExtensionPrefix) + ` add githubnext/agentics/packages/repo-assist     # Add package from nested aw.yml
+  ` + string(constants.CLIExtensionPrefix) + ` add githubnext/agentics/ci-doctor@v1.0.0         # Add with version
+  ` + string(constants.CLIExtensionPrefix) + ` add githubnext/agentics/workflows/ci-doctor.md@main
+  ` + string(constants.CLIExtensionPrefix) + ` add https://github.com/githubnext/agentics/blob/main/workflows/ci-doctor.md
+  ` + string(constants.CLIExtensionPrefix) + ` add https://example.com/my-workflow.md           # Add workflow from any HTTPS URL
+  ` + string(constants.CLIExtensionPrefix) + ` add https://example.com/workflow.json            # Import JSON workflow definition
+  ` + string(constants.CLIExtensionPrefix) + ` add githubnext/agentics/ci-doctor --create-pull-request --force
+  ` + string(constants.CLIExtensionPrefix) + ` add ./my-workflow.md                             # Add local workflow
+  ` + string(constants.CLIExtensionPrefix) + ` add ./*.md                                       # Add all local workflows
+  ` + string(constants.CLIExtensionPrefix) + ` add githubnext/agentics/ci-doctor --dir .github/workflows/shared   # Add to .github/workflows/shared/
+`,
 		Args: func(cmd *cobra.Command, args []string) error {
 			if len(args) < 1 {
 				return fmt.Errorf("missing workflow specification\n\nUsage:\n  %s <workflow>...\n\nExamples:\n  %[1]s githubnext/agentics/daily-repo-status      Add from repository\n  %[1]s ./my-workflow.md                           Add local workflow\n\nRun '%[1]s --help' for more information", cmd.CommandPath())
diff --git a/pkg/cli/add_wizard_command.go b/pkg/cli/add_wizard_command.go
index b71433b75be..1139fb84014 100644
--- a/pkg/cli/add_wizard_command.go
+++ b/pkg/cli/add_wizard_command.go
@@ -27,17 +27,6 @@ This command walks you through:
 
 Use 'add' for non-interactive workflow addition.
 
-Examples:
-  ` + string(constants.CLIExtensionPrefix) + ` add-wizard githubnext/agentics                    # Guided setup for repository-root aw.yml package
-  ` + string(constants.CLIExtensionPrefix) + ` add-wizard githubnext/agentics/packages/repo-assist # Guided setup for nested aw.yml package
-  ` + string(constants.CLIExtensionPrefix) + ` add-wizard githubnext/agentics/daily-repo-status    # Guided setup
-  ` + string(constants.CLIExtensionPrefix) + ` add-wizard githubnext/agentics/ci-doctor@v1.0.0     # Guided setup with version
-  ` + string(constants.CLIExtensionPrefix) + ` add-wizard ./my-workflow.md                         # Guided setup for local workflow
-  ` + string(constants.CLIExtensionPrefix) + ` add-wizard https://example.com/my-workflow.md       # Guided setup from any HTTPS URL
-  ` + string(constants.CLIExtensionPrefix) + ` add-wizard https://example.com/workflow.json        # Import JSON workflow definition with guided setup
-  ` + string(constants.CLIExtensionPrefix) + ` add-wizard githubnext/agentics/ci-doctor --engine copilot   # Pre-select engine
-  ` + string(constants.CLIExtensionPrefix) + ` add-wizard githubnext/agentics/ci-doctor --skip-secret      # Skip secret prompt
-
 Workflow specifications:
   - Two parts: "owner/repo[@version]" (loads repository-root aw.yml package)
   - Three+ parts without .md: "owner/repo/folder[@version]" (loads nested aw.yml package when present)
@@ -55,6 +44,16 @@ Note: In GitHub Enterprise repos, shorthand specs resolve on your enterprise hos
       For github/*, githubnext/*, and microsoft/*, shorthand resolves on github.com.
       Use full https://github.com/... URLs when sourcing other public github.com workflows.
 Note: To create a new workflow from scratch, use the 'new' command instead.`,
+		Example: `  ` + string(constants.CLIExtensionPrefix) + ` add-wizard githubnext/agentics                    # Guided setup for repository-root aw.yml package
+  ` + string(constants.CLIExtensionPrefix) + ` add-wizard githubnext/agentics/packages/repo-assist # Guided setup for nested aw.yml package
+  ` + string(constants.CLIExtensionPrefix) + ` add-wizard githubnext/agentics/daily-repo-status    # Guided setup
+  ` + string(constants.CLIExtensionPrefix) + ` add-wizard githubnext/agentics/ci-doctor@v1.0.0     # Guided setup with version
+  ` + string(constants.CLIExtensionPrefix) + ` add-wizard ./my-workflow.md                         # Guided setup for local workflow
+  ` + string(constants.CLIExtensionPrefix) + ` add-wizard https://example.com/my-workflow.md       # Guided setup from any HTTPS URL
+  ` + string(constants.CLIExtensionPrefix) + ` add-wizard https://example.com/workflow.json        # Import JSON workflow definition with guided setup
+  ` + string(constants.CLIExtensionPrefix) + ` add-wizard githubnext/agentics/ci-doctor --engine copilot   # Pre-select engine
+  ` + string(constants.CLIExtensionPrefix) + ` add-wizard githubnext/agentics/ci-doctor --skip-secret      # Skip secret prompt
+`,
 		Args: func(cmd *cobra.Command, args []string) error {
 			if len(args) < 1 {
 				return errors.New("missing workflow specification\n\nRun 'gh aw add-wizard --help' for usage information")
diff --git a/pkg/cli/audit.go b/pkg/cli/audit.go
index e6d647504d3..bc1d83a6ea8 100644
--- a/pkg/cli/audit.go
+++ b/pkg/cli/audit.go
@@ -65,10 +65,8 @@ Each argument accepts:
 When a job URL is provided (single-run mode only):
 - If a step number is included (#step:7:1), extracts that specific step's output
 - If no step number, finds and extracts the first failing step's output
-- Saves job logs to the output directory
-
-Examples:
-  ` + string(constants.CLIExtensionPrefix) + ` audit 1234567890                    # Audit run with ID 1234567890
+- Saves job logs to the output directory`,
+		Example: `  ` + 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
   ` + string(constants.CLIExtensionPrefix) + ` audit https://github.com/owner/repo/actions/runs/1234567890/job/9876543210  # Audit job and extract first failing step
   ` + string(constants.CLIExtensionPrefix) + ` audit https://github.com/owner/repo/actions/runs/1234567890/job/9876543210#step:7:1  # Extract step 7 output
diff --git a/pkg/cli/audit_diff_command.go b/pkg/cli/audit_diff_command.go
index 80dfc88ccc4..d0adb7f61a7 100644
--- a/pkg/cli/audit_diff_command.go
+++ b/pkg/cli/audit_diff_command.go
@@ -40,10 +40,8 @@ analyzes their data, and produces a diff showing:
 - Anomaly flags (new denied domains, previously-denied now allowed)
 - MCP tool invocation changes (new/removed tools, call count and error count diffs)
 - Run metrics comparison (token usage, duration, turns) when cached data is available
-- Detailed token usage breakdown (input/output/cache + AI Credits) from firewall proxy
-
-Examples:
-  ` + string(constants.CLIExtensionPrefix) + ` audit diff 12345 12346                               # Compare two runs
+- Detailed token usage breakdown (input/output/cache + AI Credits) from firewall proxy`,
+		Example: `  ` + string(constants.CLIExtensionPrefix) + ` audit diff 12345 12346                               # Compare two runs
   ` + string(constants.CLIExtensionPrefix) + ` audit diff 12345 12346 12347 12348                   # Compare base against 3 runs
   ` + string(constants.CLIExtensionPrefix) + ` audit diff 12345 12346 --format markdown             # Markdown output for PR comments
   ` + string(constants.CLIExtensionPrefix) + ` audit diff 12345 12346 --json                        # JSON for CI integration
diff --git a/pkg/cli/checks_command.go b/pkg/cli/checks_command.go
index 92e6159ccc5..3e18833937f 100644
--- a/pkg/cli/checks_command.go
+++ b/pkg/cli/checks_command.go
@@ -92,10 +92,8 @@ JSON output includes two state fields:
                    branch-protection or account-gate statuses fail
 
 Use required_state as the authoritative CI verdict in repos that have optional
-deployment integrations posting commit statuses alongside required CI checks.
-
-Examples:
-  ` + string(constants.CLIExtensionPrefix) + ` checks 42                    # Classify checks for PR #42
+deployment integrations posting commit statuses alongside required CI checks.`,
+		Example: `  ` + string(constants.CLIExtensionPrefix) + ` checks 42                    # Classify checks for PR #42
   ` + string(constants.CLIExtensionPrefix) + ` checks 42 --repo owner/repo  # Specify repository
   ` + string(constants.CLIExtensionPrefix) + ` checks 42 --json             # Output in JSON format`,
 		Args: cobra.ExactArgs(1),
diff --git a/pkg/cli/completion_command.go b/pkg/cli/completion_command.go
index 41bf5fb26eb..e6726332528 100644
--- a/pkg/cli/completion_command.go
+++ b/pkg/cli/completion_command.go
@@ -24,10 +24,8 @@ Tab completion provides:
 - Directory path completion for --dir flag
 - Helpful descriptions for workflows when available
 
-Supported shells: bash, zsh, fish, PowerShell
-
-Examples:
-  # Install completions automatically (detects your shell)
+Supported shells: bash, zsh, fish, PowerShell`,
+		Example: `  # Install completions automatically (detects your shell)
   gh aw completion install
 
   # Generate completion script for bash
@@ -81,10 +79,8 @@ Supported shells:
   - Bash:       Installs to ~/.bash_completion.d/ or /etc/bash_completion.d/
   - Zsh:        Installs to ~/.zsh/completions/
   - Fish:       Installs to ~/.config/fish/completions/
-  - PowerShell: Provides instructions to add to PowerShell profile
-
-Examples:
-  gh aw completion install           # Auto-detect and install
+  - PowerShell: Provides instructions to add to PowerShell profile`,
+		Example: `  gh aw completion install           # Auto-detect and install
   gh aw completion install --verbose # Show detailed installation steps`,
 		RunE: func(cmd *cobra.Command, args []string) error {
 			verbose, _ := cmd.Flags().GetBool("verbose")
@@ -107,10 +103,8 @@ Supported shells:
   - Bash:       Removes from ~/.bash_completion.d/ or /etc/bash_completion.d/
   - Zsh:        Removes from ~/.zsh/completions/
   - Fish:       Removes from ~/.config/fish/completions/
-  - PowerShell: Provides instructions to remove from PowerShell profile
-
-Examples:
-  gh aw completion uninstall           # Auto-detect and uninstall
+  - PowerShell: Provides instructions to remove from PowerShell profile`,
+		Example: `  gh aw completion uninstall           # Auto-detect and uninstall
   gh aw completion uninstall --verbose # Show detailed uninstallation steps`,
 		RunE: func(cmd *cobra.Command, args []string) error {
 			verbose, _ := cmd.Flags().GetBool("verbose")
diff --git a/pkg/cli/deploy_command.go b/pkg/cli/deploy_command.go
index aae31a88684..21685404580 100644
--- a/pkg/cli/deploy_command.go
+++ b/pkg/cli/deploy_command.go
@@ -28,10 +28,8 @@ func NewDeployCommand(validateEngine func(string) error) *cobra.Command {
 		Short: "Deploy agentic workflows to a target repository using a pull request",
 		Long: `Deploy one or more workflows to a target repository by combining clone, update, add, compile, and pull request creation.
 
-The command clones the target repository, updates existing workflows from source, adds the specified workflows, recompiles lock files with purge enabled, and opens a pull request.
-
-Examples:
-  ` + string(constants.CLIExtensionPrefix) + ` deploy githubnext/agentics/ci-doctor --repo owner/repo
+The command clones the target repository, updates existing workflows from source, adds the specified workflows, recompiles lock files with purge enabled, and opens a pull request.`,
+		Example: `  ` + string(constants.CLIExtensionPrefix) + ` deploy githubnext/agentics/ci-doctor --repo owner/repo
   ` + string(constants.CLIExtensionPrefix) + ` deploy githubnext/agentics/repo-assist githubnext/agentics/ci-doctor --repo owner/repo --force
   ` + string(constants.CLIExtensionPrefix) + ` deploy ./my-workflow.md --repo owner/repo`,
 		Args: validateDeployArgs,
diff --git a/pkg/cli/domains_command.go b/pkg/cli/domains_command.go
index ec247c0e1ec..1dc32d21029 100644
--- a/pkg/cli/domains_command.go
+++ b/pkg/cli/domains_command.go
@@ -55,10 +55,8 @@ domains for that workflow, including domains expanded from ecosystem identifiers
 
 The workflow argument can be:
 - A workflow ID (basename without .md extension, e.g., "weekly-research")
-- A file path (e.g., "weekly-research.md" or ".github/workflows/weekly-research.md")
-
-Examples:
-  ` + string(constants.CLIExtensionPrefix) + ` domains                      # List all workflows with domain counts
+- A file path (e.g., "weekly-research.md" or ".github/workflows/weekly-research.md")`,
+		Example: `  ` + string(constants.CLIExtensionPrefix) + ` domains                      # List all workflows with domain counts
   ` + string(constants.CLIExtensionPrefix) + ` domains weekly-research       # List domains for weekly-research workflow
   ` + string(constants.CLIExtensionPrefix) + ` domains --json                # Output summary in JSON format
   ` + string(constants.CLIExtensionPrefix) + ` domains weekly-research --json # Output workflow domains in JSON format`,
diff --git a/pkg/cli/experiments_command.go b/pkg/cli/experiments_command.go
index a91c8e86a15..e17159354eb 100644
--- a/pkg/cli/experiments_command.go
+++ b/pkg/cli/experiments_command.go
@@ -96,10 +96,8 @@ workflow's pick_experiment step, containing variant counts and run history.
 
 Available subcommands:
   - list    - List all experiment workflow branches (default)
-  - analyze - Analyze a specific experiment workflow in detail
-
-Examples:
-  ` + string(constants.CLIExtensionPrefix) + ` experiments                        # List all experiments (default)
+  - analyze - Analyze a specific experiment workflow in detail`,
+		Example: `  ` + string(constants.CLIExtensionPrefix) + ` experiments                        # List all experiments (default)
   ` + string(constants.CLIExtensionPrefix) + ` experiments list                   # List all experiments
   ` + string(constants.CLIExtensionPrefix) + ` experiments list --json            # Output in JSON format
   ` + string(constants.CLIExtensionPrefix) + ` experiments analyze my-workflow    # Analyze experiments/my-workflow
@@ -132,10 +130,8 @@ func NewExperimentsListSubcommand() *cobra.Command {
 
 Reads the state.json file from each experiments/* branch and shows a summary
 of each workflow's A/B experiments: number of experiments defined, total runs,
-and timestamp of the most recent run.
-
-Examples:
-  ` + string(constants.CLIExtensionPrefix) + ` experiments list                             # List all experiments
+and timestamp of the most recent run.`,
+		Example: `  ` + string(constants.CLIExtensionPrefix) + ` experiments list                             # List all experiments
   ` + string(constants.CLIExtensionPrefix) + ` experiments list --json                      # Output in JSON format
   ` + string(constants.CLIExtensionPrefix) + ` experiments list --repo owner/repo           # List from a specific repository`,
 		RunE: func(cmd *cobra.Command, args []string) error {
@@ -165,10 +161,8 @@ The experiment argument is the workflow ID (branch name without the "experiments
 prefix, e.g., "my-workflow" for the "experiments/my-workflow" branch).
 
 Reads the state.json file from the branch and shows per-variant counts, total
-runs, and the most recent run assignments.
-
-Examples:
-  ` + string(constants.CLIExtensionPrefix) + ` experiments analyze my-workflow              # Analyze experiments/my-workflow
+runs, and the most recent run assignments.`,
+		Example: `  ` + string(constants.CLIExtensionPrefix) + ` experiments analyze my-workflow              # Analyze experiments/my-workflow
   ` + string(constants.CLIExtensionPrefix) + ` experiments analyze my-workflow --json       # Output in JSON format
   ` + string(constants.CLIExtensionPrefix) + ` experiments analyze my-workflow --repo owner/repo  # Analyze in a specific repository`,
 		Args: cobra.ExactArgs(1),
diff --git a/pkg/cli/fix_command.go b/pkg/cli/fix_command.go
index 6351e2d5d8a..99948be6c39 100644
--- a/pkg/cli/fix_command.go
+++ b/pkg/cli/fix_command.go
@@ -56,10 +56,8 @@ all steps and additionally:
   6. Delete old template files from previous versions if present
   7. Delete old workflow-specific .agent.md files from .github/agents/ if present
 
-` + WorkflowIDExplanation + `
-
-Examples:
-  ` + string(constants.CLIExtensionPrefix) + ` fix                     # Check all workflows (dry-run)
+` + WorkflowIDExplanation,
+		Example: `  ` + string(constants.CLIExtensionPrefix) + ` fix                     # Check all workflows (dry-run)
   ` + string(constants.CLIExtensionPrefix) + ` fix --write             # Fix all workflows
   ` + string(constants.CLIExtensionPrefix) + ` fix my-workflow         # Check specific workflow
   ` + string(constants.CLIExtensionPrefix) + ` fix my-workflow --write # Fix specific workflow
diff --git a/pkg/cli/forecast_command.go b/pkg/cli/forecast_command.go
index b4b684d63b6..38e6b0bf9b8 100644
--- a/pkg/cli/forecast_command.go
+++ b/pkg/cli/forecast_command.go
@@ -63,10 +63,8 @@ Backtesting (--eval):
   P10–P90 confidence interval. Use this to validate the model before relying on
   forward projections.
 
-` + WorkflowIDExplanation + `
-
-Examples:
-  ` + string(constants.CLIExtensionPrefix) + ` forecast                        # Forecast all workflows (monthly)
+` + WorkflowIDExplanation,
+		Example: `  ` + string(constants.CLIExtensionPrefix) + ` forecast                        # Forecast all workflows (monthly)
   ` + string(constants.CLIExtensionPrefix) + ` forecast ci-doctor              # Forecast a specific workflow
   ` + string(constants.CLIExtensionPrefix) + ` forecast ci-doctor daily-planner # Compare two workflows
   ` + string(constants.CLIExtensionPrefix) + ` forecast --period week           # Weekly projections
diff --git a/pkg/cli/hash_command.go b/pkg/cli/hash_command.go
index 16168da4a7b..f5be6acac6e 100644
--- a/pkg/cli/hash_command.go
+++ b/pkg/cli/hash_command.go
@@ -25,10 +25,8 @@ The hash includes:
 - Template expressions containing env. or vars. from the markdown body
 - Version information (gh-aw, awf, agents)
 
-The hash can be used to detect configuration changes between compilation and execution.
-
-Examples:
-  gh aw hash-frontmatter my-workflow.md
+The hash can be used to detect configuration changes between compilation and execution.`,
+		Example: `  gh aw hash-frontmatter my-workflow.md
   gh aw hash-frontmatter .github/workflows/audit-workflows.md`,
 		Args: cobra.ExactArgs(1),
 		RunE: func(cmd *cobra.Command, args []string) error {
diff --git a/pkg/cli/health_command.go b/pkg/cli/health_command.go
index 10a71c4a215..effc0f52fd6 100644
--- a/pkg/cli/health_command.go
+++ b/pkg/cli/health_command.go
@@ -45,10 +45,8 @@ Shows health metrics for workflows including:
 When called without a workflow name, displays summary for all workflows.
 When called with a specific workflow name, displays detailed metrics for that workflow.
 
-` + WorkflowIDExplanation + `
-
-Examples:
-  ` + string(constants.CLIExtensionPrefix) + ` health                       # Summary of all workflows (last 7 days)
+` + WorkflowIDExplanation,
+		Example: `  ` + string(constants.CLIExtensionPrefix) + ` health                       # Summary of all workflows (last 7 days)
   ` + string(constants.CLIExtensionPrefix) + ` health issue-monster         # Detailed metrics for specific workflow
   ` + string(constants.CLIExtensionPrefix) + ` health --days 30             # Summary for last 30 days
   ` + string(constants.CLIExtensionPrefix) + ` health --threshold 90        # Warn if below 90% success rate
diff --git a/pkg/cli/init_command.go b/pkg/cli/init_command.go
index 036a0fbdb08..fb7c1cdf3b9 100644
--- a/pkg/cli/init_command.go
+++ b/pkg/cli/init_command.go
@@ -61,10 +61,8 @@ After running this command, you can:
 - Use GitHub Copilot Chat or coding agent tools with the agentic-workflows skill to get started with workflow tasks
 - The dispatcher skill will route your request to the appropriate specialized prompt
 - Add workflows from the catalog with: ` + string(constants.CLIExtensionPrefix) + ` add <workflow-name>
-- Create new workflows from scratch with: ` + string(constants.CLIExtensionPrefix) + ` new <workflow-name>
-
-Examples:
-  ` + string(constants.CLIExtensionPrefix) + ` init                                # Initialize repository with defaults
+- Create new workflows from scratch with: ` + string(constants.CLIExtensionPrefix) + ` new <workflow-name>`,
+		Example: `  ` + string(constants.CLIExtensionPrefix) + ` init                                # Initialize repository with defaults
   ` + string(constants.CLIExtensionPrefix) + ` init -v                             # Initialize with verbose output
   ` + string(constants.CLIExtensionPrefix) + ` init --engine claude                # Skip Copilot-specific artifacts
   ` + string(constants.CLIExtensionPrefix) + ` init --no-mcp                       # Skip MCP configuration
diff --git a/pkg/cli/lint_command.go b/pkg/cli/lint_command.go
index 6cc08b7abfb..1a138c40858 100644
--- a/pkg/cli/lint_command.go
+++ b/pkg/cli/lint_command.go
@@ -38,10 +38,8 @@ func NewLintCommand() *cobra.Command {
 		Long: `Lint existing .lock.yml workflow files from disk using actionlint only.
 
 This command does not recompile Markdown workflows and does not run zizmor or poutine.
-By default, shellcheck and pyflakes integrations are disabled for generated run scripts.
-
-Examples:
-  ` + string(constants.CLIExtensionPrefix) + ` lint
+By default, shellcheck and pyflakes integrations are disabled for generated run scripts.`,
+		Example: `  ` + string(constants.CLIExtensionPrefix) + ` lint
   ` + string(constants.CLIExtensionPrefix) + ` lint .github/workflows/foo.lock.yml
   ` + string(constants.CLIExtensionPrefix) + ` lint --dir .github/workflows
   ` + string(constants.CLIExtensionPrefix) + ` lint --shellcheck --pyflakes`,
diff --git a/pkg/cli/list_workflows_command.go b/pkg/cli/list_workflows_command.go
index b6d8352b322..285960af9a4 100644
--- a/pkg/cli/list_workflows_command.go
+++ b/pkg/cli/list_workflows_command.go
@@ -36,10 +36,8 @@ Displays a simplified table with workflow name, AI engine, and compilation statu
 Unlike 'status', this command does not check GitHub workflow state or time remaining.
 
 The optional pattern argument filters workflows by name (case-insensitive substring match).
-It accepts workflow IDs (basename without .md) or full filenames.
-
-Examples:
-  ` + string(constants.CLIExtensionPrefix) + ` list                              # List all workflows in current repo
+It accepts workflow IDs (basename without .md) or full filenames.`,
+		Example: `  ` + string(constants.CLIExtensionPrefix) + ` list                              # List all workflows in current repo
   ` + string(constants.CLIExtensionPrefix) + ` list --repo github/gh-aw          # List workflows from github/gh-aw repo
   ` + string(constants.CLIExtensionPrefix) + ` list --repo org/repo --path workflows  # List from custom path
   ` + string(constants.CLIExtensionPrefix) + ` list --dir custom/workflows        # List from custom local directory
diff --git a/pkg/cli/logs_command.go b/pkg/cli/logs_command.go
index 84cf2bdfc06..05dbed321a1 100644
--- a/pkg/cli/logs_command.go
+++ b/pkg/cli/logs_command.go
@@ -46,10 +46,8 @@ Downloaded artifacts include:
 - workflow-logs/: GitHub Actions workflow run logs (job logs organized in subdirectory)
 - summary.json: Complete metrics and run data for all downloaded runs
 
-` + WorkflowIDExplanation + `
-
-Examples:
-  # Basic usage
+` + WorkflowIDExplanation,
+		Example: `  # Basic usage
   ` + string(constants.CLIExtensionPrefix) + ` logs                           # Download logs for all workflows
   ` + string(constants.CLIExtensionPrefix) + ` logs weekly-research           # Download logs for specific workflow
   ` + string(constants.CLIExtensionPrefix) + ` logs weekly-research.md        # Download logs (alternative format)
diff --git a/pkg/cli/mcp.go b/pkg/cli/mcp.go
index d88bbfe03e6..3e3e7116924 100644
--- a/pkg/cli/mcp.go
+++ b/pkg/cli/mcp.go
@@ -25,10 +25,8 @@ Available subcommands:
   - list       - List MCP servers defined in agentic workflows
   - list-tools - List tools for a specific MCP server, or find workflows using it
   - inspect    - Inspect MCP servers and list available tools, resources, and roots
-  - add        - Add an MCP server to an agentic workflow
-
-Examples:
-  gh aw mcp list                              # List all workflows with MCP servers
+  - add        - Add an MCP server to an agentic workflow`,
+		Example: `  gh aw mcp list                              # List all workflows with MCP servers
   gh aw mcp inspect weekly-research           # Inspect MCP servers in workflow
   gh aw mcp add my-workflow tavily            # Add Tavily MCP server to workflow
   gh aw mcp inspect weekly-research --server github --tool create_issue  # Inspect specific tool`,
diff --git a/pkg/cli/mcp_add.go b/pkg/cli/mcp_add.go
index f9679934746..7ab25c55577 100644
--- a/pkg/cli/mcp_add.go
+++ b/pkg/cli/mcp_add.go
@@ -321,18 +321,17 @@ The workflow-id-or-file can be:
 - A workflow ID (basename without .md extension, e.g., "weekly-research")
 - A file path (e.g., "weekly-research.md" or ".github/workflows/weekly-research.md")
 
-Examples:
-  gh aw mcp add                                          # List available MCP servers
-  gh aw mcp add weekly-research makenotion/notion-mcp-server  # Add Notion MCP server to weekly-research.md
-  gh aw mcp add weekly-research makenotion/notion-mcp-server --transport stdio  # Prefer stdio transport
-  gh aw mcp add weekly-research makenotion/notion-mcp-server --registry https://custom.registry.com/v1  # Use custom registry
-  gh aw mcp add weekly-research makenotion/notion-mcp-server --tool-id my-notion  # Use custom tool ID
-
 The command will:
 - Search the MCP registry for the specified server
 - Check that the server doesn't already exist in the workflow
 - Add the MCP server configuration to the workflow's frontmatter
 - Automatically compile the workflow to generate the .lock.yml file`,
+		Example: `  gh aw mcp add                                          # List available MCP servers
+  gh aw mcp add weekly-research makenotion/notion-mcp-server  # Add Notion MCP server to weekly-research.md
+  gh aw mcp add weekly-research makenotion/notion-mcp-server --transport stdio  # Prefer stdio transport
+  gh aw mcp add weekly-research makenotion/notion-mcp-server --registry https://custom.registry.com/v1  # Use custom registry
+  gh aw mcp add weekly-research makenotion/notion-mcp-server --tool-id my-notion  # Use custom tool ID
+`,
 		Args: cobra.RangeArgs(0, 2),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			verbose, _ := cmd.Flags().GetBool("verbose")
diff --git a/pkg/cli/mcp_inspect.go b/pkg/cli/mcp_inspect.go
index 00700739eeb..680de93eba1 100644
--- a/pkg/cli/mcp_inspect.go
+++ b/pkg/cli/mcp_inspect.go
@@ -251,15 +251,6 @@ The workflow-id-or-file can be:
 When no workflow is provided, this command lists workflows that have MCP server configurations
 (equivalent to 'gh aw mcp list'). To inspect tools/resources/roots, pass a specific workflow.
 
-Examples:
-  gh aw mcp inspect                    # List workflows with MCP servers
-  gh aw mcp inspect weekly-research    # Inspect MCP servers in weekly-research.md
-  gh aw mcp inspect daily-news --server tavily  # Inspect only the tavily server
-  gh aw mcp inspect weekly-research --server github --tool create_issue  # Show details for a specific tool
-  gh aw mcp inspect weekly-research -v # Verbose output with detailed connection info
-  gh aw mcp inspect weekly-research --inspector  # Launch @modelcontextprotocol/inspector
-  gh aw mcp inspect weekly-research --check-secrets  # Check GitHub Actions secrets
-
 The command will:
 - Parse the workflow file to extract MCP server configurations
 - Start each MCP server (stdio, docker, http)
@@ -267,6 +258,14 @@ The command will:
 - Query available tools, resources, and roots
 - Validate required secrets are available
 - Display results in formatted tables with error details`,
+		Example: `  gh aw mcp inspect                    # List workflows with MCP servers
+  gh aw mcp inspect weekly-research    # Inspect MCP servers in weekly-research.md
+  gh aw mcp inspect daily-news --server tavily  # Inspect only the tavily server
+  gh aw mcp inspect weekly-research --server github --tool create_issue  # Show details for a specific tool
+  gh aw mcp inspect weekly-research -v # Verbose output with detailed connection info
+  gh aw mcp inspect weekly-research --inspector  # Launch @modelcontextprotocol/inspector
+  gh aw mcp inspect weekly-research --check-secrets  # Check GitHub Actions secrets
+`,
 		Args: cobra.MaximumNArgs(1),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			var workflowFile string
diff --git a/pkg/cli/mcp_list.go b/pkg/cli/mcp_list.go
index 4ad91cae5e0..850e1798b68 100644
--- a/pkg/cli/mcp_list.go
+++ b/pkg/cli/mcp_list.go
@@ -334,18 +334,17 @@ The workflow-id-or-file can be:
 - A workflow ID (basename without .md extension, e.g., "weekly-research")
 - A file path (e.g., "weekly-research.md" or ".github/workflows/weekly-research.md")
 
-Examples:
-  gh aw mcp list                     # List all workflows with MCP servers
-  gh aw mcp list weekly-research     # List MCP servers in weekly-research.md
-  gh aw mcp list weekly-research -v  # List with detailed information
-  gh aw mcp list --verbose           # List all workflows with detailed MCP server info
-
 The command displays:
 - Server Name: MCP server identifier
 - Status: Configuration status (✓ Ready or ⚠ Incomplete)
 - Tools Count: Number of allowed tools or "All tools"
 - Network Access: Whether network permissions are configured (✓ Enabled or ✗ Disabled)
 - In verbose mode: Also shows Type and Command/URL`,
+		Example: `  gh aw mcp list                     # List all workflows with MCP servers
+  gh aw mcp list weekly-research     # List MCP servers in weekly-research.md
+  gh aw mcp list weekly-research -v  # List with detailed information
+  gh aw mcp list --verbose           # List all workflows with detailed MCP server info
+`,
 		Args: cobra.MaximumNArgs(1),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			var workflowFile string
diff --git a/pkg/cli/mcp_list_tools.go b/pkg/cli/mcp_list_tools.go
index 0d2a945c0e2..4fe38327e13 100644
--- a/pkg/cli/mcp_list_tools.go
+++ b/pkg/cli/mcp_list_tools.go
@@ -183,16 +183,15 @@ The workflow-id-or-file can be:
 - A workflow ID (basename without .md extension, e.g., "weekly-research")
 - A file path (e.g., "weekly-research.md" or ".github/workflows/weekly-research.md")
 
-Examples:
-  gh aw mcp list-tools --server github                    # Search for workflows containing the 'github' MCP server
-  gh aw mcp list-tools weekly-research --server github    # List tools for 'github' server in weekly-research.md
-  gh aw mcp list-tools issue-triage --server safe-outputs # List tools for 'safe-outputs' server in issue-triage.md
-  gh aw mcp list-tools test-workflow --server playwright -v  # Verbose output with tool descriptions
-
 The command will:
 - Parse the workflow to find the specified MCP server configuration
 - Connect to the MCP server using the same logic as 'mcp inspect'
 - Display available tools with their descriptions and allowance status`,
+		Example: `  gh aw mcp list-tools --server github                    # Search for workflows containing the 'github' MCP server
+  gh aw mcp list-tools weekly-research --server github    # List tools for 'github' server in weekly-research.md
+  gh aw mcp list-tools issue-triage --server safe-outputs # List tools for 'safe-outputs' server in issue-triage.md
+  gh aw mcp list-tools test-workflow --server playwright -v  # Verbose output with tool descriptions
+`,
 		Args: cobra.MaximumNArgs(1),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			if serverFilter == "" {
diff --git a/pkg/cli/mcp_server_command.go b/pkg/cli/mcp_server_command.go
index e805acc0c0a..ce4d43a1e70 100644
--- a/pkg/cli/mcp_server_command.go
+++ b/pkg/cli/mcp_server_command.go
@@ -48,10 +48,8 @@ Access Control:
   (default), these tools will work without actor validation.
 
 By default, the server uses stdio transport. Use the --port flag to run
-an HTTP server with SSE (Server-Sent Events) transport instead.
-
-Examples:
-  gh aw mcp-server                                     # Run with stdio transport (default for MCP clients)
+an HTTP server with SSE (Server-Sent Events) transport instead.`,
+		Example: `  gh aw mcp-server                                     # Run with stdio transport (default for MCP clients)
   gh aw mcp-server --validate-actor                    # Run with actor validation enforced
   gh aw mcp-server --port 8080                         # Run HTTP server on port 8080 with SSE transport (for web-based clients)
   gh aw mcp-server --cmd ./gh-aw                       # Use custom gh-aw binary path
diff --git a/pkg/cli/outcomes_command.go b/pkg/cli/outcomes_command.go
index 6b4e21c95f3..304690cd8e7 100644
--- a/pkg/cli/outcomes_command.go
+++ b/pkg/cli/outcomes_command.go
@@ -29,10 +29,8 @@ For each safe output (created issue, PR, comment, label, etc.), checks the curre
 state of the GitHub object to determine whether the action was accepted, rejected,
 ignored, or is still pending.
 
-This answers the question: "Did this workflow's actions actually help?"
-
-Examples:
-  ` + string(constants.CLIExtensionPrefix) + ` outcomes 1234567890                # Check outcomes for a specific run
+This answers the question: "Did this workflow's actions actually help?"`,
+		Example: `  ` + string(constants.CLIExtensionPrefix) + ` outcomes 1234567890                # Check outcomes for a specific run
   ` + string(constants.CLIExtensionPrefix) + ` outcomes 1234567890 --json         # JSON output
   ` + string(constants.CLIExtensionPrefix) + ` outcomes 1234567890 --repo o/r     # Specify repository
   ` + string(constants.CLIExtensionPrefix) + ` outcomes 1234567890 -v             # Verbose output`,
diff --git a/pkg/cli/outcomes_history.go b/pkg/cli/outcomes_history.go
index 83a78e99167..4fd104280ea 100644
--- a/pkg/cli/outcomes_history.go
+++ b/pkg/cli/outcomes_history.go
@@ -82,10 +82,8 @@ func NewOutcomesHistorySubcommand() *cobra.Command {
 		Long: `Score recent issues and merged pull requests against the objective mapping.
 
 This gives a quick local historical view of what kinds of work the repository
-has been closing or merging under the current objective mapping.
-
-Examples:
-  ` + string(constants.CLIExtensionPrefix) + ` outcomes history
+has been closing or merging under the current objective mapping.`,
+		Example: `  ` + string(constants.CLIExtensionPrefix) + ` outcomes history
   ` + string(constants.CLIExtensionPrefix) + ` outcomes history --source issues --limit 100
   ` + string(constants.CLIExtensionPrefix) + ` outcomes history --repo owner/repo --json`,
 		Args: cobra.NoArgs,
diff --git a/pkg/cli/pr_command.go b/pkg/cli/pr_command.go
index ef7bcc93f2d..59b14ec215e 100644
--- a/pkg/cli/pr_command.go
+++ b/pkg/cli/pr_command.go
@@ -49,10 +49,8 @@ to another, including the code changes, title, and body. Useful for
 migrating work from trial repositories to production repositories.
 
 Available subcommands:
-  - transfer - Transfer a pull request to another repository
-
-Examples:
-  gh aw pr transfer https://github.com/trial/repo/pull/234
+  - transfer - Transfer a pull request to another repository`,
+		Example: `  gh aw pr transfer https://github.com/trial/repo/pull/234
   gh aw pr transfer https://github.com/source/repo/pull/123 --repo owner/target
   gh aw pr transfer https://github.com/gh-aw-trial/repo/pull/5 --repo owner/prod-repo`,
 		RunE: func(cmd *cobra.Command, args []string) error {
@@ -78,15 +76,13 @@ and creates a new pull request in the target repository with the same title and
 
 The target repository defaults to the current repository unless --repo is specified.
 
-Examples:
-  gh aw pr transfer https://github.com/owner/repo/pull/234
-  gh aw pr transfer https://github.com/owner/repo/pull/234 --repo owner/target-repo
-
 The command will:
 1. Fetch the PR details (title, body, changes)
 2. Apply changes as a single squashed commit
 3. Create a new PR in the target repository
 4. Copy the original title and body`,
+		Example: `  gh aw pr transfer https://github.com/owner/repo/pull/234
+  gh aw pr transfer https://github.com/owner/repo/pull/234 --repo owner/target-repo`,
 		Args: cobra.ExactArgs(1),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			prURL := args[0]
diff --git a/pkg/cli/project_command.go b/pkg/cli/project_command.go
index 6cd6224e672..0509d484c9a 100644
--- a/pkg/cli/project_command.go
+++ b/pkg/cli/project_command.go
@@ -44,10 +44,8 @@ This command allows you to create new projects owned by users or organizations
 and optionally link them to specific repositories.
 
 Available subcommands:
-  - new - Create a new GitHub Project V2 board
-
-Examples:
-  gh aw project new "My Project" --owner @me                      # Create user project
+  - new - Create a new GitHub Project V2 board`,
+		Example: `  gh aw project new "My Project" --owner @me                      # Create user project
   gh aw project new "Team Board" --owner myorg                    # Create org project
   gh aw project new "Bugs" --owner myorg --link myorg/myrepo     # Create and link to repo`,
 	}
@@ -75,10 +73,8 @@ Project Setup:
   Use --with-project-setup to automatically create:
   - Standard views (Progress Board, Task Tracker, Roadmap)
   - Custom fields (Tracker Id, Worker Workflow, Target Repo, Priority, Size, dates)
-  - Enhanced Status field with "Review Required" option
-
-Examples:
-  gh aw project new "My Project" --owner @me                           # Create user project
+  - Enhanced Status field with "Review Required" option`,
+		Example: `  gh aw project new "My Project" --owner @me                           # Create user project
   gh aw project new "Team Board" --owner myorg                         # Create org project  
   gh aw project new "Bugs" --owner myorg --link myorg/myrepo           # Create and link to repo
   gh aw project new "Project Q1" --owner myorg --with-project-setup     # With project setup`,
diff --git a/pkg/cli/secret_set_command.go b/pkg/cli/secret_set_command.go
index 922de7173e7..fae372acfe7 100644
--- a/pkg/cli/secret_set_command.go
+++ b/pkg/cli/secret_set_command.go
@@ -48,10 +48,8 @@ func newSecretsSetSubcommand() *cobra.Command {
 The secret value can be provided in three ways:
   1. Via the --value flag
   2. Via the --value-from-env flag (reads from environment variable)
-  3. From stdin (if neither flag is provided)
-
-Examples:
-  # From stdin (uses current repository)
+  3. From stdin (if neither flag is provided)`,
+		Example: `  # From stdin (uses current repository)
   gh aw secrets set MY_SECRET
 
   # Specify target repository
diff --git a/pkg/cli/secrets_command.go b/pkg/cli/secrets_command.go
index ffc9795c4f8..ee3527de2c3 100644
--- a/pkg/cli/secrets_command.go
+++ b/pkg/cli/secrets_command.go
@@ -22,10 +22,8 @@ AI API keys (Anthropic, OpenAI, GitHub Copilot) and GitHub tokens for workflow e
 
 Available subcommands:
   - set       - Create or update individual secrets
-  - bootstrap - Validate and configure all required secrets for workflows
-
-Examples:
-  gh aw secrets set MY_SECRET --value "secret123"    # Set a secret directly
+  - bootstrap - Validate and configure all required secrets for workflows`,
+		Example: `  gh aw secrets set MY_SECRET --value "secret123"    # Set a secret directly
   gh aw secrets bootstrap                             # Check all required secrets`,
 		Args: func(cmd *cobra.Command, args []string) error {
 			if len(args) > 0 {
diff --git a/pkg/cli/status.go b/pkg/cli/status.go
index e7814b9de77..ad8f902534e 100644
--- a/pkg/cli/status.go
+++ b/pkg/cli/status.go
@@ -16,10 +16,8 @@ Displays a table with workflow name, AI engine, compilation status, enabled/disa
 and time remaining until expiration (if stop-after is configured).
 
 The optional pattern argument filters workflows by name (case-insensitive substring match).
-It accepts workflow IDs (basename without .md) or full filenames.
-
-Examples:
-  ` + string(constants.CLIExtensionPrefix) + ` status                           # Show all workflow status
+It accepts workflow IDs (basename without .md) or full filenames.`,
+		Example: `  ` + string(constants.CLIExtensionPrefix) + ` status                           # Show all workflow status
   ` + 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
diff --git a/pkg/cli/tokens_bootstrap.go b/pkg/cli/tokens_bootstrap.go
index 10b4933d2bc..9f93b4ec6e8 100644
--- a/pkg/cli/tokens_bootstrap.go
+++ b/pkg/cli/tokens_bootstrap.go
@@ -24,10 +24,8 @@ func newSecretsBootstrapSubcommand() *cobra.Command {
 are required, check which ones are already configured, and interactively
 prompt for any missing required secrets.
 
-Only required secrets are prompted for. Optional secrets are not shown.
-
-Examples:
-  gh aw secrets bootstrap                        # Check and set up all required secrets
+Only required secrets are prompted for. Optional secrets are not shown.`,
+		Example: `  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 {
diff --git a/pkg/cli/trial_command.go b/pkg/cli/trial_command.go
index fb2db9edb46..a8c77a02ca2 100644
--- a/pkg/cli/trial_command.go
+++ b/pkg/cli/trial_command.go
@@ -18,8 +18,16 @@ This command creates a temporary private repository in your GitHub account, inst
 workflow(s) from their source repositories, and runs them in "trial mode" to capture safe outputs without
 making actual changes to the "simulated" host repository.
 
-Examples:
-  ` + string(constants.CLIExtensionPrefix) + ` trial githubnext/agentics/weekly-research                         # Run a single workflow in a temporary trial repository
+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)
+- --host-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.
+The host repository will be created as private and kept by default unless --delete-host-repo-after is specified.
+Trial results are saved both locally (in trials/ directory) and in the host repository for future reference.`,
+		Example: `  ` + string(constants.CLIExtensionPrefix) + ` trial githubnext/agentics/weekly-research                         # Run a single workflow in a temporary trial repository
   ` + string(constants.CLIExtensionPrefix) + ` trial githubnext/agentics/daily-plan githubnext/agentics/weekly-research # Compare multiple workflows
   ` + string(constants.CLIExtensionPrefix) + ` trial githubnext/agentics/daily-plan myorg/myrepo/custom-workflow # Run workflows from different repositories
   ` + string(constants.CLIExtensionPrefix) + ` trial githubnext/agentics/my-workflow --host-repo myorg/myrepo    # Use an existing host repository
@@ -33,16 +41,7 @@ Examples:
   ` + string(constants.CLIExtensionPrefix) + ` trial githubnext/agentics/my-workflow --host-repo .               # Use the current repository as the host
   ` + string(constants.CLIExtensionPrefix) + ` trial ./local-workflow.md --clone-repo upstream/repo --repeat 2   # Run a local workflow against cloned contents
   ` + string(constants.CLIExtensionPrefix) + ` trial githubnext/agentics/my-workflow --trigger-context https://github.com/owner/repo/issues/123 # Provide issue context for issue-triggered workflows
-
-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)
-- --host-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.
-The host repository will be created as private and kept by default unless --delete-host-repo-after is specified.
-Trial results are saved both locally (in trials/ directory) and in the host repository for future reference.`,
+`,
 		Args: func(cmd *cobra.Command, args []string) error {
 			if len(args) < 1 {
 				return fmt.Errorf("missing workflow specification\n\nUsage:\n  %s <workflow-spec>...\n\nExample:\n  %[1]s githubnext/agentics/daily-plan             Trial a workflow from a repository\n  %[1]s ./local-workflow.md                         Trial a local workflow\n\nRun '%[1]s --help' for more information", cmd.CommandPath())
diff --git a/pkg/cli/update_command.go b/pkg/cli/update_command.go
index 8eca12591f5..3d76f23a090 100644
--- a/pkg/cli/update_command.go
+++ b/pkg/cli/update_command.go
@@ -46,10 +46,8 @@ Note: In GitHub Enterprise repos, shorthand source specs resolve on your enterpr
       For github/*, githubnext/*, and microsoft/* sources, shorthand resolves on github.com.
       Use full https://github.com/... source URLs for other public github.com workflows.
 
-` + WorkflowIDExplanation + `
-
-Examples:
-  ` + string(constants.CLIExtensionPrefix) + ` update                    # Update all workflows from source
+` + WorkflowIDExplanation,
+		Example: `  ` + string(constants.CLIExtensionPrefix) + ` update                    # Update all workflows from source
   ` + string(constants.CLIExtensionPrefix) + ` update repo-assist        # Update a specific workflow
   ` + string(constants.CLIExtensionPrefix) + ` update repo-assist.md     # Same (alternative format)
   ` + string(constants.CLIExtensionPrefix) + ` update --no-merge         # Override local changes with upstream
diff --git a/pkg/cli/upgrade_command.go b/pkg/cli/upgrade_command.go
index cf4bdd4f46a..959c9094c15 100644
--- a/pkg/cli/upgrade_command.go
+++ b/pkg/cli/upgrade_command.go
@@ -56,10 +56,8 @@ Use --audit to check dependency health without performing upgrades. This include
 
 The --audit flag skips the normal upgrade process.
 
-This command always upgrades all Markdown files in .github/workflows.
-
-Examples:
-  ` + string(constants.CLIExtensionPrefix) + ` upgrade                    # Upgrade all workflows
+This command always upgrades all Markdown files in .github/workflows.`,
+		Example: `  ` + string(constants.CLIExtensionPrefix) + ` upgrade                    # Upgrade all workflows
   ` + string(constants.CLIExtensionPrefix) + ` upgrade --no-fix          # Update agent files only (skip codemods, actions, and compilation)
   ` + string(constants.CLIExtensionPrefix) + ` upgrade --no-actions      # Skip updating GitHub Actions versions
   ` + string(constants.CLIExtensionPrefix) + ` upgrade --no-compile      # Skip recompiling workflows (do not modify lock files)
diff --git a/pkg/cli/validate_command.go b/pkg/cli/validate_command.go
index e7fbb331976..2d7460e4ee6 100644
--- a/pkg/cli/validate_command.go
+++ b/pkg/cli/validate_command.go
@@ -19,10 +19,8 @@ generating lock files. This is equivalent to:
 
 If no workflows are specified, all Markdown files in .github/workflows will be validated.
 
-` + WorkflowIDExplanation + `
-
-Examples:
-  ` + string(constants.CLIExtensionPrefix) + ` validate                         # Validate all workflows
+` + WorkflowIDExplanation,
+		Example: `  ` + string(constants.CLIExtensionPrefix) + ` validate                         # Validate all workflows
   ` + string(constants.CLIExtensionPrefix) + ` validate ci-doctor               # Validate a specific workflow
   ` + string(constants.CLIExtensionPrefix) + ` validate ci-doctor daily         # Validate multiple workflows
   ` + string(constants.CLIExtensionPrefix) + ` validate workflow.md             # Validate by file path
diff --git a/pkg/cli/view_command.go b/pkg/cli/view_command.go
index a03baa1f3bb..09478c1f49a 100644
--- a/pkg/cli/view_command.go
+++ b/pkg/cli/view_command.go
@@ -54,10 +54,8 @@ The run argument accepts the same formats as the "audit" command:
 
 Artifacts are downloaded to the default logs directory and cached; repeated
 invocations for the same run ID will read from the local cache without
-re-downloading.
-
-Examples:
-  ` + string(constants.CLIExtensionPrefix) + ` view 1234567890
+re-downloading.`,
+		Example: `  ` + string(constants.CLIExtensionPrefix) + ` view 1234567890
   ` + string(constants.CLIExtensionPrefix) + ` view https://github.com/owner/repo/actions/runs/1234567890
   ` + string(constants.CLIExtensionPrefix) + ` view 1234567890 --repo owner/repo
   ` + string(constants.CLIExtensionPrefix) + ` view 1234567890 -o ./my-logs

From 601465355aed88bcc78cf19827794c0ff99c6c99 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Fri, 12 Jun 2026 22:33:50 +0000
Subject: [PATCH 3/4] Update tests to check cmd.Example instead of cmd.Long
 after migration

Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>
---
 pkg/cli/cli_consistency_help_test.go |  2 +-
 pkg/cli/completion_command_test.go   | 10 +++++-----
 pkg/cli/logs_command_test.go         | 17 ++++++++++++-----
 pkg/cli/mcp_server_command_test.go   |  2 +-
 pkg/cli/upgrade_command_test.go      |  2 +-
 5 files changed, 20 insertions(+), 13 deletions(-)

diff --git a/pkg/cli/cli_consistency_help_test.go b/pkg/cli/cli_consistency_help_test.go
index 9fb839b8a6c..3949c039a36 100644
--- a/pkg/cli/cli_consistency_help_test.go
+++ b/pkg/cli/cli_consistency_help_test.go
@@ -23,7 +23,7 @@ func TestAuditCommandDescriptionsAreConsistent(t *testing.T) {
 func TestTrialCommandUsesStandardExamplesHeading(t *testing.T) {
 	cmd := NewTrialCommand(func(string) error { return nil })
 
-	assert.Contains(t, cmd.Long, "Examples:", "trial long help should use the standard examples heading")
+	assert.NotEmpty(t, cmd.Example, "trial command should use cobra's Example field for examples")
 	assert.NotContains(t, cmd.Long, "Single workflow:", "trial long help should avoid custom example section headings")
 	assert.NotContains(t, cmd.Long, "Multiple workflows (for comparison):", "trial long help should avoid custom example section headings")
 	assert.NotContains(t, cmd.Long, "Workflows from different repositories:", "trial long help should avoid custom example section headings")
diff --git a/pkg/cli/completion_command_test.go b/pkg/cli/completion_command_test.go
index 2346fe6852d..bb08e0e1aa1 100644
--- a/pkg/cli/completion_command_test.go
+++ b/pkg/cli/completion_command_test.go
@@ -129,11 +129,11 @@ func TestCompletionCommand_Examples(t *testing.T) {
 	cmd := NewCompletionCommand()
 
 	// Verify examples are present for all shells
-	assert.Contains(t, cmd.Long, "gh aw completion install")
-	assert.Contains(t, cmd.Long, "gh aw completion bash")
-	assert.Contains(t, cmd.Long, "gh aw completion zsh")
-	assert.Contains(t, cmd.Long, "gh aw completion fish")
-	assert.Contains(t, cmd.Long, "gh aw completion powershell")
+	assert.Contains(t, cmd.Example, "gh aw completion install")
+	assert.Contains(t, cmd.Example, "gh aw completion bash")
+	assert.Contains(t, cmd.Example, "gh aw completion zsh")
+	assert.Contains(t, cmd.Example, "gh aw completion fish")
+	assert.Contains(t, cmd.Example, "gh aw completion powershell")
 }
 
 func TestCompletionCommand_ValidArgs(t *testing.T) {
diff --git a/pkg/cli/logs_command_test.go b/pkg/cli/logs_command_test.go
index a425b7cb655..c7474c9e372 100644
--- a/pkg/cli/logs_command_test.go
+++ b/pkg/cli/logs_command_test.go
@@ -18,7 +18,7 @@ func TestNewLogsCommand(t *testing.T) {
 	assert.Equal(t, "logs [workflow]", cmd.Use, "Command use should be 'logs [workflow]'")
 	assert.Equal(t, "Download and analyze agentic workflow logs with aggregated metrics", cmd.Short, "Command short description should match")
 	assert.Contains(t, cmd.Long, "Download and analyze agentic workflow logs", "Command long description should contain expected text")
-	assert.Contains(t, cmd.Long, "logs --cache-before -1w", "Cache maintenance examples should use the cache-before flag name")
+	assert.Contains(t, cmd.Example, "logs --cache-before -1w", "Cache maintenance examples should use the cache-before flag name")
 
 	// Verify flags are registered
 	flags := cmd.Flags()
@@ -260,17 +260,24 @@ func TestLogsCommandHelpText(t *testing.T) {
 	cmd := NewLogsCommand()
 
 	// Verify long description contains expected sections
-	expectedSections := []string{
+	expectedLongSections := []string{
 		"Download and analyze agentic workflow logs",
 		"Downloaded artifacts include:",
-		"Examples:",
+	}
+
+	for _, section := range expectedLongSections {
+		assert.Contains(t, cmd.Long, section, "Long description should contain: %s", section)
+	}
+
+	// Verify example field contains example commands
+	expectedExampleSections := []string{
 		"gh aw logs",
 		"--safe-output noop",
 		"--safe-output report-incomplete",
 	}
 
-	for _, section := range expectedSections {
-		assert.Contains(t, cmd.Long, section, "Long description should contain: %s", section)
+	for _, section := range expectedExampleSections {
+		assert.Contains(t, cmd.Example, section, "Example field should contain: %s", section)
 	}
 
 	safeOutputFlag := cmd.Flags().Lookup("safe-output")
diff --git a/pkg/cli/mcp_server_command_test.go b/pkg/cli/mcp_server_command_test.go
index f4ad8f4eb49..b580097489c 100644
--- a/pkg/cli/mcp_server_command_test.go
+++ b/pkg/cli/mcp_server_command_test.go
@@ -13,5 +13,5 @@ func TestNewMCPServerCommand_PortExampleMentionsSSE(t *testing.T) {
 	cmd := NewMCPServerCommand()
 	require.NotNil(t, cmd)
 
-	assert.Contains(t, cmd.Long, "Run HTTP server on port 8080 with SSE transport", "Port example should match SSE transport behavior")
+	assert.Contains(t, cmd.Example, "Run HTTP server on port 8080 with SSE transport", "Port example should match SSE transport behavior")
 }
diff --git a/pkg/cli/upgrade_command_test.go b/pkg/cli/upgrade_command_test.go
index a6383a1888d..1690caaf6ad 100644
--- a/pkg/cli/upgrade_command_test.go
+++ b/pkg/cli/upgrade_command_test.go
@@ -23,7 +23,7 @@ func TestUpgradeCommandHelpTextConsistency(t *testing.T) {
 	require.NotNil(t, preReleasesFlag, "--pre-releases flag should exist")
 	assert.Contains(t, preReleasesFlag.Usage, "Include pre-release versions", "--pre-releases description should mention pre-release upgrades")
 	assert.Contains(t, preReleasesFlag.Usage, "installed by exact tag", "--pre-releases description should explain prerelease pinning")
-	assert.Contains(t, cmd.Long, "stable releases are the default", "help text should distinguish stable releases from prereleases")
+	assert.Contains(t, cmd.Example, "stable releases are the default", "help text should distinguish stable releases from prereleases")
 
 	disableCodemodFlag := cmd.Flags().Lookup("disable-codemod")
 	require.NotNil(t, disableCodemodFlag, "--disable-codemod flag should exist")

From e591daa372808dbbfb58b65d972be457c3be93f4 Mon Sep 17 00:00:00 2001
From: "github-actions[bot]"
 <41898282+github-actions[bot]@users.noreply.github.com>
Date: Fri, 12 Jun 2026 23:37:54 +0000
Subject: [PATCH 4/4] docs(adr): add draft ADR-38946 for cobra Example field
 migration

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 ...obra-example-field-for-command-examples.md | 41 +++++++++++++++++++
 1 file changed, 41 insertions(+)
 create mode 100644 docs/adr/38946-use-cobra-example-field-for-command-examples.md

diff --git a/docs/adr/38946-use-cobra-example-field-for-command-examples.md b/docs/adr/38946-use-cobra-example-field-for-command-examples.md
new file mode 100644
index 00000000000..e889160a957
--- /dev/null
+++ b/docs/adr/38946-use-cobra-example-field-for-command-examples.md
@@ -0,0 +1,41 @@
+# ADR-38946: Use Cobra's `Example:` Field for Command Usage Examples
+
+**Date**: 2026-06-12
+**Status**: Draft
+
+## Context
+
+The CLI in `pkg/cli/` defines ~36 cobra commands, and historically every command embedded its usage examples as hand-written prose inside the `Long:` description field under an `Examples:` heading. Cobra provides a dedicated `Example:` field that is rendered separately in `--help` output and, critically, is consumed by `cobra/doc.GenMarkdownTree()` for documentation generation. Because the examples lived inside `Long:`, generated documentation could not surface them in the expected structured location, and the examples were not addressable for testing or tooling. This PR migrates all command definitions to use the native `Example:` field. The change is large by line count but mechanical and repetitive (moving example blocks between two struct fields).
+
+## Decision
+
+We will store all cobra command usage examples in the native cobra `Example:` field rather than embedding them as `Examples:` prose inside the `Long:` field. Non-example prose that previously followed the `Examples:` section (e.g., "Workflow specifications:", "The command will:") is moved back into `Long:` where it belongs. Tests that previously asserted example strings appeared in `cmd.Long` are updated to assert against `cmd.Example`. This aligns the codebase with cobra's intended API contract, restores correct `GenMarkdownTree()` documentation output, and makes examples independently inspectable.
+
+## Alternatives Considered
+
+### Alternative 1: Keep examples in `Long:` prose
+
+Leave the existing convention untouched and continue embedding examples under an `Examples:` heading inside `Long:`. Rejected because it breaks `cobra/doc.GenMarkdownTree()` documentation generation, keeps examples untestable as a distinct field, and diverges from cobra's documented usage of the `Example:` field.
+
+### Alternative 2: Custom help template / renderer
+
+Introduce a custom cobra help/usage template that parses the `Examples:` section out of `Long:` at render time. Rejected as unnecessary complexity: it reimplements behavior cobra already provides natively, adds a maintenance burden, and still would not feed `GenMarkdownTree()` correctly.
+
+## Consequences
+
+### Positive
+- `cobra/doc.GenMarkdownTree()` produces correct documentation with examples in their structured location.
+- Examples become independently testable and inspectable via `cmd.Example`.
+- Command definitions follow cobra's intended API convention, improving consistency across all ~36 commands.
+
+### Negative
+- Large, repetitive diff (36 command files plus 8 secondary prose fixes and 5 test updates) that touches many files at once and must be reviewed for correctness.
+- A standing convention contributors must remember to follow for new commands; without a lint check, regressions can reappear.
+
+### Neutral
+- `--help` output formatting shifts slightly because the `Example:` field is rendered under cobra's own "Examples:" section heading rather than inline within the long description.
+- Test assertions referencing example content move from `cmd.Long` to `cmd.Example`.
+
+---
+
+*This is a DRAFT ADR generated by the [Design Decision Gate](https://github.com/github/gh-aw/actions/runs/27447688258) workflow. The PR author must review, complete, and finalize this document before the PR can merge.*