docs: fix gh-aw guide — correct git add paths, demote compile step, add restricted-secrets callout

.squad/agents/pao/history.md

@@ -118,3 +118,18 @@ Completed full PRD based on research findings. **Document:** `docs/research/jsdo
 - Four-phase approach breaks large effort into digestible increments (Phase 0 validation before JSDoc audit helps mitigate risk of TypeDoc setup failing)
 
 **Decision:** PRD approved for handoff to implementation team. Ready for execution on next sprint.
+
+### gh-aw Guide Fix — Issue #1761 (2026-08-20)
+
+**Task:** Fix three verified errors in `docs/src/content/docs/guide/gh-aw.md` before Brady's end-to-end test series on 2026-08-21.
+
+**Verification:** Created scratch git repo in `$env:TEMP`, ran `gh aw add` against the two Squad workflow sources (`@dev`), inspected all created paths, cleaned up. **Finding: `.github/aw/` is NOT created by `gh aw add`.** All files land under `.github/workflows/` and `.github/skills/`.
+
+**Changes made:**
+1. **`git add` path corrected** (Quick Start step 4, Setup "Commit the workflow files"): `.github/aw/` → `.github/workflows/ .github/skills/`. This was the critical error that could cause false E2E failures.
+2. **`gh aw compile` demoted** from required step to troubleshooting note. Quick Start reduced from 6 to 5 steps. Lock files are generated automatically by `gh aw add`. Upgrading section left unchanged (correct there).
+3. **Restricted secrets callout added** in Setup immediately after the `gh aw add` block, with `--approve` flag workaround.
+
+**Decision record:** `.squad/decisions/inbox/pao-1761-gh-aw-path-verification.md`
+
+**PR:** Closes #1761

docs/src/content/docs/guide/gh-aw.md

@@ -15,7 +15,7 @@ This guide covers setup, every slash command, and daily usage patterns.
 
 ## Quick start
 
-Six steps from zero to a working Squad team:
+Five steps from zero to a working Squad team:
 
 ```bash
 # 1. Install the gh-aw extension (one-time)
@@ -31,15 +31,12 @@ gh aw add \
   bradygaster/squad/workflows/squad-implement-worker.md@dev \
   bradygaster/squad/workflows/squad.md@dev
 
-# 4. Compile the workflows to lock files
-gh aw compile
-
-# 5. Commit and push the workflow sources and generated files
-git add -- .gitattributes .github/aw/ .github/workflows/
+# 4. Commit and push the workflow sources and generated files
+git add -- .gitattributes .github/workflows/ .github/skills/
 git commit -m "ci: add Squad agentic workflow"
 git push
 
-# 6. Open an issue and type /squad cast — done!
+# 5. Open an issue and type /squad cast — done!
 ```
 
 After pushing, open an issue in your repo and write `/squad cast` in the body or
@@ -95,31 +92,39 @@ that dispatches it.
 > **Branch note:** `@dev` pulls from the latest development branch where new modes and fixes land first. Stay on `@dev` to get improvements as they ship. Once gh-aw support reaches stable, you can switch to `@main` or drop the ref entirely for the default branch.
 
 This registers the Squad workflow in your repository's agentic workflow
-configuration.
-
-### Compile to lock files
-
-```bash
-gh aw compile
-```
-
-Compiling resolves both workflow definitions and their shared imports into
-deterministic `.lock.yml` files. These lock files are what GitHub Actions
-actually executes.
+configuration and automatically compiles the workflow definitions into
+deterministic `.lock.yml` files — no separate compile step is needed.
+
+> **Restricted secrets prompt:** During `gh aw add`, you may see a safe-update-mode
+> warning listing new restricted secrets (`SQUAD_GITHUB_APP_PRIVATE_KEY`,
+> `SQUAD_GITHUB_TOKEN`). This is expected. Run with `--approve` to accept the changes:
+>
+> ```bash
+> gh aw add --approve \
+>   bradygaster/squad/workflows/squad-implement-worker.md@dev \
+>   bradygaster/squad/workflows/squad.md@dev
+> ```
 
 ### Commit the workflow files
 
 ```bash
-git add -- .gitattributes .github/aw/ .github/workflows/
+git add -- .gitattributes .github/workflows/ .github/skills/
 git commit -m "ci: add Squad agentic workflow"
 git push
 ```
 
-This stages everything under `.github/aw/` and `.github/workflows/` so new shared imports, additional lock files, or updated shared workflow files are all captured automatically — no need to update the command as Squad's shipped files evolve.
+This stages everything `gh aw add` wrote — workflow source files and their
+compiled `.lock.yml` files under `.github/workflows/`, the agentic-workflows
+skill under `.github/skills/`, and the `.gitattributes` entry that marks lock
+files as generated. No need to update this command as Squad's shipped files
+evolve.
+
+> **Troubleshooting:** If the lock files are missing or you need to regenerate
+> them manually, run `gh aw compile`. This is only needed if something went wrong
+> during `gh aw add`.
 
-Downloaded workflow audit data under `.github/aw/logs/` is local diagnostic
-output and should not be committed. The `gh aw logs` and `gh aw audit` commands
-normally create `.github/aw/logs/.gitignore`; if it is missing, add:
+Downloaded workflow audit data is local diagnostic output and should not be
+committed. If a `.gitignore` is missing from your workflow logs directory, add:
 
 ```gitignore
 # Ignore all downloaded workflow logs