Skip to content

[docs] Self-healing documentation fixes from issue analysis - 2026-06-11 #38464

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
pelikhan merged 1 commit into from
Jun 11, 2026
Merged

[docs] Self-healing documentation fixes from issue analysis - 2026-06-11 #38464

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 11 additions & 11 deletions docs/src/content/docs/setup/cli.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -132,15 +132,15 @@ Commands are organized by workflow lifecycle: creating, building, testing, monit

#### `init`

Initialize repository for agentic workflows. Configures `.gitattributes`, creates the dispatcher skill file (`.github/skills/agentic-workflows/SKILL.md`), creates the Agentic Workflows custom agent (`.github/agents/agentic-workflows.md`), and performs non-interactive setup. Enables MCP server integration by default (use `--no-mcp` to skip). Use `--no-skill` or `--no-agent` to skip either artifact, or `--engine` to select a non-Copilot engine and skip Copilot-specific artifacts.
Initialize repository for agentic workflows. Configures `.gitattributes`, creates the dispatcher skill file (`.github/skills/agentic-workflows/SKILL.md`), the workflow designer skill (`.github/skills/agentic-workflow-designer/SKILL.md`), creates the Agentic Workflows custom agent (`.github/agents/agentic-workflows.md`), and performs non-interactive setup. Enables MCP server integration by default (use `--no-mcp` to skip). Use `--no-skill` or `--no-agent` to skip either artifact, or `--engine` to select a non-Copilot engine and skip Copilot-specific artifacts.

@github-actions github-actions Bot Jun 11, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"either artifact" is now ambiguous: the sentence lists three items (dispatcher skill, designer skill, agent) but "either" implies exactly two choices.

💡 Suggested fix

Reword to make the grouping explicit:

Use --no-skill to skip both skill files, --no-agent to skip the custom agent, or --engine to select a non-Copilot engine and skip Copilot-specific artifacts.

--no-skill silently skips both .github/skills/agentic-workflows/SKILL.md and .github/skills/agentic-workflow-designer/SKILL.md (confirmed in pkg/cli/init.go), so grouping them under a single flag name is correct — the sentence just needs to say so clearly.


```bash wrap
gh aw init # Initialize repository with defaults (non-interactive)
gh aw init --engine claude # Skip Copilot-specific artifacts
gh aw init --no-mcp # Skip MCP server integration
gh aw init --no-skill # Skip dispatcher skill creation
gh aw init --no-agent # Skip custom agent creation
gh aw init --codespaces "" # Configure devcontainer for current repo only
gh aw init --codespaces "" # Configure Codespaces for current repo only
gh aw init --codespaces repo1,repo2 # Configure devcontainer for additional repos
Comment on lines +143 to 144

@github-actions github-actions Bot Jun 11, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Terminology inconsistency: this line now says "Codespaces" while the very next example still says "devcontainer" — two adjacent examples for the same flag use different terms.

💡 Suggested fix

Change the next line for consistency:

gh aw init --codespaces ""              # Configure Codespaces for current repo only
gh aw init --codespaces repo1,repo2     # Configure Codespaces for additional repos

Both examples describe the same --codespaces flag; mixing "Codespaces" and "devcontainer" forces readers to wonder whether they refer to the same thing or two different behaviours.

gh aw init --completions # Install shell completions
gh aw init --create-pull-request # Initialize and open a pull request
Expand Down Expand Up @@ -206,7 +206,7 @@ gh aw new my-workflow --force # Overwrite if exists
gh aw new my-workflow --engine claude # Inject engine into frontmatter
```

**Options:** `--force`, `--engine/-e`, `--interactive/-i`
**Options:** `--force/-f`, `--engine/-e`, `--interactive/-i`

When `--engine` is specified, the engine is injected into the generated frontmatter template:

Expand Down Expand Up @@ -394,7 +394,7 @@ gh aw list --dir custom/workflows # List from a local custom directory
gh aw list --repo owner/repo --path .github/workflows # List from a remote repository
```

**Options:** `--json`, `--label`, `--dir/-d`, `--path`, `--repo`
**Options:** `--json/-j`, `--label`, `--dir/-d`, `--path`, `--repo/-r`

Two flags control the workflow directory location, with different purposes:
- `--dir` (`-d`): overrides the **local** workflow directory. Applies only when `--repo` is not set.
Expand All @@ -413,7 +413,7 @@ gh aw status --label automation # Filter by label
gh aw status --repo owner/other-repo # Check different repository
```

**Options:** `--ref`, `--label`, `--json`, `--repo`
**Options:** `--ref`, `--label`, `--json/-j`, `--repo/-r`

#### `logs`

Expand Down Expand Up @@ -555,7 +555,7 @@ gh aw health --json # Output in JSON format
gh aw health issue-monster --days 90 # 90-day metrics for workflow
```

**Options:** `--days`, `--threshold`, `--repo`, `--json`
**Options:** `--days`, `--threshold`, `--repo/-r`, `--json/-j`

Shows success/failure rates, trend indicators (↑ improving, → stable, ↓ degrading), execution duration, token usage, costs, and warnings when success rate drops below threshold.

Expand Down Expand Up @@ -589,7 +589,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`, `--repo/-r`, `--json/-j`
**Options:** `--days`, `--period`, `--sample`, `--eval`, `--timeout`, `--repo/-r`, `--json/-j`

### Management

Expand All @@ -604,7 +604,7 @@ gh aw enable ci-doctor daily # Enable multiple workflows
gh aw enable ci-doctor --repo owner/repo # Enable in specific repository
```

**Options:** `--repo`
**Options:** `--repo/-r`

#### `disable`

Expand All @@ -617,7 +617,7 @@ gh aw disable ci-doctor daily # Disable multiple workflows
gh aw disable ci-doctor --repo owner/repo # Disable in specific repository
```

**Options:** `--repo`
**Options:** `--repo/-r`

#### `remove`

Expand Down Expand Up @@ -649,7 +649,7 @@ gh aw update --repo owner/repo # Update workflows in another reposito
gh aw update --create-pull-request # Update and open a pull request
```

**Options:** `--dir`, `--no-merge`, `--major`, `--force`, `--engine`, `--no-stop-after`, `--stop-after`, `--disable-release-bump`, `--disable-security-scanner`, `--create-pull-request`, `--no-compile`, `--no-redirect`, `--cool-down`, `--repo/-r`
**Options:** `--dir/-d`, `--no-merge`, `--major`, `--force/-f`, `--engine/-e`, `--no-stop-after`, `--stop-after`, `--disable-release-bump`, `--disable-security-scanner`, `--create-pull-request`, `--no-compile`, `--no-redirect`, `--cool-down`, `--repo/-r`

The `--no-redirect` flag causes `update` to fail when the source workflow has a [`redirect`](/gh-aw/reference/frontmatter/) field, rather than following the redirect to its new location. Use this when you want explicit control over redirect handling.

Expand Down Expand Up @@ -746,7 +746,7 @@ gh aw mcp-server --port 8080 # HTTP server with SSE
gh aw mcp-server --validate-actor # Enable actor validation
```

**Options:** `--port` (HTTP server port), `--cmd` (custom subprocess command), `--validate-actor` (enforce actor validation for logs and audit tools)
**Options:** `--port/-p` (HTTP server port), `--cmd` (custom subprocess command), `--validate-actor` (enforce actor validation for logs and audit tools)

**Available Tools:** status, compile, logs, audit, checks, mcp-inspect, add, update, fix

Expand Down
Loading