docs: clarify fine-grained PAT requirements for organization-owned Projects v2

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

@@ -15,34 +15,24 @@ Then the [`update-project`](/gh-aw/reference/safe-outputs/#project-board-updates
 
 1. **Create a Project**: Before you wire up a workflow, you must first create the Project in the GitHub UI (user or organization level). Keep the Project URL handy (you'll need to reference it in your workflow instructions).
 
-2. **Create a token**: The kind of token you need depends on whether the Project you created is **user-owned** or **organization-owned** 
-For user-owned projects, use a **classic PAT** with `read:project` scope (for queries) or `project` scope (for queries and mutations).
+2. **Create a token**: The kind of token you need depends on whether the Project you created is **user-owned** or **organization-owned**.
 
-Required scopes:
+#### User-owned Projects (v2)
 
+Use a **classic PAT** with 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)
 
-You can use either a classic or fine-grained PAT.
-
-**Classic PAT** scopes:
-
-- `project` (required)
-- `read:org` (required for org Projects)
-- `repo` (required if accessing private repositories)
-
-**Fine-grained PAT** settings:
-
-- Repository access: Select specific repos or "All repositories"
-- Organization access: Must be granted to the target organization
-- Organization permissions: 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)
+Use a **fine-grained** PAT with scopes:
+- Repository access: Select specific repos that will use the workflow
+- Repository permissions:
+  - Contents: Read
+  - Issues: Read (if workflow is triggered by issues)
+  - Pull requests: Read (if workflow is triggered by pull requests)
+- Organization permissions:
+  - Projects: Read & Write (required for updating projects)
 
 ### 3) Store the token as a secret
 
@@ -74,6 +64,10 @@ on:
 permissions:
   contents: read
   actions: read
+tools:
+  github:
+    toolsets: [default, projects]
+    github-token: ${{ secrets.GH_AW_PROJECT_GITHUB_TOKEN }}
 safe-outputs:
   update-project:
     max: 1
@@ -103,8 +97,8 @@ ProjectOps workflows use the `update-project` safe output to ensure secure proje
 ```yaml wrap
 safe-outputs:
   update-project:
-    max: 10                              # Optional: max project operations (default: 10)
-    github-token: ${{ secrets.GH_AW_PROJECT_GITHUB_TOKEN }}  # Required: PAT with Projects access (default GITHUB_TOKEN won't work)
+    max: 10
+    github-token: ${{ secrets.GH_AW_PROJECT_GITHUB_TOKEN }}
 ```
 
 The `update-project` tool provides intelligent project management:
@@ -115,95 +109,47 @@ The `update-project` tool provides intelligent project management:
 - **Applies a tracking label**: When adding a new item, it can apply a consistent tracking label to the underlying issue/PR
 - **Returns outputs**: Exposes the Project item ID (`item-id`) for downstream steps
 
-## Accessing Issue Context
+## Organization-Owned Project Configuration
 
-ProjectOps workflows can access sanitized issue content through the `needs.activation.outputs.text` variable, which combines the issue title and description while removing security risks:
+For workflows that interact with organization-owned projects and need to query GitHub information, use the following configuration:
 
 ```yaml wrap
-# In your workflow instructions:
-Analyze this issue to determine priority: "${{ needs.activation.outputs.text }}"
-```
-
-**Security Note**: Always treat user content as potentially untrusted and design workflows to be resilient against prompt injection attempts.
-
-## Common ProjectOps Patterns
-
-### Initiative Launch and Tracking
-
-Use an existing project board for a focused initiative and add related issues with tracking metadata.
-
-Create the initiative Project in the GitHub UI first (the `update-project` safe output does not create Projects).
-
-This goes beyond native GitHub automation by analyzing the codebase to generate related issues and coordinating multiple related work items.
-
-```aw wrap
 ---
 on:
-  workflow_dispatch:
-    inputs:
-      initiative_name:
-        description: "Initiative name"
-        required: true
+  issues:
+    types: [opened]
 permissions:
   contents: read
   actions: read
+tools:
+  github:
+    toolsets: [default, projects]
+    github-token: ${{ secrets.GH_AW_PROJECT_GITHUB_TOKEN }}
 safe-outputs:
-  create-issue:
-    max: 20
   update-project:
-    max: 20
+    github-token: ${{ secrets.GH_AW_PROJECT_GITHUB_TOKEN }}
 ---
 
-# Launch Initiative
-
-Use the initiative project board: "{{inputs.initiative_name}}"
-
-Analyze the repository to identify tasks needed for this initiative.
+# Smart Issue Triage for Organization Project
 
-For each task:
-1. Create an issue with detailed description
-2. Add the issue to the initiative project board
-3. Set status to "Todo"
-4. Set priority based on impact
-5. Apply a tracking label for reporting
-
-The initiative board provides a visual dashboard showing all related work.
+Analyze the issue and add it to the organization project board...
 ```
 
