diff --git a/docs/src/content/docs/reference/safe-outputs.md b/docs/src/content/docs/reference/safe-outputs.md
index a15dce0e0c..d0e23fa455 100644
--- a/docs/src/content/docs/reference/safe-outputs.md
+++ b/docs/src/content/docs/reference/safe-outputs.md
@@ -7,10 +7,21 @@ sidebar:
 
 The [`safe-outputs:`](/gh-aw/reference/glossary/#safe-outputs) element of your workflow's frontmatter declares that your agentic workflow should conclude with optional automated actions based on the agentic workflow's output. This enables your workflow to write content that is then automatically processed to create GitHub issues, comments, pull requests, or add labels—all without giving the agentic portion of the workflow any write permissions.
 
+## Why Safe Outputs?
+
+**Safe outputs are a security feature.** Your AI agent runs with minimal permissions (read-only access by default). When the agent wants to make changes to your repository—like creating an issue, adding a comment, or opening a pull request—it cannot do so directly. Instead, it "requests" that action by writing structured output to a file.
+
+A separate, permission-controlled job then reviews and executes these requests. This architecture provides:
+
+- **Principle of least privilege**: The AI never has write permissions during execution
+- **Defense against prompt injection**: Malicious inputs cannot trick the AI into making unauthorized changes
+- **Auditability**: All requested actions are logged and can be reviewed before execution
+- **Controlled blast radius**: Each safe output type has strict limits (e.g., maximum number of issues to create)
+
 **How It Works:**
-1. The agentic part of your workflow runs with minimal read-only permissions. It is given additional prompting to write its output to the special known files
+1. The agentic part of your workflow runs with minimal read-only permissions. It is given additional prompting to write its output to special known files
 2. The compiler automatically generates additional jobs that read this output and perform the requested actions
-3. Only these generated jobs receive the necessary write permissions
+3. Only these generated jobs receive the necessary write permissions—scoped precisely to what each safe output type requires
 
 For example:
 
@@ -19,7 +30,7 @@ safe-outputs:
   create-issue:
 ```
 
-This declares that the workflow should create at most one new issue.
+This declares that the workflow should create at most one new issue. The AI agent can request issue creation, but a separate job with `issues: write` permission actually creates it.
 
 ## Available Safe Output Types
 
diff --git a/docs/src/content/docs/setup/cli.md b/docs/src/content/docs/setup/cli.md
index d2b4061883..d923de7c4e 100644
--- a/docs/src/content/docs/setup/cli.md
+++ b/docs/src/content/docs/setup/cli.md
@@ -25,7 +25,56 @@ Start here! These commands cover the essential workflow lifecycle from setup to
 
 **Complete command reference below** ↓
 
+## Common Workflows for Beginners
 
+Learn how to use CLI commands together for common development tasks:
+
+### After creating a new workflow
+
+```bash wrap
+gh aw compile my-workflow      # Check for syntax errors
+gh aw run my-workflow           # Test it manually (if workflow_dispatch enabled)
+gh aw logs my-workflow          # See what happened
+```
+
+**What each command does:**
+- **`compile`**: Validates your markdown and generates the `.lock.yml` file—catches errors before running
+- **`run`**: Triggers the workflow immediately in GitHub Actions (requires `workflow_dispatch` trigger)
+- **`logs`**: Downloads and analyzes execution logs to see what the AI did
+
+### When something goes wrong
+
+```bash wrap
+gh aw status                    # Check configuration and workflow state
+gh aw logs my-workflow          # Review recent execution logs
+gh aw audit (run-id)            # Analyze specific run in detail
+```
+
+**Finding the run-id:**
+1. Go to your repository on GitHub.com
+2. Click the **Actions** tab
+3. Click on a workflow run from the list
+4. The run-id is the number in the URL: `github.com/owner/repo/actions/runs/12345678` → run-id is `12345678`
+
+**What each command reveals:**
+- **`status`**: Shows if workflows are enabled, compiled, and their schedules
+- **`logs`**: Reveals AI decisions, tool usage, network activity, and errors
+- **`audit`**: Provides deep analysis of a specific run including execution metrics, failed tools, and artifacts
+
+### Fixing common issues
+
+```bash wrap
+# Token or secret issues
+gh aw secrets bootstrap --engine copilot   # Check token configuration
+
+# Workflow not found or disabled
+gh aw status                               # List all workflows
+gh aw enable my-workflow                   # Enable if disabled
+
+# Syntax errors in workflow markdown
+gh aw compile my-workflow --validate       # Detailed validation output
+gh aw fix my-workflow --write              # Auto-fix deprecated fields
+```
 
 ## Installation
 
diff --git a/docs/src/content/docs/setup/quick-start.md b/docs/src/content/docs/setup/quick-start.md
index 0dfa2d7676..e2ab4b144d 100644
--- a/docs/src/content/docs/setup/quick-start.md
+++ b/docs/src/content/docs/setup/quick-start.md
@@ -193,6 +193,38 @@ Repository secrets are encrypted and never exposed in workflow logs. Only workfl
 
 For more information, see the [GitHub Copilot CLI documentation](https://github.com/github/copilot-cli?tab=readme-ov-file#authenticate-with-a-personal-access-token-pat).
 
+#### Verify your setup
+
+Before running workflows, verify everything is configured correctly:
+
+```bash wrap
+gh aw status
+```
+
+**Expected output:**
+```
+Workflow                 Engine    State     Enabled  Schedule
+──────────────────────────────────────────────────────────────
+daily-team-status        copilot   ✓         Yes      0 9 * * 1-5
+```
+
+This confirms:
+- ✓ The workflow is compiled and ready
+- ✓ It's enabled for execution
+- ✓ The schedule is configured correctly
+
+:::tip[Troubleshooting]
+**If the workflow isn't listed:**
+- Run `gh aw compile` to compile the workflow
+- Check that `.github/workflows/daily-team-status.md` exists
+
+**If you see errors when running the workflow:**
+- Verify `COPILOT_GITHUB_TOKEN` secret is set correctly in repository settings
+- Check that your token has "Copilot Requests" permission
+- Ensure your token hasn't expired
+- Run `gh aw secrets bootstrap --engine copilot` to check token configuration
+:::
+
 ### Step 4 — Trigger a workflow run
 
 Trigger the workflow immediately in GitHub Actions: