Add opt-in git hook for openapi.json drift

Track a project pre-commit hook under scripts/hooks/ that regenerates
openapi.json when server source is staged, and auto-stages the updated
spec into the commit. Zero external dependencies — plain bash + cargo.

Enable via `git config core.hooksPath scripts/hooks`. The CI drift
test remains the authoritative check.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

CONTRIBUTING.md

@@ -16,6 +16,23 @@ 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: enable the project's git hook to regenerate automatically when you
+commit server changes:
+
+```bash
+git config core.hooksPath scripts/hooks
+```
+
 ## Pull Requests
 
 - keep changes focused

scripts/hooks/pre-commit

@@ -0,0 +1,15 @@
+#!/usr/bin/env bash
+# Regenerate openapi.json when the server API surface changes.
+set -euo pipefail
+
+staged=$(git diff --cached --name-only --diff-filter=ACMR)
+
+echo "$staged" | grep -qE '^(crates/omnigraph-server/src/.*\.rs|crates/omnigraph-server/Cargo\.toml)$' || exit 0
+
+echo "[pre-commit] regenerating openapi.json..."
+OMNIGRAPH_UPDATE_OPENAPI=1 cargo test -p omnigraph-server --test openapi openapi_spec_is_up_to_date --quiet
+
+if ! git diff --quiet -- openapi.json; then
+  git add openapi.json
+  echo "[pre-commit] openapi.json updated and staged"
+fi