diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
new file mode 100644
index 0000000..cfe2e89
--- /dev/null
+++ b/.pre-commit-config.yaml
@@ -0,0 +1,10 @@
+repos:
+  - repo: local
+    hooks:
+      - id: openapi-sync
+        name: Sync openapi.json
+        description: Regenerate openapi.json when the server API surface changes.
+        entry: bash -c 'OMNIGRAPH_UPDATE_OPENAPI=1 cargo test -p omnigraph-server --test openapi openapi_spec_is_up_to_date --quiet'
+        language: system
+        pass_filenames: false
+        files: ^(crates/omnigraph-server/src/.*\.rs|crates/omnigraph-server/Cargo\.toml|openapi\.json)$
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 65d1e24..eb6ce7c 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -16,6 +16,24 @@ 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`. CI fails if it drifts from the source. To regenerate
+manually:
+
+```bash
+OMNIGRAPH_UPDATE_OPENAPI=1 cargo test -p omnigraph-server --test openapi openapi_spec_is_up_to_date
+```
+
+Optional: install [pre-commit](https://pre-commit.com) to run this automatically
+before each commit that touches the server:
+
+```bash
+pip install pre-commit
+pre-commit install
+```
+
 ## Pull Requests
 
 - keep changes focused