Refine permissions documentation in CLAUDE.md and README.md. Introduce minimal and alternative permission configurations for action consumers, emphasizing the use of pull-requests: write for PR access. Update troubleshooting section with detailed permission solutions.

Author: ivan-magda

CLAUDE.md

@@ -126,15 +126,26 @@ Create `.env` file based on `.env.example` to simulate GitHub Actions environmen
 
 ## Permissions Required (for consumers)
 
-Action consumers must grant these permissions in their workflow:
+### Minimal Permissions (Recommended)
+Action consumers should use these simplified permissions in their workflow:
+```yaml
+permissions:
+  pull-requests: write    # Read PR reviews and create/update PR comments
+  id-token: write         # Request OIDC token
+```
+
+### Alternative Permissions
+If the minimal permissions don't work due to repository settings, try:
 ```yaml
 permissions:
   contents: read          # Read repo metadata
-  pull-requests: read     # Read PR reviews and comments
-  issues: write           # Create/update PR comments (PRs use Issues API)
+  pull-requests: write    # Read PR reviews and comments + write comments
+  issues: read            # Additional PR comment read access
   id-token: write         # Request OIDC token
 ```
 
+**Note**: The `pull-requests: write` permission typically provides all necessary access for reading PR data and creating comments, as PRs use the Issues API for comments.
+
 ## Versioning
 
 - Follow [Semantic Versioning](https://semver.org/)
@@ -186,7 +197,7 @@ permissions:
 1. **Forgetting to bundle**: After changing `src/`, must run `npm run bundle` and commit `dist/`
 2. **Reviewing dist/**: Don't review `dist/` changes in PRs — they mirror TypeScript sources
 3. **Using console**: Use `@actions/core` logging methods instead of `console.log`
-4. **Missing permissions**: Consumers need `id-token: write` for OIDC authentication
+4. **Missing permissions**: Consumers need `pull-requests: write` and `id-token: write` at minimum
 5. **Testing without mocks**: Mock GitHub API and proxy responses in tests
 
 ## Development Container

README.md

@@ -60,9 +60,7 @@ on:
     types: [created, edited]
 
 permissions:
-  contents: read
-  pull-requests: read
-  issues: write
+  pull-requests: write
   id-token: write
 
 concurrency:
@@ -222,12 +220,14 @@ credentials
 
 ### Required Permissions
 
-| Permission      | Level | Purpose                           |
-| --------------- | ----- | --------------------------------- |
-| `contents`      | read  | Read repository metadata          |
-| `pull-requests` | read  | Fetch PR review comments          |
-| `issues`        | write | Create/update PR comments         |
-| `id-token`      | write | Request OIDC authentication token |
+| Permission      | Level | Purpose                                            |
+| --------------- | ----- | -------------------------------------------------- |
+| `pull-requests` | write | Read PR review comments and create/update comments |
+| `id-token`      | write | Request OIDC authentication token                  |
+
+> **Note:** The `pull-requests: write` permission typically covers both reading
+> PR data and writing comments. If you encounter permission issues, see the
+> [troubleshooting section](#-troubleshooting) for alternative configurations.
 
 ## 🎯 Use Cases
 
@@ -328,6 +328,24 @@ change this behavior by setting `fail-on-proxy-error: true`.
 <details>
 <summary><b>Common Issues and Solutions</b></summary>
 
+### "Permission denied" or "Resource not accessible by integration"
+
+**Cause:** Insufficient permissions for your repository settings
+
+**Solution:** If the minimal permissions don't work, try this expanded
+configuration:
+
+```yaml
+permissions:
+  contents: read # Repository metadata access
+  pull-requests: write # PR review and comment access
+  issues: read # Additional PR comment read access
+  id-token: write # OIDC authentication
+```
+
+Repository settings can vary, and some organizations may require additional
+permissions depending on their security policies.
+
 ### "Error requesting OIDC token"
 
 **Cause:** Missing `id-token: write` permission
@@ -337,8 +355,7 @@ change this behavior by setting `fail-on-proxy-error: true`.
 ```yaml
 permissions:
   id-token: write # Add this permission
-  pull-requests: read
-  issues: write
+  pull-requests: write
 ```
 
 ### "No comment appears after reviews"