docs: add "When to use" column to CLI commands summary table

[Copilot]

The "Most Common Commands" table on the CLI page had no context for when to reach for each command, leaving beginners without guidance on which command fits their situation.

Changes

• docs/src/content/docs/setup/cli.md: Added a "When to use" column to the summary table with a short, practical note per command (e.g. "After editing a workflow .md file to regenerate the .lock.yml" for gh aw compile). Anchor links from the Command column to detailed sections below were already present and are preserved.

Command	When to use
gh aw init	First time configuring a repo — creates skills, agents, and .gitattributes
gh aw add-wizard	Adding a community workflow and want guided prompts for secrets and auth
gh aw add	Scripted or CI-based workflow installation without interactive prompts
…	…

[Copilot]

Pull request overview

Improves the CLI documentation for gh aw by adding situational guidance to the “Most Common Commands” summary table, helping readers choose the right command based on their task.

Changes:

• Added a new “When to use” column to the “Most Common Commands” table.
• Filled in short, practical usage guidance for each listed command while preserving existing anchor links.

Show a summary per file

File	Description
docs/src/content/docs/setup/cli.md	Extends the “Most Common Commands” table with a “When to use” column and per-command guidance.

Review details

Tip

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

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

[github-actions]

✅ PR Code Quality Reviewer completed the code quality review.

[github-actions]

✅ Test Quality Sentinel completed test quality analysis.

No test files were added or modified in PR #43699. PR only modifies documentation (docs/src/content/docs/setup/cli.md). Test Quality Sentinel skipped.

[github-actions]

🧠 Matt Pocock Skills Reviewer has completed the skills-based review. ✅

[github-actions]

✅ Design Decision Gate 🏗️ completed the design decision gate check.

No ADR enforcement needed: PR #43699 does not have the 'implementation' label and has 0 new lines of code in business logic directories.

[github-actions]

Clean, accurate docs addition. All ten "When to use" entries correctly match their commands and add useful beginner guidance without being redundant.

🧵 Reviewed using Impeccable skills by Impeccable Skills Reviewer · 13 AIC · ⌖ 5.84 AIC · ⊞ 4.9K

[github-actions]

Skills-Based Review 🧠

Applied /grill-with-docs — requesting changes on 2 accuracy issues in the new "When to use" column.

📋 Key Themes & Highlights

Issues Found

• gh aw status entry (line 21): Claims users can "see their last run result", but run data requires --ref <branch>. Without it, the command only shows enabled/disabled state and schedules.
• gh aw logs entry (line 22): Mentions "tokens used" as a use-case, but token metrics live in gh aw audit. The logs command surfaces tool usage, errors, and raw output — not token counts.

Positive Highlights

• ✅ Great initiative — the "When to use" column meaningfully improves the table for newcomers
• ✅ All other 8 entries are accurate, concise, and practical
• ✅ Anchor links preserved correctly
• ✅ Clean, consistent tone throughout

🧠 Reviewed using Matt Pocock's skills by Matt Pocock Skills Reviewer · 53.5 AIC · ⌖ 6.68 AIC · ⊞ 6.7K
_{Comment /matt to run again}

[github-actions]

[/grill-with-docs] The entry says "seeing their last run result" but gh aw status only shows run status when --ref is passed — without it you only get enabled/disabled state and schedules.

💡 Suggested wording

| [`gh aw status`](#status) | ... | Verifying workflows are enabled and checking their schedules; add `--ref <branch>` to also see the latest run result |

This sets accurate expectations and surfaces the key flag that unlocks run-history, preventing confusion for new users who don't see run results after their first gh aw status.

@copilot please address this.

[github-actions]

[/grill-with-docs] The entry says "tokens used" but gh aw logs doesn't report token consumption — that metric lives in gh aw audit.

Looking at the logs section, the command downloads raw logs and surfaces tool usage, network patterns, errors, and warnings. Token counts require gh aw audit.

💡 Suggested wording

| [`gh aw logs`](#logs) | ... | Debugging a past run by inspecting output, tool usage, and downloaded artifacts |

Removing "tokens used" avoids sending users to gh aw logs when they actually need gh aw audit.

@copilot please address this.

[github-actions]

Two factual accuracy issues in the new "When to use" column

The addition is directionally good — beginners need this guidance. But two entries make claims that contradict the actual behavior documented on this same page.

🔍 Issues found

gh aw status (line 21) — "Verifying workflows are enabled and seeing their last run result" implies last-run info is shown by default. It is not — the status section explicitly says --ref is required to include run status. A first-time user who runs bare gh aw status will see no run data and have no idea why. (flagged inline)

gh aw logs (line 22) — "tokens used" is attributed to logs, but token consumption data belongs to audit (which explicitly lists "Token consumption, cost" in its Metrics table). The logs section covers tool usage, network patterns, errors, and warnings — not tokens. (existing review comment also covers this)

All other "When to use" entries are accurate.

🔎 Code quality review by PR Code Quality Reviewer · 55.8 AIC · ⌖ 6.53 AIC · ⊞ 5.4K
_{Comment /review to run again}

[github-actions]

Misleading default: "seeing their last run result" requires --ref; bare gh aw status shows no run info and this will confuse beginners.

💡 Suggested fix

The status section states: "With --ref, includes latest run status." — meaning a bare gh aw status shows only state, enabled/disabled, schedules, and labels, but no run results.

A user reading this table entry will run gh aw status, see no run data, and have no idea why.

Suggested rewording:

Checking which workflows are installed and their enabled/disabled state; add --ref <branch> to also see last run status

Or keep it shorter but accurate:

Verifying workflows are enabled (add --ref to also see last run result)

[github-actions]

🎉 This pull request is included in a new release.

Release: v0.82.3