Serve an OpenAPI spec at /docs

[iexwr]

Context

There is no machine-readable API description; integrators must read the README by hand.

Acceptance criteria

• Add openapi.yaml describing all current and planned endpoints with request/response schemas.
• Serve it at GET /docs (raw YAML) and/or via Swagger UI.
• Keep it in sync as endpoints land (note in PR checklist).

Technical notes

• Start minimal but valid; expand as endpoints are implemented.

Testing

• Lint the spec with a YAML/OpenAPI linter if added; otherwise manual review.