[sre-helmcode]

What changed

Builds on #201 (reasoning token budget) and #202 (budget used as sent, x-nan-truncated-in-reasoning header), merged into this branch with one coherent text per surface (details below).

The docs stop describing the deepseek-v4-flash output-budget floor (a budget below 16384 silently raised while reasoning is on) and document the new contract: the output budget (max_tokens / max_completion_tokens on /v1/chat/completions, max_output_tokens on /v1/responses) is used exactly as sent on every model, except above the model's maximum on two models, where it is lowered to that maximum: 131072 on glm5.3-flash, 393216 on deepseek-v4-flash (nan-devops#902).

• deepseek-v4-flash card (EN + ES, models.mdx): floor text removed, including the sentence saying a prompt within 16384 tokens of the window is rejected even with a small max_tokens. Now says reasoning counts inside the budget, how a reasoning-exhausted answer looks on each route, and the remedies.
• Controlling reasoning section (EN + ES): a paragraph led by "Empty answer with finish_reason: "length"?":
  • Chat Completions signal: empty content, finish_reason: "length", reasoning in message.reasoning_content, usage.completion_tokens_details.reasoning_tokens == completion_tokens.
  • The three Chat Completions facts together are the rule (from docs: the output budget is used as sent; document the reason-empty signal #202); non-streamed Chat Completions calls also carry x-nan-truncated-in-reasoning: true (nan-devops#901; it reads choices, so it is not promised on Responses).
  • Responses signal (measured live): status: "incomplete", incomplete_details.reason: "max_output_tokens", only a reasoning output item, usage.output_tokens_details.reasoning_tokens == output_tokens.
  • Reliable fix: reasoning off (reasoning_effort: "none" on Chat Completions, reasoning: {"effort": "none"} on Responses); GLM cannot turn it off (minimal is its shortest). A lower effort is a hint, not a cap, on deepseek-v4-flash and qwen3.8-flash (measured: minimal still hit the limit on a dense prompt); only qwen3.6 / gemma4 cap it, on Chat Completions; links docs(models): document the reasoning token budget #201's token-budget subsection for a hard cap. With reasoning off the answer can still stop at the budget, so the budget must fit the answer. To keep the reasoning: a generous budget plus streaming, linking the existing "Long outputs: stream them" section (120 s / 524) instead of duplicating it.
• mimo-v2.6-flash card (EN + ES): "recommended max_tokens ≥ 300" replaced by "reasoning counts inside max_tokens".
• examples.md (EN + ES): replaced the "max_tokens ≥ 300" advice with model-generic guidance.
• OpenAPI (src/data/openapi.json): max_tokens describes the pass-through contract, both per-model ceilings (including in the generic-400 rule) and the remedies; max_output_tokens states the ceilings and the Responses signal (docs: the output budget is used as sent; document the reason-empty signal #202's claim of finish_reason and the header there was Chat-only and is replaced).

Why

Owner decision 2026-10-19: remove the reasoning output-budget floor. See the internal triage note.

Tests

• Union of this PR's and docs(models): document the reasoning token budget #201/docs: the output budget is used as sent; document the reason-empty signal #202's asserts, adjusted to the merged text (header asserts kept; voseo/"never raise" wording superseded).
• src/tests/lib/docsReasoning.test.ts: suite "output budget: passed through as sent, no floor (en + es)" asserts, in both locales: no floor wording or ≥ 300 / ≥ 300 advice anywhere on models or examples; both per-model ceilings (glm5.3-flash 131072, deepseek-v4-flash 393216); the Chat Completions and Responses signals scoped per route (no finish_reason / completion_tokens_details promised for Responses); none as the reliable fix on both routes, effort as a hint, the GLM caveat; the bold lead; the reasoning-off budget note; the mimo card; model-generic examples; link anchors exist. The spec max_tokens test asserts the pass-through text.
• src/lib/openapiSpec.test.ts: floor test replaced by a pass-through test (spec max_tokens and max_output_tokens, both cards, negative asserts on the floor wording).
• Tests were written first and failed against the previous text on each iteration.
• npm test: 87 files, 2516 tests passed. npm run build: complete, exit 0.

Merge with #201/#202

• Card: docs(models): output budget passed through as sent, no reasoning floor #200 wording plus docs: the output budget is used as sent; document the reason-empty signal #202's header on the /chat/completions signal; docs: the output budget is used as sent; document the reason-empty signal #202's card phrasing (voseo, "we never raise it", "Raise the budget, or stream") superseded by one phrasing.
• Reasoning section: one paragraph, docs: the output budget is used as sent; document the reason-empty signal #202's three-field rule + header folded in; docs(models): document the reasoning token budget #201 subsection kept unchanged and linked.
• OpenAPI max_tokens: docs(models): output budget passed through as sent, no reasoning floor #200 text + header. max_output_tokens: Responses signal instead of the Chat-only header/finish_reason claim.

Deploy notes

• All prerequisites are live in prod (2026-10-19), so this can merge:
  1. Floor removal (nan-devops#898): deployed and verified live, max_tokens=256 with reasoning on returns 256 tokens.
  2. Copying max_completion_tokens to max_tokens when max_tokens is absent (nan-devops#902; DeepSeek's API ignores max_completion_tokens): deployed and verified live, deepseek-v4-flash with max_completion_tokens=256 returns 256.
  3. The deepseek-v4-flash 393216 output ceiling (nan-devops#902): deployed and verified live, max_completion_tokens=1000000 is served (lowered), not rejected.
• No VERSION file in this repo; deploy runs on push to main.

🤖 Generated with Claude Code