Add static OpenAPI spec and clean up operation IDs

[ragnorc]

Summary

• Commits a static openapi.json extracted from the Utoipa annotations, kept in sync via a golden-file test (openapi_spec_is_up_to_date). Regenerate with OMNIGRAPH_UPDATE_OPENAPI=1 cargo test -p omnigraph-server --test openapi openapi_spec_is_up_to_date — any drift between the committed spec and the Utoipa-generated output fails CI.
• Adds operation_id to every #[utoipa::path] so generated SDK methods have clean camelCase names (read, createBranch, getRun, mergeBranches, etc.) instead of the default function-name-derived IDs.

Test plan

• cargo test -p omnigraph-server --test openapi — all 65 tests pass
• openapi.json contains valid OpenAPI 3.1 with 16 paths, 30 schemas, bearer_token scheme
• Round-trip: running the golden-file test without the env var passes (committed == generated)

🤖 Generated with Claude Code

---

Note

Medium Risk
Adds a committed openapi.json golden file and CI automation that can push commits back to same-repo PR branches, which affects CI behavior and repository history. Runtime API behavior is largely unchanged, but tooling/SDK generation may be impacted by the new explicit operation_id values.

Overview
Adds a committed OpenAPI artifact and keeps it in sync automatically. This PR introduces a generated openapi.json checked into the repo, plus a golden-file test (openapi_spec_is_up_to_date) that fails when the committed spec drifts from the Utoipa-generated output.

Updates CI and docs to support spec regeneration. Workspace CI now sets OMNIGRAPH_UPDATE_OPENAPI for same-repo PRs and, when openapi.json changes, commits and pushes the regenerated file back to the PR branch (requiring contents: write).

Stabilizes SDK method naming. All #[utoipa::path] endpoints in omnigraph-server now specify explicit operation_ids (e.g., listBranches, getRun, applySchema) so generated clients get consistent names.

^{Reviewed by Cursor Bugbot for commit bcddbdf. Bugbot is set up for automated code reviews on this repo. Configure here.}

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit bcddbdf. Configure here.}

[cursor]

Script injection via github.head_ref in shell command

Medium Severity

${{ github.head_ref }} is interpolated directly into a run: shell script, which is a known GitHub Actions script injection vector. A branch name containing shell metacharacters (e.g., backticks or $()) would execute arbitrary commands in a context where GITHUB_TOKEN with contents: write is available. The safe pattern is to pass the value via an env: mapping (e.g., HEAD_REF: ${{ github.head_ref }}) and reference "$HEAD_REF" in the script instead.

 

^{Reviewed by Cursor Bugbot for commit bcddbdf. Configure here.}