[cli-consistency] Resolve CLI help/docs drift and flag convention mismatches

cmd/gh-aw/main.go

@@ -693,7 +693,7 @@ Use "` + string(constants.CLIExtensionPrefix) + ` help all" to show help for all
 	compileCmd.Flags().Bool("stats", false, "Display statistics table sorted by workflow file size (shows jobs, steps, scripts, and shells)")
 	compileCmd.Flags().Bool("fail-fast", false, "Stop at the first validation error instead of collecting all errors")
 	compileCmd.Flags().Bool("no-check-update", false, "Skip checking for gh-aw updates")
-	compileCmd.Flags().String("schedule-seed", "", "Override the repository slug (owner/repo) used as seed for fuzzy schedule scattering (e.g. 'github/gh-aw'). Bypasses git remote detection entirely. Use this when your git remote is not named 'origin' and you have multiple remotes configured")
+	compileCmd.Flags().String("schedule-seed", "", "Override the repository slug (owner/repo) used as seed for fuzzy schedule scattering (e.g. \"github/gh-aw\"). Bypasses git remote detection entirely. Use this when your git remote is not named \"origin\" and you have multiple remotes configured")
 	compileCmd.Flags().Bool("approve", false, "Approve all safe update changes. When strict mode is active (the default), the compiler emits warnings for new restricted secrets or unapproved action additions/removals not present in the existing gh-aw-manifest. Use this flag to approve and skip safe update enforcement")
 	compileCmd.Flags().Bool("validate-images", false, "Require Docker to be available for container image validation. Without this flag, container image validation is silently skipped when Docker is not installed or the daemon is not running")
 	compileCmd.Flags().String("prior-manifest-file", "", "Path to a JSON file containing pre-cached gh-aw-manifests (map[lockFile]*GHAWManifest); used by the MCP server to supply a tamper-proof manifest baseline captured at startup")

cmd/gh-aw/main_help_text_test.go

@@ -18,3 +18,10 @@ func TestRunCommandHelpTextConsistency(t *testing.T) {
 	require.NotNil(t, compileApprove, "compile command should define --approve")
 	assert.Equal(t, compileApprove.Usage, runApprove.Usage, "run and compile should share the same --approve description")
 }
+
+func TestCompileScheduleSeedHelpUsesConsistentQuotes(t *testing.T) {
+	scheduleSeedFlag := compileCmd.Flags().Lookup("schedule-seed")
+	require.NotNil(t, scheduleSeedFlag, "compile command should define --schedule-seed")
+	assert.Contains(t, scheduleSeedFlag.Usage, "\"github/gh-aw\"", "--schedule-seed example should use double quotes")
+	assert.Contains(t, scheduleSeedFlag.Usage, "\"origin\"", "--schedule-seed remote example should use double quotes")
+}

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

@@ -131,10 +131,10 @@ Commands are organized by workflow lifecycle: creating, building, testing, monit
 
 #### `init`
 
-Initialize repository for agentic workflows. Configures `.gitattributes`, creates the dispatcher agent file (`.github/agents/agentic-workflows.agent.md`). Enables MCP server integration by default (use `--no-mcp` to skip). Without arguments, enters interactive mode for engine selection and secret configuration.
+Initialize repository for agentic workflows. Configures `.gitattributes`, creates the dispatcher agent file (`.github/agents/agentic-workflows.agent.md`), and performs non-interactive setup. Enables MCP server integration by default (use `--no-mcp` to skip).
 
 ```bash wrap
-gh aw init                              # Interactive mode: select engine and configure secrets
+gh aw init                              # Initialize repository with defaults (non-interactive)
 gh aw init --no-mcp                     # Skip MCP server integration
 gh aw init --codespaces                 # Configure devcontainer for current repo
 gh aw init --codespaces repo1,repo2     # Configure devcontainer for additional repos
@@ -163,8 +163,8 @@ Add workflows from The Agentics collection or other repositories to `.github/wor
 ```bash wrap
 gh aw add githubnext/agentics/ci-doctor           # Add single workflow
 gh aw add githubnext/agentics/ci-doctor@v1.0.0   # Add specific version
-gh aw add ci-doctor --dir shared                  # Organize in subdirectory
-gh aw add ci-doctor --create-pull-request        # Create PR instead of commit
+gh aw add githubnext/agentics/ci-doctor --dir shared                  # Organize in subdirectory
+gh aw add githubnext/agentics/ci-doctor --create-pull-request        # Create PR instead of commit
 ```
 
 **Options:** `--dir/-d`, `--create-pull-request`, `--no-gitattributes`, `--append`, `--disable-security-scanner`, `--engine/-e`, `--force/-f`, `--name/-n`, `--no-stop-after`, `--stop-after`
