docs: add classic PAT guidance for collaborator/cross-org repos (aws-samples#163)

Fine-grained PATs cannot target repos the user doesn't own (or orgs
that haven't opted in). Document the classic PAT alternative with
repo + read:org scopes, add a "when to use which" decision table to
agent/README.md, and fix the dead "edge cases" reference in the
Developer Guide.

Co-authored-by: bgagent <345885+scottschreckengaust@users.noreply.github.com>
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: scottschreckengaust

agent/README.md

@@ -15,7 +15,11 @@ The Docker image is built for `linux/arm64` to match AgentCore Runtime requireme
 
 ### GitHub PAT — Minimal Permissions
 
-Create a **fine-grained PAT** at GitHub > Settings > Developer settings > Personal access tokens > Fine-grained tokens.
+Two token types work. Choose based on your access model:
+
+#### Fine-grained PAT (recommended for repos you own)
+
+Go to GitHub > **Settings** > **Developer settings** > **Fine-grained tokens**.
 
 **Repository access**: Select only the specific repo(s) the agent will work on.
 
@@ -26,7 +30,29 @@ Create a **fine-grained PAT** at GitHub > Settings > Developer settings > Person
 | **Issues** | Read | Fetch issue title, body, and comments for context |
 | **Metadata** | Read | Granted by default |
 
-No other permissions are needed.
+**Limitation:** Fine-grained PATs can only target repos you own or repos in organizations that have opted in to fine-grained token access. If you are a collaborator on someone else's repo (or an org that hasn't enabled the feature), the repo won't appear in the token creation UI.
+
+#### Classic PAT (required for collaborator/cross-org access)
+
+Use a classic PAT when fine-grained tokens cannot reach the target repository — typically when you are a collaborator on a repo owned by another user or an organization that has not enabled fine-grained token access.
+
+Go to GitHub > **Settings** > **Developer settings** > **Personal access tokens** > **Tokens (classic)**.
+
+| Scope | Reason |
+|-------|--------|
+| `repo` | Full repository access (clone, push, PRs, issues) |
+| `read:org` | Resolve org membership for org-owned repos |
+
+Set an expiration (90 days recommended) and store it in Secrets Manager the same way as a fine-grained token.
+
+#### When to use which
+
+| Scenario | Token type |
+|----------|-----------|
+| Your own repos or your org has fine-grained enabled | Fine-grained |
+| Collaborator on another user's repo | Classic |
+| Org has not opted in to fine-grained tokens | Classic |
+| Targeting repos across multiple orgs | Classic (single token covers all) |
 
 ### AWS Credentials
 

docs/guides/DEVELOPER_GUIDE.md

@@ -41,7 +41,7 @@ Permission requirements vary by task type:
 - `new_task` and `pr_iteration` require Contents (read/write) and Pull requests (read/write).
 - `pr_review` only needs Triage or higher since it does not push branches.
 
-Classic PATs with `repo` scope also work. See `agent/README.md` for edge cases.
+Classic PATs with `repo` + `read:org` scopes also work and are required when fine-grained tokens cannot reach the target repo (collaborator access, cross-org repos). See [agent/README.md](../../agent/README.md#github-pat--minimal-permissions) for when to use which token type.
 
 ### Quick setup (single repo)
 

docs/guides/QUICK_START.md

@@ -57,6 +57,8 @@ The agent authenticates to GitHub using a **fine-grained personal access token (
 
 Keep the token value - you will store it in AWS Secrets Manager after deploying.
 
+> **Collaborator or cross-org repos?** Fine-grained tokens only work for repos you own (or orgs that have opted in). If you're a collaborator on someone else's repo, create a **classic PAT** with `repo` + `read:org` scopes instead. See [agent/README.md](../../agent/README.md#github-pat--minimal-permissions) for details.
+
 ### Register the repo in CDK
 
 Every repository the agent can work on must be **onboarded** as a `Blueprint` construct in the CDK stack. The Blueprint writes a configuration record to DynamoDB; the orchestrator checks this before accepting tasks.

docs/src/content/docs/developer-guide/Repository-preparation.md

@@ -61,6 +61,8 @@ The agent authenticates to GitHub using a **fine-grained personal access token (
 
 Keep the token value - you will store it in AWS Secrets Manager after deploying.
 
+> **Collaborator or cross-org repos?** Fine-grained tokens only work for repos you own (or orgs that have opted in). If you're a collaborator on someone else's repo, create a **classic PAT** with `repo` + `read:org` scopes instead. See [agent/README.md](/architecture/readme#github-pat--minimal-permissions) for details.
+
 ### Register the repo in CDK
 
 Every repository the agent can work on must be **onboarded** as a `Blueprint` construct in the CDK stack. The Blueprint writes a configuration record to DynamoDB; the orchestrator checks this before accepting tasks.