Tighten CLI help/docs consistency for global options, forecast, and repo flag semantics

.github/skills/agentic-workflows/SKILL.md

@@ -71,6 +71,7 @@ Load these files from `github/gh-aw` (they are not available locally).
 - `.github/aw/test-coverage.md`
 - `.github/aw/test-expression.md`
 - `.github/aw/token-optimization-caching-budgets.md`
+- `.github/aw/token-optimization-observability.md`
 - `.github/aw/token-optimization.md`
 - `.github/aw/triggers.md`
 - `.github/aw/update-agentic-workflow.md`

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

@@ -126,11 +126,11 @@ The setup action installs the script at `/opt/gh-aw/actions/configure_gh_for_ghe
 | Flag | Description |
 |------|-------------|
 | `-h`, `--help` | Show help (`gh aw help [command]` for command-specific help) |
-
-For invalid nested command paths, `gh aw` now fails explicitly instead of falling back to parent help output. For example, `gh aw secrets gh --help` returns an unknown-command error rather than reprinting `gh aw secrets` help.
 | `-v`, `--verbose` | Enable verbose output showing detailed information |
 | `--banner` | Display ASCII logo banner with purple GitHub color theme |
 
+For invalid nested command paths, `gh aw` now fails explicitly instead of falling back to parent help output. For example, `gh aw secrets gh --help` returns an unknown-command error rather than reprinting `gh aw secrets` help.
+
 Use `gh aw version` to print the current version.
 
 ### The `--push` Flag
@@ -286,6 +286,8 @@ gh aw doctor --repo github/gh-aw --dir ./gh-aw --require-owner-type org
 
 Use `--repo` to verify a specific repository exists and inspect the local checkout that should correspond to it. `--require-owner-type` accepts `any`, `user`, or `org` and defaults to `any`; `--dir` and `--require-owner-type` require `--repo`.
 
+`doctor --repo` currently accepts `owner/repo` only. To target GitHub Enterprise Server, select the host via `GH_HOST` rather than prefixing the repository with `[HOST/]`.
+
 ### Building
 
 #### `fix`
@@ -658,7 +660,7 @@ gh aw forecast --repo owner/repo            # Forecast in another repository
 gh aw forecast --eval                       # Backtest forecast quality against past data
 ```
 
-**Options:** `--days`, `--period`, `--sample`, `--eval`, `--timeout`, `--repo/-r`, `--json/-j`
+**Options:** `--concurrency`, `--days`, `--period`, `--sample`, `--eval`, `--timeout`, `--repo/-r`, `--json/-j`
 
 The `--days` flag accepts only `7` or `30` (default: `30`). Other values produce an error.
 
@@ -800,6 +802,8 @@ gh aw env get ent-defaults.yml --scope ent --enterprise my-enterprise
 
 **Options:** `--scope`, `--repo/-r`, `--org`, `--enterprise`
 
+For repository scope, `--repo` currently accepts `owner/repo` only. To target GitHub Enterprise Server, select the host via `GH_HOST` rather than prefixing the repository with `[HOST/]`.
+
 ##### `env update [file]`
 
 Upload default compiler variables from a YAML file (`file.yml` by default). Use `null` (or omit a field) to delete that variable in the selected scope.
@@ -812,6 +816,8 @@ gh aw env update defaults.yml --scope ent --enterprise my-enterprise --yes
 
 **Options:** `--scope` (required), `--repo/-r`, `--org`, `--enterprise`, `--yes/-y`, `--dry-run`
 
+For repository scope, `--repo` currently accepts `owner/repo` only. To target GitHub Enterprise Server, select the host via `GH_HOST` rather than prefixing the repository with `[HOST/]`.
+
 ### Advanced
 
 #### `mcp`

pkg/cli/cli_consistency_help_test.go

