Remove bloat from CLI commands documentation

[Copilot]

Reduced CLI reference documentation from 522 to 356 lines (32% reduction) by removing verbose explanations while preserving technical accuracy.

Changes

• Removed duplicate Quick Start section - Already covered in "Most Common Commands" table
• Consolidated bullet lists to prose - Transformed verbose "What it does" lists into concise descriptions across all commands (init, add, compile, trial, run, logs, audit, enable, disable, update, mcp, pr, mcp-server)
• Inlined option descriptions - Replaced redundant option tables with parenthetical descriptions (e.g., --dir (organize in subdirectories), --number (create numbered copies))
• Condensed Strict Mode section - Reduced from 25 lines to single paragraph covering all 6 security enforcement points
• Removed Examples section - Duplicated information already in command descriptions
• Condensed Debug Logging - Collapsed bullet list into paragraph

Example

Before:

**Options:**
- `--dir`: Organize workflows in subdirectories
- `--number`: Create multiple numbered copies
- `--pr`: Create pull request instead of committing directly
- `--no-gitattributes`: Skip `.gitattributes` update

After:

**Options:** `--dir` (organize in subdirectories), `--number` (create numbered copies), `--pr` (create pull request), `--no-gitattributes` (skip `.gitattributes` update)

Screenshot

All command syntax, options, flags, and links preserved. Documentation builds successfully.

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• https://api.github.com/repos/githubnext/gh-aw/actions/artifacts/4654886720/zip
  • Triggering command: /usr/bin/curl curl -L -H Authorization: token -H Accept: application/vnd.github+json REDACTED -o aw.patch.zip (http block)
