fix(api): keep public OpenAPI metadata aligned with the deployment

changelog.d/fixes/18331-public-openapi-metadata.md

@@ -0,0 +1 @@
+- fix(api): regenerate the public OpenAPI spec with the build version and deployment-relative server URL. Builds generate it, and `npm run gen:public-openapi` refreshes the committed copy (#18331).

docs/reference/API_REFERENCE.md

@@ -13,6 +13,8 @@ Core reference for the OmniRoute API. It covers the public `/v1` surface and the
 For the focused OpenAI-compatible protocol and provider capability matrix, see
 [`OPENAI_COMPATIBILITY.md`](./OPENAI_COMPATIBILITY.md).
 
+Each deployment serves its own copy of the spec at `/openapi.yaml`, generated from `docs/openapi.yaml` during the build. It carries the build's version and a relative server URL (`./`), so requests stay on the host that served the document. A tool that imports the downloaded file has no such host, and needs the base URL set by hand.
+
 ---
 
 ## Table of Contents

package.json

@@ -39,6 +39,7 @@
     "scripts/check/check-supported-node-runtime.ts",
     "scripts/dev/sync-env.mjs",
     "scripts/build/assembleStandalone.mjs",
+    "scripts/build/publicOpenApi.mjs",
     "scripts/build/backendOnlyPages.mjs",
     "scripts/build/build-tproxy-native.mjs",
     "scripts/build/native-binary-compat.mjs",
@@ -99,6 +100,7 @@
     "dev:candidate": "node scripts/dev/candidate.mjs",
     "prebuild:docs": "node scripts/docs/gen-openapi-module.mjs",
     "gen:provider-reference": "bun scripts/docs/gen-provider-reference.ts",
+    "gen:public-openapi": "node scripts/build/publicOpenApi.mjs",
     "gen:i18n-routes": "node scripts/i18n/generate-route-namespaces.mjs",
     "bench:compression": "bun scripts/compression/benchmark.ts",
     "bench:heap-body": "node --expose-gc --import tsx/esm scripts/perf/request-body-heap.ts",