docs: document how to regenerate README.md and registry.json

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`.

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
+```