api-contract-openapi

# OpenAPI & API Contracts ## Overview The API contract is a promise the web and mobile clients depend on. A silent shape change (renamed field, changed type, removed endpoint) compiles fine on the backend and breaks every consumer at runtime. **Core principle:** The contract is the annotation + DTO in code. Change it deliberately, evolve it additively, and update consumers in the same task when you can't. ## Rules - Maintain Swagger at `/docs`; every admin and v1 endpoint is documented with exact field names, types, and required-ness. - **DTOs align with domain types** — no undocumented fields leaking through, no `map[string]any`. - **A shape change is a breaking change.** Renaming/removing a field or endpoint, or changing a type, breaks consumers. Grep the consumers (`web/src/api.ts`, mobile clients) and update them in the same task, or coordinate explicitly via the task description/interface block. - **Prefer additive evolution:** add new optional fields rather than rename; deprecate before removing. - Regenerate/verify docs after handler changes — the docs must match the code. ## Additive vs breaking | Change | Type | Action | |--------|------|--------| | Add optional field | Additive | Safe; document it | | Add required request field | Breaking | Update all callers same task | | Rename field | Breaking | Prefer add-new + deprecate-old | | Change field type | Breaking | New field or coordinated cutover | | Remove endpoint/field | Breaking | Deprecate first, remove l...