@@ -400,7 +400,7 @@ gh aw logs --train                    # Train on last 10 runs
 gh aw logs my-workflow --train -c 50  # Train on up to 50 runs of a specific workflow
 ```
 
-**Options:** `-c`, `--count`, `-e`, `--engine`, `--start-date`, `--end-date`, `--ref`, `--parse`, `--json`, `--train`, `--repo`, `--firewall`, `--no-firewall`, `--safe-output`, `--filtered-integrity`, `--after-run-id`, `--before-run-id`, `--no-staged`, `--tool-graph`, `--timeout`
+**Options:** `-c`, `--count`, `--last`, `-e`, `--engine`, `--start-date`, `--end-date`, `--ref`, `--parse`, `--json`, `--train`, `--repo`, `--firewall`, `--no-firewall`, `--safe-output`, `--filtered-integrity`, `--after-run-id`, `--before-run-id`, `--no-staged`, `--tool-graph`, `--timeout`
 
 #### `audit`
 

pkg/cli/mcp_add.go

@@ -361,7 +361,7 @@ Registry URL defaults to: https://api.mcp.github.com/v0.1`,
 	}
 
 	cmd.Flags().StringVar(&registryURL, "registry", "", "MCP registry URL (default: https://api.mcp.github.com/v0.1)")
-	cmd.Flags().StringVar(&transportType, "transport", "", "Preferred transport type (stdio, http, Docker)")
+	cmd.Flags().StringVar(&transportType, "transport", "", "Preferred transport type (stdio, http, docker)")
 	cmd.Flags().StringVar(&customToolID, "tool-id", "", "Custom tool ID to use in the workflow (default: uses server ID)")
 
 	return cmd

pkg/cli/mcp_add_test.go

@@ -157,15 +157,15 @@ This is a test workflow.
 	}
 }
 
-func TestMCPAddTransportFlagDescriptionUsesDockerCapitalization(t *testing.T) {
+func TestMCPAddTransportFlagDescriptionUsesLowercaseDocker(t *testing.T) {
 	cmd := NewMCPAddSubcommand()
 	transportFlag := cmd.Flags().Lookup("transport")
 	if transportFlag == nil {
 		t.Fatal("expected --transport flag to exist")
 	}
 
-	if !strings.Contains(transportFlag.Usage, "Docker") {
-		t.Fatalf("expected --transport usage to include Docker, got: %s", transportFlag.Usage)
+	if !strings.Contains(transportFlag.Usage, "docker") {
+		t.Fatalf("expected --transport usage to include docker, got: %s", transportFlag.Usage)
 	}
 }
 

pkg/cli/project_command.go

@@ -104,7 +104,7 @@ Examples:
 		},
 	}
 
-	cmd.Flags().StringP("owner", "o", "", "Project owner: '@me' for current user or organization name (required)")
+	cmd.Flags().String("owner", "", "Project owner: '@me' for current user or organization name (required)")
 	cmd.Flags().StringP("link", "l", "", "Repository to link project to (format: owner/repo)")
 	cmd.Flags().Bool("with-project-setup", false, "Create standard project views and custom fields")
 	_ = cmd.MarkFlagRequired("owner")

pkg/cli/project_command_test.go

@@ -26,7 +26,7 @@ func TestNewProjectNewCommand(t *testing.T) {
 	// Check flags
 	ownerFlag := cmd.Flags().Lookup("owner")
 	require.NotNil(t, ownerFlag, "Should have --owner flag")
-	assert.Equal(t, "o", ownerFlag.Shorthand, "Owner flag should have short form 'o'")
+	assert.Empty(t, ownerFlag.Shorthand, "Owner flag should not define a shorthand to avoid -o collision with output")
 
 	linkFlag := cmd.Flags().Lookup("link")
 	require.NotNil(t, linkFlag, "Should have --link flag")