Document why requestReviewsByLogin is the only path for bot reviewers

Spent a session re-verifying every alternative; recording the findings inline so future maintainers don't repeat them. The bot's REST login (Copilot, from GET user/175728472) is rejected by /requested_reviewers because that endpoint validates type=User only. GraphQL requestReviews rejects bot node IDs at schema level. The UI 🔄 button hits a github.com Rails endpoint that needs a session cookie + CSRF — gh's OAuth token cannot satisfy it.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: yeelam-gordon

skills/copilot-pr-autopilot/scripts/01-request-review.ps1

@@ -185,6 +185,18 @@ $beforeId = $beforeEvent.Id
 # ---------- trigger via GraphQL requestReviewsByLogin ----------
 
 $mut = 'mutation($p:ID!){requestReviewsByLogin(input:{pullRequestId:$p,botLogins:["copilot-pull-request-reviewer"]}){pullRequest{number}}}'
+# Why this path and not REST or `requestReviews`? Verified end-to-end:
+#   - REST POST /pulls/{n}/requested_reviewers `reviewers:["Copilot"]`
+#     (the bot's REST login per `GET user/175728472`) → 404. The REST
+#     `reviewers` field accepts type=User only; bots are rejected even
+#     when the login resolves to a Bot record.
+#   - GraphQL `requestReviews` rejects bot node IDs ("Could not resolve
+#     to User node with the global id of 'BOT_…'") at schema level.
+#   - `requestReviewsByLogin.botLogins` is the ONLY public path for bot
+#     reviewers; trade-off is that it requires repo Triage/Write.
+#   - The UI 🔄 button uses a github.com Rails endpoint with a session
+#     cookie + CSRF that gh's OAuth token cannot satisfy.
+# Catch the auth-gated case below and surface the two real workarounds.
 $r = Invoke-Gh -GhArgs @('api','graphql','-f',"query=$mut",'-f',"p=$prNodeId")
 if ($r.ExitCode -ne 0) {
     $isPermErr = ($r.Stderr -match '(?i)does not have (the )?correct permissions|forbidden|HTTP 403')