docs(gh-aw): fix setup guide contradictions and sync enlistment guidance

.squad-templates/skills/gh-aw-enlistment/SKILL.md

@@ -382,13 +382,27 @@ gh pr create \
   --base "${default_branch}" \
   --title "ci: add Squad agentic workflow" \
   --body "Installs and strictly compiles the supported Squad GH-AW workflows."
-gh pr edit --add-reviewer @copilot
+
+# Copilot's review identity is a GraphQL Bot, not a User/Team — the REST
+# `gh pr edit --add-reviewer @copilot` path silently no-ops for it. Request the
+# review through the verified GraphQL path instead:
+pr_node_id="$(gh pr view --json id --jq '.id')"
+gh api graphql -f query='
+  mutation($pr: ID!) {
+    requestReviewsByLogin(input: { pullRequestId: $pr, botLogins: ["copilot-pull-request-reviewer"] }) {
+      pullRequest { number }
+    }
+  }' -f pr="${pr_node_id}" || echo "Could not request a Copilot review via GraphQL; open the PR in the GitHub UI and add Copilot as a reviewer manually (Reviewers -> Copilot)." >&2
 gh pr checks --watch
 ```
 
 - Open the PR against the **runtime-captured** `${default_branch}`, not a hardcoded
   `main`.
-- Request Copilot review, address feedback, and wait for required checks.
+- Request Copilot review via the GraphQL `requestReviewsByLogin` mutation
+  (never the REST `--add-reviewer` shortcut, which silently no-ops for the
+  Copilot Bot reviewer), address feedback, and wait for required checks. If
+  the GraphQL call fails, add Copilot as a reviewer manually from the PR's
+  GitHub UI.
 
 ### 9. Verify the native review contract after merge
 
@@ -497,7 +511,13 @@ git push -u origin HEAD
 gh pr create --base "${default_branch}" \
   --title "ci: add Squad agentic workflow" \
   --body "Installs and strictly compiles the supported Squad GH-AW workflows."
-gh pr edit --add-reviewer @copilot   # then wait for review + checks; DO NOT merge
+pr_node_id="$(gh pr view --json id --jq '.id')"
+gh api graphql -f query='
+  mutation($pr: ID!) {
+    requestReviewsByLogin(input: { pullRequestId: $pr, botLogins: ["copilot-pull-request-reviewer"] }) {
+      pullRequest { number }
+    }
+  }' -f pr="${pr_node_id}"   # Bot-aware review request; then wait for review + checks; DO NOT merge
 ```
 
 ### ✓ Correct: STOP on an undocumented safe-update entry

packages/squad-cli/templates/skills/gh-aw-enlistment/SKILL.md

@@ -382,13 +382,27 @@ gh pr create \
   --base "${default_branch}" \
   --title "ci: add Squad agentic workflow" \
   --body "Installs and strictly compiles the supported Squad GH-AW workflows."
-gh pr edit --add-reviewer @copilot
+
+# Copilot's review identity is a GraphQL Bot, not a User/Team — the REST
+# `gh pr edit --add-reviewer @copilot` path silently no-ops for it. Request the
+# review through the verified GraphQL path instead:
+pr_node_id="$(gh pr view --json id --jq '.id')"
+gh api graphql -f query='
+  mutation($pr: ID!) {
+    requestReviewsByLogin(input: { pullRequestId: $pr, botLogins: ["copilot-pull-request-reviewer"] }) {
+      pullRequest { number }
+    }
+  }' -f pr="${pr_node_id}" || echo "Could not request a Copilot review via GraphQL; open the PR in the GitHub UI and add Copilot as a reviewer manually (Reviewers -> Copilot)." >&2
 gh pr checks --watch
 ```
 
 - Open the PR against the **runtime-captured** `${default_branch}`, not a hardcoded
   `main`.
-- Request Copilot review, address feedback, and wait for required checks.
+- Request Copilot review via the GraphQL `requestReviewsByLogin` mutation
+  (never the REST `--add-reviewer` shortcut, which silently no-ops for the
+  Copilot Bot reviewer), address feedback, and wait for required checks. If
+  the GraphQL call fails, add Copilot as a reviewer manually from the PR's
+  GitHub UI.
 
 ### 9. Verify the native review contract after merge
 
@@ -497,7 +511,13 @@ git push -u origin HEAD
 gh pr create --base "${default_branch}" \
   --title "ci: add Squad agentic workflow" \
   --body "Installs and strictly compiles the supported Squad GH-AW workflows."
-gh pr edit --add-reviewer @copilot   # then wait for review + checks; DO NOT merge
+pr_node_id="$(gh pr view --json id --jq '.id')"
+gh api graphql -f query='
+  mutation($pr: ID!) {
+    requestReviewsByLogin(input: { pullRequestId: $pr, botLogins: ["copilot-pull-request-reviewer"] }) {
+      pullRequest { number }
+    }
+  }' -f pr="${pr_node_id}"   # Bot-aware review request; then wait for review + checks; DO NOT merge
 ```
 
 ### ✓ Correct: STOP on an undocumented safe-update entry

