[enhancement] E5-1: No OpenAPI specification — no machine-readable contract

[OneStepAt4time]

Finding

ID: API-3 | Severity: 🔴 HIGH

No openapi.yaml or swagger.json. Hand-authored docs/api-reference.md only. No auto-generated SDKs, no API gateway compatibility, no request validation middleware from schemas.

Fix Required

1. Generate or author openapi.yaml covering all /v1/ endpoints
2. Use @fastify/swagger to auto-generate from Fastify schemas
3. Publish spec to /v1/openapi.json and in docs/
4. Add CI step to validate spec on every PR

Files: src/server.ts, new openapi.yaml, docs/api-reference.md

Acceptance Criteria

GET /v1/openapi.json returns a valid OpenAPI 3.1 document. swagger-cli validate passes in CI.

Milestone

M-E5: API & Integration

[OneStepAt4time]

Implemented in PR #1524 (merged). openapi.yaml added at root with 50+ endpoints, validated with swagger-cli.