docs(pre-commit): publish supported hook design

.github/workflows/integration-test.yml

@@ -470,3 +470,39 @@ jobs:
 
           pre-commit run github-action-readme-generator --all-files --verbose
           cmp ACTION.after-first-run.md docs/ACTION.md
+
+      - name: Verify documented release hook
+        working-directory: consumer
+        run: |
+          cat > docs/ACTION.md <<'MARKDOWN'
+          # Consumer
+
+          <!-- start description -->
+          stale published description
+          <!-- end description -->
+          MARKDOWN
+
+          cat > .pre-commit-config.yaml <<'YAML'
+          repos:
+            - repo: https://github.com/bitflight-devops/github-action-readme-generator
+              rev: v2.1.0
+              hooks:
+                - id: github-action-readme-generator
+                  args: [--readme, docs/ACTION.md]
+          YAML
+
+          git add docs/ACTION.md .pre-commit-config.yaml
+          pre-commit validate-config .pre-commit-config.yaml
+
+          set +e
+          pre-commit run github-action-readme-generator --all-files --verbose
+          published_status=$?
+          set -e
+
+          if [ "$published_status" -eq 0 ]; then
+            echo "::error::published hook should report the target README modification"
+            exit 1
+          fi
+
+          grep -F "Generated through the published pre-commit hook" docs/ACTION.md
+          grep -F "default README must stay stale" README.md

AGENTS.md

@@ -36,7 +36,7 @@ Load the narrow source that owns the task instead of relying on cached repositor
 
 - **Generation, README ownership, versioning, convergence, formatting, or bundles:** read `docs/tool-contract.md`.
 - **Build, test, lint, or package-script behavior:** read `package.json` and `vite.config.ts`.
-- **Git-hook behavior:** read the matching file under `.husky/` and the script it invokes in `package.json`.
+- **Git-hook behavior:** for this repository's local hooks, read `.husky/` and the invoked `package.json` script; for the published consumer hook, read `.pre-commit-hooks.yaml` and `scripts/pre-commit-hook.sh`.
 - **CI behavior:** read the relevant file under `.github/workflows/`; workflow display names are not the source of truth.
 - **Release behavior:** read the relevant workflow and the `release` configuration in `package.json`.
 - **Before declaring a fix, review finding, or your own diff settled:** read `.claude/skills/checker-principle/SKILL.md`.

README.md

@@ -154,33 +154,28 @@ You can modify the script below to include any extra variables you like or use n
 
 ### Using as a Pre-commit Hook
 
-You can automate README generation on every commit by using this tool as a pre-commit hook. This ensures your documentation stays up-to-date automatically.
+This repository publishes a pre-commit hook. Consumers need a supported Node.js/npm installation, but do not need to install this package separately.
 
-1. **Install the tool locally** (if you haven't already):
+Add the hook to `.pre-commit-config.yaml` using an immutable release tag:
 
-```sh
-npm install --save-dev github-action-readme-generator
-# or
-yarn add -D github-action-readme-generator
+```yaml
+repos:
+  - repo: https://github.com/bitflight-devops/github-action-readme-generator
+    rev: v2.1.0
+    hooks:
+      - id: github-action-readme-generator
 ```
 
-2. **Configure pre-commit**:
+Use `pre-commit autoupdate` to move to newer releases. Do not use the moving `v2` alias as `rev`: pre-commit caches repositories by repository and revision string, so moving that tag does not reliably update an existing hook environment.
 
-Add the following to your `.pre-commit-config.yaml` file:
+The hook runs on every commit because the action and README paths are configurable. Staged filenames are not passed to the generator. Pass CLI options through `args` when needed:
 
 ```yaml
-repos:
-  - repo: local
-    hooks:
       - id: github-action-readme-generator
-        name: Generate README from action.yml
-        entry: npx github-action-readme-generator
-        language: system
-        files: ^(action\.yml|\.ghadocs\.json)$
-        pass_filenames: false
+        args: [--readme, docs/ACTION.md]
 ```
 
-This configuration will automatically regenerate your README whenever `action.yml` or `.ghadocs.json` changes.
+Configuration is still read from the consumer repository's `.ghadocs.json`; there is no separate configuration-file path option.
 
 ## Configuration
 

docs/tool-contract.md

@@ -141,6 +141,14 @@ This is the case the tool exists for and the case least covered by unit tests;
 - Zero-input and zero-output actions are ordinary third-party shapes, not edge
   cases.
 
+## Published pre-commit hook
+
+The pre-commit manifest is an adapter to the released CLI, not a second installation of this development repository. `.pre-commit-hooks.yaml` uses `unsupported_script`; `scripts/pre-commit-hook.sh` requires the consumer's Node/npm runtime, reads the selected repository revision's `package.json` version, and executes that exact npm release.
+
+Consumer `args` are forwarded to the CLI. Staged filenames are not: `pass_filenames: false` keeps arbitrary staged paths from becoming CLI arguments. Action and README paths may therefore be supplied through the generator's normal CLI/config inputs, while configuration itself remains the consumer repository's `.ghadocs.json`.
+
+A published pre-commit `rev` must be an immutable release tag whose npm package already exists. Do not document a moving major tag such as `v2`: pre-commit caches hook repositories by repository and revision string, so moving the same ref does not reliably refresh an existing consumer. Use exact release tags and let `pre-commit autoupdate` select newer ones.
+
 ## Published bundles are self-contained
 
 A GitHub Actions runner gives this action no `node_modules` of its own. Every