docs(api): add OpenAPI 3.1 spec for HTTP API

[Kures]

PR1 — docs(api): add OpenAPI 3.1 spec for HTTP API

Branch: docs/openapi-spec
Closes: P2-04 from reference/todo.md (OpenAPI spec + generated client SDK for automation integrations)

Why

reference/todo.md lists this as P2-04. Today the only contract for the
HTTP API is src/api.zig (2390 lines). Anyone wanting to build an
integration, generate an SDK, or run a contract test has to read Zig.

What this PR ships

• docs/openapi.yaml — OpenAPI 3.1 spec covering all 36 HTTP
  operations and their request/response shapes.
• docs/api/README.md — viewer instructions (Redoc/Swagger UI),
  validation commands (Python/Node), and one-command SDK generation
  recipes for TypeScript, Python, and Go.

Coverage

Paths	31
Operations	36
Schemas	30
Reusable parameters	5
Reusable responses	3

All 7 enums from src/types.zig are modeled (RunStatus, StepStatus,
StepType, WorkerStatus, WorkerSource, TrackerTaskState,
ReducerType). The 6 WorkerProtocol values come from
worker_protocol.parse in src/worker_protocol.zig.

Auth and conventions documented

• bearerAuth security scheme (mirrors --api-token / NULLBOILER_API_TOKEN).
• /health and /metrics are explicitly public.
• Idempotency contract for POST /runs (Idempotency-Key header
  preferred, idempotency_key body field accepted, 409 on conflict).
• Drain mode behavior for POST /admin/drain (503 on subsequent runs).
• All error responses use the {error: {code, message}} envelope.

How it was authored

Reverse-engineered from the source of truth on main:

• src/api.zig — handleRequest route table and per-handler bodies.
• src/types.zig — every enum and DB row type.
• src/strategy.zig, src/workflow_loader.zig, src/workflow_validation.zig
  — workflow JSON shape and validation rules.
• src/metrics.zig — referenced from the /metrics example only.

info.version is pinned to 2026.3.2 (the same version
handleHealth returns).

How to validate

python -m pip install openapi-spec-validator
python -m openapi_spec_validator docs/openapi.yaml
# OK

or

npx @apidevtools/swagger-cli validate docs/openapi.yaml

Why review attention is low-risk

• Pure documentation. No Zig touched.
• No file relocation. docs/openapi.yaml and docs/api/ are new.
• Spec validates clean.
• Future maintenance: regenerate SDKs and bump info.version when the
  API surface or release version changes — instructions are in
  docs/api/README.md.

Companion repo: working TypeScript SDK

A reference TypeScript client generated from this spec lives at
Kures/nullboiler-ts-sdk
(separate repo, no PR to this one). It uses the exact openapi-generator-cli typescript-fetch command documented in
docs/api/README.md of this PR — so the spec doubles as a regenerate
recipe. The SDK exposes all 11 API groups behind a single
NullBoilerClient, preserves snake_case field names from the spec,
and ships a examples/quickstart.ts proven against the demo stack.
This closes the second half of P2-04 ("OpenAPI spec + generated
client SDK").

Follow-ups (not in this PR)

• Python and Go SDKs from the same spec (commands already in
  docs/api/README.md).
• CI step that diffs the spec against a running server's behavior
  (groundwork for P2-03 deterministic replay diagnostics).