release: promote develop to main (OpenAPI contract completion)

.changeset/openapi-complete-spec.md

@@ -0,0 +1,14 @@
+---
+"ornn-api": minor
+---
+
+Make `GET /api/v1/openapi.json` a complete, usable contract (#1214).
+
+Two defects made the published spec unusable for client generation:
+
+- **Every schema was empty.** `toSchema` called `zod-to-json-schema@3`, which only understands zod 3 internals and returns `{}` for a zod 4 schema *without throwing*. The document stayed structurally valid while describing nothing: `GET /skill-search` advertised `parameters: []`, and every request and response body was `schema: {}`. `toSchema` now uses zod 4's built-in `z.toJSONSchema`, so property names, types, descriptions, enums, defaults, and numeric bounds all reach the spec. Request and response schemas are generated in opposite directions, so a `.default()` field is correctly optional on the way in and required on the way out. The dependency is removed.
+- **Every error response was described wrong.** Errors were documented as `application/json` wrapping the legacy `{ data, error }` envelope, but the API has emitted RFC 7807 `application/problem+json` with fields at the body root since #456. Generated clients read `error.message` and got `undefined`. All error responses now declare the real problem+json body — `type`, `title`, `status`, `detail`, `instance`, `code`, `requestId`, plus per-field `errors[]` on validation failures.
+
+Coverage goes from 13 documented operations to all 107, including previously undocumented domains: skillsets, versions, dist-tags, closures, diffs, audit, analytics, notifications, announcements, broadcasts, quota, redemption codes, admin settings, LLM providers, `/me/*`, `/users/*`, permissions, ownership transfer, the GitHub mirror, and the K8s probes. Every operation now carries a summary, an integrator-facing description, a unique `operationId`, tags, an explicit security declaration, described parameters with schemas and examples, and its full set of error responses.
+
+The spec is now assembled from one module per domain under `src/openapi/paths/`, deriving schemas from the same Zod definitions the handlers validate against. Contract tests enforce both directions against the booted router — no documented endpoint the API does not serve, and no served endpoint the spec does not document — with no allowlist, so the coverage gap cannot silently reopen.

.github/release-notes-20260807.md

@@ -0,0 +1,17 @@
+## Fixed
+
+- The API reference published empty schemas for every request and response
+- Skill search documented none of its query parameters
+- Error responses were described with the wrong body shape
+- Skill download docs showed a version-tag form that fails
+- Few technical bugs fixed
+
+## New Feature
+
+- The machine-readable API reference now covers every endpoint
+- Fetching the API reference supports conditional requests and caching
+
+## Changed
+
+- API reference descriptions rewritten for agent developers
+- Technical enhancement

docs/CONVENTIONS.md

@@ -529,12 +529,43 @@ Every response carries:
 
 ## 10. OpenAPI
 
-- `GET /v1/openapi.json` is the source of truth.
+- `GET /api/v1/openapi.json` is the source of truth. It is generated at server boot from the same Zod schemas the handlers validate against, so it cannot drift from the running API.
 - Every route declares security, request content types, all documented error responses, and at least one example.
-- CI contract test asserts every handler in code appears in the spec with complete metadata.
 - Error `type` URLs point to live documentation per § 1.6.
 
-### 10.1 Skill manifest JSON Schema
+### 10.1 Where the spec lives
+
+```
+ornn-api/src/openapi/
+├── helpers.ts        shared building blocks — the ONLY sanctioned way to
+│                     declare a response, a parameter, or a request body
+├── specBuilder.ts    document assembly: info, tags, security schemes
+└── paths/<domain>.ts one module per domain, exporting (prefix) => PathMap
+```
+
+**Adding a route means adding it to the matching `paths/` module in the same change.** There is no allowlist to opt out of; CI fails otherwise (§ 10.2).
+
+Two rules keep the document honest:
+
+- **Schemas are derived, not transcribed.** Import the domain's Zod schema and pass it to `toSchema` / `jsonBody` / `queryParams` / `jsonResponse`. Hand-written JSON Schema is a last resort, permitted only where no Zod schema exists, and must name the TypeScript interface it mirrors.
+- **`toSchema` uses zod 4's built-in `z.toJSONSchema`.** Do **not** reintroduce `zod-to-json-schema`: that package only understands zod 3 internals and returns `{}` for every zod 4 schema *without throwing*. It silently emptied every schema and parameter list in the published document (#1214). `helpers.test.ts` and `tests/contract/openapi.test.ts` both assert schemas are non-empty.
+
+Request and response schemas are generated in different directions. A field with a `.default()` is optional on the way in and guaranteed on the way out, so `jsonBody` / `queryParams` use `io: "input"` and `jsonResponse` uses `io: "output"`. Response schemas are emitted without `additionalProperties: false` so adding a field server-side does not break clients validating against a cached spec.
+
+### 10.2 Enforced invariants
+
+`ornn-api/tests/contract/` asserts, against the **booted router**, in both directions:
+
+| Invariant | Meaning | Test |
+|---|---|---|
+| documented ⇒ registered | The spec never advertises an endpoint the API does not serve. | `openapiRoutes.test.ts` |
+| registered ⇒ documented | The API never serves an endpoint the spec does not describe. | `openapiRoutes.test.ts` |
+
+`openapi.test.ts` additionally requires, per operation: a summary, a description of real substance, a unique `operationId`, at least one declared tag (itself declared at the document root), an explicit `security` declaration, every templated path parameter declared, a description and non-empty schema on every parameter, at least one 2xx with content, at least one error response, and every 4xx/5xx typed as `application/problem+json` with RFC 7807 fields at the body root.
+
+Both directions matter. Before #1214 only the first was enforced, and the document decayed to describing 13 of 104 routes while still passing CI.
+
+### 10.3 Skill manifest JSON Schema
 
 The canonical JSON Schema for `SKILL.md` YAML frontmatter is published at:
 

ornn-api/package.json

@@ -24,8 +24,7 @@
     "pino-pretty": "^13.1.3",
     "posthog-node": "^5.38.6",
     "yaml": "^2.9.0",
-    "zod": "^4.4.3",
-    "zod-to-json-schema": "^3.25.1"
+    "zod": "^4.4.3"
   },
   "devDependencies": {
     "@types/bun": "latest",

ornn-api/src/bootstrap.ts

@@ -11,6 +11,7 @@ import type { ContentfulStatusCode } from "hono/utils/http-status";
 import { cors } from "hono/cors";
 import { join } from "node:path";
 import { readFileSync } from "node:fs";
+import { createHash } from "node:crypto";
 import pino from "pino";
 import { type SkillConfig } from "./infra/config";
 
@@ -1127,7 +1128,23 @@ export async function bootstrap(
     serverUrl: config.ornnApiBaseUrl,
     version: pkg.version,
   });
-  app.get("/api/v1/openapi.json", (c) => c.json(spec));
+  // Serialize once at boot. The document is static for the lifetime of the
+  // process, and now that it describes all 107 operations it is ~1 MB — so
+  // `c.json(spec)` would re-run JSON.stringify over the whole thing on every
+  // request. `ETag` + `Cache-Control` per CONVENTIONS.md §8, which lists this
+  // endpoint as public and cacheable; a conditional request costs a hash
+  // comparison instead of a megabyte of transfer.
+  const specJson = JSON.stringify(spec);
+  const specEtag = `"${createHash("sha256").update(specJson).digest("hex").slice(0, 32)}"`;
+  logger.info({ bytes: specJson.length, etag: specEtag }, "OpenAPI spec built");
+  app.get("/api/v1/openapi.json", (c) => {
+    if (c.req.header("if-none-match") === specEtag) return c.body(null, 304);
+    return c.body(specJson, 200, {
+      "Content-Type": "application/json; charset=UTF-8",
+      "Cache-Control": "public, max-age=300",
+      ETag: specEtag,
+    });
+  });
 
   // Kubernetes liveness probe — process is alive. No dependency checks.
   // `/health` kept as an alias for backward compatibility; K8s manifests