Clarify ProjectOps PAT requirements for user vs org Projects v2

Co-authored-by: mnkiefer <8320933+mnkiefer@users.noreply.github.com>

Author: Copilot

docs/src/content/docs/examples/issue-pr-events/projectops.md

@@ -13,6 +13,46 @@ By default, `update-project` is update-only: create the Project once in the GitH
 
 **Important**: GitHub Projects v2 requires a PAT or GitHub App token - the default `GITHUB_TOKEN` cannot access Projects v2. Configure [`GH_AW_PROJECT_GITHUB_TOKEN`](/gh-aw/reference/tokens/#gh_aw_project_github_token-github-projects-v2) before using `update-project`.
 
+## Token Requirements for Projects v2
+
+The type of Personal Access Token (PAT) you need depends on whether you're working with **user-owned** or **organization-owned** Projects:
+
+### User-owned Projects (v2)
+
+**Must use a classic PAT** - Fine-grained PATs do **not** work with user-owned Projects.
+
+Required scopes:
+- `project` (required for user Projects)
+- `repo` (required if accessing private repositories)
+
+Create at: [https://github.com/settings/tokens/new](https://github.com/settings/tokens/new)
+
+### Organization-owned Projects (v2)
+
+**Can use either classic or fine-grained PAT**:
+
+**Option 1: Classic PAT**
+- `project` (required)
+- `read:org` (required for org Projects)
+- `repo` (required if accessing private repositories)
+
+**Option 2: Fine-grained PAT**
+- Repository access: Select specific repos or "All repositories"
+- **Organization permissions** (must be explicitly granted):
+  - **Organization access**: Must be granted to the target organization
+  - **Projects**: Read+Write
+- **Important**: Fine-grained PATs work by default only for public org resources. You must explicitly grant organization access and Projects permissions.
+
+Create at: [https://github.com/settings/personal-access-tokens/new](https://github.com/settings/personal-access-tokens/new)
+
+**Setup**: After creating your PAT, add it to your repository:
+
+```bash
+gh aw secrets set GH_AW_PROJECT_GITHUB_TOKEN --value "YOUR_PROJECT_PAT"
+```
+
+See the [GitHub Projects v2 token reference](/gh-aw/reference/tokens/#gh_aw_project_github_token-github-projects-v2) for complete details.
+
 ## When to Use ProjectOps
 
 ProjectOps complements [GitHub's built-in Projects automation](https://docs.github.com/en/issues/planning-and-tracking-with-projects/automating-your-project/using-the-built-in-automations) with AI-powered intelligence:

docs/src/content/docs/reference/safe-outputs.md

@@ -360,7 +360,11 @@ safe-outputs:
 
 Agent output **must include a full GitHub project URL** in the `project` field (e.g., `https://github.com/orgs/myorg/projects/42` or `https://github.com/users/username/projects/5`). Project names or numbers alone are not accepted. Can also supply `content_number`, `content_type`, `fields`, and `campaign_id`. The job adds the issue or PR to the board, updates custom fields, applies `campaign:<id>` labels, and exposes `project-id`, `project-number`, `project-url`, `campaign-id`, and `item-id` outputs. Cross-repository targeting not supported.
 
-To opt in to creating missing project boards, include `create_if_missing: true` in the `update_project` output. Your token must have sufficient permissions to create projects in the organization (classic PAT with `project` + `repo` scopes, or fine-grained PAT with Projects: Read+Write, or GitHub App with Projects permissions).
+To opt in to creating missing project boards, include `create_if_missing: true` in the `update_project` output. Your token must have sufficient permissions:
+- **User-owned Projects**: Classic PAT with `project` + `repo` scopes (fine-grained PATs don't work)
+- **Organization-owned Projects**: Classic PAT with `project` + `read:org` scopes, or fine-grained PAT with explicit Organization access and Projects: Read+Write, or GitHub App with Projects permissions
+
+See [GitHub Projects v2 token requirements](/gh-aw/reference/tokens/#gh_aw_project_github_token-github-projects-v2) for detailed setup instructions.
 
 ### Pull Request Creation (`create-pull-request:`)
 

docs/src/content/docs/reference/tokens.md

@@ -197,13 +197,35 @@ A specialized token for GitHub Projects v2 operations used by the [`update-proje
 
 **Setup**:
 
-1. Create a **classic PAT** with `project` and `repo` scopes, **OR** a [fine-grained PAT](https://github.com/settings/personal-access-tokens/new) with:
+The required token type depends on whether you're working with **user-owned** or **organization-owned** Projects:
+
+**For User-owned Projects (v2)**:
+
+You **must** use a **classic PAT** with the `project` scope. Fine-grained PATs do **not** work with user-owned Projects.
+
+1. Create a [classic PAT](https://github.com/settings/tokens/new) with scopes:
+   - `project` (required for user Projects)
+   - `repo` (required if accessing private repositories)
+
+**For Organization-owned Projects (v2)**:
+
+You can use either a classic PAT or a fine-grained PAT:
+
+1. **Option A**: Create a **classic PAT** with `project` and `read:org` scopes:
+   - `project` (required)
+   - `read:org` (required for org Projects)
+   - `repo` (required if accessing private repositories)
+
+2. **Option B**: Create a [fine-grained PAT](https://github.com/settings/personal-access-tokens/new) with:
    - Repository access: Select specific repos or "All repositories"
-   - Organization permissions:
-     - Projects: Read+Write (for creating and managing org Projects)
-   - **OR** use a GitHub App with Projects: Read+Write permission
+   - **Organization permissions** (must be explicitly granted):
+     - **Organization access**: Must be granted to the target organization
+     - **Projects**: Read+Write (for creating and managing org Projects)
+   - **Important**: Fine-grained PATs work by default only for public org resources. You must explicitly grant organization access and Projects permissions.
 
-2. Add to repository secrets:
+3. **Option C**: Use a GitHub App with Projects: Read+Write permission
+
+After creating your token, add it to repository secrets:
 
 ```bash wrap
 gh aw secrets set GH_AW_PROJECT_GITHUB_TOKEN --value "YOUR_PROJECT_PAT"
@@ -235,7 +257,12 @@ safe-outputs:
 :::note[Default behavior]
 By default, `update-project` is **update-only**: it will not create projects. If a project doesn't exist, the job fails with instructions to create it manually.
 
-**Important**: The default `GITHUB_TOKEN` **cannot** be used for Projects v2 operations. You **must** configure `GH_AW_PROJECT_GITHUB_TOKEN` or provide a custom token via `safe-outputs.update-project.github-token`. GitHub Projects v2 requires GraphQL API access with a PAT (classic with `project` + `repo` scopes, or fine-grained with Projects permissions) or a GitHub App.
+**Important**: The default `GITHUB_TOKEN` **cannot** be used for Projects v2 operations. You **must** configure `GH_AW_PROJECT_GITHUB_TOKEN` or provide a custom token via `safe-outputs.update-project.github-token`. 
+
+**GitHub Projects v2 PAT Requirements**:
+- **User-owned Projects**: Require a **classic PAT** with the `project` scope (plus `repo` if accessing private repos). Fine-grained PATs do **not** work with user-owned Projects.
+- **Organization-owned Projects**: Can use either a classic PAT with `project` + `read:org` scopes, **or** a fine-grained PAT with explicit Organization access granted plus Projects: Read+Write permission. Fine-grained PATs work by default only for public org resources and must be explicitly granted organization access.
+- **GitHub App**: Works for both user and org Projects with Projects: Read+Write permission.
 
 To opt-in to creating projects, the agent must include `create_if_missing: true` in its output, and the token must have sufficient permissions to create projects in the organization.
 :::