diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 65d1e24..fcd67ef 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -16,6 +16,21 @@ cargo test --workspace
 If you touch S3-backed flows, the CI model uses a local RustFS instance for
 integration tests.
 
+### OpenAPI spec
+
+`openapi.json` is a committed artifact generated from the Utoipa annotations in
+`crates/omnigraph-server`. For PRs opened from this repository, a CI job
+regenerates it automatically and commits the updated file back to the PR
+branch. For PRs from forks (where CI cannot push), run the regeneration
+manually:
+
+```bash
+OMNIGRAPH_UPDATE_OPENAPI=1 cargo test -p omnigraph-server --test openapi openapi_spec_is_up_to_date
+```
+
+The workspace test run fails if the committed `openapi.json` drifts from what
+the source generates.
+
 ## Pull Requests
 
 - keep changes focused