diff --git a/.github/actions/iris-pr/README.md b/.github/actions/iris-pr/README.md
new file mode 100644
index 0000000..d64228c
--- /dev/null
+++ b/.github/actions/iris-pr/README.md
@@ -0,0 +1,70 @@
+# Iris PR Insights — GitHub Action
+
+Analyze a pull request with Iris and post AI-aware engineering insights as a PR
+comment, automatically, on every PR.
+
+## Setup
+
+Copy this workflow into the consuming repository as
+`.github/workflows/iris.yml`:
+
+```yaml
+name: Iris PR Insights
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened]
+
+jobs:
+  iris-pr:
+    name: Iris PR Analysis
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read        # required: actions/checkout reads the repo
+      pull-requests: write  # required: post the insights comment
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0     # full history → churn / cascade context
+
+      - uses: RocketBus/clickbus-iris/.github/actions/iris-pr@main
+```
+
+## Important: the `permissions` block
+
+The moment you declare a `permissions:` block, **every permission you do not
+list is set to `none`** — not the default `read`. Iris needs both:
+
+- `contents: read` — without it, `actions/checkout` cannot read the repo. On a
+  **private** repo this surfaces as a confusing `remote: Repository not found`
+  / `fatal: repository '...' not found` (GitHub returns 404, not 403, to a
+  token that lacks access). This is the most common setup failure.
+- `pull-requests: write` — without it, the final `gh pr comment` step fails.
+
+If you omit the `permissions:` block entirely, the workflow inherits the
+repository's default token permissions, which may or may not include
+`pull-requests: write`. Declaring both explicitly is the reliable setup.
+
+## Inputs
+
+| Input | Default | Description |
+|---|---|---|
+| `pr-number` | event context | PR number (auto-detected from the `pull_request` event) |
+| `churn-days` | `14` | Churn context window in days |
+| `python-version` | `3.11` | Python version to install |
+
+Example with overrides:
+
+```yaml
+      - uses: RocketBus/clickbus-iris/.github/actions/iris-pr@main
+        with:
+          churn-days: '30'
+          python-version: '3.12'
+```
+
+## Notes
+
+- `fetch-depth: 0` gives Iris full history for churn and cascade context. With a
+  shallow clone the action degrades gracefully and runs with `--no-context`.
+- `@main` always runs the latest action. Pin to a tag or commit SHA if you need
+  reproducible behavior across runs.
diff --git a/.github/actions/iris-pr/action.yml b/.github/actions/iris-pr/action.yml
index 5d9f7d5..536e49b 100644
--- a/.github/actions/iris-pr/action.yml
+++ b/.github/actions/iris-pr/action.yml
@@ -21,7 +21,12 @@ runs:
       with:
         python-version: ${{ inputs.python-version }}
 
-    - run: pip install iris
+    # Install Iris from this action's own repo checkout (the repo root holds
+    # pyproject.toml). Iris is not published to public PyPI — `pip install iris`
+    # would pull an unrelated package and leave `iris` unavailable.
+    # $GITHUB_ACTION_PATH = .../.github/actions/iris-pr, so ../../.. is the repo root.
+    - name: Install Iris
+      run: pip install "$GITHUB_ACTION_PATH/../../.."
       shell: bash
 
     - name: Run Iris PR analysis
diff --git a/.github/actions/iris-pr/example-workflow.yml b/.github/actions/iris-pr/example-workflow.yml
new file mode 100644
index 0000000..76e21e8
--- /dev/null
+++ b/.github/actions/iris-pr/example-workflow.yml
@@ -0,0 +1,25 @@
+# Canonical Iris PR Insights workflow.
+# Copy this file into a consuming repo as: .github/workflows/iris.yml
+#
+# Both permissions are required:
+#   contents: read       -> actions/checkout (private repos 404 without it)
+#   pull-requests: write -> posting the insights comment
+name: Iris PR Insights
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened]
+
+jobs:
+  iris-pr:
+    name: Iris PR Analysis
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: write
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: RocketBus/clickbus-iris/.github/actions/iris-pr@main
diff --git a/README.md b/README.md
index fb392b6..fbeea6c 100644
--- a/README.md
+++ b/README.md
@@ -118,6 +118,19 @@ Generates concise markdown insights for code review:
 
 Requires `gh` CLI installed and authenticated.
 
+### GitHub Actions (automatic PR comments)
+
+To post Iris insights on every PR automatically, copy
+[`.github/actions/iris-pr/example-workflow.yml`](.github/actions/iris-pr/example-workflow.yml)
+into the consuming repo as `.github/workflows/iris.yml`. See the
+[action README](.github/actions/iris-pr/README.md) for inputs and setup notes.
+
+> The workflow **must** grant `contents: read` (for checkout) and
+> `pull-requests: write` (to comment). Declaring a `permissions:` block sets
+> every unlisted permission to `none`, so on private repos a missing
+> `contents: read` shows up as a misleading `Repository not found` during
+> checkout.
+
 ### Options
 
 | Flag | Default | Description |