From 9412cfd5ab92b8a61ddcaa013c50825fa3d83938 Mon Sep 17 00:00:00 2001
From: Matt Miller <mattmiller@comfy.org>
Date: Fri, 23 Oct 2026 21:46:41 +0000
Subject: [PATCH 1/2] feat(router-docs): render alt-provider leg limits on
 model pages and the providers matrix
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

A leg's `limits` object on `x-comfy-router-alt-providers` now renders as
indented sub-bullets under its Serving providers row (accepted formats,
duration, aspect ratios, current price from the rate snapshot, rejected
inputs, fallback). The providers matrix marks such a cell `✓*` with a
footnote. A malformed `limits` is dropped and the leg row is unchanged.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .github/scripts/snippets/README.md            |  18 +-
 .../scripts/snippets/gen-code-pages.test.ts   | 180 +++++++++++++
 .github/scripts/snippets/gen-code-pages.ts    | 250 +++++++++++++++++-
 .../scripts/snippets/gen-router-pricing.ts    |   2 +-
 4 files changed, 434 insertions(+), 16 deletions(-)

diff --git a/.github/scripts/snippets/README.md b/.github/scripts/snippets/README.md
index 2a5337c049..3c03e43927 100644
--- a/.github/scripts/snippets/README.md
+++ b/.github/scripts/snippets/README.md
@@ -76,7 +76,7 @@ provider renders sanely without a code change.
 
 Some models can be served by more than one provider. Router publishes the
 relationship on the schema documents themselves: a **native** document lists its
-legs in `x-comfy-router-alt-providers` (`[{provider, model_id}]`), and each leg
+legs in `x-comfy-router-alt-providers` (`[{provider, model_id?, limits?}]`), and each leg
 also has an **alias** document of its own carrying `x-comfy-router-alias-of` (the
 native model id) and `x-comfy-router-alias-provider` (the provider serving it).
 
@@ -96,12 +96,26 @@ The generator reads both and organises the docs by model rather than by route:
   per leg with the provider's label, the leg's alias model id, and the same call
   on the same endpoint with `?model_provider=<provider>` added. A native model
   with no leg renders no section.
+- A leg whose entry carries a **`limits`** object (a leg materially narrower
+  than its native model) gets indented sub-bullets under its row: what it
+  accepts (resolution, audio, duration range, aspect ratios), its price, the
+  inputs it rejects and with which error, and its fallback. The price comes
+  from `router-pricing/metronome-rates.json`, keyed on the native model id and
+  the provider label, current rows only, with credits rounded to 2 decimals.
+  With no matching row the price line is omitted. The lines are indented
+  because `gen-router-pricing.ts` counts a page's providers from its column-0
+  `- **<Label>**` lines. A malformed `limits` is dropped as a whole and the
+  leg row renders as if it had none. Only what the JSON and the rate snapshot
+  say is printed, and no value containing `/` is accepted, so a held-back leg
+  id cannot reach the page through `limits`.
 - A **`development/comfy-router/providers.mdx`** index is generated listing each
   serving provider and the native models it covers, and is added to the `Models`
   nav group beside the catalog index. Comfy is described rather than enumerated:
   it serves the whole catalog, and the catalog index one link away already is
   that list. The page exists only while some model publishes a leg, so a catalog
-  with no alternate routing gains no page, no nav entry and no diff.
+  with no alternate routing gains no page, no nav entry and no diff. A cell
+  whose leg carries `limits` renders `✓*`, with one footnote under the table
+  pointing at the model page.
 
 The redirect destination is resolved through the page the native model is
 actually documented on, which is not always `models/<provider>/<model>/code`: a
diff --git a/.github/scripts/snippets/gen-code-pages.test.ts b/.github/scripts/snippets/gen-code-pages.test.ts
index 7cf591bee5..684358800a 100644
--- a/.github/scripts/snippets/gen-code-pages.test.ts
+++ b/.github/scripts/snippets/gen-code-pages.test.ts
@@ -20,7 +20,11 @@ import {
   renderModelsIndex,
   renderProvidersPage,
   servingProvidersSection,
+  legPrice,
+  roundCredits,
 } from "./gen-code-pages.ts";
+import type { RateSnapshot } from "./gen-code-pages.ts";
+import { servingProviders } from "./gen-router-pricing.ts";
 
 const ROOT = join(import.meta.dir, "../../..");
 
@@ -432,6 +436,182 @@ describe("the Providers page", () => {
   });
 });
 
