doc clean up phase 2

docs/integration/openapi/README.md

@@ -42,15 +42,38 @@ Two things that cost time the first run:
 Then update the table above — date, commit, and endpoint count — in the same change. A snapshot whose
 provenance is unrecorded is what this chain exists to stop.
 
-## Scope
+## Scope — `v1`, and why `v1.1` is empty
 
-`v1` only. [The old README](../../../dev/contracts/openapi/README.md) claimed the server publishes
-documents `v1` **and** `v1.1`, but only `v1` has ever been committed and `v1.1` was not fetched during
-the phase 0 survey. `UNVERIFIED:` check `/swagger/v1.1/swagger.json` when the server is next up
-(contradiction C-9).
+Both documents **are** registered: `Program.cs` calls `AddSwagger("v1", "v1.1")`, so
+`/swagger/v1.1/swagger.json` is served. It contains **zero paths**.
+
+`ApiVersionDocumentProcessor` removes every path whose URL does not contain the document's own version
+segment, and all **55 controllers declare `[ApiVersion("1")]`** with the route template
+`api/v{version:apiVersion}/…`. So every URL contains `v1` and none contains `v1.1`.
+
+That resolves contradiction **C-9**: the old README's "publishes `v1` and `v1.1`" was literally true and
+substantively empty. `v1` is the contract. Only `v1` is worth committing.
+
+## One provenance wrinkle
+
+The document's `servers` block reads `http://127.0.0.1:5099`, while the regeneration command above uses
+port 5002. NSwag records whichever host answered the request, so this only means the phase-0 snapshot was
+taken from a run bound to 5099. **The document content is port-independent** — no path, schema or parameter
+depends on it — so this is a provenance note, not a defect. Re-taking the snapshot from 5002 would change
+that one string and nothing else.
 
 ## The human contract
 
-The prose half — one file per domain — lands in [`../domains/`](../index.md) in phase 2. **The two must
+The prose half — one file per domain — is in [`../domains/`](../domains/index.md): **22 files, one per
+client `services/` domain**, with all 186 operations assigned to exactly one of them. **The two must
 agree**: this JSON is the wire truth, the markdown explains it. When they disagree, the JSON wins and
 the markdown is wrong.
+
+Two things the JSON **cannot** tell you, which is why the markdown exists:
+
+- **Enum vocabularies.** Exactly 1 of 339 schemas has an `enum`, and it is the integer
+  `ApiResultStatusCode`. Every status/code field is a bare `string`. The vocabularies live in the domain
+  files, cross-checked against `Baya.Domain`'s code sets.
+- **`Idempotency-Key`.** Two endpoints require it, and neither declares it — it is read from
+  `Request.Headers`, not bound as a parameter. See
+  [`../api-contract.md`](../api-contract.md#idempotency).