diff --git a/docs/src/content/docs/setup/cli.md b/docs/src/content/docs/setup/cli.md
index 2c2ee507d52..51c866dbe54 100644
--- a/docs/src/content/docs/setup/cli.md
+++ b/docs/src/content/docs/setup/cli.md
@@ -144,6 +144,14 @@ For `init`, `update`, and `upgrade`, use `--create-pull-request` instead.
 
 Commands are organized by workflow lifecycle: creating, building, testing, monitoring, and managing workflows.
 
+Use this table to choose between the similarly named setup commands:
+
+| Command | Best fit |
+|---------|----------|
+| [`gh aw add-wizard`](#add-wizard) | Guided, interactive setup for an existing workflow, including prompts for engine auth and secrets |
+| [`gh aw add`](#add) | Direct, non-interactive installation of an existing local, remote, or packaged workflow |
+| [`gh aw new`](#new) | Scaffold a new workflow template in this repository before writing custom instructions |
+
 ### Getting Workflows
 
 #### `init`
diff --git a/docs/src/content/docs/setup/quick-start.mdx b/docs/src/content/docs/setup/quick-start.mdx
index af3b580d380..8b94a31860c 100644
--- a/docs/src/content/docs/setup/quick-start.mdx
+++ b/docs/src/content/docs/setup/quick-start.mdx
@@ -126,6 +126,70 @@ This will take you through an interactive process to:
 > [!NOTE]
 > The `.lock.yml` is the compiled GitHub Actions workflow generated from your Markdown source. GitHub Actions executes this file; regenerate it with `gh aw compile` after frontmatter changes instead of editing it by hand. See [Lock File](/gh-aw/reference/workflow-structure/#lock-file-header) for the full explanation.
 
+For example, a short Markdown source file compiles into a longer GitHub Actions workflow. In the compiled excerpt, the top-level `permissions` map is empty because `gh-aw` moves source-level permissions onto the generated jobs that need them.
+
+<div style={{ display: 'grid', gridTemplateColumns: 'repeat(auto-fit, minmax(18rem, 1fr))', gap: '1rem' }}>
+
+<div>
+
+**Markdown source (`.md`)**
+
+```aw title=".github/workflows/issue-helper.md"
+---
+name: Issue Helper
+on:
+  issues:
+    types: [opened]
+permissions:
+  contents: read
+  issues: read
+engine: copilot
+---
+
+Summarize the new issue and suggest next steps.
+```
+
+</div>
+
+<div>
+
+**Compiled workflow (`.lock.yml`, excerpt)**
+
+```yaml title=".github/workflows/issue-helper.lock.yml"
+# This file was automatically generated by gh-aw. DO NOT EDIT.
+name: "Issue Helper"
+on:
+  issues:
+    types:
+      - opened
+
+permissions: {}
+
+jobs:
+  activation:
+    runs-on: ...
+    permissions:
+      contents: read
+      issues: read
+    steps:
+      - name: Generate workflow metadata
+        id: generate_aw_info
+        ...
+  agent:
+    needs: activation
+    runs-on: ...
+    permissions:
+      contents: read
+      issues: read
+    steps:
+      - name: Run agent
+        ...
+```
+
+</div>
+
+</div>
+
 **Configuring authentication?** Select the engine you chose above:
 
 <Tabs>