@@ -88,6 +88,10 @@ func TestCLIDocsReflectStatusAuditAndExperimentsCommands(t *testing.T) {
 	assert.Contains(t, text, "`--require-owner-type` accepts `any`, `user`, or `org` and defaults to `any`", "doctor docs should document the full owner type set and default")
 	assert.Contains(t, text, "`--dir` and `--require-owner-type` require `--repo`", "doctor docs should document the repo requirement for repository-only flags")
 	assert.Contains(t, text, "Outside a checkout, run `gh auth login --hostname <host>` to authenticate and set `GH_HOST=<host>` so repository diagnostics target the correct host.", "doctor docs should explain that enterprise hosts outside a checkout require both authentication and host selection")
+	assert.Contains(t, text, "`doctor --repo` currently accepts `owner/repo` only.", "doctor docs should explicitly distinguish their narrower repo format")
+	assert.Contains(t, text, "For repository scope, `--repo` currently accepts `owner/repo` only.", "env docs should explicitly distinguish their narrower repo format")
+	assert.Contains(t, text, "**Options:** `--concurrency`, `--days`, `--period`, `--sample`, `--eval`, `--timeout`, `--repo/-r`, `--json/-j`", "forecast docs should include --concurrency")
+	assert.Contains(t, text, "| `-h`, `--help` | Show help (`gh aw help [command]` for command-specific help) |\n| `-v`, `--verbose` | Enable verbose output showing detailed information |\n| `--banner` | Display ASCII logo banner with purple GitHub color theme |", "global options table rows should remain contiguous")
 }
 
 func TestSubcommandListingsUseHyphenBullets(t *testing.T) {

pkg/cli/doctor_command.go

@@ -59,7 +59,7 @@ target the correct host.`,
 		},
 	}
 
-	cmd.Flags().StringP("repo", "r", "", "Target repository (owner/repo format)")
+	cmd.Flags().StringP("repo", "r", "", "Target repository (owner/repo format only; GHES host prefixes are not supported)")
 	cmd.Flags().StringP("dir", "d", "", "Checkout directory to inspect (defaults to the repo name)")
 	cmd.Flags().String("require-owner-type", "any", "Require a specific owner type: any, org, or user")
 	addJSONFlag(cmd)

pkg/cli/doctor_command_test.go

@@ -28,6 +28,7 @@ func TestNewDoctorCommand(t *testing.T) {
 	assert.NotNil(t, cmd.Flags().Lookup("dir"), "should expose --dir flag")
 	assert.NotNil(t, cmd.Flags().Lookup("require-owner-type"), "should expose --require-owner-type flag")
 	assert.False(t, cmd.HasSubCommands())
+	assert.Contains(t, cmd.Flags().Lookup("repo").Usage, "owner/repo format only", "doctor --repo help should explicitly document its narrower repo format")
 }
 
 func TestDoctorCommandUsesNoArgs(t *testing.T) {

pkg/cli/env_command.go

@@ -160,7 +160,7 @@ Scope resolution:
 	}
 
 	cmd.Flags().StringVar(&scope, "scope", "", "Variable scope (repo|org|ent). Defaults to repo")
-	cmd.Flags().StringVarP(&repo, "repo", "r", "", "Target repository (owner/repo format). Defaults to current repository")
+	cmd.Flags().StringVarP(&repo, "repo", "r", "", "Target repository (owner/repo format only; GHES host prefixes are not supported). Defaults to current repository")
 	cmd.Flags().StringVar(&org, "org", "", "Target organization (required for --scope org unless inferable from --repo/current repo)")
 	cmd.Flags().StringVar(&enterprise, "enterprise", "", "Target enterprise slug (required for --scope ent)")
 	return cmd
@@ -199,7 +199,7 @@ Scope and flag behavior:
 	}
 
 	cmd.Flags().StringVar(&scope, "scope", "", "Variable scope (repo|org|ent)")
-	cmd.Flags().StringVarP(&repo, "repo", "r", "", "Target repository (owner/repo format). Defaults to current repository")
+	cmd.Flags().StringVarP(&repo, "repo", "r", "", "Target repository (owner/repo format only; GHES host prefixes are not supported). Defaults to current repository")
 	cmd.Flags().StringVar(&org, "org", "", "Target organization (required for --scope org unless inferable from --repo/current repo)")
 	cmd.Flags().StringVar(&enterprise, "enterprise", "", "Target enterprise slug (required for --scope ent)")
 	cmd.Flags().BoolVarP(&yes, "yes", "y", false, "Skip confirmation prompt")

pkg/cli/env_command_test.go

@@ -47,10 +47,12 @@ func TestNewEnvCommand(t *testing.T) {
 	getRepoFlag := getCmd.Flags().Lookup("repo")
 	require.NotNil(t, getRepoFlag)
 	assert.Equal(t, "r", getRepoFlag.Shorthand)
+	assert.Contains(t, getRepoFlag.Usage, "owner/repo format only", "env get --repo help should explicitly document its narrower repo format")
 
 	updateRepoFlag := updateCmd.Flags().Lookup("repo")
 	require.NotNil(t, updateRepoFlag)
 	assert.Equal(t, "r", updateRepoFlag.Shorthand)
+	assert.Contains(t, updateRepoFlag.Usage, "owner/repo format only", "env update --repo help should explicitly document its narrower repo format")
 }
 
 func TestResolveDefaultsTarget(t *testing.T) {