From 3b5b60289e504238e71d4391c3dc84ecc6ef7146 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Marc-Andr=C3=A9=20Bombeck?= <mbombeck@gmail.com>
Date: Sat, 20 Jun 2026 13:00:20 +0200
Subject: [PATCH] docs(api): mark coach done.usage.model optional to match
 runtime

The streaming-doc description listed `model` as a required field of the
`done.usage` envelope, but the runtime CoachUsage type has it optional /
nullable. Align the description and regenerate the OpenAPI contract.
---
 docs/api/openapi.yaml           | 2 +-
 src/lib/openapi/routes/coach.ts | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/api/openapi.yaml b/docs/api/openapi.yaml
index 679c837c7..ed87905d3 100644
--- a/docs/api/openapi.yaml
+++ b/docs/api/openapi.yaml
@@ -4152,7 +4152,7 @@ paths:
         (a cadence-suggestion card: `{ type, suggestion }`), `reasoning` (v1.18.9, optional reasoning-summary text: `{
         type, text }` — emitted only by reasoning-capable providers; absent otherwise), `done` (`{ type, conversationId,
         messageId, usage? }` — v1.18.9 adds the optional `usage` envelope `{ totalTokens, promptTokens?,
-        completionTokens?, model }`, server-authoritative; clients display it, never recompute), or `error` (`{ type,
+        completionTokens?, model? }`, server-authoritative; clients display it, never recompute), or `error` (`{ type,
         code, message }`). The HTTP status is 200 even for a provider/refusal outcome — clients dispatch on the `error`
         frame, not the status. Clients ignore unknown frame types (additive evolution). Omitting `conversationId` starts
         a new conversation. Coach-gated; budget- and rate-limited. Auth via cookie or Bearer."
diff --git a/src/lib/openapi/routes/coach.ts b/src/lib/openapi/routes/coach.ts
index 8a091018d..dcc6250c5 100644
--- a/src/lib/openapi/routes/coach.ts
+++ b/src/lib/openapi/routes/coach.ts
@@ -438,7 +438,7 @@ export const coachPaths: NonNullable<ZodOpenApiObject["paths"]> = {
       tags: ["Insights"],
       summary: "Send a Coach turn (streaming reply)",
       description:
-        "v1.18.0 — sends a user turn and streams the assistant reply as Server-Sent Events. The response is `text/event-stream`, not JSON: one `data: <json>\\n\\n` frame per event. Frame `type` is one of `token` (a chunk of reply text: `{ type, token }`), `provenance` (the evidence envelope: `{ type, metricSource }`), `suggestion` (a cadence-suggestion card: `{ type, suggestion }`), `reasoning` (v1.18.9, optional reasoning-summary text: `{ type, text }` — emitted only by reasoning-capable providers; absent otherwise), `done` (`{ type, conversationId, messageId, usage? }` — v1.18.9 adds the optional `usage` envelope `{ totalTokens, promptTokens?, completionTokens?, model }`, server-authoritative; clients display it, never recompute), or `error` (`{ type, code, message }`). The HTTP status is 200 even for a provider/refusal outcome — clients dispatch on the `error` frame, not the status. Clients ignore unknown frame types (additive evolution). Omitting `conversationId` starts a new conversation. Coach-gated; budget- and rate-limited. Auth via cookie or Bearer.",
+        "v1.18.0 — sends a user turn and streams the assistant reply as Server-Sent Events. The response is `text/event-stream`, not JSON: one `data: <json>\\n\\n` frame per event. Frame `type` is one of `token` (a chunk of reply text: `{ type, token }`), `provenance` (the evidence envelope: `{ type, metricSource }`), `suggestion` (a cadence-suggestion card: `{ type, suggestion }`), `reasoning` (v1.18.9, optional reasoning-summary text: `{ type, text }` — emitted only by reasoning-capable providers; absent otherwise), `done` (`{ type, conversationId, messageId, usage? }` — v1.18.9 adds the optional `usage` envelope `{ totalTokens, promptTokens?, completionTokens?, model? }`, server-authoritative; clients display it, never recompute), or `error` (`{ type, code, message }`). The HTTP status is 200 even for a provider/refusal outcome — clients dispatch on the `error` frame, not the status. Clients ignore unknown frame types (additive evolution). Omitting `conversationId` starts a new conversation. Coach-gated; budget- and rate-limited. Auth via cookie or Bearer.",
       requestBody: {
         required: true,
         content: {