free-coding-models 0.5.59 → 0.5.61

package/README.md

@@ -550,6 +550,35 @@ The `source` field is `"header"` when the value came from a passive response hea
 
 ---
 
+## 📈 Runtime telemetry: real-world scores
+
+Every routed request through the daemon feeds a persistent per-model telemetry file (`~/.free-coding-models/runtime-telemetry.json`) — the **honesty layer** that complements SWE-bench with what models actually do on free tiers.
+
+- **Real success rate** — `(successCalls / totalCalls)` updated on every routed request (success and failure paths alike).
+- **Real throughput** — `avgTokensPerSecond` derived from completion tokens / total latency, so you see what your code actually streams at.
+- **Recent calls (last 50)** — for debugging "why did this just 500?" without rebuilding state.
+- **Composite `Real` score** — `successRate × 0.6 + sigmoid01(tok/s) × 0.25 + recency × 0.15`. Null when below `MIN_CALLS_FOR_SCORE = 5` (no penalty for new models).
+
+### Where it shows up
+
+| Surface | What you'll see |
+|---------|-----------------|
+| TUI `Real` column | Inline composite score per row, `–` when insufficient data |
+| TUI `W` sort key | Sort by real-world score descending |
+| TUI `Shift+W` | Runtime Report overlay — per-model breakdown + recent calls |
+| Web Dashboard | "Runtime Telemetry" cards with animated success-rate bars |
+| `/api/router/stats.runtime` | `{ stats: { modelsTracked, totalCalls, modelsWithSignal }, models: { ... } }` |
+
+### Privacy
+
+The telemetry file lives **locally only** (`~/.free-coding-models/runtime-telemetry.json`, `0600` perms). Nothing is sent upstream unless you opt in to a future aggregate leaderboard. The file holds **metadata only** — success, latency, tokens, error reason. No prompts, no responses, no content.
+
+### CLI flag
+
+- `--clear-runtime` — wipe the file before launching (reset the baseline).
+
+---
+
 ## π Pi Extension — FCM-Pi ⚠️ BETA
 
 **FCM-Pi** is a native [Pi coding agent](https://pi.dev) extension that integrates `free-coding-models` directly into your Pi session. It stays silent by default, scans only when you run `/fcm`, and lets you explicitly hot-swap models mid-session.
@@ -764,6 +793,9 @@ See [`packages/fcm-agent-core/README.md`](./packages/fcm-agent-core/README.md) f
 - **Last release timestamp** — light pink footer shows `Last release: Mar 27, 2026, 09:42 PM` from npm so users know how fresh the data is
 - **Persistent probe-cache (t1)** — every health probe result is cached to `~/.free-coding-models/probe-cache.json` for 24h. Warm starts render the full ranking in <500ms, only re-ping the models that are due (broken or TTL-expired). Broken models are auto-hidden across sessions — toggle visibility with **Shift+B**. See [Persistent probe cache](#-persistent-probe-cache) below for `--reprobe`, `--probe-ttl`, `--show-broken`.
 - **Live quota from response headers (t2)** — every routed chat-completion response already carries `x-ratelimit-*` headers. The daemon parses them in 8 variants and exposes live per-provider quota on the TUI footer (`📊 groq 78% · sambanova 41%`) and in the Web Dashboard (`Provider Quota` section with animated progress bars). Zero extra network requests, zero quota waste. See [Live quota from headers](#-live-quota-from-response-headers) below.
+- **Runtime telemetry: real-world scores (t3)** — every routed request through the daemon feeds a persistent per-model telemetry file (`~/.free-coding-models/runtime-telemetry.json`) with real success rate, throughput, and recent calls. The `Real` column + `W` sort key in the TUI rank models by what *actually* works on free tiers, not what they claim on SWE-bench. See [Runtime telemetry](#-runtime-telemetry-real-world-scores) below.
+- **Extended benchmark catalog (t4)** — `src/data/benchmarks.json` (49 well-known models committed, refreshed at every release via `pnpm update:benchmarks`) layers **Coding Index, Math Index, Agentic Index, Reasoning Index, MMLU-Pro, GPQA, HLE** on top of `sources.js` with a lazy `Proxy` load + prefix-indexed O(key length) lookup. Surfaced on the TUI footer as `📊 bench 49 (2026-07-25)`. Curated SWE-bench scores are never overwritten — the overlay is additive.
+- **Live `models.dev` enrichment + drift detection (t5)** — the community-maintained `models.dev` catalog is fetched in the background (5 min in-process cache, 3 retries × 250 ms backoff) and overlaid onto every merged model with `metaSource` provenance. The footer chip shows `📡 102 live · 62 curated` so you see at a glance which values came from upstream. `--check-drift` prints a human-readable drift report vs `sources.js`; a weekly CI job opens a `catalog-drift` issue if anything changed.
 
 ---
 

package/bin/free-coding-models.js

@@ -62,6 +62,37 @@ async function main() {
     process.exit(0);
   }
 
+  // 📖 --clear-runtime (t3): wipe ~/.free-coding-models/runtime-telemetry.json
+  // 📖 before launching any surface. Keeps the TUI / daemon / web flows consistent.
+  if (cliArgs.clearRuntimeMode) {
+    try {
+      const { clearRuntimeTelemetry } = await import('../src/core/runtime-telemetry.js')
+      const ok = clearRuntimeTelemetry()
+      console.log(chalk.dim(`  ${ok ? '✓' : '✗'} runtime-telemetry.json ${ok ? 'cleared' : 'clear failed'}`))
+    } catch (err) {
+      console.log(chalk.dim(`  runtime-telemetry.json clear failed: ${err?.message || err}`))
+    }
+  }
+
+  // 📖 --check-drift (t5): diff sources.js against models.dev and print a report.
+  // 📖 Runs BEFORE the config + update check so it works on bare clones and CI.
+  if (cliArgs.checkDriftMode) {
+    const threshold = cliArgs.driftThreshold ?? 0
+    const args = ['--threshold', String(threshold)]
+    const { spawn } = await import('node:child_process')
+    const { fileURLToPath } = await import('node:url')
+    const { dirname, join } = await import('node:path')
+    const here = dirname(fileURLToPath(import.meta.url))
+    const script = join(here, '..', 'scripts', 'check-drift.mjs')
+    const child = spawn(process.execPath, [script, ...args], { stdio: 'inherit' })
+    child.on('exit', code => process.exit(code ?? 1))
+    child.on('error', err => {
+      console.error(chalk.red(`failed to spawn check-drift: ${err.message}`))
+      process.exit(3)
+    })
+    return
+  }
+
   // Load JSON config before operational modes so the mandatory update policy can
   // 📖 persist failure counters for TUI, Web Dashboard, Docker daemon, and Desktop sidecar launches.
   const config = loadConfig();

package/changelog/v0.5.60.md

@@ -0,0 +1,54 @@
+# Changelog v0.5.60 - 2026-07-26
+
+### Added
+
+- 📈 **Runtime telemetry: real-world scores** (t3) — every routed request through the daemon now feeds a persistent per-model telemetry file with real success rate, throughput, and recent calls. FCM stops showing you only what models *claim* on SWE-bench and starts showing you what they **actually do** on free tiers.
+
+  - **Composite `Real` score** (0..100) — `successRate × 0.6 + sigmoid01(tok/s) × 0.25 + recency × 0.15`. Null when below `MIN_CALLS_FOR_SCORE = 5` (no penalty for new models).
+  - **Real success rate** — `(successCalls / totalCalls)`. Updated on every routed request, success AND failure paths alike (auth_error / 5xx / 429 all count).
+  - **Real throughput** — `avgTokensPerSecond` from completion tokens / total latency. What your code actually streams at.
+  - **Recent calls (last 50)** — FIFO trim per model. Useful for debugging "why did this just 500?" without rebuilding state.
+  - **Local-only by default** — the file lives at `~/.free-coding-models/runtime-telemetry.json` (`0600` perms). Nothing leaves your machine unless you opt in to a future aggregate leaderboard. Metadata only — no prompts, no responses.
+
+- 🆕 **New sort key `W`** in the TUI: sorts by `Real` score descending. Models with insufficient data (null score) sink to the bottom in both directions.
+
+- 📊 **New TUI `Real` column**: shows the composite score inline per row, or `–` when there's not enough signal yet.
+
+- 🔥 **`Shift+W` Runtime Report overlay** — per-model breakdown (success rate, avg latency, avg tok/s, recent calls list). Same pattern as `Shift+R` Router Dashboard / `Shift+T` Token Usage. Scroll with j/k/up/down/pageup/pagedown/home/end, close with Escape.
+
+- 🌐 **Web Dashboard `Runtime Telemetry` section** — per-model cards with animated success-rate bars (red ≤ 50% / amber 50-80% / green ≥ 80%). Updated every `/api/router/stats` poll (5 s). Models with < 5 calls are excluded so the section only shows real signal.
+
+- 🛰️ **New daemon endpoint `/stats/runtime`** — returns `{ ok, stats: { modelsTracked, totalCalls, modelsWithSignal }, models: { [key]: ModelTelemetry } }`. Same shape as the in-TUI dashboard digest.
+
+- 🧪 **`recordModelCall(providerKey, modelId, callResult, opts?)`** — drop-in hook for any future surface (Tauri Desktop, scripts) that wants to feed runtime telemetry.
+
+- 🛠️ **`--clear-runtime` CLI flag** — wipe the telemetry file before launching any surface. Useful when the user wants to reset the baseline.
+
+### Changed
+
+- 🩺 **Daemon reverse proxy** records every successful + failed routed outcome via `recordRuntimeCall()`. A debounced 5 s flush keeps the file in sync without thrashing the disk. The flush timer is cleared in `shutdown()` so no orphan writes after exit.
+
+- 📋 **Daemon `statsPayload`** now exposes `runtimeTelemetry: { stats, models }` so the existing `/stats` consumers get the digest for free.
+
+- 🔧 **Internal** — added `sigmoid01(x)` (logistic curve so 50 tok/s → 0.5) and `recencyDecay(lastUpdatedMs)` (1.0 today → 0.0 at 30 d) to the real-world score formula. Both are pure functions with no dependencies.
+
+### Non-goals (explicit)
+
+- **Streaming token extraction** — the known gap from the PRD stays. The runtime telemetry only counts requests where the upstream returned `usage` (i.e. non-streaming, or streaming providers that emit usage on the final chunk).
+- **Sharing / leaderboard** — no aggregation server yet. When there is one, opt-in.
+
+### Maintenance
+
+- 🧪 **+30 unit tests** (`test/runtime-telemetry.test.js`, new file): path resolution (XDG-aware), constants sanity, `recordModelCall` write/accumulate/drop garbage/FIFO cap, `tokensPerSecond` computation, derived fields, `getRealWorldScore` null below threshold / healthy → high / error-heavy → mid / age decay, `getCacheStats` aggregates + `modelsWithSignal` threshold, `pruneStaleEntries` drops old, persistence round-trip + corrupt recovery + missing file + clear + read-merge-write concurrency safety.
+- 🧪 **671 → 701 tests passing** (`pnpm test`), **125 → 134 suites**.
+- 🧹 `vite build` succeeds.
+- 📖 README updated with a new **📈 Runtime telemetry: real-world scores** section (where it shows up, privacy, `--clear-runtime`).
+
+### Inspiration
+
+This implementation is informed by [`apmantza/pi-free`](https://github.com/apmantza/pi-free)'s `lib/telemetry.ts` (which credits us in their other direction too). pi-free's `turn_end` hook is the daemon-side equivalent of our `recordRuntimeCall`; the schema, the 50-call FIFO, and the local-only file mirror their approach. Where we diverge: we expose the composite `Real` score as a first-class ranking signal (not just a debugging surface), ship it in 3 user-facing surfaces (CLI TUI / Web Dashboard / daemon `/stats`), and add the success×0.6 / speed×0.25 / recency×0.15 weights so the user sees a single number per model.
+
+### Files
+
+- **New**: `src/core/runtime-telemetry.js` (377 lines, 11 exports), `test/runtime-telemetry.test.js` (390 lines, 30 tests), `changelog/v0.5.60.md`.
+- **Modified**: `src/core/router-daemon.js` (record on every routed outcome + `/stats/runtime` + runtimeTelemetry in statsPayload), `src/core/utils.js` (`'realworld'` sort case), `src/tui/app.js` (boot-time score computation per result), `src/tui/tui-state.js` (5 new state fields for the overlay), `src/tui/key-handler.js` (Shift+W + overlay keyboard handling + command palette action), `bin/free-coding-models.js` (`--clear-runtime` flag plumbing), `web/src/components/router/RouterView.jsx` (Runtime Telemetry section), `README.md`, `tasks/t3.md`, `package.json` (test script).

package/changelog/v0.5.61.md

@@ -0,0 +1,65 @@
+# Changelog v0.5.61 - 2026-07-27
+
+### Added
+
+- 📊 **Extended benchmark catalog** (t4) — a new `src/data/benchmarks.json` (49 well-known models committed, refreshed at every release) layered on top of `sources.js` gives you 6 extra ranking signals per model: **Coding Index, Math Index, Agentic Index, Reasoning Index, MMLU-Pro, GPQA, HLE**, plus `supportsReasoning`, `supportsVision`, and a real `contextWindow` from Artificial Analysis + curated manual overlay.
+
+  - **Lazy load via `Proxy`** — the JSON is only parsed on first lookup, not at module load. Cold start stays at ~0 ms.
+  - **Prefix-indexed O(key length) lookup** — `lookupExtendedBenchmark('deepseek-ai/deepseek-v4-pro')` is fast even on a 500-entry catalog. Falls back through the `-`/`/`-prefixed segments (e.g. `deepseek-ai` → `deepseek-ai/deepseek` → `deepseek-ai/deepseek-v4` → `deepseek-ai/deepseek-v4-pro`) and picks the best-scoring candidate.
+  - **Curated seed wins** — the `mergeExtendedBenchmark` overlay only fills fields that are null in `sources.js`. Your curated `sweScore` / `tier` / `ctx` are never overwritten by the live data.
+
+- 🛰️ **Live `models.dev` enrichment** (t5) — the community-maintained `models.dev` catalog is fetched in the background (5 min in-process cache, 3 retries × 250 ms backoff, 8 s per-request timeout) and overlaid onto every merged model with `metaSource: 'models.dev' | 'sources.js'` provenance.
+
+  - **Substring matches skipped for drift detection** — the indexer tries exact → aliased → substring, but the drift detector only counts exact + aliased matches (avoids the "DeepSeek Chat" vs "DeepSeek Reasoner" false positive).
+  - **Provider aliases** — 40+ mappings bridge sources.js provider keys (`nvidiaNim`, `together`, `novita`, `kilocode`, …) to models.dev provider keys (`nvidia`, `togetherai`, `novita-ai`, `kilo`, …).
+  - **Offline-safe** — if the fetch fails (3×8 s = up to 24 s, capped to 12 s in the background task), `metaSource` stays at `'sources.js'` and the TUI keeps rendering. No crashes, no hangs.
+
+- 🔍 **`--check-drift` CLI flag** — diff `sources.js` against `models.dev` and print a human-readable report grouped by model. Each row shows the field, the sources.js value, the models.dev value, and an action arrow (`← UPDATE` or `← ADD`).
+
+  ```bash
+  free-coding-models --check-drift                       # exit 1 on any drift
+  free-coding-models --check-drift --drift-threshold 5   # only fail on 5+ mismatches
+  pnpm check:drift                                       # npm alias
+  ```
+
+  Exit codes: `0` no drift · `1` drift detected · `2` fetch failed · `3` invalid args.
+
+- 🤖 **`pnpm update:benchmarks`** — regenerate `src/data/benchmarks.json` from a fresh models.dev fetch. The script preserves curated values via a 3-way merge (synthesized + curated + existing). Wired into the release process and the weekly CI workflow.
+
+- 🦾 **TUI footer enrichment chip** — `📊 bench 49 (2026-07-25) · 📡 102 live · 62 curated` on the bottom line. Tells you at a glance: how many models have extended metrics, when the catalog was last refreshed, how many models got live metadata from models.dev vs staying at curated values.
+
+- 🌐 **Web Dashboard data exposure** — `/api/models` now includes `extendedBench` + `metaSource` per row. Detail panels (radar chart) can pick up the data when the UI component lands.
+
+- 🕒 **`.github/workflows/update-benchmarks.yml`** — weekly Monday 04:00 UTC job. Runs `pnpm update:benchmarks --dry-run`, diffs against the committed JSON, and opens a PR with the change if the catalog drifted. Manual trigger via `workflow_dispatch`.
+
+- 🕵️ **`.github/workflows/check-drift.yml`** — weekly Monday 05:00 UTC job. Runs `pnpm check:drift --no-fail`. If drift is detected, opens a `catalog-drift` issue with the report; on subsequent runs, comments on the existing issue; auto-closes the issue when drift drops to 0.
+
+### Changed
+
+- 📦 **CLI help (`--help`)** — new flags `--check-drift` and `--drift-threshold <N>` documented under the **Analysis Flags** section, right next to the existing probe-cache flags.
+- 🧠 **`src/core/utils.js` `parseArgs()`** — two new return fields: `checkDriftMode` (boolean) and `driftThreshold` (number|null). The TUI's `bin/free-coding-models.js` early-exits before the config + update check so the flag works on bare clones (CI / scripts).
+
+### Non-goals (explicit, tracked for follow-up)
+
+- **TUI detail-view benchmark block** — the chip is the visible surface for now. A full "Press `?` on a row to see Coding/Math/Agentic/Reasoning/MMLU-Pro/GPQA/HLE + vision/reasoning flags" overlay is tracked in the t4 follow-up. The data layer + tests are ready.
+- **6 new sort keys for the benchmark indices** — the key map is already crowded (R/O/M/L/A/S/C/H/V/U/B/T/W/Z/E/F/Y/X/Q/G/N/P/I). Adding 6 more would conflict. Tracked for a "Sort by benchmark" submenu in the Command Palette.
+- **Web Dashboard radar chart component** — the data is exposed, the UI component is a separate task. The /api/models payload includes everything the chart needs.
+
+### Maintenance
+
+- 🧪 **+66 unit tests** across 3 new files:
+  - `test/extended-benchmarks.test.js` (31 tests, 9 suites) — path resolution, lazy load + cache, prefix index build, exact + fallback + best-scoring lookup, overlay bag shape, performance (10k lookups in 3.3 ms, 1k cached in 1 ms).
+  - `test/models-dev.test.js` (35 tests, 8 suites) — fetcher URL/TTL, normalizeModelDevEntry (flat + nested + malformed), buildModelIndex (auto-detect), lookupModelDevMeta (exact + alias + substring + unknown), detectDrift (drift + add + threshold), summarizeDrift, formatDriftReport (with/without color), parseCtxToNum (k/m/plain/edge), PROVIDER_ALIASES mappings.
+  - `test/model-merger.test.js` (extended to 12 tests) — overlayExtendedBenchmarks, overlayModelsDevMetadata (sync + async + mutate), getEnrichmentStats.
+- 🧪 **701 → 779 tests passing** (`pnpm test`), **134 → 155 suites**.
+- 🛡️ `pnpm start` runs without runtime error (TUI, Web Dashboard, daemon all load the new modules cleanly).
+- 🐛 Fixed a real freeze: the initial draft had a top-level `await import` in `src/tui/app.js` that blocked module load. Refactored to a sync read for the catalog stats + a 12 s-bounded fire-and-forget IIFE for the models.dev fetch. The TUI now starts in <1 s even when the network is unreachable.
+
+### Inspiration
+
+This implementation is informed by [`apmantza/pi-free`](https://github.com/apmantza/pi-free)'s `lib/model-metadata.ts` (the fetcher + retry + cache + provider aliases shape) and `provider-failover/benchmark-lookup.ts` + `hardcoded-benchmarks.ts` (the prefix index + lazy `Proxy` load pattern). Where we diverge: we ship a curated **49-entry seed** in the repo (their TS version relies on hardcoded constants at build time), we add the **drift detector** + weekly **CI workflow** for proactive catalog hygiene, and we expose the data on all 3 surfaces (CLI TUI, Web Dashboard, Desktop) with consistent `metaSource` provenance.
+
+### Files
+
+- **New**: `src/core/extended-benchmarks.js` (320 lines, 11 exports), `src/core/models-dev-fetcher.js` (180 lines, 7 exports), `src/core/models-dev-index.js` (290 lines, 5 exports), `src/core/models-drift.js` (320 lines, 6 exports), `src/data/benchmarks.json` (49 entries committed), `scripts/update-benchmarks.mjs` (220 lines, executable), `scripts/check-drift.mjs` (170 lines, executable), `.github/workflows/update-benchmarks.yml`, `.github/workflows/check-drift.yml`, `test/extended-benchmarks.test.js` (310 lines, 31 tests), `test/models-dev.test.js` (380 lines, 35 tests), `changelog/v0.5.61.md`.
+- **Modified**: `src/core/model-merger.js` (+155 lines: 3 new exports + async overlay with mutate), `src/core/utils.js` (+14 lines: parseArgs + checkDriftMode/driftThreshold), `src/tui/app.js` (+80 lines: ensureBenchStatsLoaded + runModelsDevEnrichmentInBackground + tableOpts wiring), `src/tui/render-table.js` (+40 lines: enrichmentLabel chip), `src/tui/cli-help.js` (+2 lines: new flags in ANALYSIS_FLAGS), `bin/free-coding-models.js` (+19 lines: --check-drift early-exit), `web/server.js` (+40 lines: serializeModel includes extendedBench + metaSource, webEnrichmentCache primed at boot), `package.json` (+5 lines: test commands + scripts), `test/model-merger.test.js` (+100 lines: new test cases), `tasks/t4.md`, `tasks/t5.md`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "free-coding-models",
-  "version": "0.5.59",
+  "version": "0.5.61",
   "description": "Find the fastest coding LLM models in seconds \u2014 ping free models from multiple providers, pick the best one for OpenCode, Cursor, or any AI coding assistant.",
   "keywords": [
     "nvidia",
@@ -53,7 +53,11 @@
   ],
   "scripts": {
     "start": "node bin/free-coding-models.js",
-    "test": "node --test test/test.js test/fcm-agent-core.test.js test/patch-openclaw.test.js test/provider-metadata.test.js test/config-permission-hint.test.js test/probe-cache.test.js test/passive-quota.test.js",
+    "test": "node --test test/test.js test/fcm-agent-core.test.js test/patch-openclaw.test.js test/provider-metadata.test.js test/config-permission-hint.test.js test/probe-cache.test.js test/passive-quota.test.js test/runtime-telemetry.test.js test/extended-benchmarks.test.js test/models-dev.test.js test/model-merger.test.js",
+    "test:extended-benchmarks": "node --test test/extended-benchmarks.test.js",
+    "test:models-dev": "node --test test/models-dev.test.js",
+    "update:benchmarks": "node scripts/update-benchmarks.mjs",
+    "check:drift": "node scripts/check-drift.mjs",
     "prepack": "npm run build:web",
     "dev": "node scripts/dev-web.mjs",
     "dev:web": "node scripts/dev-web.mjs",

package/src/core/extended-benchmarks.js

@@ -0,0 +1,421 @@
+/**
+ * @file extended-benchmarks.js
+ * @description Extended per-model benchmark catalog (Coding/Math/Agentic/Reasoning indices
+ *              + MMLU-Pro / GPQA / HLE + reasoning/vision support) with O(key length) prefix-indexed
+ *              lookup and lazy JSON load.
+ *
+ * @details
+ *   📖 Why this exists:
+ *   📖 - `sources.js` carries a single SWE-bench score per model — useful for tier, but
+ *   📖   blind to a model's math/reasoning/vision capabilities. The extended catalog
+ *   📖   adds 6 indices (Coding, Math, Agentic, Reasoning, MMLU-Pro, GPQA, HLE) plus
+ *   📖   context-window, reasoning-support and vision-support flags.
+ *   📖 - With ~50–500 catalog entries, a linear lookup on every TUI re-render is wasteful.
+ *   📖   We build a prefix index on the `-`-separated model id so lookups only visit
+ *   📖   candidate variants of the base model (e.g. "deepseek-ai/deepseek-v4-pro" falls
+ *   📖   back to "deepseek-ai/deepseek-v4-pro" exact, then "deepseek-ai/deepseek-v4",
+ *   📖   then "deepseek-ai/deepseek", …) — O(key length) instead of O(catalog size).
+ *   📖 - The JSON file is large but only needed when the user actually looks at model
+ *   📖   metadata. A Proxy deferral defers readFileSync until first property access.
+ *
+ *   📖 Data shape (see src/data/benchmarks.json):
+ *   📖   {
+ *   📖     "_meta": { "schemaVersion": 1, "lastUpdated": "...", "source": "..." },
+ *   📖     "<modelId>": {
+ *   📖       "codingIndex":    72.4,   // 0–100
+ *   📖       "mathIndex":      68.1,   // 0–100
+ *   📖       "agenticIndex":   55.0,   // 0–100
+ *   📖       "reasoningIndex": 71.2,   // 0–100
+ *   📖       "mmluPro":        78.3,   // 0–100
+ *   📖       "gpqa":           54.0,   // 0–100
+ *   📖       "hle":            12.1,   // 0–100  (Humanity's Last Exam)
+ *   📖       "contextWindow":  1000000,
+ *   📖       "supportsReasoning": true,
+ *   📖       "supportsVision":    false,
+ *   📖       "lastUpdated":    "2026-07-20",
+ *   📖       "originalModel":  "DeepSeek V4 Pro"
+ *   📖     },
+ *   📖     ...
+ *   📖   }
+ *
+ *   📖 Cross-surface: pure logic, consumed everywhere — CLI TUI, Web Dashboard, Desktop.
+ *
+ * @functions
+ *   → getBenchmarksDataPath()                — Resolves the JSON file path
+ *   → getCatalog()                           — Lazy-loaded catalog (Proxy)
+ *   → lookupExtendedBenchmark(modelId, opts?) — Returns the entry (or null) for a model
+ *   → buildPrefixIndex(catalog)              — Builds the prefix index (idempotent, cached)
+ *   → getCatalogStats()                      — { total, byField, lastUpdated }
+ *   → mergeExtendedBenchmark(model, entry?)  — Helper to overlay onto a result object
+ *   → EXTENDED_BENCH_FIELDS                 — The list of overlay field names
+ *
+ * @exports getBenchmarksDataPath, getCatalog, lookupExtendedBenchmark, getCatalogStats,
+ *          mergeExtendedBenchmark, EXTENDED_BENCH_FIELDS
+ *
+ * @see src/data/benchmarks.json                — The committed seed catalog
+ * @see scripts/update-benchmarks.mjs           — Regenerates the JSON (release-time)
+ * @see src/core/utils.js                       — parseSweToNum, parseCtxToK (related)
+ * @see src/core/model-merger.js                — Calls mergeExtendedBenchmark at merge time
+ */
+
+import fs from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+// ─── Constants ────────────────────────────────────────────────────────────────
+
+/** 📖 Default location of the benchmark catalog JSON, resolved at runtime. */
+const DATA_FILENAME = 'benchmarks.json'
+
+/** 📖 Canonical list of extended fields overlaid onto a model. Used for the detail view. */
+export const EXTENDED_BENCH_FIELDS = [
+  'codingIndex', 'mathIndex', 'agenticIndex', 'reasoningIndex',
+  'mmluPro', 'gpqa', 'hle',
+  'contextWindow', 'supportsReasoning', 'supportsVision',
+  'lastUpdated', 'originalModel',
+]
+
+// ─── Module-level state ──────────────────────────────────────────────────────
+
+/** 📖 Cached parsed catalog (object). Loaded lazily on first access. */
+let _catalog = null
+
+/** 📖 Cached prefix index, lazily built from the catalog. */
+let _index = null
+
+/** 📖 Resolved path the catalog was last loaded from (for debug / hot-reload). */
+let _catalogPath = null
+
+// ─── Path resolution ──────────────────────────────────────────────────────────
+
+/**
+ * 📖 Resolves the absolute path to `src/data/benchmarks.json`. Works regardless of
+ * 📖 CWD (the file is resolved relative to this module's location, not the user's cwd).
+ *
+ * @returns {string} Absolute path to benchmarks.json
+ */
+export function getBenchmarksDataPath() {
+  const here = path.dirname(fileURLToPath(import.meta.url))
+  return path.join(here, '..', 'data', DATA_FILENAME)
+}
+
+// ─── Lazy catalog load ───────────────────────────────────────────────────────
+
+/**
+ * 📖 Force-load the catalog from disk and return the parsed object. Safe to call
+ * 📖 repeatedly — the second+ calls return the cached object. Corrupt JSON or
+ * 📖 missing file yield an empty catalog (logged to stderr) — never throw, because
+ * 📖 the TUI must keep rendering even if the catalog is missing.
+ *
+ * @returns {object} The catalog object keyed by modelId (with a `_meta` key mixed in)
+ */
+export function loadCatalog() {
+  if (_catalog) return _catalog
+  const target = getBenchmarksDataPath()
+  try {
+    const raw = fs.readFileSync(target, 'utf-8')
+    const parsed = JSON.parse(raw)
+    if (parsed && typeof parsed === 'object') {
+      _catalog = parsed
+      _catalogPath = target
+      return _catalog
+    }
+  } catch (err) {
+    // 📖 File missing or corrupt — log once and fall back to empty catalog.
+    // 📖 We intentionally don't throw: the TUI must keep working with sources.js data.
+    if (process.env.FCM_BENCH_DEBUG) {
+      console.warn(`[extended-benchmarks] failed to load ${target}: ${err.message}`)
+    }
+  }
+  _catalog = {}
+  _catalogPath = target
+  return _catalog
+}
+
+/**
+ * 📖 Reset the module cache. Used by tests + by the update script after a refresh.
+ * 📖 Production code should not need to call this — the catalog is append-mostly.
+ */
+export function resetCatalogCache() {
+  _catalog = null
+  _index = null
+  _catalogPath = null
+}
+
+/**
+ * 📖 Lazy proxy: defer `readFileSync` until the first property access. This shaves
+ * 📖 startup time (the JSON is ~16KB and grows as the catalog expands). Mirrors
+ * 📖 pi-free's `hardcoded-benchmarks.ts` pattern.
+ *
+ * 📖 IMPORTANT: Property access triggers `load()`. Iteration (`Object.keys`,
+ * 📖 `Reflect.ownKeys`, `for..in`) also triggers the load via the traps.
+ */
+export const BENCHMARKS = new Proxy({}, {
+  get(_t, prop, receiver) {
+    if (prop === Symbol.toPrimitive || prop === 'toJSON') return undefined
+    if (prop === 'then') return undefined  // makes the proxy non-thenable
+    const data = loadCatalog()
+    return Reflect.get(data, prop, receiver)
+  },
+  has(_t, prop) {
+    const data = loadCatalog()
+    return Reflect.has(data, prop)
+  },
+  ownKeys() {
+    const data = loadCatalog()
+    return Reflect.ownKeys(data)
+  },
+  getOwnPropertyDescriptor(_t, p) {
+    const data = loadCatalog()
+    return Reflect.getOwnPropertyDescriptor(data, p)
+  },
+  set(_t, prop, value) {
+    const data = loadCatalog()
+    return Reflect.set(data, prop, value)
+  },
+  deleteProperty(_t, prop) {
+    const data = loadCatalog()
+    return Reflect.deleteProperty(data, prop)
+  },
+})
+
+/**
+ * 📖 Direct accessor (no Proxy) for code that wants the raw object, e.g. the
+ * 📖 web dashboard backend iterating keys, or tests inspecting `_meta`.
+ */
+export function getCatalog() {
+  return loadCatalog()
+}
+
+// ─── Prefix index ─────────────────────────────────────────────────────────────
+
+/**
+ * 📖 Build a prefix index over the catalog so a lookup is O(key length) instead
+ * 📖 of O(catalog size). For each model id, every `-`-separated prefix maps to
+ * 📖 the entries that start with that prefix.
+ *
+ * 📖 Example (preserves the original `-`/`/` separator at each level):
+ * 📖   "deepseek-ai/deepseek-v4-pro" → prefixes:
+ * 📖     "deepseek-ai"
+ * 📖     "deepseek-ai/deepseek"          ← keeps the `/` from the source
+ * 📖     "deepseek-ai/deepseek-v4"
+ * 📖     "deepseek-ai/deepseek-v4-pro"   (exact)
+ *
+ * 📖 When a model id like "deepseek-ai/deepseek-v4-pro" is looked up, we try:
+ * 📖   1. exact match → fast hit
+ * 📖   2. longest-to-shortest prefix walk → best-effort match for cross-provider
+ * 📖      variants ("z-ai/glm-5.2" vs "zai-glm-4.7" etc.)
+ *
+ * @param {object} [catalog] — Defaults to the lazy-loaded catalog. Tests inject a fixture.
+ * @returns {{ exact: Map<string, object>, variants: Map<string, Array<[string, object]>> }}
+ */
+export function buildPrefixIndex(catalog) {
+  const data = catalog ?? loadCatalog()
+  const exact = new Map()
+  const variants = new Map()
+  for (const [key, value] of Object.entries(data)) {
+    if (key === '_meta') continue  // 📖 metadata key, not a model entry
+    if (!value || typeof value !== 'object') continue
+    exact.set(key, value)
+    // 📖 Walk the original string char-by-char to preserve both `-` and `/`
+    // 📖 separators. A prefix ends right after each separator in the source.
+    // 📖 This way "deepseek-ai/deepseek-v4-pro" produces:
+    // 📖   "deepseek-ai", "deepseek-ai/deepseek", "deepseek-ai/deepseek-v4", ...
+    // 📖 and "z-ai/glm-5.2" produces:
+    // 📖   "z-ai", "z-ai/glm", "z-ai/glm-5", "z-ai/glm-5.2"
+    const indices = []
+    for (let i = 0; i < key.length; i++) {
+      const ch = key[i]
+      if (ch === '-' || ch === '/') indices.push(i)
+    }
+    for (const sepIdx of indices) {
+      const prefix = key.slice(0, sepIdx)
+      if (!prefix) continue
+      const arr = variants.get(prefix) ?? []
+      arr.push([key, value])
+      variants.set(prefix, arr)
+    }
+  }
+  return { exact, variants }
+}
+
+/**
+ * 📖 Get the prefix index, building it on first call. Cached so repeated lookups
+ * 📖 (every TUI render) are free.
+ */
+function getIndex() {
+  if (_index) return _index
+  _index = buildPrefixIndex(loadCatalog())
+  return _index
+}
+
+/**
+ * 📖 Score how good a candidate entry is for the requested model id. Higher = better.
+ * 📖 Tie-breakers are used when multiple candidates share the same longest prefix
+ * 📖 (e.g. "deepseek-ai/deepseek-v4-pro" exact vs. "deepseek-ai/deepseek-v4-flash" fallback).
+ */
+function scoreCandidate(requestedId, candidateKey) {
+  if (requestedId === candidateKey) return 10_000  // exact match always wins
+  // 📖 Prefer entries that share more characters with the requested id
+  let commonPrefixLen = 0
+  const min = Math.min(requestedId.length, candidateKey.length)
+  while (commonPrefixLen < min && requestedId[commonPrefixLen] === candidateKey[commonPrefixLen]) {
+    commonPrefixLen++
+  }
+  return commonPrefixLen
+}
+
+/**
+ * 📖 Look up a model's extended benchmark entry. Tries in order:
+ * 📖   1. exact match (O(1) Map lookup)
+ * 📖   2. longest-prefix walk — picks the highest-scoring candidate
+ * 📖   3. returns null (no throw)
+ *
+ * 📖 Performance: O(key length) since each prefix walk visits at most N candidates
+ * 📖 where N is the number of entries sharing the current prefix (typically 1–3).
+ *
+ * @param {string} modelId
+ * @param {object} [opts]
+ * @param {object} [opts.catalog] — Override the catalog (tests)
+ * @param {object} [opts.index]   — Override the prefix index (tests)
+ * @returns {object|null} The extended benchmark entry, or null if not found.
+ */
+export function lookupExtendedBenchmark(modelId, opts = {}) {
+  if (!modelId || typeof modelId !== 'string') return null
+  let index = opts.index
+  let catalog = opts.catalog
+  if (!index) {
+    if (catalog) {
+      index = buildPrefixIndex(catalog)
+    } else {
+      index = getIndex()
+    }
+  }
+  const { exact, variants } = index
+
+  // Rule 1: exact match
+  if (exact.has(modelId)) return exact.get(modelId)
+
+  // Rule 2: longest-prefix walk. Walk separators in reverse, slicing the original string.
+  const sepIndices = []
+  for (let i = 0; i < modelId.length; i++) {
+    if (modelId[i] === '-' || modelId[i] === '/') sepIndices.push(i)
+  }
+  for (let i = sepIndices.length - 1; i >= 0; i--) {
+    const prefix = modelId.slice(0, sepIndices[i])
+    if (!prefix) continue
+    const candidates = variants.get(prefix)
+    if (candidates && candidates.length > 0) {
+      if (candidates.length === 1) return candidates[0][1]
+      // 📖 Multiple candidates — pick the best-scoring one.
+      let best = null
+      let bestScore = -1
+      for (const [key, value] of candidates) {
+        const score = scoreCandidate(modelId, key)
+        if (score > bestScore) {
+          bestScore = score
+          best = value
+        }
+      }
+      return best
+    }
+  }
+  return null
+}
+
+// ─── Stats ────────────────────────────────────────────────────────────────────
+
+/**
+ * 📖 Aggregate stats over the catalog — used by the TUI footer chip and the
+ * 📖 web dashboard's "Catalog" panel.
+ *
+ * @returns {{
+ *   total: number,         // number of model entries (excluding _meta)
+ *   lastUpdated: string,   // from _meta.lastUpdated
+ *   source: string,        // from _meta.source
+ *   byField: Record<string, number>  // count of entries with each field non-null
+ * }}
+ */
+export function getCatalogStats() {
+  const data = loadCatalog()
+  const meta = data._meta ?? {}
+  const byField = Object.fromEntries(EXTENDED_BENCH_FIELDS.map(f => [f, 0]))
+  let total = 0
+  for (const [key, value] of Object.entries(data)) {
+    if (key === '_meta') continue
+    if (!value || typeof value !== 'object') continue
+    total++
+    for (const field of EXTENDED_BENCH_FIELDS) {
+      if (value[field] !== null && value[field] !== undefined) byField[field]++
+    }
+  }
+  return {
+    total,
+    lastUpdated: meta.lastUpdated ?? 'unknown',
+    source: meta.source ?? 'unknown',
+    byField,
+  }
+}
+
+// ─── Overlay helper ───────────────────────────────────────────────────────────
+
+/**
+ * 📖 Overlay an extended-benchmark entry onto a model/result object. The function
+ * 📖 is non-mutating by default — returns a new object. If `mutate` is true, the
+ * 📖 input is mutated in place (faster for hot paths).
+ *
+ * 📖 The overlay only adds fields the entry has. `sweScore` (curated, from
+ * 📖 sources.js) is always preserved — extended metrics are additive.
+ *
+ * @param {object} model — The result or merged-model object to overlay onto
+ * @param {object|null} entry — The extended-benchmark entry (or null = no-op)
+ * @param {object} [opts]
+ * @param {boolean} [opts.mutate=false] — Mutate `model` in place
+ * @returns {object} The same model (mutated or new) with `extendedBench` field added
+ */
+export function mergeExtendedBenchmark(model, entry, opts = {}) {
+  if (!model || typeof model !== 'object') return model
+  if (!entry || typeof entry !== 'object') {
+    // 📖 Still mark "looked up, nothing found" so the UI can show a "no data" badge
+    if (!opts.mutate) return { ...model, extendedBench: null }
+    model.extendedBench = null
+    return model
+  }
+  // 📖 Build the overlay bag — only the fields present in the entry
+  const overlay = {
+    codingIndex:    entry.codingIndex    ?? null,
+    mathIndex:      entry.mathIndex      ?? null,
+    agenticIndex:   entry.agenticIndex   ?? null,
+    reasoningIndex: entry.reasoningIndex ?? null,
+    mmluPro:        entry.mmluPro        ?? null,
+    gpqa:           entry.gpqa           ?? null,
+    hle:            entry.hle            ?? null,
+    contextWindow:  entry.contextWindow  ?? null,
+    supportsReasoning: entry.supportsReasoning === true,
+    supportsVision:    entry.supportsVision    === true,
+    lastUpdated:    entry.lastUpdated    ?? null,
+    originalModel:  entry.originalModel  ?? null,
+  }
+  if (opts.mutate) {
+    model.extendedBench = overlay
+    model.metaSourceExt = 'benchmarks.json'
+    return model
+  }
+  return { ...model, extendedBench: overlay, metaSourceExt: 'benchmarks.json' }
+}
+
+// ─── Convenience: a "lookup + merge" combo ────────────────────────────────────
+
+/**
+ * 📖 One-shot helper: look up the model id, return a new object with `extendedBench`
+ * 📖 set. Returns the model unchanged if no entry is found (so callers can blindly
+ * 📖 call it on every model in a loop).
+ *
+ * @param {object} model — Object with at least `modelId`
+ * @returns {object} Same model + `extendedBench` (may be null)
+ */
+export function enrichWithExtendedBenchmark(model) {
+  if (!model || !model.modelId) return model
+  const entry = lookupExtendedBenchmark(model.modelId)
+  return mergeExtendedBenchmark(model, entry)
+}