docs(api): an OpenAPI spec, checked against the router

The brief asked for one. docs/api.md is complete and hand-written, and
there was nothing a tool could read.

Written by hand rather than generated from annotations, which would have
meant every handler carrying a second copy of itself in a comment. The
risk with a hand-written spec is that it goes stale, so it does not
depend on anybody remembering: openapi_test.go walks the chi router and
fails both on a route nothing describes and on a description with no
route behind it. CI separately checks it is a valid OpenAPI document.

The test reads the file with a forty-line scanner rather than pulling in
a YAML library. It needs two things — which paths are listed and which
methods each has — and both sit at fixed indentation in a document the
test also owns, which is worth more than a dependency in a project whose
whole shape is one static binary.

The CalDAV routes are excluded deliberately: PROPFIND and REPORT are
outside what OpenAPI can describe, and docs/caldav.md covers them.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

mkdocs.yml

@@ -56,6 +56,8 @@ nav:
       - Mail to task: mail.md
       - Claude (MCP): mcp.md
       - AI features: ai.md
+  # openapi.yaml is deliberately not in the nav: MkDocs copies it to the site as a
+  # file, and api.md links to it. A nav entry expects a page to render.
   - Reference:
       - API: api.md