+// ---------------------------------------------------------------------------
+// Per-leg limits (BE-23008's `limits` object on an alt-provider entry). The
+// fixture is the Tencent leg on Kling V3: silent 720P only, 3 to 15 seconds,
+// the std tier only, text-to-video only. Its own catalog id is held back, so the
+// one id that must never reach a page is in the fixture too, where the exporter
+// could plausibly leak it (a `reason`).
+// ---------------------------------------------------------------------------
+
+const KLING = "kling/kling-v3";
+const KLING_PAGE = "development/comfy-router/models/kling/kling-v3/code";
+const HELD_ID = "tencent-kling-v3";
+const TENCENT_LIMITS = {
+  resolutions: ["720P"],
+  audio: ["silent"],
+  duration_seconds: { min: 3, max: 15, default: 5 },
+  aspect_ratios: ["16:9", "9:16", "1:1"],
+  rejected_inputs: [
+    { field: "image", rule: "set", reason: `text-to-video only (${HELD_ID})` },
+    { field: "image_tail", rule: "set", reason: "text-to-video only" },
+    { field: "sound", rule: "equals", values: ["on"], example: "on", reason: "no audio yet" },
+    { field: "mode", rule: "not_in", values: ["std"], example: "pro", reason: "std tier only" },
+    { field: "multi_shot", rule: "set", example: true, reason: "single shot" },
+    { field: "multi_prompt", rule: "set", reason: "single shot" },
+    { field: "shot_type", rule: "set", example: "customize", reason: "single shot" },
+  ],
+  rejected_with: "400 invalid_input",
+  fallback: { provider: "kling", default: true, opt_out: "fallback_provider=false" },
+};
+const HIGGSFIELD_KLING_LEG = { provider: "higgsfield", model_id: "higgsfield/higgsfield-kling-3-std" };
+const KLING_DOC = {
+  paths: {},
+  "x-comfy-router-alt-providers": [HIGGSFIELD_KLING_LEG, { provider: "tencent", limits: TENCENT_LIMITS }],
+};
+const TENCENT_RATE = {
+  model_id: KLING, serving_provider: "Tencent", kind: "metered", price_usd: "0.096", credits: "20.256",
+  unit: "per second", conditions: "720P, silent", effective_from: "2026-10-20",
+};
+const HIGGSFIELD_RATE = {
+  model_id: KLING, serving_provider: "Higgsfield", kind: "metered", price_usd: "0.1262", credits: "26.6282",
+  unit: "per second", conditions: "Kling 3 Standard", effective_from: "2026-09-20",
+};
+const RATES: RateSnapshot = { snapshot_at: "2026-10-23T00:00:00Z", rates: [HIGGSFIELD_RATE, TENCENT_RATE] };
+const NO_RATES: RateSnapshot = { snapshot_at: "2026-10-23T00:00:00Z", rates: [] };
+
+const EXPECTED_TENCENT_ROWS = [
+  "- **Tencent**: `POST https://api.comfy.org/v2/models/kling/kling-v3?model_provider=tencent`",
+  "  - Limits: 720P, silent; 3–15 seconds (default 5); aspect ratio 16:9, 9:16 or 1:1",
+  "  - Price: 20.26 credits ($0.096) per second",
+  '  - Rejected with `400 invalid_input`: `image`, `image_tail`, `sound: "on"`, `mode` other than `std` (e.g. `"pro"`), `multi_shot`, `multi_prompt`, `shot_type`',
+  "  - Fallback: if Tencent fails, the request retries once on Kling (the default provider). Send `fallback_provider=false` to opt out. Rejected inputs and BYOK requests don't fall back.",
+].join("\n");
+
+describe("alt-provider leg limits", () => {
+  const legs = () => readRelations(KLING, KLING_DOC).altProviders;
+
+  test("readRelations keeps a well-formed `limits` on its leg and none on a leg without one", () => {
+    const [higgsfield, tencent] = legs();
+    expect(higgsfield).toEqual(HIGGSFIELD_KLING_LEG);
+    expect(tencent.provider).toBe("tencent");
+    expect(tencent).not.toHaveProperty("model_id");
+    expect(tencent.limits?.duration_seconds).toEqual({ min: 3, max: 15, default: 5 });
+    expect(tencent.limits?.rejected_inputs).toHaveLength(7);
+  });
+
+  test("the Tencent leg renders its row plus the four limit lines, under the row", () => {
+    const out = servingProvidersSection([{ model: KLING, legs: legs() }], RATES);
+    expect(out).toContain(EXPECTED_TENCENT_ROWS);
+    expect(out).not.toContain("—");
+  });
+
+  test("a leg without `limits` renders byte-identically to before limits existed", () => {
+    const before = [
+      "- **Comfy** (default): `POST https://api.comfy.org/v2/models/kling/kling-v3`",
+      "- **Higgsfield**, as `higgsfield/higgsfield-kling-3-std`: `POST https://api.comfy.org/v2/models/kling/kling-v3?model_provider=higgsfield`",
+      "- **Tencent**:",
+    ].join("\n");
+    expect(servingProvidersSection([{ model: KLING, legs: legs() }], RATES)).toContain(before);
+    // And the section a page with no limited leg gets is untouched by the rate snapshot.
+    const plain = [{ model: KLING, legs: [HIGGSFIELD_KLING_LEG] }];
+    expect(servingProvidersSection(plain, RATES)).toBe(servingProvidersSection(plain, NO_RATES));
+    expect(servingProvidersSection(plain, RATES)).not.toContain("  - ");
+  });
+
+  test("a malformed `limits` is dropped and the leg row is kept", () => {
+    const bad = [
+      "720P",
+      [],
+      { resolutions: "720P" },
+      { resolutions: ["720P"], duration_seconds: { min: 15, max: 3 } },
+      { duration_seconds: { min: 3, max: 15, default: 30 } },
+      { rejected_inputs: [{ field: "mode", rule: "not_in" }] },
+      { rejected_inputs: [{ field: "mode", rule: "unknown_rule" }] },
+      { fallback: { provider: "kling" } },
+      { fallback: { provider: "kling", default: true, opt_out: "`rm -rf`" } },
+      { aspect_ratios: ["<b>16:9</b>"] },
+      // A `provider/model` id smuggled into a printed value.
+      { resolutions: [`tencent/${HELD_ID}`] },
+      {},
+    ];
+    for (const limits of bad) {
+      const [leg] = readRelations(KLING, { paths: {}, "x-comfy-router-alt-providers": [{ provider: "tencent", limits }] }).altProviders;
+      expect(leg).toEqual({ provider: "tencent" });
+      expect(servingProvidersSection([{ model: KLING, legs: [leg] }], RATES)).toContain(
+        "- **Tencent**: `POST https://api.comfy.org/v2/models/kling/kling-v3?model_provider=tencent`\n\n`strict_mode`"
+      );
+    }
+  });
+
+  test("with no matching rate row the price line is omitted, never guessed", () => {
+    const out = servingProvidersSection([{ model: KLING, legs: legs() }], NO_RATES);
+    expect(out).toContain("  - Limits: 720P, silent");
+    expect(out).not.toContain("Price:");
+    // Higgsfield's row is for another provider; it must not stand in for Tencent's.
+    expect(legPrice(KLING, "Tencent", { ...RATES, rates: [HIGGSFIELD_RATE] })).toBeUndefined();
+  });
+
+  test("only the current, priced, entitled row is rendered; the 1080P tier is not", () => {
+    const rates = (...rows: object[]): RateSnapshot => ({ ...RATES, rates: rows as RateSnapshot["rates"] });
+    // An older row is superseded by the current one.
+    const older = { ...TENCENT_RATE, price_usd: "0.2", credits: "42.2", effective_from: "2026-01-01" };
+    expect(legPrice(KLING, "Tencent", rates(older, TENCENT_RATE))).toBe("20.26 credits ($0.096) per second");
+    // An un-entitled or ended row is not a current price.
+    expect(legPrice(KLING, "Tencent", rates({ ...TENCENT_RATE, entitled: false }))).toBeUndefined();
+    expect(legPrice(KLING, "Tencent", rates({ ...TENCENT_RATE, effective_until: "2026-10-21" }))).toBeUndefined();
+    expect(legPrice(KLING, "Tencent", rates({ ...TENCENT_RATE, kind: "usage", price_usd: undefined, credits: undefined }))).toBeUndefined();
+    // The snapshot carries no 1080P row, and nothing renders one.
+    const out = servingProvidersSection([{ model: KLING, legs: legs() }], RATES);
+    expect(out).not.toContain("1080");
+    expect(out).not.toContain("0.128");
+  });
+
+  test("credits round half up to 2 decimals on the decimal string", () => {
+    expect(roundCredits("20.256")).toBe("20.26");
+    expect(roundCredits("26.6282")).toBe("26.63");
+    expect(roundCredits("29.54")).toBe("29.54");
+    expect(roundCredits("21.1")).toBe("21.1");
+    expect(roundCredits("0.004")).toBe("0");
+    expect(roundCredits("1.005")).toBe("1.01");
+    expect(roundCredits("abc")).toBeUndefined();
+  });
+
+  test("the providers matrix marks the limited cell `✓*`, adds the footnote, and leaves other cells alone", () => {
+    const pages = new Map([[KLING, { page: KLING_PAGE, title: "Kling V3" }]]);
+    const { rows, problems } = providerRelationRows(new Map([[KLING, legs()]]), [], pages);
+    expect(problems).toEqual([]);
+    const page = renderProvidersPage(rows);
+    expect(page).toContain("| Model / provider | **Comfy (default)** | **Higgsfield** | **Tencent** |");
+    expect(page).toContain(`| [Kling V3](/${KLING_PAGE}) | ✓ | ✓ | ✓* |`);
+    expect(page).toContain("\n\\* This provider serves the model with narrower limits than the default; see the model page.\n");
+    expect(page).not.toContain(HELD_ID);
+    // With no limited leg anywhere, the page is exactly what it was.
+    const plain = providerRelationRows(new Map([[KLING, [HIGGSFIELD_KLING_LEG]]]), [], pages).rows;
+    expect(plain[0]).not.toHaveProperty("limited");
+    expect(renderProvidersPage(plain)).not.toContain("✓*");
+    expect(renderProvidersPage(plain)).not.toContain("narrower limits");
+  });
+
+  test("the pricing generator still counts exactly the three providers on the Kling V3 page", () => {
+    const section = servingProvidersSection([{ model: KLING, legs: legs() }], RATES);
+    expect(servingProviders(`# Kling V3\n\n${section}\n\n## Schema\n`, KLING)).toEqual(["Comfy", "Higgsfield", "Tencent"]);
+  });
+
+  test("the held-back leg id appears nowhere in a whole run", () => {
+    const schema = { authored: false, components: {}, ...readRelations(KLING, KLING_DOC) };
+    const page = renderDerivedPage(KLING, schema);
+    expect(page).toContain("Rejected with `400 invalid_input`");
+    const pages = new Map([[KLING, { page: KLING_PAGE, title: "Kling V3" }]]);
+    const providers = renderProvidersPage(providerRelationRows(new Map([[KLING, schema.altProviders]]), [], pages).rows);
+    for (const out of [servingProvidersSection([{ model: KLING, legs: schema.altProviders }], RATES), page, providers]) {
+      expect(out).not.toContain(HELD_ID);
+      expect(out).not.toContain("tencent/");
+      expect(out).not.toContain("undefined");
+    }
+  });
+});
+
 describe("modelsNav: pricing and provider indexes sit beside the catalog", () => {
   const live = [{ model: "kling/kling-v3", page: "development/comfy-router/models/kling/kling-v3/code" }];
 
diff --git a/.github/scripts/snippets/gen-code-pages.ts b/.github/scripts/snippets/gen-code-pages.ts
index e1996d090f..28ba31913b 100644
--- a/.github/scripts/snippets/gen-code-pages.ts
+++ b/.github/scripts/snippets/gen-code-pages.ts
@@ -16,6 +16,7 @@
 import { readFileSync, writeFileSync, existsSync, mkdirSync, mkdtempSync, rmSync } from "node:fs";
 import { join, dirname, relative } from "node:path";
 import { tmpdir } from "node:os";
+import { formatAmount } from "./router-pricing-display.ts";
 
 const ROOT = join(import.meta.dir, "../../..");
 const SPEC_GLOB = "development/comfy-router/models/**/code.yaml";
@@ -559,7 +560,31 @@ type SchemaDoc = {
  * native model (Router's `DirectHeld`, BE-22964): its own catalog id is held back,
  * publishes no document, and must not be printed on a public page.
  */
-export type AltProvider = { provider: string; model_id?: string };
+export type AltProvider = { provider: string; model_id?: string; limits?: LegLimits };
+
+/**
+ * One native input a leg refuses before dispatch. `set` refuses any non-empty
+ * value, `equals` refuses each value in `values`, `not_in` refuses any value
+ * outside `values`; `example` is a value that triggers the refusal.
+ */
+export type RejectedInput = { field: string; rule: "set" | "equals" | "not_in"; values?: string[]; example?: string | number | boolean };
+
+/**
+ * What an alternate-provider leg accepts when it is materially narrower than its
+ * native model: the `limits` object of an `x-comfy-router-alt-providers` entry
+ * (BE-23008, built in cloud from the constants the leg's translator enforces).
+ * Every field is optional; an absent one means "no narrower than the native schema".
+ * `rejected_with` is normalized to the one string the page prints (`400 invalid_input`).
+ */
+export type LegLimits = {
+  resolutions?: string[];
+  audio?: string[];
+  duration_seconds?: { min: number; max: number; default?: number };
+  aspect_ratios?: string[];
+  rejected_inputs?: RejectedInput[];
+  rejected_with?: string;
+  fallback?: { provider: string; default: boolean; opt_out?: string };
+};
 
 /** What an alias document says it is a leg of, from `x-comfy-router-alias-of` / `-alias-provider`. */
 export type AliasRelation = { aliasOf: string; provider: string };
@@ -635,6 +660,79 @@ const isSlug = (v: unknown): v is string => typeof v === "string" && /^[^\s/?#]+
 /** A `<provider>/<model>` model ID: exactly two non-empty, slug-shaped segments. */
 const isModelId = (v: unknown): v is string => typeof v === "string" && /^[^\s/?#]+\/[^\s/?#]+$/.test(v);
 
+/**
+ * A value printed as-is on the page: no Markdown, MDX, or URL syntax, and no `/`, so
+ * nothing in `limits` can spell a `provider/model` catalog id onto a public page.
+ */
+const isLimitToken = (v: unknown): v is string => typeof v === "string" && /^[A-Za-z0-9][A-Za-z0-9 _:.+-]*$/.test(v);
+/** A request field name, dotted for a nested one. */
+const isFieldName = (v: unknown): v is string => typeof v === "string" && /^[A-Za-z_][A-Za-z0-9_.]*$/.test(v);
+const tokenList = (v: unknown): string[] | null =>
+  Array.isArray(v) && v.length > 0 && v.every(isLimitToken) ? [...v] : null;
+
+/**
+ * A leg's `limits`, or `undefined` when it is absent, empty, or malformed in any
+ * field. All-or-nothing on purpose: a half-read object would print a leg as
+ * narrower in one way and silently as wide as its native model in another, so a
+ * bad value drops the whole object and the leg row renders exactly as it did
+ * before limits existed.
+ */
+function readLimits(raw: unknown): LegLimits | undefined {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return undefined;
+  const r = raw as Record<string, unknown>;
+  const out: LegLimits = {};
+  for (const key of ["resolutions", "audio", "aspect_ratios"] as const) {
+    if (r[key] === undefined) continue;
+    const list = tokenList(r[key]);
+    if (!list) return undefined;
+    out[key] = list;
+  }
+  if (r.duration_seconds !== undefined) {
+    const d = r.duration_seconds as Record<string, unknown> | null;
+    const num = (v: unknown): v is number => typeof v === "number" && Number.isFinite(v) && v >= 0;
+    if (!d || typeof d !== "object" || !num(d.min) || !num(d.max) || d.min > d.max) return undefined;
+    if (d.default !== undefined && (!num(d.default) || d.default < d.min || d.default > d.max)) return undefined;
+    out.duration_seconds = d.default === undefined ? { min: d.min, max: d.max } : { min: d.min, max: d.max, default: d.default };
+  }
+  if (r.rejected_inputs !== undefined) {
+    if (!Array.isArray(r.rejected_inputs) || !r.rejected_inputs.length) return undefined;
+    const rejected: RejectedInput[] = [];
+    for (const entry of r.rejected_inputs) {
+      const e = (entry ?? {}) as Record<string, unknown>;
+      if (!isFieldName(e.field) || (e.rule !== "set" && e.rule !== "equals" && e.rule !== "not_in")) return undefined;
+      const item: RejectedInput = { field: e.field, rule: e.rule };
+      if (e.values !== undefined || e.rule !== "set") {
+        const values = tokenList(e.values);
+        if (!values) return undefined;
+        item.values = values;
+      }
+      if (e.example !== undefined) {
+        const ok = typeof e.example === "boolean" || (typeof e.example === "number" && Number.isFinite(e.example)) || isLimitToken(e.example);
+        if (!ok) return undefined;
+        item.example = e.example as RejectedInput["example"];
+      }
+      rejected.push(item);
+    }
+    out.rejected_inputs = rejected;
+  }
+  if (r.rejected_with !== undefined) {
+    // A string (`"400 invalid_input"`) or its parts (`{status: 400, code: "invalid_input"}`).
+    const w = r.rejected_with as Record<string, unknown> | string | null;
+    const text = typeof w === "string" ? w
+      : w && typeof w === "object" && Number.isInteger(w.status) && isLimitToken(w.code) ? `${w.status} ${w.code}`
+      : undefined;
+    if (!isLimitToken(text)) return undefined;
+    out.rejected_with = text;
+  }
+  if (r.fallback !== undefined) {
+    const f = r.fallback as Record<string, unknown> | null;
+    if (!f || typeof f !== "object" || !isSlug(f.provider) || typeof f.default !== "boolean") return undefined;
+    if (f.opt_out !== undefined && (typeof f.opt_out !== "string" || !/^[a-z_]+=[A-Za-z0-9_]+$/.test(f.opt_out))) return undefined;
+    out.fallback = f.opt_out === undefined ? { provider: f.provider, default: f.default } : { provider: f.provider, default: f.default, opt_out: f.opt_out };
+  }
+  return Object.keys(out).length ? out : undefined;
+}
+
 export function readRelations(model: string, doc: SchemaDoc): ModelRelations {
   const aliasOf = doc["x-comfy-router-alias-of"];
   if (isModelId(aliasOf) && aliasOf !== model) {
@@ -647,12 +745,16 @@ export function readRelations(model: string, doc: SchemaDoc): ModelRelations {
   const altProviders: AltProvider[] = [];
   for (const entry of raw) {
     if (!entry || typeof entry !== "object") continue;
-    const { provider, model_id } = entry as Record<string, unknown>;
+    const { provider, model_id, limits: rawLimits } = entry as Record<string, unknown>;
     if (!isSlug(provider)) continue;
     if (model_id !== undefined && (!isModelId(model_id) || model_id === model)) continue;
     if (seen.has(provider)) continue;
     seen.add(provider);
-    altProviders.push(model_id === undefined ? { provider } : { provider, model_id });
+    const leg: AltProvider = model_id === undefined ? { provider } : { provider, model_id };
+    // A malformed `limits` costs the leg its limits, never its row.
+    const limits = readLimits(rawLimits);
+    if (limits) leg.limits = limits;
+    altProviders.push(leg);
   }
   altProviders.sort((a, b) => (a.provider < b.provider ? -1 : a.provider > b.provider ? 1 : 0));
   return { altProviders };
@@ -894,6 +996,123 @@ export function opaqueOutputExample(s: ModelSchema): string {
 /** One model on a page, with whatever alternate serving providers its document lists. */
 type NativeLegs = { model: string; legs: AltProvider[] };
 
+/** One row of `router-pricing/metronome-rates.json`, the same snapshot `pricing.mdx` renders from. */
+export type LegRate = {
+  model_id: string;
+  serving_provider: string;
+  kind: string;
+  unit: string;
+  price_usd?: string;
+  credits?: string;
+  conditions?: string;
+  effective_from: string;
+  effective_until?: string;
+  entitled?: boolean;
+};
+export type RateSnapshot = { snapshot_at: string; rates: LegRate[] };
+
+let rateSnapshot: RateSnapshot | undefined;
+/** The repo's rate snapshot, read once; its supplemental sources count as rates too. */
+function routerRates(): RateSnapshot {
+  if (rateSnapshot) return rateSnapshot;
+  const data = JSON.parse(readFileSync(join(ROOT, "router-pricing/metronome-rates.json"), "utf8"));
+  const rates: LegRate[] = [...(data.rates ?? []), ...(data.supplemental_sources ?? []).flatMap((s: { rates?: LegRate[] }) => s.rates ?? [])];
+  return (rateSnapshot = { snapshot_at: String(data.snapshot_at ?? ""), rates });
+}
+
+/**
+ * Round a decimal credit amount to 2 places, half up, on the decimal string
+ * itself (`20.256` -> `20.26`) so binary floating point cannot round it down.
+ * This is the rounding `X-Comfy-Credits-Used` reports.
+ */
+export function roundCredits(value: string): string | undefined {
+  const m = /^(\d+)(?:\.(\d+))?$/.exec(value);
+  if (!m) return undefined;
+  const frac = m[2] ?? "";
+  const cents = BigInt(m[1] + (frac + "00").slice(0, 2)) + (frac.length > 2 && frac[2] >= "5" ? 1n : 0n);
+  const s = cents.toString().padStart(3, "0");
+  return formatAmount(`${s.slice(0, -2)}.${s.slice(-2)}`);
+}
+
+/**
+ * The price of one leg, from its CURRENT rate rows: priced (not usage-based),
+ * not explicitly un-entitled, not ended by the snapshot date, and at the latest
+ * `effective_from` among those. No matching row means no price line: the page
+ * never guesses a price, and a tier the snapshot does not carry never appears.
+ */
+export function legPrice(model: string, provider: string, snapshot: RateSnapshot): string | undefined {
+  const asOf = snapshot.snapshot_at.slice(0, 10);
+  const live = snapshot.rates.filter(
+    (r) =>
+      r.model_id === model &&
+      r.serving_provider === provider &&
+      r.kind !== "usage" &&
+      r.entitled !== false &&
+      r.price_usd !== undefined &&
+      r.credits !== undefined &&
+      !(r.effective_until && asOf && r.effective_until.slice(0, 10) <= asOf)
+  );
+  if (!live.length) return undefined;
+  const latest = live.reduce((max, r) => (r.effective_from > max ? r.effective_from : max), "");
+  const current = live.filter((r) => r.effective_from === latest);
+  const amounts = current.map((r) => {
+    const credits = roundCredits(r.credits!);
+    if (!credits || !/^\d+(\.\d+)?$/.test(r.price_usd!)) return undefined;
+    const unit = r.unit.startsWith("per ") ? r.unit : `per ${r.unit}`;
+    const conditions = current.length > 1 && r.conditions ? ` (${r.conditions})` : "";
+    return `${credits} credits ($${formatAmount(r.price_usd!)}) ${unit}${conditions}`;
+  });
+  return amounts.every(Boolean) ? amounts.join("; ") : undefined;
+}
+
+/** `a`, `a or b`, `a, b or c`. */
+const orList = (items: string[]) => (items.length < 2 ? items.join("") : `${items.slice(0, -1).join(", ")} or ${items.at(-1)}`);
+
+function rejectedInput(r: RejectedInput): string {
+  const code = (v: string) => `\`${v}\``;
+  if (r.rule === "set") return code(r.field);
+  if (r.rule === "equals") return r.values!.map((v) => code(`${r.field}: ${JSON.stringify(v)}`)).join(", ");
+  const example = r.example === undefined ? "" : ` (e.g. ${code(JSON.stringify(r.example))})`;
+  return `${code(r.field)} other than ${orList(r.values!.map(code))}${example}`;
+}
+
+/**
+ * The indented sub-bullets under a leg row that carries `limits`. They are
+ * indented on purpose: `gen-router-pricing.ts` counts a page's serving providers
+ * as the column-0 `- **<Label>**` lines in this section, so a limit line must
+ * never start one.
+ */
+export function legLimitLines(model: string, leg: AltProvider, snapshot: RateSnapshot): string[] {
+  const l = leg.limits;
+  if (!l) return [];
+  const label = providerLabel(leg.provider);
+  const lines: string[] = [];
+  const accepts: string[] = [];
+  const formats = [...(l.resolutions ?? []), ...(l.audio ?? [])];
+  if (formats.length) accepts.push(formats.join(", "));
+  if (l.duration_seconds) {
+    const { min, max, default: dflt } = l.duration_seconds;
+    accepts.push(`${min === max ? min : `${min}–${max}`} seconds${dflt === undefined ? "" : ` (default ${dflt})`}`);
+  }
+  if (l.aspect_ratios) accepts.push(`aspect ratio ${orList(l.aspect_ratios)}`);
+  if (accepts.length) lines.push(`Limits: ${accepts.join("; ")}`);
+  const price = legPrice(model, label, snapshot);
+  if (price) lines.push(`Price: ${price}`);
+  if (l.rejected_inputs) {
+    const how = l.rejected_with ? `Rejected with \`${l.rejected_with}\`` : "Rejected";
+    lines.push(`${how}: ${l.rejected_inputs.map(rejectedInput).join(", ")}`);
+  }
+  if (l.fallback) {
+    const target = providerLabel(l.fallback.provider);
+    lines.push(
+      l.fallback.default
+        ? `Fallback: if ${label} fails, the request retries once on ${target} (the default provider).${l.fallback.opt_out ? ` Send \`${l.fallback.opt_out}\` to opt out.` : ""} Rejected inputs and BYOK requests don't fall back.`
+        : `Fallback: if ${label} fails, the request is not retried on ${target}.`
+    );
+  }
+  return lines.map((line) => `  - ${line}`);
+}
+
 const callExample = (model: string, provider?: string) =>
   `\`POST ${BASE_URL}${ROUTE}/${model}${provider ? `?model_provider=${provider}` : ""}\``;
 
@@ -903,7 +1122,7 @@ const callExample = (model: string, provider?: string) =>
  * `model_provider` is served by Router directly, and every row below it is the
  * same endpoint with that one query parameter added.
  */
-export function servingProvidersSection(natives: NativeLegs[]): string {
+export function servingProvidersSection(natives: NativeLegs[], rates: RateSnapshot = routerRates()): string {
   const withLegs = natives.filter((n) => n.legs.length > 0);
   if (!withLegs.length) return "";
   const rows = (n: NativeLegs) =>
@@ -911,9 +1130,10 @@ export function servingProvidersSection(natives: NativeLegs[]): string {
       `- **Comfy** (default): ${callExample(n.model)}`,
       // A leg with no `model_id` is reachable only through `model_provider`, so
       // it gets no "as <id>": naming its held-back catalog id would publish it.
-      ...n.legs.map(
-        (leg) => `- **${providerLabel(leg.provider)}**${leg.model_id ? `, as \`${leg.model_id}\`` : ""}: ${callExample(n.model, leg.provider)}`
-      ),
+      ...n.legs.flatMap((leg) => [
+        `- **${providerLabel(leg.provider)}**${leg.model_id ? `, as \`${leg.model_id}\`` : ""}: ${callExample(n.model, leg.provider)}`,
+        ...legLimitLines(n.model, leg, rates),
+      ]),
     ].join("\n");
   // A page that documents one model needs no header per model; a curated spec
   // covering several does, or the rows below it have no subject.
@@ -1335,7 +1555,7 @@ ${jump ? `${jump}\n\n` : ""}${sections}
 // ---------------------------------------------------------------------------
 
 /** A native model covered by an alternate provider, resolved to the page that documents it. */
-type Coverage = { provider: string; model: string; aliasId: string; page: string; title: string };
+type Coverage = { provider: string; model: string; aliasId: string; page: string; title: string; limited?: boolean };
 
 /**
  * Resolve the declared alt-provider relationship to Providers-index rows.
@@ -1359,7 +1579,7 @@ export function providerRelationRows(
   const rows: Coverage[] = [];
   const problems: string[] = [];
   const seen = new Map<string, string>();
-  const add = (provider: string, model: string, aliasId: string) => {
+  const add = (provider: string, model: string, aliasId: string, limited = false) => {
     const key = `${provider}\u0000${model}`;
     const known = seen.get(key);
     if (known !== undefined) {
@@ -1376,10 +1596,11 @@ export function providerRelationRows(
     const target = pageByModel.get(model);
     // A leg pointing at a model with no page of its own has nothing to link.
     if (!target) return;
-    rows.push({ provider, model, aliasId, page: target.page, title: target.title });
+    rows.push({ provider, model, aliasId, page: target.page, title: target.title, ...(limited ? { limited } : {}) });
   };
   // The native documents first: their lists win when the two sides disagree.
-  for (const [model, legs] of legsByModel) for (const leg of legs) add(leg.provider, model, leg.model_id ?? "");
+  // Only a native document carries `limits`, so only its rows can be marked narrower.
+  for (const [model, legs] of legsByModel) for (const leg of legs) add(leg.provider, model, leg.model_id ?? "", leg.limits !== undefined);
   // Then every alias document, including the ones that kept a page of their own
   // because the model they alias is not documented here yet.
   for (const a of aliasDocs) add(a.provider, a.aliasOf, a.model);
@@ -1409,7 +1630,10 @@ function providerMatrixTable(rows: Coverage[]): string {
   for (const row of rows) models.set(row.model, { page: row.page, title: row.title });
   const modelsInOrder = [...models.entries()].sort(([, a], [, b]) => a.title.localeCompare(b.title));
   const providers = providerCoverage(rows);
-  const cell = (providerRows: Coverage[], model: string) => providerRows.some((row) => row.model === model) ? "✓" : "-";
+  const cell = (providerRows: Coverage[], model: string) => {
+    const row = providerRows.find((r) => r.model === model);
+    return !row ? "-" : row.limited ? "✓*" : "✓";
+  };
   const header = ["Model / provider", "**Comfy (default)**", ...providers.map((provider) => `**${provider.label}**`)].join(" | ");
   const divider = ["---", "---", ...providers.map(() => "---")].join(" | ");
   const lines = [`| ${header} |`, `| ${divider} |`];
@@ -1443,7 +1667,7 @@ Every model uses \`POST /v2/models/{provider}/{model}\`. Comfy is the default pr
 ## Provider coverage
 
 ${providerMatrixTable(rows)}
-
+${rows.some((row) => row.limited) ? `\n\\* This provider serves the model with narrower limits than the default; see the model page.\n` : ""}
 \`strict_mode=false\` (the default) translates the native request and response for the selected provider. Fields that cannot be translated are listed in the \`X-Comfy-Router-Dropped-Params\` response header.
 `;
 }
diff --git a/.github/scripts/snippets/gen-router-pricing.ts b/.github/scripts/snippets/gen-router-pricing.ts
index f9a6bde175..2b40229d51 100644
--- a/.github/scripts/snippets/gen-router-pricing.ts
+++ b/.github/scripts/snippets/gen-router-pricing.ts
@@ -1226,4 +1226,4 @@ if (import.meta.main) {
   }
 }
 
-export { checkPricingCoverage, compactOptions, findUnpricedRoutes, loadUnpricedWaivers, groupImageTiers, groupResolutionTiers, groupRates, loadCatalog, loadMetronomeData, render, resolveKeyedRates, tokenPriceCell, validateCreditConversion };
+export { checkPricingCoverage, compactOptions, servingProviders, findUnpricedRoutes, loadUnpricedWaivers, groupImageTiers, groupResolutionTiers, groupRates, loadCatalog, loadMetronomeData, render, resolveKeyedRates, tokenPriceCell, validateCreditConversion };

From 3e8d0f5a7e8d6d065e10cb4dcb014a10fd235f14 Mon Sep 17 00:00:00 2001
From: Matt Miller <mattmiller@comfy.org>
Date: Sat, 24 Oct 2026 05:33:21 +0000
Subject: [PATCH 2/2] fix(router-docs): skip scheduled rate rows, match
 provider case-insensitively, load rates only for limited legs

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .github/scripts/snippets/README.md              |  4 +++-
 .github/scripts/snippets/gen-code-pages.test.ts |  7 +++++++
 .github/scripts/snippets/gen-code-pages.ts      | 13 ++++++++-----
 3 files changed, 18 insertions(+), 6 deletions(-)

diff --git a/.github/scripts/snippets/README.md b/.github/scripts/snippets/README.md
index 3c03e43927..6c76c0780b 100644
--- a/.github/scripts/snippets/README.md
+++ b/.github/scripts/snippets/README.md
@@ -101,7 +101,9 @@ The generator reads both and organises the docs by model rather than by route:
   accepts (resolution, audio, duration range, aspect ratios), its price, the
   inputs it rejects and with which error, and its fallback. The price comes
   from `router-pricing/metronome-rates.json`, keyed on the native model id and
-  the provider label, current rows only, with credits rounded to 2 decimals.
+  the provider label (matched without regard to case), current rows only
+  (started and not ended by the snapshot date), with credits rounded to 2
+  decimals.
   With no matching row the price line is omitted. The lines are indented
   because `gen-router-pricing.ts` counts a page's providers from its column-0
   `- **<Label>**` lines. A malformed `limits` is dropped as a whole and the
diff --git a/.github/scripts/snippets/gen-code-pages.test.ts b/.github/scripts/snippets/gen-code-pages.test.ts
index 684358800a..6d2fa2e244 100644
--- a/.github/scripts/snippets/gen-code-pages.test.ts
+++ b/.github/scripts/snippets/gen-code-pages.test.ts
@@ -560,6 +560,13 @@ describe("alt-provider leg limits", () => {
     // An un-entitled or ended row is not a current price.
     expect(legPrice(KLING, "Tencent", rates({ ...TENCENT_RATE, entitled: false }))).toBeUndefined();
     expect(legPrice(KLING, "Tencent", rates({ ...TENCENT_RATE, effective_until: "2026-10-21" }))).toBeUndefined();
+    // A scheduled row that starts after the snapshot is not current yet.
+    const scheduled = { ...TENCENT_RATE, price_usd: "0.5", credits: "105.5", effective_from: "2026-11-01" };
+    expect(legPrice(KLING, "Tencent", rates(TENCENT_RATE, scheduled))).toBe("20.26 credits ($0.096) per second");
+    expect(legPrice(KLING, "Tencent", rates(scheduled))).toBeUndefined();
+    // The provider label matches regardless of case.
+    expect(legPrice(KLING, "tencent", rates(TENCENT_RATE))).toBe("20.26 credits ($0.096) per second");
+    expect(legPrice(KLING, "Tencent", rates({ ...TENCENT_RATE, serving_provider: "TENCENT" }))).toBe("20.26 credits ($0.096) per second");
     expect(legPrice(KLING, "Tencent", rates({ ...TENCENT_RATE, kind: "usage", price_usd: undefined, credits: undefined }))).toBeUndefined();
     // The snapshot carries no 1080P row, and nothing renders one.
     const out = servingProvidersSection([{ model: KLING, legs: legs() }], RATES);
diff --git a/.github/scripts/snippets/gen-code-pages.ts b/.github/scripts/snippets/gen-code-pages.ts
index 28ba31913b..332bbf30e1 100644
--- a/.github/scripts/snippets/gen-code-pages.ts
+++ b/.github/scripts/snippets/gen-code-pages.ts
@@ -1036,8 +1036,9 @@ export function roundCredits(value: string): string | undefined {
 
 /**
  * The price of one leg, from its CURRENT rate rows: priced (not usage-based),
- * not explicitly un-entitled, not ended by the snapshot date, and at the latest
- * `effective_from` among those. No matching row means no price line: the page
+ * not explicitly un-entitled, started and not ended by the snapshot date, and at
+ * the latest `effective_from` among those. The provider label matches without
+ * regard to case, as `gen-router-pricing.ts` labels some providers differently. No matching row means no price line: the page
  * never guesses a price, and a tier the snapshot does not carry never appears.
  */
 export function legPrice(model: string, provider: string, snapshot: RateSnapshot): string | undefined {
@@ -1045,11 +1046,12 @@ export function legPrice(model: string, provider: string, snapshot: RateSnapshot
   const live = snapshot.rates.filter(
     (r) =>
       r.model_id === model &&
-      r.serving_provider === provider &&
+      r.serving_provider.toLowerCase() === provider.toLowerCase() &&
       r.kind !== "usage" &&
       r.entitled !== false &&
       r.price_usd !== undefined &&
       r.credits !== undefined &&
+      !(asOf && r.effective_from.slice(0, 10) > asOf) &&
       !(r.effective_until && asOf && r.effective_until.slice(0, 10) <= asOf)
   );
   if (!live.length) return undefined;
@@ -1122,7 +1124,7 @@ const callExample = (model: string, provider?: string) =>
  * `model_provider` is served by Router directly, and every row below it is the
  * same endpoint with that one query parameter added.
  */
-export function servingProvidersSection(natives: NativeLegs[], rates: RateSnapshot = routerRates()): string {
+export function servingProvidersSection(natives: NativeLegs[], rates?: RateSnapshot): string {
   const withLegs = natives.filter((n) => n.legs.length > 0);
   if (!withLegs.length) return "";
   const rows = (n: NativeLegs) =>
@@ -1132,7 +1134,8 @@ export function servingProvidersSection(natives: NativeLegs[], rates: RateSnapsh
       // it gets no "as <id>": naming its held-back catalog id would publish it.
       ...n.legs.flatMap((leg) => [
         `- **${providerLabel(leg.provider)}**${leg.model_id ? `, as \`${leg.model_id}\`` : ""}: ${callExample(n.model, leg.provider)}`,
-        ...legLimitLines(n.model, leg, rates),
+        // Only a leg with limits reads the rate snapshot, so a page without one never depends on it.
+        ...(leg.limits ? legLimitLines(n.model, leg, rates ?? routerRates()) : []),
       ]),
     ].join("\n");
   // A page that documents one model needs no header per model; a curated spec