auto-model-router 0.2.30 → 0.2.32

package/.github/workflows/pages.yml

@@ -0,0 +1,50 @@
+name: pages
+
+# Build the static site (tools/build-site.ts) and publish it to GitHub Pages.
+# Runs on pushes to main that touch the site, and on demand. The build is
+# dependency-free; benchmark numbers come from the committed
+# site/data/benchmarks.json, regenerated locally with `bun run site:data`
+# (CI has no ledger, so it never overwrites that data).
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'site/**'
+      - 'tools/build-site.ts'
+      - '.github/workflows/pages.yml'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# One live deploy at a time; don't cancel an in-flight publish.
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: latest
+      - name: Build site
+        run: bun run tools/build-site.ts
+      - uses: actions/configure-pages@v6
+      - uses: actions/upload-pages-artifact@v5
+        with:
+          path: site/dist
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v5

package/.omp-plugin/marketplace.json

@@ -7,14 +7,14 @@
   },
   "metadata": {
     "description": "auto-model-router: a local cost/complexity-aware model router for Oh My Pi, backed by OpenRouter",
-    "version": "0.2.21",
+    "version": "0.2.32",
     "pluginRoot": "."
   },
   "plugins": [
     {
       "name": "auto-model-router",
       "description": "Local cost/complexity-aware model router for Oh My Pi, backed by OpenRouter. Runs in-process, routes per turn by price and task complexity, with budget caps, mid-stream escalation, and cache-aware hysteresis.",
-      "version": "0.2.21",
+      "version": "0.2.32",
       "author": {
         "name": "drewappling",
         "email": "drewappling@gmail.com"

package/README.md

@@ -1,5 +1,7 @@
 # auto-model-router
 
+**[Website & benchmarks →](https://drewappling.github.io/auto-model-router/)**
+
 A local model router for [Oh My Pi](https://github.com/oh-my-pi). It presents
 itself as one keyless OpenAI-compatible provider, then picks a concrete
 OpenRouter model **per turn** based on measured price and estimated task
@@ -389,6 +391,26 @@ replaces it.
 The embedded router reports the key source via its in-process `GET /health`
 (`config` | `env` | `omp-auth-store` | `none`) — never the key itself.
 
+### Available models & guardrails
+
+The router never ships a hand-curated model list. With a key configured it
+fetches the **key-scoped catalog** (`GET /models/user`) — the exact set of
+models that key is *entitled to* under your account's active
+[OpenRouter guardrails](https://openrouter.ai/docs/guides/features/guardrails),
+provider preferences, and data policies — and routes only within it. Keyless, it
+falls back to the public `/models` for pricing and capability discovery, but
+dispatch still needs a key.
+
+Your OpenRouter guardrails — model and provider allowlists, budget limits,
+Zero-Data-Retention and privacy rules — are therefore the router's outer
+boundary: a model your key cannot reach is never a routing candidate. The
+catalog is refetched in the background every `catalogRefreshMs` (default 5 min),
+so tightening or relaxing a guardrail is picked up without a restart. If a
+guardrail narrows the eligible set below a tier's quality floor,
+`adaptiveTierFloors` (on by default) relaxes that tier to the best available
+models rather than leaving it empty — see [Adaptive tier floors](#adaptive-tier-floors)
+and [Tier rescue](#tier-rescue) below.
+
 ---
 
 ## How it runs
@@ -555,6 +577,9 @@ Each task (`coding`, `vision`, `documentation`, `data`, `chat`) is a
 | `minTrustSamples` | `12` | Attempts before trust is enforced. |
 | `trustScopedByHarness` | `false` | `true` = each harness reads only its own trust rows. |
 | `contextHeadroom` | `1.25` | Fraction of context kept free (a model must fit prompt × this). |
+| `latencyWeight` | `0` | How hard to penalise slow models in scoring (soft multiplier on effective cost). `0` disables it. |
+| `latencyMinSamples` | `20` | Streamed samples before latency is judged against a model. |
+| `maxExpectedWaitMs` | unset | Absolute expected-wait ceiling (ms): a hard drop for models *proven* slower (≥ `latencyMinSamples`), regardless of price. The soft penalty is multiplicative and capped, so it cannot demote a slow-but-cheap model — this can. New models keep their cold-start turns; relaxed with trust in tier rescue. Undefined ⇒ off. |
 
 ### `classifier` — complexity adjudication
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "auto-model-router",
-  "version": "0.2.30",
+  "version": "0.2.32",
   "private": false,
   "description": "Local cost/complexity-aware model router for Oh My Pi, backed by OpenRouter",
   "type": "module",
@@ -12,6 +12,8 @@
     "typecheck:src": "tsc --noEmit",
     "test": "bun test",
     "smoke": "bun run tools/smoke.ts",
+    "site": "bun run tools/build-site.ts",
+    "site:data": "bun run tools/export-benchmarks.ts",
     "version": "bun run tools/sync-marketplace-version.ts",
     "release": "npm version $1 && git push --follow-tags"
   },

package/site/assets/style.css

@@ -0,0 +1,108 @@
+/* auto-model-router site. Hand-authored, dependency-free. */
+:root {
+  --bg: #0d1117;
+  --bg-alt: #161b22;
+  --border: #30363d;
+  --fg: #e6edf3;
+  --fg-dim: #9198a1;
+  --accent: #4ea1ff;
+  --accent-dim: #1f6feb;
+  --good: #3fb950;
+  --code-bg: #161b22;
+  --max: 900px;
+}
+* { box-sizing: border-box; }
+html { scroll-behavior: smooth; }
+body {
+  margin: 0;
+  background: var(--bg);
+  color: var(--fg);
+  font: 16px/1.65 -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif;
+  -webkit-font-smoothing: antialiased;
+}
+a { color: var(--accent); text-decoration: none; }
+a:hover { text-decoration: underline; }
+code, pre, kbd {
+  font-family: ui-monospace, SFMono-Regular, "SF Mono", Menlo, Consolas, monospace;
+  font-size: 0.9em;
+}
+code { background: var(--code-bg); padding: 0.15em 0.4em; border-radius: 4px; border: 1px solid var(--border); }
+pre {
+  background: var(--code-bg);
+  border: 1px solid var(--border);
+  border-radius: 8px;
+  padding: 1rem 1.15rem;
+  overflow-x: auto;
+  line-height: 1.5;
+}
+pre code { background: none; border: none; padding: 0; }
+
+header.nav {
+  position: sticky; top: 0; z-index: 10;
+  background: rgba(13,17,23,0.85);
+  backdrop-filter: blur(8px);
+  border-bottom: 1px solid var(--border);
+}
+header.nav .inner {
+  max-width: var(--max); margin: 0 auto; padding: 0.75rem 1.25rem;
+  display: flex; align-items: center; gap: 1.5rem;
+}
+header.nav .brand { font-weight: 700; color: var(--fg); letter-spacing: -0.02em; }
+header.nav nav { display: flex; gap: 1.15rem; flex-wrap: wrap; }
+header.nav nav a { color: var(--fg-dim); font-size: 0.94rem; }
+header.nav nav a.active, header.nav nav a:hover { color: var(--fg); text-decoration: none; }
+header.nav .spacer { flex: 1; }
+
+main { max-width: var(--max); margin: 0 auto; padding: 2.5rem 1.25rem 4rem; }
+
+.hero { text-align: center; padding: 3rem 0 2rem; }
+.hero h1 { font-size: 2.6rem; margin: 0 0 0.5rem; letter-spacing: -0.03em; }
+.hero p.tagline { font-size: 1.25rem; color: var(--fg-dim); margin: 0 auto 1.75rem; max-width: 40rem; }
+.hero .cta { display: inline-flex; gap: 0.75rem; flex-wrap: wrap; justify-content: center; }
+.btn {
+  display: inline-block; padding: 0.6rem 1.25rem; border-radius: 8px;
+  font-weight: 600; border: 1px solid var(--border);
+}
+.btn.primary { background: var(--accent-dim); border-color: var(--accent-dim); color: #fff; }
+.btn.primary:hover { background: var(--accent); text-decoration: none; }
+.btn.ghost { color: var(--fg); }
+.btn.ghost:hover { border-color: var(--fg-dim); text-decoration: none; }
+
+.stats { display: grid; grid-template-columns: repeat(auto-fit, minmax(160px, 1fr)); gap: 1rem; margin: 2.5rem 0; }
+.stat { background: var(--bg-alt); border: 1px solid var(--border); border-radius: 10px; padding: 1.25rem; text-align: center; }
+.stat .n { font-size: 2rem; font-weight: 700; color: var(--good); letter-spacing: -0.02em; }
+.stat .l { color: var(--fg-dim); font-size: 0.9rem; margin-top: 0.25rem; }
+
+h2 { font-size: 1.6rem; margin: 2.75rem 0 1rem; letter-spacing: -0.02em; padding-top: 0.5rem; }
+h3 { font-size: 1.2rem; margin: 2rem 0 0.75rem; }
+h2:first-child { margin-top: 0; }
+p, ul, ol { margin: 0 0 1rem; }
+ul, ol { padding-left: 1.4rem; }
+li { margin: 0.3rem 0; }
+
+table { width: 100%; border-collapse: collapse; margin: 1rem 0 1.5rem; font-size: 0.95rem; }
+th, td { text-align: left; padding: 0.6rem 0.8rem; border-bottom: 1px solid var(--border); }
+th { color: var(--fg-dim); font-weight: 600; }
+td.win { color: var(--good); font-weight: 600; }
+tbody tr:hover { background: var(--bg-alt); }
+table caption { text-align: left; color: var(--fg-dim); font-size: 0.9rem; margin-bottom: 0.6rem; caption-side: bottom; }
+
+.card { background: var(--bg-alt); border: 1px solid var(--border); border-radius: 10px; padding: 1.25rem 1.4rem; margin: 1rem 0; }
+.card h3 { margin-top: 0; }
+.note { color: var(--fg-dim); font-size: 0.95rem; }
+.pill { display: inline-block; background: var(--bg-alt); border: 1px solid var(--border); border-radius: 999px; padding: 0.15rem 0.7rem; font-size: 0.8rem; color: var(--fg-dim); }
+
+dl.knobs { margin: 0; }
+dl.knobs dt { font-family: ui-monospace, monospace; color: var(--accent); margin-top: 1.1rem; font-size: 0.95rem; }
+dl.knobs dd { margin: 0.25rem 0 0; color: var(--fg); }
+dl.knobs dd .default { color: var(--fg-dim); font-size: 0.88rem; }
+
+footer { border-top: 1px solid var(--border); color: var(--fg-dim); font-size: 0.9rem; }
+footer .inner { max-width: var(--max); margin: 0 auto; padding: 2rem 1.25rem; display: flex; gap: 1rem; flex-wrap: wrap; }
+footer .spacer { flex: 1; }
+
+@media (max-width: 600px) {
+  .hero h1 { font-size: 2rem; }
+  header.nav .inner { gap: 1rem; }
+  main { padding-top: 1.5rem; }
+}

package/site/data/benchmarks.json

@@ -0,0 +1,139 @@
+{
+  "generatedAt": "2026-08-29",
+  "baseline": "claude-opus-5",
+  "headline": {
+    "coreCostMultiple": "26.5×",
+    "coreCostMultipleLabel": "cheaper at identical correctness",
+    "realWorldMultiple": "≈15×",
+    "realWorldSavedPct": "~93%"
+  },
+  "suites": {
+    "core": {
+      "title": "Core suite — 10 coding tasks × 3 trials",
+      "note": "Both engines solved everything, so this measures cost at equal correctness. 26.5× cheaper — in fewer turns, fewer tool calls, and 19 minutes less wall clock. The one regression is time to first token: a routed turn pays for classification and dispatch before anything streams.",
+      "columns": [
+        "",
+        "auto-model-router",
+        "Claude Opus 5"
+      ],
+      "rows": [
+        [
+          "Tasks solved",
+          "30 / 30",
+          "30 / 30"
+        ],
+        [
+          "Total cost",
+          "$0.63",
+          "$16.61"
+        ],
+        [
+          "Cost per solved task",
+          "$0.0209",
+          "$0.5538"
+        ],
+        [
+          "Turns to finish",
+          "278",
+          "303"
+        ],
+        [
+          "Tool calls",
+          "265",
+          "337"
+        ],
+        [
+          "Wall clock",
+          "2 057 s",
+          "3 185 s"
+        ],
+        [
+          "Median time to first token",
+          "5 776 ms",
+          "1 490 ms"
+        ]
+      ],
+      "winnerCol": 1
+    },
+    "ladder": {
+      "title": "Difficulty ladder — 7 rungs, run twice",
+      "note": "A second suite of deliberately escalating difficulty, ending in npm semver range semantics and a minimal diff with a specified tie-break. At the top of the ladder the engines separate.",
+      "columns": [
+        "",
+        "auto-model-router",
+        "Claude Opus 5"
+      ],
+      "rows": [
+        [
+          "Run 1",
+          "5 / 7 · $0.30",
+          "5 / 7 · $6.25"
+        ],
+        [
+          "Run 2",
+          "5 / 7 · $0.46",
+          "6 / 7 · $6.60"
+        ]
+      ],
+      "winnerCol": 1
+    },
+    "routed": {
+      "title": "What it routed to",
+      "note": "Across 464 routed turns in all five runs. Tier escalation converts to a costlier model roughly one-for-one; the escalation target is chosen live from trust and latency history, so it differs between runs on the same catalog.",
+      "columns": [
+        "Model",
+        "Turns",
+        "Input price",
+        "Role"
+      ],
+      "rows": [
+        [
+          "z-ai/glm-5.3-flash",
+          "389 (84%)",
+          "$0.07 / MTok",
+          "default"
+        ],
+        [
+          "google/gemini-3.7-flash",
+          "56 (12%)",
+          "$0.75 / MTok",
+          "escalation target"
+        ],
+        [
+          "x-ai/grok-4.6",
+          "18 (4%)",
+          "$2.00 / MTok",
+          "escalation target"
+        ]
+      ]
+    },
+    "realWorld": {
+      "title": "Real-world — a week on the live ledger",
+      "note": "6 918 billed turns across 299 conversations, 7 days, 410:1 input-to-output, 68% cache hit — the identical token stream repriced against a single Opus 5 model with its own cache namespace. ≈15× cheaper, ~93% saved: a four-figure monthly bill becomes a three-figure one.",
+      "columns": [
+        "",
+        "auto-model-router",
+        "Claude Opus 5 (single-model)"
+      ],
+      "rows": [
+        [
+          "Spend over the week",
+          "$61.69",
+          "$921.20"
+        ],
+        [
+          "Per turn",
+          "$0.0089",
+          "$0.133"
+        ],
+        [
+          "Extrapolated / month",
+          "$263",
+          "$3 932"
+        ]
+      ],
+      "winnerCol": 1
+    }
+  },
+  "ledgerSnapshot": null
+}

package/src/config/defaults.ts

@@ -20,6 +20,9 @@ export const DEFAULT_CONFIG: RouterConfig = {
 		baseUrl: "https://openrouter.ai/api/v1",
 		// May stay empty: catalog and `config` work keyless; only dispatch fails.
 		apiKey: "",
+		// App attribution for OpenRouter's Activity/Apps ranking. `title` is the
+		// display name; `referer` is the identity OpenRouter groups requests by.
+		referer: "https://github.com/drewappling/auto-model-router",
 		title: "auto-model-router",
 		// Agent turns are long; a frontier model with tools can stream for minutes.
 		timeoutMs: 600_000,

package/src/config/schema.ts

@@ -73,6 +73,7 @@ const filters = z.strictObject({
 	latencyReferenceMs: z.number().positive().optional(),
 	latencyReferenceTokensPerSec: z.number().positive().optional(),
 	latencyMinSamples: z.number().int().nonnegative().optional(),
+	maxExpectedWaitMs: z.number().positive().optional(),
 });
 
 const classifier = z.strictObject({

package/src/config/types.ts

@@ -206,6 +206,19 @@ export interface FilterConfig {
 	latencyReferenceTokensPerSec: number;
 	/** Streamed samples required before latency is scored against a model. */
 	latencyMinSamples: number;
+	/**
+	 * Absolute expected-wait ceiling (ms). A hard drop, mirroring the price
+	 * ceiling: any model whose expected total wait (TTFT + streaming the expected
+	 * completion at its measured throughput) exceeds this is rejected outright,
+	 * regardless of tier or price. This is the gate the latency *penalty* cannot
+	 * be — the penalty is multiplicative on cost and capped, so on an ultra-cheap
+	 * model even the capped multiple leaves it cheapest; a slow-but-cheap model is
+	 * never demoted by scoring alone. Only models with at least `latencyMinSamples`
+	 * observations are dropped, so a new model still gets its cold-start turns.
+	 * Relaxed alongside trust in tier rescue so a narrowed catalog never 500s.
+	 * Undefined ⇒ off (the default).
+	 */
+	maxExpectedWaitMs?: number;
 }
 
 export interface ClassifierConfig {

package/src/router/candidates.ts

@@ -71,6 +71,12 @@ const UNMEASURED_TRUST = 0.9;
 /** Excess-ratio cap so one very slow model cannot be penalised into oblivion. */
 const LATENCY_EXCESS_CAP = 3;
 
+/** Expected total wait: time to first token plus streaming the expected completion at measured throughput. */
+function expectedWaitMs(latency: ModelLatency, expectedCompletionTokens: number): number {
+	const streamMs = latency.tokensPerSec > 0 ? (expectedCompletionTokens / latency.tokensPerSec) * 1000 : 0;
+	return latency.ttftMs + streamMs;
+}
+
 /**
  * Latency penalty as a multiplier on effective cost (>= 1; 1 = no penalty).
  *
@@ -81,13 +87,15 @@ const LATENCY_EXCESS_CAP = 3;
  * model of equal quality and price outranks a sluggish one. Capturing throughput,
  * not just TTFT, is what catches a model that starts fast but streams slowly
  * (deepseek-v4-flash: ~2s TTFT yet ~20 tok/s → ~38s total). Inert when the weight
- * is 0 or the model has too few streamed samples to judge; when throughput is
- * unmeasured it degrades to a TTFT-only comparison against the reference wait.
+ * is 0 or the model has too few streamed samples to judge.
+ *
+ * The penalty CANNOT discipline a slow-but-cheap model: it is multiplicative on a
+ * tiny cost and capped at LATENCY_EXCESS_CAP, so the model stays cheapest. That is
+ * `filters.maxExpectedWaitMs`'s job — a hard drop, applied in buildCandidates.
  */
 function latencyMultiplier(latency: ModelLatency | null, filters: FilterConfig, expectedCompletionTokens: number): number {
 	if (latency === null || filters.latencyWeight <= 0 || latency.samples < filters.latencyMinSamples) return 1;
-	const streamMs = latency.tokensPerSec > 0 ? (expectedCompletionTokens / latency.tokensPerSec) * 1000 : 0;
-	const waitMs = latency.ttftMs + streamMs;
+	const waitMs = expectedWaitMs(latency, expectedCompletionTokens);
 	const refWaitMs = filters.latencyReferenceMs + (expectedCompletionTokens / filters.latencyReferenceTokensPerSec) * 1000;
 	const excess = refWaitMs > 0 ? Math.max(0, (waitMs - refWaitMs) / refWaitMs) : 0;
 	return 1 + filters.latencyWeight * Math.min(excess, LATENCY_EXCESS_CAP);
@@ -233,6 +241,33 @@ export function buildCandidates(args: BuildCandidatesArgs): { candidates: Candid
 			continue;
 		}
 
+		// Fetch latency ONCE for both the ceiling gate here and the scoring
+		// multiplier below. Absolute latency ceiling: a hard drop, mirroring the
+		// price ceiling, for models PROVEN slow (>= latencyMinSamples). The penalty
+		// alone cannot demote a slow-but-cheap model (see latencyMultiplier); this
+		// gate can. Only measured models are dropped, so a new model still gets its
+		// cold-start turns to accumulate samples. Relaxed with trust in rescue.
+		const needLatency = filters.latencyWeight > 0 || filters.maxExpectedWaitMs !== undefined;
+		const latency = needLatency
+			? (ledger?.latency(slug, filters.trustScopedByHarness ? req.harnessId : undefined) ?? null)
+			: null;
+		if (
+			!relaxTrust &&
+			filters.maxExpectedWaitMs !== undefined &&
+			latency !== null &&
+			latency.samples >= filters.latencyMinSamples
+		) {
+			const waitMs = expectedWaitMs(latency, expectedCompletionTokens);
+			if (waitMs > filters.maxExpectedWaitMs) {
+				rejected.push({
+					slug,
+					reason: "over_latency_ceiling",
+					detail: `expected wait ${Math.round(waitMs)}ms > ceiling ${filters.maxExpectedWaitMs}ms (ttft ${Math.round(latency.ttftMs)}ms, ${latency.tokensPerSec.toFixed(0)} tok/s over ${latency.samples} samples)`,
+				});
+				continue;
+			}
+		}
+
 		// Every candidate is priced COLD, deliberately, and this has been measured
 		// rather than assumed. Two reasons:
 		//  1. `coldUsd` feeds the budget guard in select.ts, and a budget must
@@ -259,10 +294,6 @@ export function buildCandidates(args: BuildCandidatesArgs): { candidates: Candid
 		// 20% of the time really costs ~25% more in retries. Latency does the same
 		// for slowness (TTFT over the reference). qualityExponent 0 makes this
 		// "cheapest above the floor"; the floor does the quality work.
-		const latency =
-			filters.latencyWeight > 0
-				? (ledger?.latency(slug, filters.trustScopedByHarness ? req.harnessId : undefined) ?? null)
-				: null;
 		const latencyMult = latencyMultiplier(latency, filters, expectedCompletionTokens);
 		const effectiveUsd = (fc.expectedUsd / Math.max(trustScore, 0.5)) * latencyMult;
 		// Score is assigned in a SECOND PASS below: both qualityNormalization and

package/src/router/types.ts

@@ -127,6 +127,7 @@ export type RejectionReason =
 	| "no_image_support"
 	| "below_quality_floor"
 	| "over_price_ceiling"
+	| "over_latency_ceiling"
 	| "over_budget"
 	| "denylisted"
 	| "not_allowlisted"

package/test/select.test.ts

@@ -594,6 +594,31 @@ describe("latency scoring", () => {
 		const d = run({ tier: "simple", cfg: withWeight(2), ledger });
 		expect(d.slug).not.toBe(slow);
 	});
+
+	const withCeiling = (maxExpectedWaitMs: number, latencyWeight = 0): RouterConfig => ({
+		...BASE,
+		filters: { ...BASE.filters, latencyWeight, latencyReferenceMs: 5000, latencyMinSamples: 20, maxExpectedWaitMs },
+	});
+
+	test("ceiling hard-drops a proven-slow model the penalty cannot, even at weight 0", () => {
+		const slow = run({ tier: "simple" }).slug;
+		const ledger = ledgerWithLatency({ [slow]: { ttftMs: 60_000, samples: 50 } });
+		// latencyWeight 0 → the multiplier is inert; only the hard ceiling can act.
+		const d = run({ tier: "simple", cfg: withCeiling(20_000), ledger });
+		expect(d.slug).not.toBe(slow);
+	});
+
+	test("ceiling spares an under-sampled slow model (cold-start grace)", () => {
+		const slow = run({ tier: "simple" }).slug;
+		const ledger = ledgerWithLatency({ [slow]: { ttftMs: 60_000, samples: 5 } });
+		expect(run({ tier: "simple", cfg: withCeiling(20_000), ledger }).slug).toBe(slow);
+	});
+
+	test("ceiling unset ⇒ no latency gate (proven-slow model still wins on price)", () => {
+		const slow = run({ tier: "simple" }).slug;
+		const ledger = ledgerWithLatency({ [slow]: { ttftMs: 60_000, samples: 50 } });
+		expect(run({ tier: "simple", cfg: withWeight(0), ledger }).slug).toBe(slow);
+	});
 });
 
 describe("context compaction", () => {

package/tools/build-site.ts

@@ -0,0 +1,385 @@
+#!/usr/bin/env bun
+/**
+ * Static site generator for the auto-model-router GitHub Pages site.
+ *
+ * Dependency-free by design: content is authored as HTML in this file and the
+ * only dynamic input is `site/data/benchmarks.json`, which the head-to-head
+ * suite tables render from and which `tools/export-benchmarks.ts` regenerates
+ * from a live ledger at release time. Emits `site/dist/`, ready for
+ * `actions/upload-pages-artifact`.
+ *
+ * Run by hand: `bun tools/build-site.ts` (then open site/dist/index.html).
+ */
+
+import { cpSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+
+const ROOT = resolve(import.meta.dir, "..");
+const SITE = join(ROOT, "site");
+const DIST = join(SITE, "dist");
+const REPO = "https://github.com/drewappling/auto-model-router";
+
+// ---------------------------------------------------------------------------
+// Benchmark data
+// ---------------------------------------------------------------------------
+
+interface SuiteTable {
+	title: string;
+	note: string;
+	columns: string[];
+	rows: string[][];
+	winnerCol?: number;
+}
+interface LedgerSnapshot {
+	generatedAt: string;
+	windowDays: number | null;
+	requests: number;
+	spendAllTimeUsd: number;
+	spend7dUsd: number;
+	perTurnUsd: number;
+	escalationRatePct: number;
+	perModel: { slug: string; requests: number; sharePct: number }[];
+}
+interface Benchmarks {
+	generatedAt: string;
+	baseline: string;
+	headline: {
+		coreCostMultiple: string;
+		coreCostMultipleLabel: string;
+		realWorldMultiple: string;
+		realWorldSavedPct: string;
+	};
+	suites: { core: SuiteTable; ladder: SuiteTable; routed: SuiteTable; realWorld: SuiteTable };
+	ledgerSnapshot: LedgerSnapshot | null;
+}
+
+const bench = JSON.parse(readFileSync(join(SITE, "data", "benchmarks.json"), "utf8")) as Benchmarks;
+
+// ---------------------------------------------------------------------------
+// HTML helpers
+// ---------------------------------------------------------------------------
+
+function esc(s: string): string {
+	return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+}
+
+function suiteTable(t: SuiteTable): string {
+	const head = t.columns.map((c) => `<th>${esc(c)}</th>`).join("");
+	const body = t.rows
+		.map((row) => {
+			const cells = row
+				.map((cell, i) => {
+					const win = t.winnerCol !== undefined && i === t.winnerCol && i > 0;
+					return `<td${win ? ' class="win"' : ""}>${esc(cell)}</td>`;
+				})
+				.join("");
+			return `<tr>${cells}</tr>`;
+		})
+		.join("\n");
+	return `<h3>${esc(t.title)}</h3>
+<table>
+<thead><tr>${head}</tr></thead>
+<tbody>
+${body}
+</tbody>
+</table>
+<p class="note">${esc(t.note)}</p>`;
+}
+
+function ledgerPanel(s: LedgerSnapshot | null): string {
+	if (s === null) {
+		return `<p class="note">No live ledger snapshot is bundled with this build. Maintainers regenerate one with <code>bun tools/export-benchmarks.ts</code> against a real install before a release.</p>`;
+	}
+	const window = s.windowDays === null ? "all time" : `last ${s.windowDays} days`;
+	const rows = s.perModel
+		.map((m) => `<tr><td><code>${esc(m.slug)}</code></td><td>${m.requests}</td><td>${m.sharePct.toFixed(1)}%</td></tr>`)
+		.join("\n");
+	return `<p class="note">Generated ${esc(s.generatedAt)} from a real install's ledger (${window}).</p>
+<div class="stats">
+  <div class="stat"><div class="n">${s.requests.toLocaleString()}</div><div class="l">billed turns</div></div>
+  <div class="stat"><div class="n">$${s.perTurnUsd.toFixed(4)}</div><div class="l">per turn</div></div>
+  <div class="stat"><div class="n">$${s.spend7dUsd.toFixed(2)}</div><div class="l">spend, 7 days</div></div>
+  <div class="stat"><div class="n">${s.escalationRatePct.toFixed(1)}%</div><div class="l">escalation rate</div></div>
+</div>
+<table>
+<thead><tr><th>Model</th><th>Requests</th><th>Spend share</th></tr></thead>
+<tbody>
+${rows}
+</tbody>
+</table>`;
+}
+
+// ---------------------------------------------------------------------------
+// Layout
+// ---------------------------------------------------------------------------
+
+interface Page {
+	slug: string; // "" for index
+	title: string;
+	nav: string;
+	body: string;
+}
+
+const NAV: { href: string; label: string; key: string }[] = [
+	{ href: "index.html", label: "Overview", key: "home" },
+	{ href: "install.html", label: "Install", key: "install" },
+	{ href: "config.html", label: "Configuration", key: "config" },
+	{ href: "benchmarks.html", label: "Benchmarks", key: "benchmarks" },
+];
+
+function layout(p: Page): string {
+	const nav = NAV.map(
+		(n) => `<a href="${n.href}"${n.key === p.nav ? ' class="active"' : ""}>${esc(n.label)}</a>`,
+	).join("\n        ");
+	return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>${esc(p.title)}</title>
+<meta name="description" content="A local cost/complexity-aware model router for Oh My Pi, backed by OpenRouter. Well over an order of magnitude cheaper at equal correctness.">
+<link rel="stylesheet" href="assets/style.css">
+</head>
+<body>
+<header class="nav">
+  <div class="inner">
+    <a class="brand" href="index.html">auto-model-router</a>
+    <div class="spacer"></div>
+    <nav>
+        ${nav}
+        <a href="${REPO}">GitHub</a>
+    </nav>
+  </div>
+</header>
+<main>
+${p.body}
+</main>
+<footer>
+  <div class="inner">
+    <span>auto-model-router \u2014 MIT licensed</span>
+    <div class="spacer"></div>
+    <a href="${REPO}">GitHub</a>
+    <a href="https://www.npmjs.com/package/auto-model-router">npm</a>
+    <a href="${REPO}/issues">Issues</a>
+  </div>
+</footer>
+</body>
+</html>
+`;
+}
+
+// ---------------------------------------------------------------------------
+// Pages
+// ---------------------------------------------------------------------------
+
+const indexBody = `<section class="hero">
+  <h1>The right model for every turn</h1>
+  <p class="tagline">A local, keyless model router for <a href="https://github.com/oh-my-pi">Oh My Pi</a>. One OpenAI-compatible provider that picks a concrete OpenRouter model <strong>per turn</strong> from measured price and estimated task complexity \u2014 including mid-conversation.</p>
+  <div class="cta">
+    <a class="btn primary" href="install.html">Get started</a>
+    <a class="btn ghost" href="benchmarks.html">See the benchmarks</a>
+  </div>
+</section>
+
+<div class="stats">
+  <div class="stat"><div class="n">${esc(bench.headline.coreCostMultiple)}</div><div class="l">${esc(bench.headline.coreCostMultipleLabel)}</div></div>
+  <div class="stat"><div class="n">${esc(bench.headline.realWorldMultiple)}</div><div class="l">cheaper on a real week of traffic</div></div>
+  <div class="stat"><div class="n">${esc(bench.headline.realWorldSavedPct)}</div><div class="l">of spend saved</div></div>
+</div>
+
+<h2>Why this exists when OpenRouter already ships routers</h2>
+<p>OpenRouter has <code>openrouter/auto</code> and <code>openrouter/pareto-code</code>. Both are opaque, server-side, and \u2014 per Pareto's own docs \u2014 <em>"you can't directly cap cost or latency per request."</em> This router does the things a prompt classifier structurally cannot:</p>
+<div class="card">
+  <h3>Agent-loop awareness</h3>
+  <p class="note">OpenRouter sees a prompt. We see omp's tool array, tool-result depth, and whether the previous tool call failed. Most agent turns are mechanical post-tool-result continuations \u2014 the largest cost lever in agent traffic, and invisible upstream.</p>
+</div>
+<div class="card">
+  <h3>Budget enforcement</h3>
+  <p class="note">Per-turn, per-conversation, and rolling-24h caps, checked against a <strong>cold-cache forecast</strong> before dispatch, with forced downgrade at the ceiling.</p>
+</div>
+<div class="card">
+  <h3>Mid-stream escalation</h3>
+  <p class="note">Hold the first N tokens; on a malformed tool call, refusal, empty completion, or repeated tool call, abort and re-dispatch upward. omp never observes the failure.</p>
+</div>
+<div class="card">
+  <h3>Cache-aware hysteresis</h3>
+  <p class="note">Switching models forfeits the warm prompt cache. The decision is arithmetic, not vibes: expected saving must beat the forfeited cache-read discount by a configured margin.</p>
+</div>
+<div class="card">
+  <h3>Closed-loop trust</h3>
+  <p class="note">Per-model escalation and error rates from <em>your</em> traffic demote cheap-but-flaky models automatically.</p>
+</div>
+<div class="card">
+  <h3>Explainability</h3>
+  <p class="note">Every decision \u2014 candidates, rejections, forecasts, reasons \u2014 is persisted and replayable via <code>auto-model-router explain</code>.</p>
+</div>
+
+<h2>How it runs</h2>
+<p>auto-model-router runs <strong>embedded inside the omp process</strong> as an extension \u2014 no separate server, no orphaned process. It binds a free OS-assigned port and lives and dies with the omp session. For non-omp harnesses (Hermes, Claude, any OpenAI-compatible client), run it standalone with <code>auto-model-router serve --port &lt;n&gt;</code>.</p>
+<p><a href="install.html">Install it &rarr;</a></p>`;
+
+const installBody = `<h2>Installing</h2>
+<p>No separate Bun install is needed for the embedded path. The standalone <code>serve</code> binary bundles Bun.</p>
+
+<h3>Via npm (recommended)</h3>
+<pre><code>npm install -g auto-model-router</code></pre>
+<p>Then add the shipped extensions to omp's <code>~/.omp/agent/config.yml</code> (<code>$PI_CODING_AGENT_DIR/config.yml</code> when that env var relocates the agent dir):</p>
+<pre><code># ~/.omp/agent/config.yml
+extensions:
+  - auto-model-router/omp-extension/router-embed.ts
+  - auto-model-router/omp-extension/router-toast.ts      # optional: chosen-model toasts
+  - auto-model-router/omp-extension/router-configure.ts  # optional: /router command</code></pre>
+
+<h3>From the repo (cross-platform installer)</h3>
+<pre><code>bun tools/install.ts</code></pre>
+<p>It wires the extensions into omp's <code>~/.omp/agent/config.yml</code>, backing up the previous file first. It is idempotent. Use <code>--no-toast --no-configure</code> for only the required embed extension.</p>
+
+<h3>From the marketplace</h3>
+<p>This repo doubles as its own marketplace. Add it as a source, then install:</p>
+<pre><code>omp plugin marketplace add drewappling/auto-model-router
+omp plugin install auto-model-router@auto-model-router</code></pre>
+<p>Or in the TUI: <code>/marketplace add drewappling/auto-model-router</code> then <code>/marketplace install auto-model-router@auto-model-router</code>.</p>
+
+<h3>As a Pi package</h3>
+<pre><code>pi install npm:auto-model-router
+# or from git:
+pi install git:github.com/drewappling/auto-model-router</code></pre>
+
+<h2>Setup \u2014 the OpenRouter key</h2>
+<p>There is exactly one OpenRouter key on the machine, owned by omp. Once you have run <code>/login openrouter</code> inside omp, auto-model-router borrows that key with no config and no second copy to rotate or leak. Alternatively set <code>OPENROUTER_API_KEY</code> in the environment, or <code>openrouter.apiKey</code> in <code>config.yml</code>.</p>
+<p class="note">The catalog and the <code>config</code> command work keyless; only dispatch needs a key.</p>
+
+<h2>Available models &amp; guardrails</h2>
+<p>The router never ships a hand-curated model list. When an OpenRouter key is configured it fetches the key-scoped catalog (<code>GET /models/user</code>) \u2014 the exact set of models that key is <strong>entitled to</strong> under your account's active <a href="https://openrouter.ai/docs/guides/features/guardrails">guardrails</a>, provider preferences, and data policies \u2014 and routes only within it. Keyless, it falls back to the public catalog for pricing and capability discovery, but dispatch still needs a key.</p>
+<p>This means your OpenRouter <a href="https://openrouter.ai/docs/guides/features/guardrails">guardrails</a> \u2014 model and provider allowlists, budget limits, Zero-Data-Retention and privacy rules \u2014 are the router's outer boundary: a model your key cannot reach is never a routing candidate. The catalog is refetched in the background every few minutes, so tightening or relaxing a guardrail is picked up without a restart.</p>
+<div class="card">
+  <p class="note"><strong>Narrow guardrails still route.</strong> If a guardrail shrinks the eligible set so far that a complexity tier's quality floor admits nothing, <code>adaptiveTierFloors</code> (on by default) relaxes that tier's economic envelope to the best available models rather than leaving it empty \u2014 so the router keeps working on a tightly restricted key instead of stalling on the cheapest tier.</p>
+</div>
+
+<h2>Activating it</h2>
+<p>After installing, <strong>restart the omp session</strong> (extensions load at session start), then run <code>/model</code> and pick <code>auto-model-router/auto</code>.</p>
+<div class="card">
+  <p class="note"><strong>Note on updates.</strong> The embedded router is long-lived per omp session and reads its config and code at boot. Config changes to hot-reloadable knobs apply live; changes to the listening socket, the OpenRouter client, or the agentdox bridge require a session restart.</p>
+</div>
+
+<h2>Standalone (Hermes / any OpenAI-compatible client)</h2>
+<pre><code>auto-model-router serve --port 8788</code></pre>
+<p>Register it as a plain OpenAI-compatible provider pointing at <code>http://127.0.0.1:8788/v1</code>. No API key is enforced unless you set <code>server.apiKey</code>.</p>
+
+<h2>Configuring behaviour</h2>
+<p>Every routing lever lives in <code>$AUTO_MODEL_ROUTER_HOME/config.yml</code>. See the <a href="config.html">configuration reference</a> for the knobs and their shipped defaults.</p>`;
+
+const configBody = `<h2>Configuration reference</h2>
+<p>auto-model-router is configured through <code>$AUTO_MODEL_ROUTER_HOME/config.yml</code> (defaults to <code>~/.auto-model-router/config.yml</code>). The file is a deep-partial overlay on the built-in defaults: set only the keys you want to change. Most per-turn knobs <strong>hot-reload</strong> \u2014 edits apply on the next turn with no restart. The listening socket (<code>server.*</code>), the OpenRouter client (<code>openrouter.*</code>), and the agentdox bridge (<code>context.*</code>) are captured at boot and need a session restart.</p>
+<p class="pill">All values below are the shipped defaults.</p>
+
+<h3>openrouter \u2014 upstream &amp; attribution</h3>
+<dl class="knobs">
+  <dt>openrouter.apiKey</dt><dd>OpenRouter key. The router routes only within the models this key is entitled to under your <a href="https://openrouter.ai/docs/guides/features/guardrails">OpenRouter guardrails</a> (fetched via <code>/models/user</code>). <span class="default">Default: empty \u2014 borrowed from omp's credential store, or <code>OPENROUTER_API_KEY</code>.</span></dd>
+  <dt>openrouter.title / openrouter.referer</dt><dd>App attribution for OpenRouter's Activity/Apps ranking. <code>title</code> is the display name; <code>referer</code> is the identity requests are grouped by. <span class="default">Default: <code>auto-model-router</code> and the project URL.</span></dd>
+  <dt>openrouter.timeoutMs</dt><dd>Per-request timeout. Agent turns are long. <span class="default">Default: 600000 (10 min).</span></dd>
+</dl>
+
+<h3>tiers \u2014 the complexity ladder</h3>
+<p>Each complexity tier sets a quality floor and a price ceiling. A model priced above a tier's ceiling is excluded before ranking; within the tier, <code>score = (quality/100) ^ qualityExponent / effectiveUsd</code> picks the winner. <code>hard</code> has no ceiling \u2014 quality is the point of the top tier.</p>
+<dl class="knobs">
+  <dt>tiers.trivial</dt><dd>minQuality 0, maxInputPerMtok $0.30, qualityExponent 0 <span class="default">(cheapest above the floor).</span></dd>
+  <dt>tiers.simple</dt><dd>minQuality 40, maxInputPerMtok $1.50, qualityExponent 0.</dd>
+  <dt>tiers.moderate</dt><dd>minQuality 60, maxInputPerMtok $4.00, qualityExponent 1.</dd>
+  <dt>tiers.hard</dt><dd>minQuality 72, no price ceiling, qualityExponent 3.</dd>
+  <dt>tiers.&lt;tier&gt;.capabilityFloorUsd</dt><dd>Optional. Pick the highest-quality candidate whose cold-cache cost fits this cap, ignoring quality-per-dollar. Buys quality with money deliberately. <span class="default">Default: unset.</span></dd>
+  <dt>tiers.&lt;tier&gt;.pin</dt><dd>Force a specific slug set for the tier. <span class="default">Default: none.</span></dd>
+</dl>
+
+<h3>filters \u2014 the eligible catalog</h3>
+<dl class="knobs">
+  <dt>filters.includeFree</dt><dd>Include $0 models. <span class="default">Default: false \u2014 free models are rate-limited enough that retries cost more than they save.</span></dd>
+  <dt>filters.requireToolSupport</dt><dd><span class="default">Default: true.</span></dd>
+  <dt>filters.minTrust / minTrustSamples</dt><dd>Demote models whose measured reliability falls below the floor once enough samples exist. <span class="default">Default: 0.7 over 12 samples.</span></dd>
+  <dt>filters.contextHeadroom</dt><dd>Require a context window this multiple of the estimated prompt. <span class="default">Default: 1.25.</span></dd>
+  <dt>filters.latencyWeight</dt><dd>Inflate a model's effective cost by expected wait (TTFT + completion time). <span class="default">Default: 0 (off) \u2014 opt in after establishing a baseline.</span></dd>
+  <dt>filters.maxExpectedWaitMs</dt><dd>Absolute expected-wait ceiling: a hard drop for models <em>proven</em> slower than this (≥ latencyMinSamples), regardless of price \u2014 the soft penalty above is multiplicative and capped, so it cannot demote a slow-but-cheap model. New models keep their cold-start turns. <span class="default">Default: unset (off).</span></dd>
+</dl>
+
+<h3>escalation \u2014 mid-stream recovery</h3>
+<dl class="knobs">
+  <dt>escalation.enabled</dt><dd><span class="default">Default: true.</span></dd>
+  <dt>escalation.probeTokens</dt><dd>Hold this many tokens before committing, to catch a bad start. <span class="default">Default: 48.</span></dd>
+  <dt>escalation.maxAttempts</dt><dd>Original try plus retries. Each retry beyond the first can abandon generated tokens. <span class="default">Default: 3.</span></dd>
+  <dt>escalation.triggers</dt><dd>malformed_tool_args, refusal, empty_completion, repeat_tool_call, missing_expected_tool_call.</dd>
+  <dt>escalation.probeTiers</dt><dd>trivial, simple, moderate \u2014 never <code>hard</code>, which has nowhere to escalate to.</dd>
+</dl>
+
+<h3>hysteresis \u2014 cache-aware stickiness</h3>
+<dl class="knobs">
+  <dt>hysteresis.holdTurns / holdTurnsAfterEscalation</dt><dd>Hold the current tier for N turns to protect the warm cache. <span class="default">Default: 2, and 4 after an escalation.</span></dd>
+  <dt>hysteresis.switchMargin</dt><dd>Expected saving must beat the forfeited cache discount by this factor to switch. <span class="default">Default: 1.3.</span></dd>
+  <dt>hysteresis.maxDowngradePerTurn</dt><dd>Step tiers down at most this fast. <span class="default">Default: 1.</span></dd>
+  <dt>hysteresis.breakHoldOnMechanical</dt><dd>Let a mechanical tool-result continuation break a hold that sits above the fresh classification. <span class="default">Default: false.</span></dd>
+</dl>
+
+<h3>budget \u2014 spend caps</h3>
+<dl class="knobs">
+  <dt>budget.perTurnUsd / perConversationUsd / rolling24hUsd</dt><dd>Optional ceilings, checked against the cold-cache forecast before dispatch. <span class="default">Default: no caps.</span></dd>
+  <dt>budget.onExceeded</dt><dd><code>downgrade</code> or <code>fail</code> at the ceiling. <span class="default">Default: downgrade.</span></dd>
+</dl>
+
+<h3>context \u2014 agentdox bridge (restart to change)</h3>
+<dl class="knobs">
+  <dt>context.enabled</dt><dd>Inject one shared project-context block per conversation. <span class="default">Default: false \u2014 needs a URL and token.</span></dd>
+  <dt>context.baseUrl / token / defaultScope</dt><dd>agentdox endpoint, bearer, and fallback project scope.</dd>
+  <dt>context.memoryLimit / docsLimit / sessionLimit / briefChars</dt><dd>Bound what the server selects, so the block is ranked rather than byte-truncated. <span class="default">Default: 8 / 2 / 6 / 12000, inside a 24000-char cap.</span></dd>
+</dl>
+
+<h3>compaction \u2014 prompt shrinking</h3>
+<dl class="knobs">
+  <dt>compaction.enabled</dt><dd>Shrink stale, low-value context before dispatch. <span class="default">Default: false \u2014 elision is lossy, never implicit.</span></dd>
+  <dt>compaction.budgetTokens</dt><dd>Fire above this prompt size. <span class="default">Default: 40000.</span></dd>
+  <dt>compaction.floorRatio</dt><dd>Compact to this fraction of the budget. Below 1 overshoots and holds the plan (cache-friendly); 1 re-tightens every turn. <span class="default">Default: 1; 0.75 recommended once you have watched your ledger.</span></dd>
+</dl>
+
+<h2>Inspecting decisions</h2>
+<pre><code>auto-model-router stats            # spend and per-model distribution
+auto-model-router explain          # candidates, rejections, forecasts for the last turn
+auto-model-router models           # the eligible catalog per tier</code></pre>
+<p class="note">The full type surface and every field's doc-comment live in <a href="${REPO}/blob/main/src/config/types.ts"><code>src/config/types.ts</code></a>.</p>`;
+
+const benchmarksBody = `<h2>Benchmarks</h2>
+<p>Measured against Claude Opus 5 on Anthropic first-party. Each task is a real omp session working in a pristine git workspace from a written spec; hidden tests are copied in only <em>after</em> the agent exits, so they cannot be read or edited. Every task is verified to fail an untouched workspace and to pass a reference solution. Both arms are metered from omp's own event stream under an identical tool surface. The router arm routes freely \u2014 nothing pinned.</p>
+<p class="pill">Data generated ${esc(bench.generatedAt)} \u00b7 baseline <code>${esc(bench.baseline)}</code></p>
+
+${suiteTable(bench.suites.core)}
+${suiteTable(bench.suites.ladder)}
+${suiteTable(bench.suites.routed)}
+${suiteTable(bench.suites.realWorld)}
+
+<h2>Live ledger snapshot</h2>
+${ledgerPanel(bench.ledgerSnapshot)}
+
+<h2>Scope &amp; honesty</h2>
+<p class="note">These are small, self-contained tasks of one to three files. On the core suite both engines solved everything, so it measures cost at equal correctness rather than capability; the ladder is where capability separates. The cost multiple varied between 14\u00d7 and 32\u00d7 across runs depending on which task the baseline stalled on \u2014 treat "well over an order of magnitude" as the claim, not a specific figure. Full harness, tasks, and raw per-turn data are in <a href="${REPO}/blob/main/docs/routing-benchmark-findings.md"><code>docs/routing-benchmark-findings.md</code></a>.</p>`;
+
+const PAGES: Page[] = [
+	{ slug: "index", title: "auto-model-router \u2014 the right model for every turn", nav: "home", body: indexBody },
+	{ slug: "install", title: "Install \u2014 auto-model-router", nav: "install", body: installBody },
+	{ slug: "config", title: "Configuration \u2014 auto-model-router", nav: "config", body: configBody },
+	{ slug: "benchmarks", title: "Benchmarks \u2014 auto-model-router", nav: "benchmarks", body: benchmarksBody },
+];
+
+// ---------------------------------------------------------------------------
+// Emit
+// ---------------------------------------------------------------------------
+
+function main(): void {
+	rmSync(DIST, { recursive: true, force: true });
+	mkdirSync(DIST, { recursive: true });
+	for (const p of PAGES) {
+		writeFileSync(join(DIST, `${p.slug}.html`), layout(p), "utf8");
+	}
+	cpSync(join(SITE, "assets"), join(DIST, "assets"), { recursive: true });
+	// .nojekyll: the artifact is already built HTML; skip GitHub's Jekyll pass.
+	writeFileSync(join(DIST, ".nojekyll"), "", "utf8");
+	console.log(`built ${PAGES.length} pages \u2192 ${DIST}`);
+}
+
+main();

package/tools/export-benchmarks.ts

@@ -0,0 +1,82 @@
+#!/usr/bin/env bun
+/**
+ * Regenerates the `ledgerSnapshot` section of `site/data/benchmarks.json` from a
+ * real install's ledger, so the published site can show live routing economics
+ * instead of only the authored head-to-head suites.
+ *
+ * It reuses `computeStats` \u2014 the exact aggregation behind the `stats` command
+ * and the `/stats` endpoint \u2014 so the site can never drift from what the tool
+ * reports. The authored `suites` block is preserved untouched; only
+ * `ledgerSnapshot` is rewritten.
+ *
+ * Intended to run at release time, on the machine that holds the live ledger,
+ * and to commit the refreshed JSON alongside the version bump. When no ledger
+ * exists the snapshot is set to null and the site renders a "no snapshot"
+ * placeholder rather than fabricating numbers.
+ *
+ *   bun tools/export-benchmarks.ts               # all-time snapshot
+ *   bun tools/export-benchmarks.ts --days 7       # last 7 days
+ *   bun tools/export-benchmarks.ts --db path.db   # a specific ledger
+ */
+
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { loadConfig } from "../src/config/load.ts";
+import { createLedger } from "../src/cost/ledger.ts";
+import { computeStats } from "../src/server/http.ts";
+import { openDb } from "../src/util/sqlite.ts";
+
+const ROOT = resolve(import.meta.dir, "..");
+const DATA_PATH = join(ROOT, "site", "data", "benchmarks.json");
+
+function parseDays(argv: string[]): number | undefined {
+	const i = argv.indexOf("--days");
+	if (i === -1) return undefined;
+	const n = Number(argv[i + 1]);
+	if (!Number.isFinite(n) || n <= 0) throw new Error(`--days needs a positive number, got ${argv[i + 1]}`);
+	return n;
+}
+
+function parseDb(argv: string[]): string | undefined {
+	const i = argv.indexOf("--db");
+	return i === -1 ? undefined : argv[i + 1];
+}
+
+const argv = process.argv.slice(2);
+const days = parseDays(argv);
+const cfg = loadConfig({});
+const dbPath = parseDb(argv) ?? cfg.ledger.path;
+
+const data = JSON.parse(readFileSync(DATA_PATH, "utf8")) as Record<string, unknown>;
+
+if (!existsSync(dbPath)) {
+	console.error(`no ledger at ${dbPath}; setting ledgerSnapshot to null`);
+	data.ledgerSnapshot = null;
+	writeFileSync(DATA_PATH, `${JSON.stringify(data, null, 2)}\n`, "utf8");
+	process.exit(0);
+}
+
+const db = openDb(dbPath);
+try {
+	const stats = computeStats(createLedger(db, cfg), days === undefined ? {} : { windowDays: days });
+	const perTurnUsd = stats.requests > 0 ? stats.windowSpendUsd / stats.requests : 0;
+	data.ledgerSnapshot = {
+		generatedAt: new Date(stats.generatedAtMs).toISOString().slice(0, 10),
+		windowDays: stats.windowDays,
+		requests: stats.requests,
+		spendAllTimeUsd: Number(stats.spendAllTimeUsd.toFixed(2)),
+		spend7dUsd: Number(stats.spend7dUsd.toFixed(2)),
+		perTurnUsd: Number(perTurnUsd.toFixed(4)),
+		escalationRatePct: Number((stats.escalationRate * 100).toFixed(1)),
+		// Top models by spend share; the long tail adds noise, not signal.
+		perModel: stats.perModel.slice(0, 8).map((m) => ({
+			slug: m.slug,
+			requests: m.requests,
+			sharePct: Number((m.share * 100).toFixed(1)),
+		})),
+	};
+	writeFileSync(DATA_PATH, `${JSON.stringify(data, null, 2)}\n`, "utf8");
+	console.log(`ledgerSnapshot \u2190 ${stats.requests} turns from ${dbPath} (${stats.windowDays === null ? "all time" : `${stats.windowDays}d`})`);
+} finally {
+	db.close();
+}

package/tools/replay.ts

@@ -35,8 +35,12 @@
  *  - `messages` are not recorded, so compaction cannot be re-planned. Replay
  *    forces `compaction.enabled=false` and feeds the POST-compaction prompt
  *    size (`usage.promptTokens`), i.e. the prompt selection actually saw.
- *  - `stickyUntilTurn` was never persisted per turn, so the hysteresis hold
- *    window is absent. This is the main residual gap.
+ *  - Hysteresis holds ARE modelled: the window is re-armed after each replayed
+ *    decision exactly as `turn.ts` does, and evolved PER VARIANT so a change
+ *    that stops arming an expensive tier also drops the holds that followed it.
+ *    What remains absent is escalation-lengthened holds, since replay does not
+ *    retry, and `hold_arm` exploration draws are reproduced from the
+ *    conversation key rather than read back from the row.
  *  - `requestedReasoning` IS recorded and is now used. It was previously forced
  *    to undefined here on the belief the ledger omitted it, which under-scored
  *    ~42% of dispatches and reproduced 27 hard decisions against 120 served.
@@ -63,6 +67,7 @@ import { computeCost } from "../src/cost/forecast.ts";
 import { createLedger } from "../src/cost/ledger.ts";
 import type { UsageCounts } from "../src/cost/types.ts";
 import { scoreHeuristic } from "../src/router/classify.ts";
+import { resolveHoldTurns } from "../src/router/explore.ts";
 import { select } from "../src/router/select.ts";
 import type { ConversationState, Decision, Features, Tier } from "../src/router/types.ts";
 import type { UpstreamClient } from "../src/upstream/types.ts";
@@ -140,6 +145,7 @@ interface Row {
 	reported_usd: number | null;
 	predicted_usd: number;
 	created_at_ms: number;
+	error_kind: string | null;
 }
 
 /**
@@ -201,17 +207,24 @@ function requestOf(row: Row, f: Features): NormRequest {
  * prompt size. Deriving state from the RECORDED outcome rather than the
  * replayed one also stops replay error compounding down a conversation.
  *
- * Still not modelled: `stickyUntilTurn`, which was never persisted per turn, so
- * the hysteresis hold window remains absent.
+ * `stickyUntilTurn` and `currentTier` are the exception: they are SIMULATED per
+ * variant, by re-arming the hold exactly as `turn.ts` does after each replayed
+ * decision. Without that, replay never held a tier and every hysteresis change
+ * priced as zero.
  */
-function stateOf(row: Row, prior: PriorTurn | undefined): ConversationState {
+function stateOf(row: Row, prior: PriorTurn | undefined, hold: HoldState | undefined): ConversationState {
 	return {
 		key: row.conversation_key,
 		sessionId: `omp-${row.conversation_key}`,
-		turn: row.turn,
+		// `turn.ts` computes turnNumber = state.turn + 1 and records THAT, so the
+		// state `select` sees carries the PREVIOUS turn number. Passing row.turn
+		// would expire every hold a turn early.
+		turn: row.turn - 1,
 		currentSlug: prior?.slug ?? null,
-		currentTier: (prior?.tier as Tier | undefined) ?? null,
-		stickyUntilTurn: 0,
+		// Tier and hold window come from THIS VARIANT's own history (see
+		// HoldState); everything else comes from the recorded outcome.
+		currentTier: hold?.tier ?? ((prior?.tier as Tier | undefined) ?? null),
+		stickyUntilTurn: hold?.stickyUntilTurn ?? 0,
 		escalations: 0,
 		spentUsd: prior?.spentUsd ?? 0,
 		lastPromptTokens: prior?.promptTokens ?? 0,
@@ -235,6 +248,24 @@ interface PriorTurn {
 	atMs: number;
 }
 
+/**
+ * Hysteresis state, evolved PER VARIANT.
+ *
+ * A hold is a consequence of the decisions a variant made, so A and B must each
+ * carry their own: if both read the recorded holds, a change that stops arming
+ * `hard` would still be charged for the holds that followed it in production,
+ * and the change would price as smaller than it is.
+ *
+ * This is the one place replay departs from "inputs come from the recorded
+ * outcome". The cost is that hold state compounds a variant's own replay error
+ * down a conversation; the benefit is that hold policy becomes measurable at
+ * all, which it was not.
+ */
+interface HoldState {
+	tier: Tier | null;
+	stickyUntilTurn: number;
+}
+
 /**
  * Re-prices a decision against the tokens the turn ACTUALLY used, via the real
  * `computeCost` so price tiers, the cache split and reasoning/request fees are
@@ -281,7 +312,7 @@ const predicate = args.where === "" ? "" : ` AND (${args.where})`;
 const rows = (
 	db
 		.query(
-			`SELECT id, conversation_key, turn, requested_model, harness_id, served_slug, tier, features, usage, reported_usd, predicted_usd, created_at_ms
+			`SELECT id, conversation_key, turn, requested_model, harness_id, served_slug, tier, features, usage, reported_usd, predicted_usd, created_at_ms, error_kind
 			 FROM ledger
 			 WHERE features IS NOT NULL AND wasted = 0${predicate}
 			 ORDER BY created_at_ms DESC LIMIT ?`,
@@ -307,23 +338,49 @@ interface Outcome {
 	tier: Tier;
 	slug: string;
 	usd: number;
+	/** Whether the hysteresis hold bound this dispatch, for reporting. */
+	held: boolean;
+	/** Hold state to carry into this variant's next dispatch. */
+	hold: HoldState;
 }
 
-function run(cfg: RouterConfig, row: Row, usage: UsageCounts, prior: PriorTurn | undefined): Outcome {
+function run(cfg: RouterConfig, row: Row, usage: UsageCounts, prior: PriorTurn | undefined, hold: HoldState | undefined): Outcome {
 	const f = featuresOf(row, usage.promptTokens);
 	const req = requestOf(row, f);
+	const state = stateOf(row, prior, hold);
 	const decision: Decision = select({
 		req,
 		features: f,
 		classification: scoreHeuristic(f, cfg),
 		profile: profileOf(cfg, row.requested_model),
-		state: stateOf(row, prior),
+		state,
 		snapshot: catalogSnapshot,
 		ledger,
 		cfg,
 		nowMs: Date.now(),
 	});
-	return { tier: decision.tier, slug: decision.slug, usd: repriceUsd(bySlug.get(decision.slug), usage) };
+
+	// Re-arm exactly as turn.ts does: only when the served tier CHANGED, because
+	// re-arming every turn extends the window forever and the router then never
+	// downgrades. `escalated` is false — replay does not model escalation
+	// retries, so escalation-lengthened holds are still absent.
+	// Only a dispatch that reaches the COMMIT path re-arms, as in turn.ts: an
+	// aborted one never gets there, and 27% of rows abort (omp closing the
+	// stream once it has the tool calls). Re-arming on those inflated the hold
+	// count roughly 4x against what production recorded.
+	const committed = row.error_kind === null;
+	const tierChanged = committed && (hold?.tier ?? null) !== decision.tier;
+	const next: HoldState = tierChanged
+		? { tier: decision.tier, stickyUntilTurn: row.turn + resolveHoldTurns(cfg, row.conversation_key, false).turns }
+		: { tier: committed ? decision.tier : (hold?.tier ?? null), stickyUntilTurn: hold?.stickyUntilTurn ?? 0 };
+
+	return {
+		tier: decision.tier,
+		slug: decision.slug,
+		usd: repriceUsd(bySlug.get(decision.slug), usage),
+		held: decision.classification.source === "sticky",
+		hold: next,
+	};
 }
 
 const tallyA = new Map<string, number>();
@@ -344,13 +401,23 @@ const bump = (m: Map<string, number>, k: string) => m.set(k, (m.get(k) ?? 0) + 1
 // Carries the RECORDED outcome of each conversation's previous dispatch forward,
 // so cache warmth and the prior slug are real rather than assumed absent.
 const priorByConv = new Map<string, PriorTurn>();
+// Hold state is per VARIANT, since a hold follows from that variant's own
+// decisions. See HoldState.
+const holdA = new Map<string, HoldState>();
+const holdB = new Map<string, HoldState>();
+let heldA = 0;
+let heldB = 0;
 
 for (const row of rows) {
 	const u = JSON.parse(row.usage) as UsageCounts;
 	if (!(u.promptTokens > 0)) continue;
 	const prior = priorByConv.get(row.conversation_key);
-	const a = run(cfgA, row, u, prior);
-	const b = run(cfgB, row, u, prior);
+	const a = run(cfgA, row, u, prior, holdA.get(row.conversation_key));
+	const b = run(cfgB, row, u, prior, holdB.get(row.conversation_key));
+	holdA.set(row.conversation_key, a.hold);
+	holdB.set(row.conversation_key, b.hold);
+	if (a.held) heldA++;
+	if (b.held) heldB++;
 	priorByConv.set(row.conversation_key, {
 		slug: row.served_slug,
 		tier: row.tier,
@@ -386,8 +453,8 @@ console.log(`variant B overrides: ${args.setB.length ? args.setB.join(" ") : "(n
 console.log(`\nFIDELITY vs what actually ran:`);
 console.log(`  same model ${fidelitySlug}/${comparable} (${pct(fidelitySlug, comparable)}%)   same tier ${fidelityTier}/${comparable} (${pct(fidelityTier, comparable)}%)`);
 console.log("  Divergence is expected where code has changed since those rows were served");
-console.log("  (replay runs CURRENT code); the rest is the unmodelled neutral state.");
-console.log("  Low fidelity => treat the A/B delta below as weak evidence.");
+console.log("  (replay runs CURRENT code); the rest is what replay cannot model.");
+console.log(`  hysteresis holds bound ${heldA} dispatches in A, ${heldB} in B (simulated per variant).`);
 
 function table(label: string, rec: Map<string, number>, A: Map<string, number>, B: Map<string, number>) {
 	const keys = [...new Set([...rec.keys(), ...A.keys(), ...B.keys()])].sort((x, y) => (B.get(y) ?? 0) - (B.get(x) ?? 0));