diff --git a/README.md b/README.md
index e21bd05..6394c52 100644
--- a/README.md
+++ b/README.md
@@ -51,4 +51,11 @@ See [`docs/registry-schema.md`](docs/registry-schema.md) for what the registry a
 (and what it does not), and [`docs/plugin-descriptor-schema.md`](docs/plugin-descriptor-schema.md)
 for the `plugin.yaml` descriptor that each plugin repository provides.
 
-To register a new plugin, open a PR adding it to `registry.yaml`.
+To register a new plugin, open a PR adding it to `registry.yaml`. After editing it, run:
+
+```bash
+uv run scripts/generate_registry.py
+```
+
+and commit the resulting changes to `README.md` and `registry.json` — CI rejects the PR if they
+drift from `registry.yaml`.
diff --git a/docs/registry-schema.md b/docs/registry-schema.md
index a42dd79..bb62576 100644
--- a/docs/registry-schema.md
+++ b/docs/registry-schema.md
@@ -63,3 +63,10 @@ overlapping rule ID ranges across plugins and reserved ranges — are checked se
 validation does when it finds a violation. CI runs both, then regenerates `README.md` and
 `registry.json` and fails on any drift (`git diff --exit-code`), so the generated files can never
 go stale relative to `registry.yaml`.
+
+Contributors editing `registry.yaml` should run the same generator locally before opening a PR,
+so the regenerated files are already part of the diff instead of failing CI:
+
+```bash
+uv run scripts/generate_registry.py
+```