docs(tokens): correct the note claiming gateway max_output is unenforced (#109)

* docs(tokens): correct the note claiming gateway max_output is unenforced

The comment added in 3.35.2 said the gateway's max_output values are 'not
enforced: Franklin sends max_tokens 16384 to haiku today and the gateway
accepts it.' Accepting the request and honoring it are different things. The
gateway clamps with Math.min(request.max_tokens, model.maxOutput) on both
handlers and prices the quote off the clamped ceiling — the request is
accepted rather than rejected, so the clamp stays invisible until a reply is
long enough to hit it. The smoke test that produced that claim returned ten
tokens.

The conclusion the comment supports is unchanged: the static tables stay
authoritative, because the gateway's values are wrong for models we know.
Only the reasoning was wrong, and a wrong reason is how a right rule gets
reverted later.

* docs(tokens): make the correction itself precise

Two things the first pass got imprecise, in a comment whose entire job is
precision about this mechanism:

- It cited 8192 / 64000 in the present tense. Those exact values are being
  corrected upstream (BlockRunAI/blockrun#266), so the comment was written
  pre-stale. Reframed as a dated observation, with the durable point stated
  separately: the catalog can be wrong, and a wrong value here is not
  cosmetic.
- It called the clamp 'invisible' without qualification. The handler does
  log 'capping to <limit>' — server-side, where no caller sees it
  (chat/completions/route.ts:1343). Invisible from here, not silent
  everywhere. Someone who finds that warn should not conclude the comment
  is wrong again.

---------

Co-authored-by: 1bcMax <195689928+1bcMax@users.noreply.github.com>

Author: VickyXAI

src/gateway-models.ts

@@ -92,11 +92,21 @@ export function clearGatewayModelsCache(): void {
  * Deliberately ignores the TTL: a stale gateway record still beats no record
  * at all, and the only callers are fallbacks for models we have no static
  * entry for. Callers must treat the static tables as authoritative — the
- * gateway's own metadata is not reliable (verified 2026-07-20: it reports
- * max_output 8192 for claude-haiku-4.5, which Anthropic documents as 64000,
- * and 64000 for claude-sonnet-4.6, documented as 128000). It is also not
- * enforced: Franklin sends max_tokens 16384 to haiku today and the gateway
- * accepts it. Treat this as "better than a blind default", nothing more.
+ * gateway's own metadata has been wrong for models we already know. As of
+ * 2026-07-20 it reported max_output 8192 for claude-haiku-4.5 (Anthropic
+ * documents 64000) and 64000 for claude-sonnet-4.6 (documented 128000).
+ * Those two specific numbers are being corrected upstream, so do not treat
+ * them as current — the point that outlives them is that the catalog can be
+ * wrong, and a wrong value here is not cosmetic.
+ *
+ * Correction to an earlier note here: these values are NOT inert metadata.
+ * The gateway clamps with them — Math.min(request.max_tokens, model.maxOutput)
+ * in both the messages and chat/completions handlers — and derives its price
+ * quote from the clamped ceiling. An over-cap request is accepted rather than
+ * rejected: the handler logs "capping to <limit>" server-side and continues,
+ * so from here the clamp is invisible until a reply is long enough to hit it.
+ * That is why a short smoke test against a wrongly-capped model looks healthy.
+ * Treat this as "better than a blind default", nothing more.
  */
 export function peekGatewayModel(id: string): GatewayModel | null {
   if (!cache) return null;