+This configuration ensures:
+1. The GitHub MCP toolset can query repository and project information
+2. The `update-project` safe output can modify the organization project
+3. Both operations use the same token with appropriate permissions
 
+## Accessing Issue Context
 
-### Content-Based Priority Assignment
-
-Analyze issue content to set priority automatically, going beyond what labels can provide:
-
-```aw wrap
----
-on:
-  issues:
-    types: [opened]
-permissions:
-  contents: read
-  actions: read
-safe-outputs:
-  update-project:
-    max: 1
----
-
-# Intelligent Priority Triage
-
-When an issue is created, analyze its content to set priority and effort.
-
-Analyze the issue description for:
-- Security vulnerabilities → Priority: "Critical", add to "Security" project
-- Production crashes or data loss → Priority: "High", Effort: "Medium"
-- Performance degradation → Priority: "High", Effort: "Large"
-- Minor bugs or improvements → Priority: "Low", Effort: "Small"
+ProjectOps workflows can access sanitized issue content through the `needs.activation.outputs.text` variable, which combines the issue title and description while removing security risks:
 
-Add to "Engineering Backlog" project with calculated priority and effort fields.
+```yaml wrap
+# In your workflow instructions:
+Analyze this issue to determine priority: "${{ needs.activation.outputs.text }}"
 ```
 
-**Why use ProjectOps:** Native GitHub automation can't analyze issue content to determine priority - it only reacts to labels and status changes.
-
+**Security Note**: Always treat user content as potentially untrusted and design workflows to be resilient against prompt injection attempts.
 
 
 ## Project Management Features

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

@@ -216,12 +216,15 @@ You can use either a classic PAT or a fine-grained PAT:
    - `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"
+2. **Option B (recommended)**: Create a [fine-grained PAT](https://github.com/settings/personal-access-tokens/new) with:
+   - **Repository access**: Select specific repos that will use the workflow
+   - **Repository permissions**:
+     - Contents: Read
+     - Issues: Read (if needed for issue-triggered workflows)
+     - Pull requests: Read (if needed for PR-triggered workflows)
    - **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.
+     - Projects: Read & Write (required for updating org Projects)
+   - **Important**: You must explicitly grant organization access during token creation
 
 3. **Option C**: Use a GitHub App with Projects: Read+Write permission
 
@@ -252,16 +255,31 @@ The compiler automatically sets the `GH_AW_PROJECT_GITHUB_TOKEN` environment var
 safe-outputs:
   update-project:
     github-token: ${{ secrets.CUSTOM_PROJECT_TOKEN }}
+
+# Option 3: Organization projects with GitHub tools integration
+tools:
+  github:
+    toolsets: [default, projects]
+    github-token: ${{ secrets.ORG_PROJECT_WRITE }}
+safe-outputs:
+  update-project:
+    github-token: ${{ secrets.ORG_PROJECT_WRITE }}
 ```
 
+**For organization-owned projects**, the complete configuration should include both the GitHub tools and safe outputs using the same token with appropriate permissions.
+
 :::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 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.
+- **Organization-owned Projects**: Can use either a classic PAT with `project` + `read:org` scopes, **or** a fine-grained PAT with:
+  - Repository access to specific repositories
+  - Repository permissions: Contents: Read, Issues: Read, Pull requests: Read (as needed)
+  - Organization permissions: Projects: Read & Write
+  - Explicit organization access granted during token creation
 - **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.