chore(api): add OpenAPI 3.1 spec

Generates `docs/api/openapi.yaml` covering the full REST surface — 100+
paths across 24 tags, 130+ schemas under `components.schemas`. Two
security schemes: `sessionCookie` (HttpOnly `healthlog_session`) plus
`bearerAuth` (HTTP Bearer for the API tokens at `/api/tokens`). Admin
routes are explicitly tagged + restricted to `sessionCookie`.

`docs/api/README.md` documents how to preview the spec locally
(`npx @redocly/cli preview docs/api/openapi.yaml`) and lists the few
known lint warnings (localhost server, redirect endpoints without 2xx).
Lint pass: 0 errors, 17 warnings (none introduced by this commit).

Spec is hand-maintained for now; a future commit can wire it into a
`pnpm openapi:lint` CI step.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

docs/api/README.md

@@ -0,0 +1,76 @@
+# HealthLog API Spec
+
+`openapi.yaml` is the canonical OpenAPI 3.1 description for the HealthLog
+Next.js API. It is the source of truth for the native iOS client's
+DTO codegen.
+
+## Preview locally
+
+Open an interactive Redoc preview in your browser:
+
+```bash
+npx @redocly/cli preview docs/api/openapi.yaml
+```
+
+Generate static HTML for sharing:
+
+```bash
+npx @redocly/cli build-docs docs/api/openapi.yaml --output docs/api/index.html
+```
+
+## Validate
+
+```bash
+npx @redocly/cli lint docs/api/openapi.yaml
+```
+
+The spec is expected to be lint-clean (errors = 0). Some warnings are
+intentional:
+
+- `no-server-example.com` — `http://localhost:3000` is the dev server.
+- `operation-2xx-response` / `operation-4xx-response` — webhook + redirect
+  endpoints intentionally omit one or the other.
+- `no-unused-components` — `ReminderPhase` is exposed for client codegen
+  even though no path response references it directly.
+
+## Layout
+
+- **`info`** — title, version (mirrored from `package.json`), description.
+- **`servers`** — production `https://healthlog.bombeck.io` plus
+  `http://localhost:3000` for local development.
+- **`tags`** — domain groupings (`Auth`, `Measurements`, `Medications`,
+  `Mood`, `Dashboard`, `Insights`, `Achievements`, `DoctorReport`,
+  `Integrations`, `User`, `Tokens`, `Notifications`, `Onboarding`,
+  `Health`, `Settings`, `Analytics`, `Export`, `AuditLog`, `Feedback`,
+  `BugReport`, `Monitoring`, `Webhooks`, `Ingest`, `Admin`).
+- **`securitySchemes`**:
+  - `bearerAuth` — long-lived `hlk_*` API tokens issued via `POST /api/tokens`.
+    Required on `/api/ingest/medication`.
+  - `sessionCookie` — HttpOnly `healthlog_session` cookie set by the
+    password and passkey login flows. Used by the web app and any iOS
+    client running inside a web view.
+- **`components.schemas`** — DTOs for all routes plus the underlying
+  Prisma models (e.g. `Measurement`, `Medication`, `MedicationIntakeEvent`,
+  `MoodEntry`, `User`, `DashboardLayout`, `ApiEnvelope`, `ApiError`).
+- **`paths`** — all routes from `src/app/api/**/route.ts`, including
+  the `/api/admin/*` family which is tagged `Admin` and marked internal.
+
+## Conventions
+
+- Successful responses use the envelope `{ data, error: null }`.
+- Error responses use the envelope `{ data: null, error: '<message>' }`.
+- Pagination uses `limit` + `offset` query parameters and a
+  `meta: { total, limit, offset }` block on the response.
+- All timestamps are ISO 8601 / RFC 3339 (`format: date-time`) in UTC.
+- IDs are CUIDs (opaque strings).
+
+## Updating the spec
+
+When adding or changing routes:
+
+1. Update the relevant route handler under `src/app/api/**/route.ts`.
+2. Mirror the change in `openapi.yaml`. Keep `operationId` camelCase and
+   stable — the iOS codegen keys off it.
+3. Run `npx @redocly/cli lint docs/api/openapi.yaml` and resolve all
+   errors. Warnings are tolerated when documented above.
+4. Bump `info.version` if the change is breaking for clients.