write-openapilisted

# OpenAPI Specification Skill `openapi.yaml` is the public contract for the REST API, consumed by documentation generators, client code generators, and API testing tools. Every field name, type, and status code is a durable commitment once published. **Before touching `openapi.yaml`**, read the entire file, and read the Go handler code for every endpoint you are about to change. The spec must match exactly what the server returns, not what you think it should return. --- ## After Every Edit Run these in order after any change to `openapi.yaml`: ```bash pnpm format # runs Prettier over all files pnpm lint:openapi # validates the spec with Redocly ``` Never ship a change that fails `pnpm lint:openapi`. Warnings are not errors, but document any known, intentional one (see Suppressed Warnings). Then update the TypeScript types in the JS client `pkg/js/rest/src/` to match the spec change, and run `pnpm lint:typecheck` to confirm. --- ## Project Layout ``` openapi.yaml # The single-file OpenAPI 3.1 spec (edit this) pkg/js/rest/src/ # JS client that must stay in sync with the spec ``` Everything lives in `openapi.yaml`; there is no multi-file splitting. Use `$ref` for reusable components defined under `components/` in the same file: ```yaml $ref: "#/components/schemas/jwk" $ref: "#/components/responses/notFound" $ref: "#/components/parameters/jwkID" ``` --- ## Toolchain Linting runs **Redocly CLI** via `pnpm redocly lint openapi.yaml`. A `redocl