packages/squad-sdk/templates/skills/gh-aw-enlistment/SKILL.md

@@ -382,13 +382,27 @@ gh pr create \
   --base "${default_branch}" \
   --title "ci: add Squad agentic workflow" \
   --body "Installs and strictly compiles the supported Squad GH-AW workflows."
-gh pr edit --add-reviewer @copilot
+
+# Copilot's review identity is a GraphQL Bot, not a User/Team — the REST
+# `gh pr edit --add-reviewer @copilot` path silently no-ops for it. Request the
+# review through the verified GraphQL path instead:
+pr_node_id="$(gh pr view --json id --jq '.id')"
+gh api graphql -f query='
+  mutation($pr: ID!) {
+    requestReviewsByLogin(input: { pullRequestId: $pr, botLogins: ["copilot-pull-request-reviewer"] }) {
+      pullRequest { number }
+    }
+  }' -f pr="${pr_node_id}" || echo "Could not request a Copilot review via GraphQL; open the PR in the GitHub UI and add Copilot as a reviewer manually (Reviewers -> Copilot)." >&2
 gh pr checks --watch
 ```
 
 - Open the PR against the **runtime-captured** `${default_branch}`, not a hardcoded
   `main`.
-- Request Copilot review, address feedback, and wait for required checks.
+- Request Copilot review via the GraphQL `requestReviewsByLogin` mutation
+  (never the REST `--add-reviewer` shortcut, which silently no-ops for the
+  Copilot Bot reviewer), address feedback, and wait for required checks. If
+  the GraphQL call fails, add Copilot as a reviewer manually from the PR's
+  GitHub UI.
 
 ### 9. Verify the native review contract after merge
 
@@ -497,7 +511,13 @@ git push -u origin HEAD
 gh pr create --base "${default_branch}" \
   --title "ci: add Squad agentic workflow" \
   --body "Installs and strictly compiles the supported Squad GH-AW workflows."
-gh pr edit --add-reviewer @copilot   # then wait for review + checks; DO NOT merge
+pr_node_id="$(gh pr view --json id --jq '.id')"
+gh api graphql -f query='
+  mutation($pr: ID!) {
+    requestReviewsByLogin(input: { pullRequestId: $pr, botLogins: ["copilot-pull-request-reviewer"] }) {
+      pullRequest { number }
+    }
+  }' -f pr="${pr_node_id}"   # Bot-aware review request; then wait for review + checks; DO NOT merge
 ```
 
 ### ✓ Correct: STOP on an undocumented safe-update entry

templates/skills/gh-aw-enlistment/SKILL.md

@@ -382,13 +382,27 @@ gh pr create \
   --base "${default_branch}" \
   --title "ci: add Squad agentic workflow" \
   --body "Installs and strictly compiles the supported Squad GH-AW workflows."
-gh pr edit --add-reviewer @copilot
+
+# Copilot's review identity is a GraphQL Bot, not a User/Team — the REST
+# `gh pr edit --add-reviewer @copilot` path silently no-ops for it. Request the
+# review through the verified GraphQL path instead:
+pr_node_id="$(gh pr view --json id --jq '.id')"
+gh api graphql -f query='
+  mutation($pr: ID!) {
+    requestReviewsByLogin(input: { pullRequestId: $pr, botLogins: ["copilot-pull-request-reviewer"] }) {
+      pullRequest { number }
+    }
+  }' -f pr="${pr_node_id}" || echo "Could not request a Copilot review via GraphQL; open the PR in the GitHub UI and add Copilot as a reviewer manually (Reviewers -> Copilot)." >&2
 gh pr checks --watch
 ```
 
 - Open the PR against the **runtime-captured** `${default_branch}`, not a hardcoded
   `main`.
-- Request Copilot review, address feedback, and wait for required checks.
+- Request Copilot review via the GraphQL `requestReviewsByLogin` mutation
+  (never the REST `--add-reviewer` shortcut, which silently no-ops for the
+  Copilot Bot reviewer), address feedback, and wait for required checks. If
+  the GraphQL call fails, add Copilot as a reviewer manually from the PR's
+  GitHub UI.
 
 ### 9. Verify the native review contract after merge
 
@@ -497,7 +511,13 @@ git push -u origin HEAD
 gh pr create --base "${default_branch}" \
   --title "ci: add Squad agentic workflow" \
   --body "Installs and strictly compiles the supported Squad GH-AW workflows."
-gh pr edit --add-reviewer @copilot   # then wait for review + checks; DO NOT merge
+pr_node_id="$(gh pr view --json id --jq '.id')"
+gh api graphql -f query='
+  mutation($pr: ID!) {
+    requestReviewsByLogin(input: { pullRequestId: $pr, botLogins: ["copilot-pull-request-reviewer"] }) {
+      pullRequest { number }
+    }
+  }' -f pr="${pr_node_id}"   # Bot-aware review request; then wait for review + checks; DO NOT merge
 ```
 
 ### ✓ Correct: STOP on an undocumented safe-update entry

