add build development phases

dev/contracts/openapi/README.md

@@ -0,0 +1,22 @@
+# OpenAPI snapshots
+
+The server already generates OpenAPI via **NSwag** (Swagger UI at `/swagger`, documents `v1`, `v1.1`).
+This folder holds the **published `swagger.json` snapshot(s)** so the frontend can generate/verify types
+without running the backend.
+
+## Backend: publish on every API-shipping phase
+After adding/changing endpoints and confirming the build, export the OpenAPI document and commit it here
+as `swagger.v1.json` (overwrite — git history is the version trail). Typical options:
+
+- Run the API and save `GET /swagger/v1/swagger.json` to `dev/contracts/openapi/swagger.v1.json`, **or**
+- Use the NSwag CLI / build target the server already wires to emit the document.
+
+Record in your handoff that the snapshot was refreshed. Keep it in sync with `../domains/*.md` — the
+markdown is the human contract, this JSON is the machine contract; they must agree.
+
+## Frontend: consume
+Generate types from `swagger.v1.json` (e.g. an `openapi-typescript`-style step) **or** hand-write
+`src/services/{domain}/types.ts` to match it. Either way, the wire shapes come from here — not from
+guessing. Casing/format questions are resolved by this file.
+
+> Until the first API-shipping backend phase runs, this folder is empty by design.