# ADR 0004 — Contract-first OpenAPI API

Status: accepted (2026-07-07) · Plan: rev 3, R3-2/R3-3

## Context
Future UIs, a CLI client, and an MCP surface must stay in sync with the
API. Code-first (Gin + generated docs) drifts.

## Decision
api/openapi.yaml (OpenAPI 3.1) is the source of truth. Server stubs via
oapi-codegen (strict server, chi router); clients generated for Go (CLI)
and TypeScript (future UI). Conventions: RFC 9457 problem+json errors,
{items, next_cursor} envelopes, cursor pagination, Idempotency-Key on
unsafe POSTs, ETag/If-Match optimistic concurrency, scopes
(operator/viewer/agent) annotated per operation. CI fails on spec/handler
drift. MCP tools wrap the same service layer.

## Consequences
- UI development needs only the running API (spec served at /openapi.yaml).
- Handler changes require spec changes first — deliberate friction.
- Breaking changes ship as /api/v2 side by side; v1 is additive-only.