From 1d44b42b89fc1de22fa2ada80e0e933aed8b31a6 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Mon, 6 Jul 2026 06:06:07 +0000
Subject: [PATCH 1/2] Initial plan


From 385172882c4c1be6755ffbcc8406028d2fa046f5 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Mon, 6 Jul 2026 06:11:59 +0000
Subject: [PATCH 2/2] docs: add When to use column to CLI summary table

Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>
---
 docs/src/content/docs/setup/cli.md | 24 ++++++++++++------------
 1 file changed, 12 insertions(+), 12 deletions(-)

diff --git a/docs/src/content/docs/setup/cli.md b/docs/src/content/docs/setup/cli.md
index 03b5c6570e2..f76645d7875 100644
--- a/docs/src/content/docs/setup/cli.md
+++ b/docs/src/content/docs/setup/cli.md
@@ -9,18 +9,18 @@ The `gh aw` CLI extension enables developers to create, manage, and execute AI-p
 
 ## Most Common Commands
 
-| Command | Description |
-|---------|-------------|
-| [`gh aw init`](#init) | Set up your repository for agentic workflows |
-| [`gh aw add-wizard`](#add-wizard) | Add workflows with interactive guided setup |
-| [`gh aw add`](#add) | Add workflows from other repositories (non-interactive) |
-| [`gh aw new`](#new) | Create a new workflow from scratch |
-| [`gh aw compile`](#compile) | Convert markdown to GitHub Actions YAML |
-| [`gh aw list`](#list) | Quick listing of all workflows |
-| [`gh aw run`](#run) | Execute workflows immediately in GitHub Actions |
-| [`gh aw status`](#status) | Check current state of all workflows |
-| [`gh aw logs`](#logs) | Download and analyze agentic workflow logs and artifacts |
-| [`gh aw audit`](#audit) | Audit and compare workflow runs |
+| Command | Description | When to use |
+|---------|-------------|-------------|
+| [`gh aw init`](#init) | Set up your repository for agentic workflows | First time configuring a repo — creates skills, agents, and `.gitattributes` |
+| [`gh aw add-wizard`](#add-wizard) | Add workflows with interactive guided setup | Adding a community workflow and want guided prompts for secrets and auth |
+| [`gh aw add`](#add) | Add workflows from other repositories (non-interactive) | Scripted or CI-based workflow installation without interactive prompts |
+| [`gh aw new`](#new) | Create a new workflow from scratch | Building a custom workflow when no existing template fits |
+| [`gh aw compile`](#compile) | Convert markdown to GitHub Actions YAML | After editing a workflow `.md` file to regenerate the `.lock.yml` |
+| [`gh aw list`](#list) | Quick listing of all workflows | Checking which workflows are installed in the current repository |
+| [`gh aw run`](#run) | Execute workflows immediately in GitHub Actions | Triggering a workflow run from the command line without opening GitHub |
+| [`gh aw status`](#status) | Check current state of all workflows | Verifying workflows are enabled and seeing their last run result |
+| [`gh aw logs`](#logs) | Download and analyze agentic workflow logs and artifacts | Debugging a past run by inspecting output, tokens used, and artifacts |
+| [`gh aw audit`](#audit) | Audit and compare workflow runs | Investigating cost, tool usage, or comparing two runs side-by-side |
 
 > [!TIP]
 > New to `gh aw`? You can stop here for day-one usage and jump to [Commands](#commands) when you're ready. The advanced enterprise setup is collapsed below and can be skipped for most users.