diff --git a/.github/workflows/pr-review.yml b/.github/workflows/pr-review.yml
index 3c36e5e40..982b49aa7 100644
--- a/.github/workflows/pr-review.yml
+++ b/.github/workflows/pr-review.yml
@@ -1,22 +1,26 @@
 name: PR Review
-
 on:
-  issue_comment:
+  issue_comment: # Enables /review command in PR comments
     types: [created]
-  pull_request_review_comment:
+  pull_request_review_comment: # Captures feedback on review comments for learning
     types: [created]
-  pull_request_target:
+  pull_request: # Triggers auto-review on PR open (same-repo branches only; fork PRs use /review)
     types: [ready_for_review, opened]
 
 permissions:
-  contents: read
+  contents: read # Required at top-level to give `issue_comment` events access to the secrets below.
 
 jobs:
   review:
-    uses: docker/cagent-action/.github/workflows/review-pr.yml@3a12dbd0c6cd7dda3d4e05f24f0143c9701456de # latest (v1.2.13)
+    uses: docker/cagent-action/.github/workflows/review-pr.yml@dba0ca51938c78afb363625363c50582243218d6 # v1.3.1
+    # Scoped to the job so other jobs in this workflow aren't over-permissioned
     permissions:
-      contents: read
-      pull-requests: write
-      issues: write
-      checks: write
-    secrets: inherit
+      contents: read # Read repository files and PR diffs
+      pull-requests: write # Post review comments and approve/request changes
+      issues: write # Create security incident issues if secrets are detected in output
+      checks: write # (Optional) Show review progress as a check run on the PR
+    secrets:
+      ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+      CAGENT_ORG_MEMBERSHIP_TOKEN: ${{ secrets.CAGENT_ORG_MEMBERSHIP_TOKEN }} # PAT with read:org scope; gates auto-reviews to org members only
+      CAGENT_REVIEWER_APP_ID: ${{ secrets.CAGENT_REVIEWER_APP_ID }} # GitHub App ID; reviews appear as your app instead of github-actions[bot]
+      CAGENT_REVIEWER_APP_PRIVATE_KEY: ${{ secrets.CAGENT_REVIEWER_APP_PRIVATE_KEY }} # GitHub App private key; paired with App ID above