feat: commit openapi-schema.yml + add freshness gate

.gitattributes

@@ -0,0 +1 @@
+openapi-schema.yml text eol=lf merge=binary

.github/workflows/openapi-spec-freshness.yml

@@ -0,0 +1,34 @@
+name: OpenAPI spec freshness
+
+on:
+  pull_request:
+
+jobs:
+  verify-spec-fresh:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+          prune-cache: false
+
+      - name: Install Python
+        run: uv python install 3.11
+
+      - name: Install dependencies
+        run: uv sync
+
+      - name: Verify openapi-schema.yml matches code
+        run: |
+          uv run python manage.py spectacular --file openapi-schema.yml
+          if ! git diff --exit-code -- openapi-schema.yml; then
+            echo "::error::openapi-schema.yml is out of date with the code on this branch."
+            echo "::error::Regenerate locally with:"
+            echo "::error::  uv run python manage.py spectacular --file openapi-schema.yml"
+            echo "::error::Then commit the updated file and push."
+            exit 1
+          fi
+          echo "openapi-schema.yml is up to date."

.gitignore

@@ -31,8 +31,6 @@ server/whoosh_index/
 api/tests/approved_files/*.recieved.*
 
 # Generated files
-openapi-schema.yml
-
 server/vector_index.pkl
 
 # Temporary files for magic items update

README.md

@@ -45,7 +45,7 @@ All v1 content is still available for hosting your own version, if required
   * [Build](#build)
     + [Search Indexing](#search-indexing)
   * [Run](#run)
-  * [Building the OAS file](#building-the-oas-file)
+  * [OpenAPI Spec](#openapi-spec)
 - [Contributing](#contributing)
   * [Editing existing sources](#editing-existing-sources)
   * [Adding a new source](#adding-a-new-source)
@@ -118,13 +118,22 @@ gunicorn -b :8888 server.wsgi:application
 
 You can use our Dockerfile as inspiration, but it likely will not work without significant edits to your operating environment. We have customized our production environment to use it.
 
-## Building the OAS file
+## OpenAPI Spec
+
+`openapi-schema.yml` (at the repo root) is the canonical API contract for `/v2/`,
+generated from the serializers/views by drf-spectacular. It is committed to the
+repo so consumers and reviewers can read and diff the contract directly.
+
+CI verifies it stays in sync with the code on every PR into `staging-with-spec`.
+If you change a serializer, view, model, or schema-affecting setting, regenerate:
 
-After completing a build, you can generate an OAS file to be used by another application.
 ```bash
-uv run python manage.py spectacular --color --file openapi-schema.yml
+uv run python manage.py spectacular --file openapi-schema.yml
 ```
 
+Then commit the updated file. Do **not** hand-edit `openapi-schema.yml` — it is
+a build artifact.
+
 # Contributing
 See [contribution guide](.github/CONTRIBUTING.md).
 # Tests