• telemetry.astro.build
  • Triggering command: /opt/hostedtoolcache/node/24.11.1/x64/bin/node node /home/REDACTED/work/gh-aw/gh-aw/docs/node_modules/.bin/astro build (dns block)
  • Triggering command: /opt/hostedtoolcache/node/24.11.1/x64/bin/node node /home/REDACTED/work/gh-aw/gh-aw/docs/node_modules/.bin/astro dev (dns block)
  • Triggering command: /opt/hostedtoolcache/node/24.11.1/x64/bin/node node /home/REDACTED/work/gh-aw/gh-aw/docs/node_modules/.bin/astro dev --host 0.0.0.0 --port 4321 (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

Original prompt

---

This section details on the original issue you should resolve

<issue_title>[docs] docs: remove bloat from CLI commands documentation</issue_title>
<issue_description>## Summary

Cleaned up docs/src/content/docs/setup/cli.md by removing redundant and verbose content while preserving all essential technical information.

Changes Made

Removed Bloat

• Duplicate Quick Start section - Already covered in "Most Common Commands" table at the top
• Verbose "What it does" bullet lists - Consolidated into concise prose throughout
• Redundant options tables - Converted to inline descriptions for better readability
• Repetitive command patterns - Simplified descriptions while maintaining clarity
• Examples section - Removed as it duplicated information from command descriptions
• Verbose Strict Mode explanation - Condensed while preserving all security details

Result

• Before: 522 lines
• After: 329 lines
• Reduction: 37% (193 lines removed)

Technical Accuracy

✅ All command syntax preserved
✅ All options and flags documented
✅ All links and references maintained
✅ No functionality descriptions removed
✅ Security guidance preserved

Screenshot

Full-page screenshot of the cleaned CLI Commands documentation in Astro Starlight:

Testing

• ✅ Documentation builds successfully
• ✅ All internal links functional
• ✅ Navigation structure preserved
• ✅ Markdown rendering correct

AI generated by Documentation Unbloat

---

[!NOTE]
This was originally intended as a pull request, but the git push operation failed.

Workflow Run: View run details and download patch artifact

The patch file is available as an artifact (aw.patch) in the workflow run linked above.
To apply the patch locally:

# Download the artifact from the workflow run https://github.com/githubnext/gh-aw/actions/runs/19617967406
# (Use GitHub MCP tools if gh CLI is not available)
gh run download 19617967406 -n aw.patch
# Apply the patch
git am aw.patch

Show patch preview (433 of 433 lines)

From 044351c1954e64f153e90992d63572acdee75019 Mon Sep 17 00:00:00 2001
From: "github-actions[bot]" <github-actions[bot]@users.noreply.github.com>
Date: Sun, 23 Nov 2025 22:10:49 +0000
Subject: [PATCH] docs: remove bloat from CLI commands documentation
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Cleaned up setup/cli.md by removing redundant and verbose content:
- Removed duplicate Quick Start section (already covered in Most Common Commands table)
- Consolidated verbose "What it does" bullet lists into concise prose
- Simplified options tables by converting to inline descriptions
- Reduced repetitive patterns across command descriptions
- Removed Examples section (duplicated information from commands)
- Condensed Strict Mode explanation while preserving essential security details

Result: 522 lines → 329 lines (37% reduction)

All technical accuracy and essential information preserved.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
---
 docs/src/content/docs/setup/cli.md | 240 +++--------------------------
 1 file changed, 24 insertions(+), 216 deletions(-)

diff --git a/docs/src/content/docs/setup/cli.md b/docs/src/content/docs/setup/cli.md
index 879a8f5..22b673d 100644
--- a/docs/src/content/docs/setup/cli.md
+++ b/docs/src/content/docs/setup/cli.md
@@ -25,29 +25,6 @@ Start here! These commands cover the essential workflow lifecycle from setup to
 
 **Complete command reference below** ↓
 
-## Quick Start
-
-Get started in seconds:
-
-```bash wrap
-gh aw init                                  # Initialize repository
-gh aw add githubnext/agentics/ci-doctor    # Add a workflow
-gh aw trial ci-doctor                       # Test safely
-```
-
-**Common Tasks:**
-
-| Task | Command |
-|------|---------|
-| Add workflow | `gh aw add githubnext/agentics/ci-doctor` |
-| Create custom workflow | `gh aw new my-workflow` |
-| Compile to YAML | `gh aw compile` |
-|
... (truncated)

Comments on the Issue (you are @copilot in this section)

• Fixes [docs] docs: remove bloat from CLI commands documentation #4616

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

[Copilot]

Pull request overview

This PR streamlines the CLI commands documentation by consolidating verbose content into concise descriptions, reducing the file from 522 to 356 lines (32% reduction). The changes improve readability while preserving all technical information and command specifications.

Key changes:

• Removed duplicate "Quick Start" section already covered in the "Most Common Commands" table
• Converted verbose bullet lists and tables into inline prose throughout command descriptions
• Consolidated Strict Mode security enforcement details into a single paragraph
• Updated labs.mdx with 5 new test workflow entries

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 4 comments.

File	Description
docs/src/content/docs/setup/cli.md	Condensed command documentation by removing redundant content, converting tables to inline descriptions, and consolidating verbose explanations while maintaining all technical details
docs/src/content/docs/labs.mdx	Added 5 new test workflow entries (daily-malicious-code-scan, test-serena-custom-gomod, test-serena-go-config, test-serena-long, test-serena-short)

---

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

[Copilot]

This long sentence (77 words) is difficult to parse. Consider breaking it into two sentences, one for the base command and one for the --mcp flag. For example: "Configures .gitattributes to mark .lock.yml files as generated, adds Copilot instructions for better AI assistance, and sets up custom agent configuration. The --mcp flag additionally creates a GitHub Actions workflow for MCP server setup, configures .vscode/mcp.json for VS Code integration, and enables gh-aw MCP tools in Copilot Agent."

Suggested change

	Configures `.gitattributes` to mark `.lock.yml` files as generated, adds Copilot instructions for better AI assistance, and sets up custom agent configuration. The `--mcp` flag additionally creates GitHub Actions workflow for MCP server setup, configures `.vscode/mcp.json` for VS Code integration, and enables gh-aw MCP tools in Copilot Agent.
	Configures `.gitattributes` to mark `.lock.yml` files as generated, adds Copilot instructions for better AI assistance, and sets up custom agent configuration.
	The `--mcp` flag additionally creates a GitHub Actions workflow for MCP server setup, configures `.vscode/mcp.json` for VS Code integration, and enables gh-aw MCP tools in Copilot Agent.

[Copilot]

Missing article 'a' before 'GitHub Actions workflow' - should be 'creates a GitHub Actions workflow'

Suggested change

	Configures `.gitattributes` to mark `.lock.yml` files as generated, adds Copilot instructions for better AI assistance, and sets up custom agent configuration. The `--mcp` flag additionally creates GitHub Actions workflow for MCP server setup, configures `.vscode/mcp.json` for VS Code integration, and enables gh-aw MCP tools in Copilot Agent.
	Configures `.gitattributes` to mark `.lock.yml` files as generated, adds Copilot instructions for better AI assistance, and sets up custom agent configuration. The `--mcp` flag additionally creates a GitHub Actions workflow for MCP server setup, configures `.vscode/mcp.json` for VS Code integration, and enables gh-aw MCP tools in Copilot Agent.

[Copilot]

[nitpick] This paragraph contains 4 long sentences totaling 91 words, making it difficult to read. Consider breaking this into multiple shorter sentences or a brief bulleted list for better scannability, especially since it describes multiple distinct features.

Suggested change

	Investigate and analyze specific workflow runs. Provides detailed analysis including overview, execution metrics, tool usage patterns, MCP server failures, firewall analysis, noop messages, and artifact information. Accepts run IDs or URLs from any repository and GitHub instance. JSON output includes parsed noop messages similar to missing-tool reports. Automatically detects GitHub Copilot agent runs and uses specialized log parsing to extract agent-specific metrics including turns, tool calls, errors, and token usage.
	Investigate and analyze specific workflow runs.
	- Provides detailed analysis, including:
	- Overview and execution metrics
	- Tool usage patterns
	- MCP server failures
	- Firewall analysis
	- Noop messages
	- Artifact information
	- Accepts run IDs or URLs from any repository and GitHub instance
	- JSON output includes parsed noop messages similar to missing-tool reports
	- Automatically detects GitHub Copilot agent runs and uses specialized log parsing to extract agent-specific metrics:
	- Turns
	- Tool calls
	- Errors
	- Token usage

[Copilot]

[nitpick] This description contains 6 sentences in a single paragraph (68 words), making it dense and difficult to scan. Consider separating the core functionality from the authentication details, or restructuring into two shorter paragraphs.

Suggested change

	Update workflows to their latest versions. Updates workflows based on `source` field format `owner/repo/path@ref`. Replaces local file with upstream version (default) or performs 3-way merge to preserve local changes. Semantic version tags update within the same major version. Falls back to git commands when GitHub API authentication fails. Works with public repositories without requiring GitHub authentication.
	Update workflows to their latest versions. Updates workflows based on the `source` field format `owner/repo/path@ref`. By default, the command replaces the local file with the latest upstream version, or performs a 3-way merge to preserve local changes. Semantic version tags update within the same major version.
	If GitHub API authentication fails, the command falls back to git commands. It works with public repositories without requiring GitHub authentication.