test/gh-aw-enlistment-skill.test.ts

@@ -497,7 +497,7 @@ describe('gh-aw-enlistment skill', () => {
 
       const setupSection = guide.slice(
         guide.indexOf('### Enable GitHub Issues'),
-        guide.indexOf('### Allow workflow-created pull requests'),
+        guide.indexOf('### Set Actions pull-request permissions (Profile A, recommended)'),
       );
       expect(setupSection).toContain(
         'test "$(gh api "repos/${owner_repo}" --jq \'.has_issues\')" = "true" || {',

test/standalone-release-workflow.test.ts

@@ -703,7 +703,8 @@ describe('automated package publication', () => {
     expect(ghAwGuide).toContain('gh aw compile --strict --approve');
     expect(ghAwGuide).toContain('gh aw compile --strict');
     expect(ghAwGuide).toContain('gh pr create');
-    expect(ghAwGuide).toContain('gh pr edit --add-reviewer @copilot');
+    expect(ghAwGuide).toContain('requestReviewsByLogin');
+    expect(ghAwGuide).toContain('copilot-pull-request-reviewer');
     expect(ghAwGuide).toContain('gh pr checks --watch');
     expect(ghAwGuide).toContain('.github/aw/');
     expect(ghAwGuide).toContain('`.vscode/settings.json`');

workflows/skills/gh-aw-enlistment/SKILL.md

@@ -382,13 +382,27 @@ gh pr create \
   --base "${default_branch}" \
   --title "ci: add Squad agentic workflow" \
   --body "Installs and strictly compiles the supported Squad GH-AW workflows."
-gh pr edit --add-reviewer @copilot
+
+# Copilot's review identity is a GraphQL Bot, not a User/Team — the REST
+# `gh pr edit --add-reviewer @copilot` path silently no-ops for it. Request the
+# review through the verified GraphQL path instead:
+pr_node_id="$(gh pr view --json id --jq '.id')"
+gh api graphql -f query='
+  mutation($pr: ID!) {
+    requestReviewsByLogin(input: { pullRequestId: $pr, botLogins: ["copilot-pull-request-reviewer"] }) {
+      pullRequest { number }
+    }
+  }' -f pr="${pr_node_id}" || echo "Could not request a Copilot review via GraphQL; open the PR in the GitHub UI and add Copilot as a reviewer manually (Reviewers -> Copilot)." >&2
 gh pr checks --watch
 ```
 
 - Open the PR against the **runtime-captured** `${default_branch}`, not a hardcoded
   `main`.
-- Request Copilot review, address feedback, and wait for required checks.
+- Request Copilot review via the GraphQL `requestReviewsByLogin` mutation
+  (never the REST `--add-reviewer` shortcut, which silently no-ops for the
+  Copilot Bot reviewer), address feedback, and wait for required checks. If
+  the GraphQL call fails, add Copilot as a reviewer manually from the PR's
+  GitHub UI.
 
 ### 9. Verify the native review contract after merge
 
@@ -497,7 +511,13 @@ git push -u origin HEAD
 gh pr create --base "${default_branch}" \
   --title "ci: add Squad agentic workflow" \
   --body "Installs and strictly compiles the supported Squad GH-AW workflows."
-gh pr edit --add-reviewer @copilot   # then wait for review + checks; DO NOT merge
+pr_node_id="$(gh pr view --json id --jq '.id')"
+gh api graphql -f query='
+  mutation($pr: ID!) {
+    requestReviewsByLogin(input: { pullRequestId: $pr, botLogins: ["copilot-pull-request-reviewer"] }) {
+      pullRequest { number }
+    }
+  }' -f pr="${pr_node_id}"   # Bot-aware review request; then wait for review + checks; DO NOT merge
 ```
 
 ### ✓ Correct: STOP on an undocumented safe-update entry

workflows/squad-workflows.manifest.json

@@ -225,7 +225,7 @@
       "name": "gh-aw-enlistment",
       "source": "workflows/skills/gh-aw-enlistment/SKILL.md",
       "destination": ".github/skills/gh-aw-enlistment/SKILL.md",
-      "sha256": "fc6b63c3156d7861d28fcf459abee9e7f041d3581516ec38a684d5a902a27ac5"
+      "sha256": "dcf8b2975ecfd049f1689a4f68c183b074cebbd7455c19af680e25af673f1c5c"
     }
   ],
   "bootstrap": {