Describe the API spec as generated and complete the MCP catalogue

- api/README: the YAML is emitted from the Zod registry by
  pnpm openapi:generate with a CI drift check; document the real
  servers, tags, and coverage (client-facing REST, most admin routes
  and the OAuth/webhook surfaces excluded) and replace the hand-edit
  workflow with the generator workflow
- mcp-capabilities: add the registered get_intraday_pulse,
  get_ecg_recordings and get_nutrients tools and the
  nutrient/{code} resource template to the tables

docs/api/README.md

@@ -1,8 +1,12 @@
 # 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.
+`openapi.yaml` is the OpenAPI 3.1 description for the HealthLog
+Next.js API and the source of truth for the native iOS client's DTO
+codegen. The file is **generated**: `pnpm openapi:generate` emits it
+from the Zod registry under `src/lib/openapi/` (`registry.ts` plus the
+route modules in `src/lib/openapi/routes/`). Do not edit the YAML by
+hand; the next generation overwrites it, and CI (`openapi:check`)
+fails the build when the committed YAML drifts from the registry.
 
 The MCP server is documented separately — it is a distinct contract over
 JSON-RPC, not part of the REST OpenAPI spec:
@@ -34,36 +38,38 @@ npx @redocly/cli build-docs docs/api/openapi.yaml --output docs/api/index.html
 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.
+The spec is expected to be lint-clean (errors = 0). Warnings such as
+`no-server-example.com` for the localhost dev server are tolerated;
+re-run the lint to see what it produces against the current file
+before treating a warning as a regression.
 
 ## 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`,
-  `Monitoring`, `Webhooks`, `Ingest`, `Admin`).
+- **`info`** — title, description, and `version` mirrored automatically
+  from `package.json` at generation time. Never bump it by hand.
+- **`servers`** — `https://healthlog.example.com` as the self-hosted
+  placeholder plus `http://localhost:3000` for local development.
+- **`tags`** — domain groupings; the current set lives at the top of
+  the generated file (`Auth`, `Measurements`, `Medications`, `Mood`,
+  `Analytics`, `Insights`, `Consent`, `Dashboard`, `Notifications`,
+  `Devices`, `Export`, `Sync`, `Cycle`, `MeasurementReminders`,
+  `Labs`, `Illness`, `Documents`, `Records`, `Admin`, `Meta`,
+  `Retired`).
 - **`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.
+- **`components.schemas`** — DTOs for the documented routes plus the
+  underlying Prisma models (e.g. `Measurement`, `Medication`,
+  `MedicationIntakeEvent`, `MoodEntry`, `User`, `DashboardLayout`,
+  `ApiEnvelope`, `ApiError`).
+- **`paths`** — the client-facing REST surface. Not every
+  `src/app/api/**/route.ts` is in the contract: most `/api/admin/*`
+  routes, the OAuth connect/callback legs, and the webhook surfaces
+  are not documented here. The `Retired` tag lists removed paths that
+  answer `410 Gone`.
 
 ## Conventions
 
@@ -79,8 +85,12 @@ intentional:
 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.
+2. Change the Zod schemas and their `.meta()` registrations under
+   `src/lib/openapi/` (registry entry plus the matching module in
+   `src/lib/openapi/routes/`). Keep `operationId` camelCase and
+   stable; the iOS codegen keys off it.
+3. Run `pnpm openapi:generate` and commit the regenerated
+   `openapi.yaml` alongside the schema change. CI's `openapi:check`
+   fails on drift.
+4. Never edit the YAML directly and never bump `info.version` by
+   hand; the version follows `package.json` at generation time.