diff --git a/.gitattributes b/.gitattributes
new file mode 100644
index 0000000..33108d0
--- /dev/null
+++ b/.gitattributes
@@ -0,0 +1,4 @@
+# Action bundles are generated by `pnpm build` and verified by check_dist:required.
+# Marking them as generated collapses them in pull request diffs, so reviewers see
+# the source changes instead of thousands of lines of bundled output.
+actions/*/dist/** linguist-generated=true
diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md
index 7e40f0b..5d54a06 100644
--- a/.github/CONTRIBUTING.md
+++ b/.github/CONTRIBUTING.md
@@ -119,3 +119,15 @@ pnpm build
 ```
 
 The GitHub actions pipeline will attempt to build the actions and check if there are any differences between the built files and those that are committed to the repository. If there are any differences, the pipeline will fail.
+
+### Why the bundles are committed
+
+GitHub runs a JavaScript action (`using: node24`) straight from its committed `dist/index.js`. It does not install dependencies or run a build first, so every runtime dependency is bundled into that one file.
+
+This has a consequence that is easy to miss: updating a bundled dependency in `package.json` and `pnpm-lock.yaml` changes nothing about what actually runs until the bundles are rebuilt. A dependency fix that is not accompanied by rebuilt bundles is not applied.
+
+The bundles are marked as generated in `.gitattributes`, so they are collapsed in pull request diffs. Review the source changes rather than the bundled output; the `check_dist:required` job is what guarantees the committed bundles are exactly what that source compiles to.
+
+### When an automated dependency update fails the check
+
+Automated dependency updates change `package.json` and `pnpm-lock.yaml` but cannot rebuild the bundles, so `check_dist:required` fails on those pull requests. Check the branch out, run `pnpm build`, and commit the rebuilt bundles to it.
diff --git a/.github/workflows/self-check-dist.yaml b/.github/workflows/self-check-dist.yaml
index 932a495..2b0bcc3 100644
--- a/.github/workflows/self-check-dist.yaml
+++ b/.github/workflows/self-check-dist.yaml
@@ -14,7 +14,8 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        action_name: ['create-pr', 'assemble-docs', 'submit-docs']
+        action_name:
+          ['create-pr', 'assemble-docs', 'submit-docs', 'extract-version']
     steps:
       - name: Checkout repository
         uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
diff --git a/README.md b/README.md
index 026d435..ad83c11 100644
--- a/README.md
+++ b/README.md
@@ -49,6 +49,18 @@ Example:
 name: my_action:required
 ```
 
+### Generated files
+
+A JavaScript action (`using: node24`) is executed by GitHub straight from the committed file its `main` points at, with no install or build step beforehand. Its dependencies therefore have to be committed too, which is why they are bundled into a single `dist/index.js`.
+
+Mark that output as generated so it collapses in pull request diffs instead of burying the source changes:
+
+```gitattributes
+actions/*/dist/** linguist-generated=true
+```
+
+Pair it with a job that rebuilds the bundles and fails on any difference. That check is what makes collapsing the diff safe, because it proves the committed output is exactly what the reviewed source compiles to.
+
 ## Locking Versions
 
 When referencing 3rd party actions, use a specific commit SHA to lock the version. This ensures that the action will not change unexpectedly, which could lead to breaking changes in your workflows.