@kontextmind/kxm 0.7.186 → 0.7.188

package/.claude-plugin/marketplace.json

@@ -11,7 +11,7 @@
       "name": "kxm",
       "source": "./plugins/kxm",
       "description": "Durable workflows, peer agents, and kxm tui",
-      "version": "0.7.186",
+      "version": "0.7.188",
       "category": "development",
       "tags": ["kxm", "multi-agent", "workflows", "mcp"]
     }

package/.kxm/README.md

@@ -19,6 +19,7 @@ a `default` workflow, `gates.yaml` and `template-provenance.yaml`.
 | `models/inventory.yaml` | The discovered model catalog | Generated; track it for a reviewed snapshot |
 | `config.yaml` | Shared personalization settings | Tracked if the project shares them |
 | `memory/` | Project memory facts that `kxm memory` projects into `AGENTS.md`, `CLAUDE.md` and `GEMINI.md` | Tracked |
+| `knowledge/` | Authored project wiki. The hub-compiled view, when written, is `knowledge/wiki/` | Tracked |
 | `assets/` | Intentional workflow inputs and outputs; `assets/generated/` is for machine output | Tracked intentionally; `generated/` ignored |
 | `tasks/` | Task records from `kxm task` | Your choice |
 | `logs/` | Hub, worker and agent logs | Ignored |

package/CHANGELOG.md

@@ -6,6 +6,15 @@ All notable user-facing changes are documented here. The project follows [Semant
 
 ### Added
 
+- **OpenRouter model prices and the inventory refresh weekly.**
+  `.github/workflows/refresh-models.yml` runs Monday at 13:00 UTC, or on
+  demand, and opens one pull request on `automation/model-refresh` when
+  `.kxm/prices.yaml` or the OpenRouter slice of `.kxm/models/inventory.yaml`
+  changes. A model still named by `.kxm/routes.yaml` or a roster is kept when
+  it leaves the catalog, and the `model-catalog-guard` check fails until a
+  human decides. Run it locally with
+  `node --disable-warning=ExperimentalWarning --experimental-strip-types scripts/refresh-model-catalog.mjs`.
+
 - **The witnessed MG1 Python control-plane foundation is now reproducible from this repository.**
   `python/kxm-control` provides the pinned Python 3.13 uv workspace, fixed
   `kxmd` Postgres/Temporal caller, Authentik user and runner verification

package/docs/README.md

@@ -110,6 +110,7 @@ KXM connects coding agents through a durable, authenticated [hub](glossary.md#hu
 |---|---|---|
 | [Develop KXM](contributing/development.md) | Contributors | Setup, build and verify, packaging, and the repository layout |
 | [CI and release](contributing/ci-and-release.md) | Maintainers | What CI runs on each change and how releases ship |
+| [Project knowledge wiki](../.kxm/knowledge/index.md) | Maintainers | Authored notes on architecture, routing, release, and CI, with file-path sources |
 | [Write KXM documentation](contributing/writing-docs.md) | Contributors | The style rules, the page template and the docs checks |
 | [Test matrix](contributing/test-matrix.md) | Maintainers | Features and use cases mapped to automated evidence |
 | [Assignment runner](contributing/assignment-runner.md) | Maintainers | Developer assignments, witness verification and dual-critic acceptance |

package/docs/architecture/index.md

@@ -18,3 +18,4 @@ against the current checkout.
 
 - [Roadmap](../roadmap/dashboard.md)
 - [Trust model](../concepts/trust-model.md)
+- [Project knowledge wiki](../../.kxm/knowledge/architecture/overview.md)

package/docs/contributing/ci-and-release.md

@@ -46,6 +46,7 @@ together.
 | Push to `main`, or manual | `ci.yml` (Validate matrix) | `validate:pr` on Linux and Windows for Node 22.19.0 and Node 24; not on a pull request |
 | Code pull request and code push | `ci.yml` (Plugin validation) | `claude plugin validate --strict` on the marketplace and the plugin |
 | Daily at 04:00 UTC, or manual | `nightly.yml` | `test:coverage:complete`, `check`, `check:generated`, `npm pack --dry-run` |
+| Monday at 13:00 UTC, or manual | `refresh-models.yml` | Fetches the public OpenRouter catalog, and opens or updates one pull request on `automation/model-refresh` when `.kxm/prices.yaml` or `.kxm/models/inventory.yaml` changes. Uses `GITHUB_TOKEN` only, then dispatches `ci.yml` on that branch |
 | Merged pull request | `auto-release.yml` | Tags the merge commit and dispatches `release.yml` |
 | Tag push or dispatch | `release.yml` | Verifies, packs and publishes (see [Release flow](#release-flow)) |
 | Manual only | `smoke.yml` | Real Pi smoke, currently disabled (see [Smoke tests](#smoke-tests)) |
@@ -298,3 +299,4 @@ implying automated coverage.
 - [Test matrix](test-matrix.md): which test proves which behavior
 - [Write KXM documentation](writing-docs.md): doc gates and pinned paths
 - [Upgrade KXM](../operations/upgrade.md): the operator side of a new version
+- [Project knowledge wiki](../../.kxm/knowledge/index.md): authored notes for [CI](../../.kxm/knowledge/patterns/ci.md) and [release](../../.kxm/knowledge/patterns/release-flow.md)

package/docs/contributing/development.md

@@ -400,6 +400,28 @@ authentication are the protocol. A change to any of them needs:
 Prefer additive changes. KXM does not keep backward-compatible aliases for
 retired names: an old name fails closed instead.
 
+## Refresh model prices and inventory
+
+OpenRouter list prices and the model inventory are refreshed by
+`.github/workflows/refresh-models.yml` every Monday at 13:00 UTC. To run the
+same refresh before that, from the repository root:
+
+```bash
+node --disable-warning=ExperimentalWarning --experimental-strip-types scripts/refresh-model-catalog.mjs --dry-run
+```
+
+`--dry-run` prints models added, removed, and repriced, and writes nothing.
+Drop `--dry-run` to update `.kxm/prices.yaml` and `.kxm/models/inventory.yaml`.
+Exit 2 means a model named by `.kxm/routes.yaml` or a roster left the OpenRouter
+catalog; the refresh keeps that inventory row and sets `missingUpstream: true`.
+Review the diff and commit it yourself, or wait for the Monday pull request on
+`automation/model-refresh`. The field reference is
+[Weekly OpenRouter refresh](../reference/config-reference.md#weekly-openrouter-refresh).
+
+`kxm models inventory-refresh` still rewrites the whole inventory from Pi, Grok,
+agy, OpenRouter, and Nous, including a new `fetchedAt` timestamp. The weekly
+script does not call those local CLIs.
+
 ## Troubleshooting
 
 | Symptom | Cause | Fix |

package/docs/glossary.md

@@ -397,7 +397,7 @@ Project facts stored as state keys with a `proposed → current → superseded`
 
 ### Wiki
 
-Markdown pages compiled from a project's context records by `kxm context wiki-compile` (a dry run unless you pass `--out`), with state, decisions, contradictions and history linked to their evidence. `kxm context wiki-lint` checks the result.
+Markdown pages compiled from a project's context records by `kxm context wiki-compile` (a dry run unless you pass `--out`), with state, decisions, contradictions and history linked to their evidence. `kxm context wiki-lint` checks the result. This repository's authored notes live at [`.kxm/knowledge/`](../.kxm/knowledge/index.md) and are not that compiled view.
 
 ## Configuration and routing
 

package/docs/guides/context-and-memory.md

@@ -230,6 +230,8 @@ kxm context wiki-lint demo
 
 Pages land under `.kxm/knowledge/wiki/`: one page per section (`architecture`, `decisions`, `incidents`, `patterns`), a temporal-state page that keeps superseded values visible, a contradictions page, a superseded-history page and `index.md`. Every claim links its record id and source. Compilation never resolves a contradiction. Output is deterministic except the timestamp in `index.md`, so diffs stay small. `wiki-lint` checks for broken references, orphan pages, stale state links and hidden contradictions, and exits 1 on an error.
 
+This repository also keeps an authored project wiki at [`.kxm/knowledge/`](../../.kxm/knowledge/index.md). Those pages are maintainer notes with file-path sources. `kxm context wiki-compile` does not read them. With `--out`, the compiled view is still written under `.kxm/knowledge/wiki/`.
+
 ## Author Git memory
 
 Git memory is the durable, reviewed layer: facts a person has approved, versioned with the code. Each fact is a Markdown file with `kxm.memory.v1` front matter.

package/docs/reference/config-reference.md

@@ -1264,10 +1264,44 @@ file even when a source fails, and exits 1 if any source failed.
 | `models[].sources` | Which sources listed the model |
 | `models[].standard` | OpenRouter per-million rates: `inputPerMillion`, `outputPerMillion`, `cacheReadPerMillion`, `cacheWritePerMillion` |
 | `models[].discount` | Nous per-million rates, same fields |
+| `models[].missingUpstream` | `true` when the weekly refresh kept a row that OpenRouter no longer lists because a route or roster still names it |
 
 The inventory is discovery data, not admission. Admitting a route is a
 separate, reviewed change to `.kxm/routes.yaml`.
 
+### Weekly OpenRouter refresh
+
+`.github/workflows/refresh-models.yml` runs every Monday at 13:00 UTC and on
+`workflow_dispatch`. It fetches `https://openrouter.ai/api/v1/models` and
+updates the OpenRouter `standard` rates in this inventory, plus the matching
+single-tier rows in `.kxm/prices.yaml`. Nous `discount` rates and the `pi`,
+`grok`, and `agy` source blocks stay as the last `kxm models inventory-refresh`
+left them. Output is sorted by model id. `prices.yaml` `date` and the
+inventory `fetchedAt` (midnight UTC of that date) change only when the catalog
+content changes, so an unchanged week does not open a pull request.
+
+A model named by `.kxm/routes.yaml` (`admitted` or `disabled`) or by a roster
+entry in `.kxm/roles/*.yaml` is not deleted when it leaves OpenRouter. The
+refresh keeps the previous inventory row, sets `missingUpstream: true`, and
+the workflow's `model-catalog-guard` check fails. The pull request lists that
+model, and any referenced model whose input or output rate moved by more than
+20 percent, at the top. A multi-tier price row is left unchanged and called
+out the same way. `anthropic/fable` is matched through its aliases; when those
+OpenRouter rows disagree, the price row is left unchanged.
+
+Run the same refresh from a checkout:
+
+```bash
+node --disable-warning=ExperimentalWarning --experimental-strip-types scripts/refresh-model-catalog.mjs --dry-run
+node --disable-warning=ExperimentalWarning --experimental-strip-types scripts/refresh-model-catalog.mjs
+```
+
+`--dry-run` prints the summary and writes nothing. Exit 2 means a referenced
+model would be kept after leaving the catalog. The workflow pushes a non-empty
+diff to `automation/model-refresh` and opens or updates one pull request with
+`GITHUB_TOKEN`. It then dispatches `ci.yml` on that branch, because a push
+made with `GITHUB_TOKEN` does not start CI by itself.
+
 ## Personalization settings (`kxm.config.v1`)
 
 Personal and workflow preferences, merged in three layers: built-in defaults
@@ -1699,6 +1733,7 @@ Everything under `.kxm/` at the project root falls into one of three groups.
 | `roles/`, `routes.yaml`, `prices.yaml`, `modes.yaml`, `the role files` | Tracked configuration outside the bundle | You and their commands |
 | `config.yaml` | Tracked if the project wants shared preferences; otherwise ignore it | `kxm config set` |
 | `memory/`, `skills/`, `candidates/`, `goals/` | Tracked durable records | Their commands |
+| `knowledge/` | Tracked authored wiki. `knowledge/wiki/` is the compiled view from `kxm context wiki-compile --out` | Maintainers, and `kxm context wiki-compile` for `wiki/` |
 | `models/inventory.yaml` | Generated; track it if you want a reviewed snapshot | `kxm models inventory-refresh` |
 | `assets/` | Tracked intentionally; `assets/generated/` is ignored | Workflows, `kxm improve`, `kxm session start` |
 | `tasks/` | Ignored in the KXM repository; your choice | `kxm task` |

package/docs/reference/harness-routing.md

@@ -520,6 +520,21 @@ kxm models refresh
 kxm routing report --equivalent-list-cost
 ```
 
+## Weekly price and inventory refresh
+
+OpenRouter list prices in `.kxm/prices.yaml` and `.kxm/models/inventory.yaml`
+go stale as models are added, removed, and repriced. A Monday 13:00 UTC
+workflow, `.github/workflows/refresh-models.yml`, fetches the public OpenRouter
+models API and opens one pull request on `automation/model-refresh` when the
+catalog changed. The pull request body lists models added, removed, and
+repriced. A route or roster model that disappeared, or whose input or output
+rate moved by more than 20 percent, is listed first. A disappeared referenced
+model stays in the inventory with `missingUpstream: true`, and the
+`model-catalog-guard` check fails until someone removes the reference or
+restores the model.
+
+Manual run, and the file fields, are in [Weekly OpenRouter refresh](config-reference.md#weekly-openrouter-refresh). `kxm models inventory-refresh` remains the local command that also queries Pi, Grok, agy, and Nous.
+
 ## Where the code is looser than the rules
 
 These are places where the code decides less than the [routing rules](#routing-rules) say. Each one is an open operator policy question, not a defect with an obvious fix. Until it is decided, follow the rule.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kontextmind/kxm",
-  "version": "0.7.186",
+  "version": "0.7.188",
   "description": "KXM local-first multi-agent orchestration and operator dashboard",
   "type": "module",
   "author": "KontextMind",

package/plugins/kxm/.claude-plugin/plugin.json

@@ -2,7 +2,7 @@
   "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
   "name": "kxm",
   "displayName": "KXM",
-  "version": "0.7.186",
+  "version": "0.7.188",
   "description": "Headless multi-agent orchestration, durable workflows, and a live operator dashboard for Pi and Claude Code",
   "author": {
     "name": "KontextMind",

package/plugins/kxm/dist/cli.js

@@ -28793,6 +28793,32 @@ function rates(raw) {
 function modelId(id) {
   return id.trim().toLowerCase();
 }
+function blankModel(id, item) {
+  return {
+    id,
+    ...typeof item?.name === "string" ? { name: item.name } : {},
+    ...typeof item?.context_length === "number" ? { contextLength: item.context_length } : {},
+    capabilities: { thinking: { supported: null, source: "unknown" }, speed: { fast: null, source: "unknown" } },
+    sources: []
+  };
+}
+function applyAggregatorItem(current, item, source, kind) {
+  if (!current.sources.includes(source)) current.sources.push(source);
+  const parsed = rates(item.pricing);
+  if (parsed) {
+    if (kind === "standard") current.standard = parsed;
+    else current.discount = parsed;
+  }
+  if (!current.name && typeof item.name === "string") current.name = item.name;
+  if (!current.contextLength && typeof item.context_length === "number") current.contextLength = item.context_length;
+  const parameters = Array.isArray(item.supported_parameters) ? item.supported_parameters.filter((value) => typeof value === "string") : [];
+  if (parameters.some((value) => /reasoning|thinking/i.test(value))) current.capabilities.thinking = { supported: true, source };
+  if (parameters.some((value) => /speed|service.?tier|fast/i.test(value))) current.capabilities.speed = { fast: true, tiers: ["fast"], source };
+  if (Array.isArray(item.thinkingLevels) && item.thinkingLevels.length > 0) {
+    current.capabilities.thinking = { supported: true, levels: item.thinkingLevels, ...item.defaultThinking ? { default: item.defaultThinking } : {}, source };
+  }
+  if (item.fast === true) current.capabilities.speed = { fast: true, tiers: ["fast"], source };
+}
 async function fetchModels(url, authorization) {
   try {
     const headers = { Accept: "application/json" };
@@ -28814,20 +28840,8 @@ async function refreshModelInventory(options) {
   const add = (item, source, kind) => {
     if (!item || typeof item.id !== "string" || !item.id.trim()) return;
     const key = modelId(item.id);
-    const current = byId.get(key) ?? { id: item.id, ...typeof item.name === "string" ? { name: item.name } : {}, ...typeof item.context_length === "number" ? { contextLength: item.context_length } : {}, capabilities: { thinking: { supported: null, source: "unknown" }, speed: { fast: null, source: "unknown" } }, sources: [] };
-    if (!current.sources.includes(source)) current.sources.push(source);
-    const parsed = rates(item.pricing);
-    if (parsed) {
-      if (kind === "standard") current.standard = parsed;
-      else current.discount = parsed;
-    }
-    if (!current.name && typeof item.name === "string") current.name = item.name;
-    if (!current.contextLength && typeof item.context_length === "number") current.contextLength = item.context_length;
-    const parameters = Array.isArray(item.supported_parameters) ? item.supported_parameters.filter((value) => typeof value === "string") : [];
-    if (parameters.some((value) => /reasoning|thinking/i.test(value))) current.capabilities.thinking = { supported: true, source };
-    if (parameters.some((value) => /speed|service.?tier|fast/i.test(value))) current.capabilities.speed = { fast: true, tiers: ["fast"], source };
-    if (Array.isArray(item.thinkingLevels) && item.thinkingLevels.length > 0) current.capabilities.thinking = { supported: true, levels: item.thinkingLevels, ...item.defaultThinking ? { default: item.defaultThinking } : {}, source };
-    if (item.fast === true) current.capabilities.speed = { fast: true, tiers: ["fast"], source };
+    const current = byId.get(key) ?? blankModel(item.id, item);
+    applyAggregatorItem(current, item, source, kind);
     byId.set(key, current);
   };
   const native2 = async (command, args, source) => {
@@ -28860,13 +28874,14 @@ async function refreshModelInventory(options) {
   writeFileSync18(join28(options.outputRoot, ".kxm", "models", "inventory.yaml"), (0, import_yaml17.stringify)(inventory), "utf8");
   return inventory;
 }
-var import_yaml17, OR_URL, NOUS_URL;
+var import_yaml17, OPENROUTER_MODELS_URL, OR_URL, NOUS_URL;
 var init_model_inventory = __esm({
   "plugins/kxm/src/model-inventory.ts"() {
     "use strict";
     import_yaml17 = __toESM(require_dist(), 1);
     init_oneshot_process();
-    OR_URL = "https://openrouter.ai/api/v1/models";
+    OPENROUTER_MODELS_URL = "https://openrouter.ai/api/v1/models";
+    OR_URL = OPENROUTER_MODELS_URL;
     NOUS_URL = "https://inference-api.nousresearch.com/v1/models";
   }
 });

package/plugins/kxm/dist/mcp-server.js

@@ -25462,7 +25462,7 @@ function sessionTokenFixHint(policy) {
 }
 
 // plugins/kxm/src/mcp-server.ts
-var VERSION = "0.7.186";
+var VERSION = "0.7.188";
 var CONFIGURE_PLUGIN = "/plugin configure kxm@kxm";
 var inbox = /* @__PURE__ */ new Map();
 var notifiedInbox = /* @__PURE__ */ new Set();

package/plugins/kxm/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-plugin",
-  "version": "0.7.186",
+  "version": "0.7.188",
   "private": true,
   "type": "module",
   "engines": {

package/plugins/kxm/src/mcp-server.ts

@@ -11,7 +11,7 @@ import { deliverInboxNotification } from "./inbox.ts";
 import type { HubEvent, MessageRecord } from "./protocol.ts";
 import { sessionTokenFixHint } from "./session-token-hint.ts";
 
-const VERSION = "0.7.186";
+const VERSION = "0.7.188";
 const CONFIGURE_PLUGIN = "/plugin configure kxm@kxm";
 const inbox = new Map<string, MessageRecord>();
 const notifiedInbox = new Set<string>();

package/plugins/kxm/src/model-catalog-refresh.ts

@@ -0,0 +1,572 @@
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { isAlias, isMap, isSeq, parse, parseDocument, stringify, type YAMLMap } from "yaml";
+import type { PriceCatalog } from "./price-calc.ts";
+import { hashPriceCatalog, parsePriceCatalog } from "./prices.ts";
+import {
+  OPENROUTER_MODELS_URL,
+  inventoryModelFromAggregatorItem,
+  type InventoryModel,
+  type InventoryPrice,
+  type ModelInventory,
+} from "./model-inventory.ts";
+
+export { OPENROUTER_MODELS_URL };
+
+const RATE_FIELDS = ["inputPerMillion", "outputPerMillion", "cacheReadPerMillion", "cacheWritePerMillion"] as const;
+type RateField = (typeof RATE_FIELDS)[number];
+const LIST_CAP = 40;
+
+export interface CatalogReference {
+  label: string;
+  ids: readonly string[];
+}
+
+export interface RateChange {
+  field: RateField;
+  before: number | null;
+  after: number | null;
+  /** Absolute relative change. Infinite when a numeric rate becomes null or leaves zero. */
+  ratio: number;
+}
+
+export interface FlaggedModel {
+  id: string;
+  kind: "disappeared" | "repriced";
+  detail: string;
+  references: string[];
+}
+
+export interface CatalogRefreshPlan {
+  inventoryText: string;
+  pricesText: string;
+  changed: boolean;
+  guardFailed: boolean;
+  summary: string;
+  added: string[];
+  removed: string[];
+  repriced: Array<{ id: string; changes: RateChange[] }>;
+  priceRepriced: Array<{ id: string; changes: RateChange[] }>;
+  retained: FlaggedModel[];
+  flaggedRepriced: FlaggedModel[];
+  tieredUnchanged: FlaggedModel[];
+  ambiguousPrices: string[];
+  date: string;
+  pricedDate: string | null;
+}
+
+interface LoosePriceRow {
+  id: string;
+  provider: string;
+  model: string;
+  aliases?: string[];
+  tiers: Array<Record<string, unknown>>;
+}
+
+function nearlyEqual(left: number, right: number): boolean {
+  const scale = Math.max(1, Math.abs(left), Math.abs(right));
+  return Math.abs(left - right) <= 1e-8 * scale;
+}
+
+function canonicalRate(value: number | null): number | null {
+  if (value === null) return null;
+  return Number(value.toFixed(10));
+}
+
+function ratesNearlyEqual(left: InventoryPrice | undefined, right: InventoryPrice | undefined): boolean {
+  return rateChanges(left, right).length === 0;
+}
+
+export function rateChanges(before: InventoryPrice | undefined, after: InventoryPrice | undefined): RateChange[] {
+  const changes: RateChange[] = [];
+  for (const field of RATE_FIELDS) {
+    const previous = before?.[field] ?? null;
+    const next = after?.[field] ?? null;
+    if (previous === null && next === null) continue;
+    if (previous !== null && next !== null && nearlyEqual(previous, next)) continue;
+    let ratio = Infinity;
+    if (previous !== null && next !== null) {
+      ratio = previous === 0 ? (next === 0 ? 0 : Infinity) : Math.abs(next - previous) / Math.abs(previous);
+    }
+    if (ratio === 0) continue;
+    changes.push({ field, before: previous, after: next, ratio });
+  }
+  return changes;
+}
+
+function isSignificant(change: RateChange): boolean {
+  if (change.before === null) return false;
+  if (!Number.isFinite(change.ratio)) {
+    return change.field === "inputPerMillion" || change.field === "outputPerMillion";
+  }
+  return change.ratio > 0.2;
+}
+
+function expandIds(raw: string): string[] {
+  const out = new Set<string>();
+  const addOne = (value: string): void => {
+    const token = value.trim().toLowerCase();
+    if (!token || out.has(token)) return;
+    out.add(token);
+    if (token.startsWith("openrouter/")) addOne(token.slice("openrouter/".length));
+    const slash = token.indexOf("/");
+    if (slash <= 0) return;
+    const vendor = token.slice(0, slash);
+    const rest = token.slice(slash + 1);
+    if (vendor === "xai") addOne(`x-ai/${rest}`);
+    else if (vendor === "x-ai") addOne(`xai/${rest}`);
+    const effort = rest.match(/^(.*)-(low|medium|high|max)$/);
+    if (effort?.[1]) addOne(`${vendor}/${effort[1]}`);
+  };
+  addOne(raw);
+  return [...out];
+}
+
+function priceRowTokens(row: LoosePriceRow): string[] {
+  const tokens = new Set<string>();
+  const add = (value: string): void => {
+    for (const id of expandIds(value)) tokens.add(id);
+  };
+  add(row.id);
+  if (row.model.includes("/")) add(row.model);
+  else add(`${row.provider}/${row.model}`);
+  // Aliases on native and OpenRouter rows point at the catalog id. A different
+  // plan (qwen-token-plan, zai-coding-cn) keeps its own rate unless it shares a YAML anchor.
+  const trackAliases = new Set(["anthropic", "openai", "google", "xai", "openrouter"]);
+  if (trackAliases.has(row.provider)) {
+    for (const alias of row.aliases ?? []) add(alias.includes("/") ? alias : `${row.provider}/${alias}`);
+  }
+  return [...tokens];
+}
+
+function readLoosePrices(text: string): { date: string; rows: LoosePriceRow[] } {
+  const parsed = parse(text) as { date?: unknown; models?: unknown };
+  if (!parsed || typeof parsed !== "object" || !Array.isArray(parsed.models)) {
+    throw new Error("price catalog must contain a models array");
+  }
+  if (typeof parsed.date !== "string") throw new Error("price catalog date must be a string");
+  const rows: LoosePriceRow[] = parsed.models.map((item, index) => {
+    if (!item || typeof item !== "object") throw new Error(`price catalog model at index ${index} must be an object`);
+    const row = item as Record<string, unknown>;
+    if (typeof row.id !== "string" || typeof row.provider !== "string" || typeof row.model !== "string") {
+      throw new Error(`price catalog model at index ${index} is missing id, provider, or model`);
+    }
+    const aliases = Array.isArray(row.aliases) ? row.aliases.filter((alias): alias is string => typeof alias === "string") : undefined;
+    const tiers = Array.isArray(row.tiers) ? row.tiers.filter((tier): tier is Record<string, unknown> => Boolean(tier) && typeof tier === "object") : [];
+    return { id: row.id, provider: row.provider, model: row.model, ...(aliases ? { aliases } : {}), tiers };
+  });
+  return { date: parsed.date, rows };
+}
+
+function tierRates(tier: Record<string, unknown> | undefined): InventoryPrice | undefined {
+  if (!tier) return undefined;
+  const num = (value: unknown): number | null => (typeof value === "number" && Number.isFinite(value) ? value : null);
+  const input = num(tier.inputPerMillion);
+  const output = num(tier.outputPerMillion);
+  if (input === null && output === null) return undefined;
+  return {
+    inputPerMillion: input,
+    outputPerMillion: output,
+    cacheReadPerMillion: num(tier.cacheReadPerMillion),
+    cacheWritePerMillion: num(tier.cacheWritePerMillion),
+  };
+}
+
+function formatRate(value: number | null): string {
+  if (value === null) return "none";
+  if (Number.isInteger(value)) return String(value);
+  return String(Number(value.toFixed(10)));
+}
+
+function formatRatio(change: RateChange): string {
+  if (!Number.isFinite(change.ratio) || change.before === null || change.after === null || change.before === 0) return "";
+  const signed = (change.after - change.before) / Math.abs(change.before);
+  const pct = Math.round(signed * 1000) / 10;
+  const text = Number.isInteger(pct) ? String(pct) : pct.toFixed(1);
+  return ` (${pct > 0 ? "+" : ""}${text}%)`;
+}
+
+export function formatRateChanges(changes: readonly RateChange[]): string {
+  return changes.map((change) => `${change.field} ${formatRate(change.before)} → ${formatRate(change.after)}${formatRatio(change)}`).join(", ");
+}
+
+function remember(map: Map<string, string[]>, token: string, label: string): void {
+  const labels = map.get(token) ?? [];
+  if (!labels.includes(label)) labels.push(label);
+  map.set(token, labels);
+}
+
+function labelsFor(map: Map<string, string[]>, id: string): string[] {
+  const labels = new Set<string>();
+  for (const token of expandIds(id)) {
+    for (const label of map.get(token) ?? []) labels.add(label);
+  }
+  return [...labels].sort((left, right) => left.localeCompare(right));
+}
+
+function indexOpenRouter(items: readonly unknown[]): Map<string, InventoryModel> {
+  const byId = new Map<string, InventoryModel>();
+  for (const item of items) {
+    const model = inventoryModelFromAggregatorItem(item, "openrouter", "standard");
+    if (!model) continue;
+    byId.set(model.id.toLowerCase(), model);
+  }
+  if (byId.size === 0) throw new Error("OpenRouter catalog is empty");
+  return byId;
+}
+
+function assignRates(target: InventoryPrice, incoming: InventoryPrice): boolean {
+  let changed = false;
+  for (const field of RATE_FIELDS) {
+    const before = target[field];
+    const after = canonicalRate(incoming[field]);
+    if (before === null && after === null) continue;
+    if (before !== null && after !== null && nearlyEqual(before, after)) continue;
+    target[field] = after;
+    changed = true;
+  }
+  return changed;
+}
+
+function desiredRates(matches: readonly InventoryModel[]): { rates?: InventoryPrice; ambiguous: boolean } {
+  const priced = matches.filter((model) => model.standard);
+  if (priced.length === 0) return { ambiguous: false };
+  const first = priced[0]?.standard;
+  if (!first) return { ambiguous: false };
+  const ambiguous = priced.slice(1).some((model) => !ratesNearlyEqual(first, model.standard));
+  return ambiguous ? { ambiguous: true } : { rates: first, ambiguous: false };
+}
+
+function writeTierRates(map: YAMLMap, previous: InventoryPrice, incoming: InventoryPrice): boolean {
+  let changed = false;
+  for (const field of RATE_FIELDS) {
+    const before = previous[field];
+    const after = canonicalRate(incoming[field]);
+    if (before === null && after === null) continue;
+    if (before !== null && after !== null && nearlyEqual(before, after)) continue;
+    map.set(field, after);
+    changed = true;
+  }
+  return changed;
+}
+
+function updatePrices(text: string, updates: Map<string, InventoryPrice>, date: string): { text: string; dateChanged: boolean } {
+  if (updates.size === 0) return { text, dateChanged: false };
+  const doc = parseDocument(text);
+  const models = doc.get("models", true);
+  if (!isSeq(models)) throw new Error("price catalog models must be a sequence");
+  const maps = new Map<string, YAMLMap>();
+  let wrote = false;
+  for (const row of models.items) {
+    if (!isMap(row)) continue;
+    const tiers = row.get("tiers", true);
+    if (!isSeq(tiers) || tiers.items.length !== 1) continue;
+    const tier = tiers.items[0];
+    if (isMap(tier) && tier.anchor) maps.set(String(tier.anchor), tier);
+  }
+  const seen = new Set<YAMLMap>();
+  for (const row of models.items) {
+    if (!isMap(row)) continue;
+    const id = row.get("id");
+    if (typeof id !== "string" || !updates.has(id)) continue;
+    const incoming = updates.get(id);
+    if (!incoming) continue;
+    const tiers = row.get("tiers", true);
+    if (!isSeq(tiers) || tiers.items.length !== 1) continue;
+    const tier = tiers.items[0];
+    const target = isMap(tier) ? tier : (isAlias(tier) ? maps.get(String(tier.source)) : undefined);
+    if (!target || seen.has(target)) continue;
+    seen.add(target);
+    const previous = tierRates(target.toJSON() as Record<string, unknown>);
+    if (!previous) continue;
+    if (writeTierRates(target, previous, incoming)) wrote = true;
+  }
+  if (!wrote) return { text, dateChanged: false };
+  doc.set("date", date);
+  const draft = doc.toString();
+  const body = parse(draft) as { sha256?: string; schema: "kxm.prices.v1"; date: string; currency?: string; models: LoosePriceRow[] };
+  const { sha256: _ignored, ...rest } = body;
+  doc.set("sha256", hashPriceCatalog(rest as unknown as Omit<PriceCatalog, "sha256">));
+  const next = doc.toString();
+  parsePriceCatalog(next);
+  return { text: next, dateChanged: true };
+}
+
+function listLines(title: string, ids: readonly string[]): string[] {
+  const lines = [`- ${title}: ${ids.length}`];
+  const shown = ids.slice(0, LIST_CAP);
+  for (const id of shown) lines.push(`  - \`${id}\``);
+  if (ids.length > LIST_CAP) lines.push(`  - … and ${ids.length - LIST_CAP} more`);
+  return lines;
+}
+
+export function renderCatalogSummary(plan: Omit<CatalogRefreshPlan, "summary">): string {
+  const lines: string[] = ["## Needs a human", ""];
+  if (plan.retained.length === 0 && plan.flaggedRepriced.length === 0 && plan.tieredUnchanged.length === 0) {
+    lines.push("No admitted route or roster model disappeared or was repriced by more than 20%.");
+  } else {
+    for (const flag of plan.retained) {
+      lines.push(`- **Disappeared, kept:** \`${flag.id}\` — ${flag.references.join("; ") || "referenced model"}`);
+    }
+    for (const flag of plan.flaggedRepriced) {
+      lines.push(`- **Repriced more than 20%:** \`${flag.id}\` ${flag.detail}${flag.references.length ? ` — ${flag.references.join("; ")}` : ""}`);
+    }
+    for (const flag of plan.tieredUnchanged) {
+      lines.push(`- **Tiered price left unchanged:** \`${flag.id}\` ${flag.detail}${flag.references.length ? ` — ${flag.references.join("; ")}` : ""}`);
+    }
+  }
+  lines.push("", "## Inventory", "");
+  lines.push(...listLines("Added", plan.added));
+  lines.push(...listLines("Removed", plan.removed));
+  lines.push(`- Repriced: ${plan.repriced.length}`);
+  for (const row of plan.repriced.slice(0, LIST_CAP)) lines.push(`  - \`${row.id}\` ${formatRateChanges(row.changes)}`);
+  if (plan.repriced.length > LIST_CAP) lines.push(`  - … and ${plan.repriced.length - LIST_CAP} more`);
+  lines.push("", "## Prices", "");
+  lines.push(`- Repriced: ${plan.priceRepriced.length}`);
+  for (const row of plan.priceRepriced.slice(0, LIST_CAP)) lines.push(`  - \`${row.id}\` ${formatRateChanges(row.changes)}`);
+  if (plan.priceRepriced.length > LIST_CAP) lines.push(`  - … and ${plan.priceRepriced.length - LIST_CAP} more`);
+  if (plan.pricedDate) lines.push(`- Date: ${plan.pricedDate}`);
+  if (plan.ambiguousPrices.length > 0) {
+    lines.push(`- Ambiguous OpenRouter matches left unchanged: ${plan.ambiguousPrices.length}`);
+    for (const id of plan.ambiguousPrices.slice(0, LIST_CAP)) lines.push(`  - \`${id}\``);
+  }
+  lines.push("");
+  return lines.join("\n");
+}
+
+function sortFlags(flags: FlaggedModel[]): FlaggedModel[] {
+  return flags.sort((left, right) => left.id.localeCompare(right.id));
+}
+
+/**
+ * Applies an OpenRouter models payload to the checked-in inventory and price catalog.
+ * The dated price field and inventory `fetchedAt` change only when the catalog content changes.
+ * `fetchedAt` is midnight UTC on `date`, not a clock timestamp.
+ */
+export function planModelCatalogRefresh(input: {
+  inventory: ModelInventory;
+  inventoryText: string;
+  pricesText: string;
+  openRouterItems: readonly unknown[];
+  references: readonly CatalogReference[];
+  date: string;
+  openRouterUrl?: string;
+}): CatalogRefreshPlan {
+  if (!/^\d{4}-\d{2}-\d{2}$/.test(input.date)) throw new Error("date must be YYYY-MM-DD");
+  const feed = indexOpenRouter(input.openRouterItems);
+  const loose = readLoosePrices(input.pricesText);
+  const labelMap = new Map<string, string[]>();
+  for (const reference of input.references) {
+    for (const id of reference.ids) {
+      for (const token of expandIds(id)) remember(labelMap, token, reference.label);
+    }
+  }
+  for (const row of loose.rows) {
+    const tokens = priceRowTokens(row);
+    const labels = [...new Set(tokens.flatMap((token) => labelMap.get(token) ?? []))].sort((left, right) => left.localeCompare(right));
+    if (labels.length === 0) continue;
+    for (const token of tokens) {
+      for (const label of labels) remember(labelMap, token, label);
+    }
+  }
+  const referenced = (id: string): string[] => labelsFor(labelMap, id);
+
+  const next = structuredClone(input.inventory) as ModelInventory;
+  const previousRates = new Map(input.inventory.models.map((model) => [model.id, model.standard ? { ...model.standard } : undefined]));
+  const present = new Set(feed.keys());
+  const added: string[] = [];
+  const removed: string[] = [];
+  const retained: FlaggedModel[] = [];
+
+  for (const [id, incoming] of feed) {
+    const current = next.models.find((model) => model.id.toLowerCase() === id);
+    if (!current) {
+      const created: InventoryModel = {
+        id: incoming.id,
+        ...(incoming.name ? { name: incoming.name } : {}),
+        ...(incoming.contextLength !== undefined ? { contextLength: incoming.contextLength } : {}),
+        capabilities: incoming.capabilities,
+        sources: ["openrouter"],
+        ...(incoming.standard ? { standard: incoming.standard } : {}),
+      };
+      next.models.push(created);
+      added.push(incoming.id);
+      continue;
+    }
+    if (incoming.standard) {
+      if (current.standard) assignRates(current.standard, incoming.standard);
+      else current.standard = { ...incoming.standard };
+    }
+    if (!current.sources.includes("openrouter")) current.sources.push("openrouter");
+    if (!current.name && incoming.name) current.name = incoming.name;
+    if (current.contextLength === undefined && incoming.contextLength !== undefined) current.contextLength = incoming.contextLength;
+    if (current.missingUpstream) delete current.missingUpstream;
+  }
+
+  next.models = next.models.filter((model) => {
+    const key = model.id.toLowerCase();
+    if (present.has(key) || !model.sources.includes("openrouter")) return true;
+    const references = referenced(model.id);
+    if (references.length > 0) {
+      if (!model.missingUpstream) {
+        model.missingUpstream = true;
+        retained.push({ id: model.id, kind: "disappeared", detail: "left the OpenRouter catalog; previous row kept", references });
+      }
+      return true;
+    }
+    model.sources = model.sources.filter((source) => source !== "openrouter");
+    delete model.standard;
+    if (model.sources.length === 0) {
+      removed.push(model.id);
+      return false;
+    }
+    return true;
+  });
+  next.models.sort((left, right) => left.id.localeCompare(right.id));
+  added.sort((left, right) => left.localeCompare(right));
+  removed.sort((left, right) => left.localeCompare(right));
+
+  const url = input.openRouterUrl ?? OPENROUTER_MODELS_URL;
+  const source = next.sources.openrouter ?? { url, ok: true };
+  if (source.url !== url || source.ok !== true || source.error) {
+    next.sources.openrouter = { url, ok: true };
+  } else if (source !== next.sources.openrouter) {
+    next.sources.openrouter = source;
+  }
+
+  const repriced: Array<{ id: string; changes: RateChange[] }> = [];
+  const flaggedRepriced: FlaggedModel[] = [];
+  for (const model of next.models) {
+    if (!previousRates.has(model.id)) continue;
+    const changes = rateChanges(previousRates.get(model.id), model.standard);
+    if (changes.length === 0) continue;
+    repriced.push({ id: model.id, changes });
+    if (!changes.some(isSignificant)) continue;
+    const references = referenced(model.id);
+    if (references.length === 0) continue;
+    flaggedRepriced.push({ id: model.id, kind: "repriced", detail: formatRateChanges(changes), references });
+  }
+  repriced.sort((left, right) => left.id.localeCompare(right.id));
+
+  const priceUpdates = new Map<string, InventoryPrice>();
+  const tieredUnchanged: FlaggedModel[] = [];
+  const ambiguousPrices: string[] = [];
+  const beforeTiers = new Map(loose.rows.map((row) => [row.id, tierRates(row.tiers[0])]));
+  for (const row of loose.rows) {
+    const matched = new Map<string, InventoryModel>();
+    for (const token of priceRowTokens(row)) {
+      const hit = feed.get(token);
+      if (hit) matched.set(hit.id.toLowerCase(), hit);
+    }
+    const desired = desiredRates([...matched.values()].sort((left, right) => left.id.localeCompare(right.id)));
+    const current = beforeTiers.get(row.id);
+    if (desired.ambiguous) {
+      ambiguousPrices.push(row.id);
+      continue;
+    }
+    if (!desired.rates || !current) continue;
+    const canonical: InventoryPrice = {
+      inputPerMillion: canonicalRate(desired.rates.inputPerMillion),
+      outputPerMillion: canonicalRate(desired.rates.outputPerMillion),
+      cacheReadPerMillion: canonicalRate(desired.rates.cacheReadPerMillion),
+      cacheWritePerMillion: canonicalRate(desired.rates.cacheWritePerMillion),
+    };
+    const changes = rateChanges(current, canonical);
+    if (changes.length === 0) continue;
+    const references = referenced(row.id);
+    if (row.tiers.length !== 1) {
+      if (references.length > 0 && changes.some(isSignificant)) {
+        tieredUnchanged.push({ id: row.id, kind: "repriced", detail: formatRateChanges(changes), references });
+      }
+      continue;
+    }
+    priceUpdates.set(row.id, canonical);
+  }
+  ambiguousPrices.sort((left, right) => left.localeCompare(right));
+
+  const priced = updatePrices(input.pricesText, priceUpdates, input.date);
+  const priceRepriced: Array<{ id: string; changes: RateChange[] }> = [];
+  for (const row of readLoosePrices(priced.text).rows) {
+    const changes = rateChanges(beforeTiers.get(row.id), tierRates(row.tiers[0]));
+    if (changes.length === 0) continue;
+    priceRepriced.push({ id: row.id, changes });
+    const references = referenced(row.id);
+    if (references.length > 0 && changes.some(isSignificant)) {
+      flaggedRepriced.push({ id: row.id, kind: "repriced", detail: formatRateChanges(changes), references });
+    }
+  }
+  priceRepriced.sort((left, right) => left.id.localeCompare(right.id));
+  const inventoryChanged = JSON.stringify({ sources: next.sources, models: next.models }) !== JSON.stringify({ sources: input.inventory.sources, models: input.inventory.models });
+  let inventoryText = input.inventoryText;
+  if (inventoryChanged) {
+    next.fetchedAt = `${input.date}T00:00:00.000Z`;
+    inventoryText = stringify(next);
+  }
+  const pricedDate = priced.dateChanged ? `${loose.date} → ${input.date}` : null;
+  const plan: Omit<CatalogRefreshPlan, "summary"> = {
+    inventoryText,
+    pricesText: priced.text,
+    changed: inventoryText !== input.inventoryText || priced.text !== input.pricesText,
+    guardFailed: retained.length > 0,
+    added,
+    removed,
+    repriced,
+    priceRepriced,
+    retained: sortFlags(retained),
+    flaggedRepriced: sortFlags(flaggedRepriced),
+    tieredUnchanged: sortFlags(tieredUnchanged),
+    ambiguousPrices,
+    date: input.date,
+    pricedDate,
+  };
+  return { ...plan, summary: renderCatalogSummary(plan) };
+}
+
+export function loadCatalogReferences(root: string): CatalogReference[] {
+  const references: CatalogReference[] = [];
+  const routesPath = join(root, ".kxm", "routes.yaml");
+  if (!existsSync(routesPath)) throw new Error(`missing ${routesPath}`);
+  const routes = parse(readFileSync(routesPath, "utf8")) as { admitted?: unknown; disabled?: unknown };
+  const collect = (ids: unknown, kind: "admitted" | "disabled"): void => {
+    if (!Array.isArray(ids)) return;
+    for (const id of ids) {
+      if (typeof id !== "string" || !id) continue;
+      references.push({ label: `routes.yaml ${kind} \`${id}\``, ids: [id] });
+    }
+  };
+  collect(routes.admitted, "admitted");
+  collect(routes.disabled, "disabled");
+  const rolesDir = join(root, ".kxm", "roles");
+  if (!existsSync(rolesDir)) return references;
+  for (const file of readdirSync(rolesDir).filter((name) => name.endsWith(".yaml")).sort()) {
+    const role = parse(readFileSync(join(rolesDir, file), "utf8")) as { id?: unknown; roster?: unknown };
+    const roleId = typeof role.id === "string" ? role.id : file.replace(/\.yaml$/, "");
+    if (!Array.isArray(role.roster)) continue;
+    for (const entry of role.roster) {
+      if (!entry || typeof entry !== "object") continue;
+      const route = (entry as { route?: unknown }).route;
+      if (typeof route !== "string" || !route) continue;
+      const ids = [route];
+      const modelPath = join(root, ".kxm", "models", `${route}.yaml`);
+      if (existsSync(modelPath)) {
+        const model = parse(readFileSync(modelPath, "utf8")) as { model?: unknown; vendor?: unknown };
+        if (typeof model.model === "string" && model.model) {
+          ids.push(model.model);
+          if (typeof model.vendor === "string" && model.vendor && !model.model.includes("/")) ids.push(`${model.vendor}/${model.model}`);
+        }
+      }
+      references.push({ label: `roster ${roleId} \`${route}\``, ids });
+    }
+  }
+  return references;
+}
+
+export function readCatalogFiles(root: string): { inventory: ModelInventory; inventoryText: string; pricesText: string } {
+  const inventoryText = readFileSync(join(root, ".kxm", "models", "inventory.yaml"), "utf8");
+  const pricesText = readFileSync(join(root, ".kxm", "prices.yaml"), "utf8");
+  const inventory = parse(inventoryText) as ModelInventory;
+  if (inventory.schema !== "kxm.model-inventory.v1" || !Array.isArray(inventory.models)) {
+    throw new Error("inventory.yaml is not a kxm.model-inventory.v1 catalog");
+  }
+  return { inventory, inventoryText, pricesText };
+}

package/plugins/kxm/src/model-inventory.ts

@@ -23,6 +23,8 @@ export interface InventoryModel {
   standard?: InventoryPrice;
   discount?: InventoryPrice;
   sources: string[];
+  /** Set when a referenced model left the OpenRouter catalog and the refresh kept the previous row. */
+  missingUpstream?: true;
 }
 
 export interface ModelInventory {
@@ -33,7 +35,8 @@ export interface ModelInventory {
   models: InventoryModel[];
 }
 
-const OR_URL = "https://openrouter.ai/api/v1/models";
+export const OPENROUTER_MODELS_URL = "https://openrouter.ai/api/v1/models";
+const OR_URL = OPENROUTER_MODELS_URL;
 const NOUS_URL = "https://inference-api.nousresearch.com/v1/models";
 
 function price(value: unknown): number | null {
@@ -56,6 +59,42 @@ function rates(raw: any): InventoryPrice | undefined {
 function modelId(id: string): string {
   return id.trim().toLowerCase();
 }
+
+function blankModel(id: string, item?: { name?: unknown; context_length?: unknown }): InventoryModel {
+  return {
+    id,
+    ...(typeof item?.name === "string" ? { name: item.name } : {}),
+    ...(typeof item?.context_length === "number" ? { contextLength: item.context_length } : {}),
+    capabilities: { thinking: { supported: null, source: "unknown" }, speed: { fast: null, source: "unknown" } },
+    sources: [],
+  };
+}
+
+function applyAggregatorItem(current: InventoryModel, item: any, source: string, kind: "standard" | "discount"): void {
+  if (!current.sources.includes(source)) current.sources.push(source);
+  const parsed = rates(item.pricing);
+  if (parsed) {
+    if (kind === "standard") current.standard = parsed;
+    else current.discount = parsed;
+  }
+  if (!current.name && typeof item.name === "string") current.name = item.name;
+  if (!current.contextLength && typeof item.context_length === "number") current.contextLength = item.context_length;
+  const parameters = Array.isArray(item.supported_parameters) ? item.supported_parameters.filter((value: unknown): value is string => typeof value === "string") : [];
+  if (parameters.some((value: string) => /reasoning|thinking/i.test(value))) current.capabilities.thinking = { supported: true, source };
+  if (parameters.some((value: string) => /speed|service.?tier|fast/i.test(value))) current.capabilities.speed = { fast: true, tiers: ["fast"], source };
+  if (Array.isArray(item.thinkingLevels) && item.thinkingLevels.length > 0) {
+    current.capabilities.thinking = { supported: true, levels: item.thinkingLevels, ...(item.defaultThinking ? { default: item.defaultThinking } : {}), source };
+  }
+  if (item.fast === true) current.capabilities.speed = { fast: true, tiers: ["fast"], source };
+}
+
+/** One OpenRouter or Nous payload row, using the same price and capability rules as inventory refresh. */
+export function inventoryModelFromAggregatorItem(item: any, source: string, kind: "standard" | "discount"): InventoryModel | undefined {
+  if (!item || typeof item.id !== "string" || !item.id.trim()) return undefined;
+  const current = blankModel(item.id, item);
+  applyAggregatorItem(current, item, source, kind);
+  return current;
+}
 async function fetchModels(url: string, authorization?: string): Promise<{ data: any[]; error?: string }> {
   try {
     const headers: Record<string, string> = { Accept: "application/json" };
@@ -79,20 +118,8 @@ export async function refreshModelInventory(options: { outputRoot: string; env?:
   const add = (item: any, source: string, kind: "standard" | "discount") => {
     if (!item || typeof item.id !== "string" || !item.id.trim()) return;
     const key = modelId(item.id);
-    const current: InventoryModel = byId.get(key) ?? { id: item.id, ...(typeof item.name === "string" ? { name: item.name } : {}), ...(typeof item.context_length === "number" ? { contextLength: item.context_length } : {}), capabilities: { thinking: { supported: null, source: "unknown" }, speed: { fast: null, source: "unknown" } }, sources: [] };
-    if (!current.sources.includes(source)) current.sources.push(source);
-    const parsed = rates(item.pricing);
-    if (parsed) {
-      if (kind === "standard") current.standard = parsed;
-      else current.discount = parsed;
-    }
-    if (!current.name && typeof item.name === "string") current.name = item.name;
-    if (!current.contextLength && typeof item.context_length === "number") current.contextLength = item.context_length;
-    const parameters = Array.isArray(item.supported_parameters) ? item.supported_parameters.filter((value: unknown): value is string => typeof value === "string") : [];
-    if (parameters.some((value: string) => /reasoning|thinking/i.test(value))) current.capabilities.thinking = { supported: true, source };
-    if (parameters.some((value: string) => /speed|service.?tier|fast/i.test(value))) current.capabilities.speed = { fast: true, tiers: ["fast"], source };
-    if (Array.isArray(item.thinkingLevels) && item.thinkingLevels.length > 0) current.capabilities.thinking = { supported: true, levels: item.thinkingLevels, ...(item.defaultThinking ? { default: item.defaultThinking } : {}), source };
-    if (item.fast === true) current.capabilities.speed = { fast: true, tiers: ["fast"], source };
+    const current = byId.get(key) ?? blankModel(item.id, item);
+    applyAggregatorItem(current, item, source, kind);
     byId.set(key, current);
   };
   const native = async (command: string, args: string[], source: string) => {

package/scripts/refresh-model-catalog.mjs

@@ -0,0 +1,67 @@
+#!/usr/bin/env node
+// Refresh .kxm/prices.yaml and the OpenRouter slice of .kxm/models/inventory.yaml.
+// Usage:
+//   node --disable-warning=ExperimentalWarning --experimental-strip-types scripts/refresh-model-catalog.mjs [--dry-run] [--json] [--date YYYY-MM-DD] [--root dir] [--openrouter-file path]
+import { readFileSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { OPENROUTER_MODELS_URL, loadCatalogReferences, planModelCatalogRefresh, readCatalogFiles } from "../plugins/kxm/src/model-catalog-refresh.ts";
+
+const args = process.argv.slice(2);
+const option = (name) => {
+  const index = args.indexOf(name);
+  return index >= 0 ? args[index + 1] : undefined;
+};
+const dryRun = args.includes("--dry-run");
+const json = args.includes("--json");
+const root = resolve(option("--root") ?? process.cwd());
+const date = option("--date") ?? new Date().toISOString().slice(0, 10);
+const fixture = option("--openrouter-file");
+
+async function loadOpenRouter() {
+  if (fixture) return JSON.parse(readFileSync(resolve(fixture), "utf8"));
+  const url = process.env.KXM_OPENROUTER_MODELS_URL?.trim() || OPENROUTER_MODELS_URL;
+  const headers = { Accept: "application/json" };
+  if (process.env.OPENROUTER_API_KEY?.trim()) headers.Authorization = `Bearer ${process.env.OPENROUTER_API_KEY.trim()}`;
+  const response = await fetch(url, { headers, signal: AbortSignal.timeout(60_000) });
+  if (!response.ok) throw new Error(`OpenRouter models request failed: HTTP ${response.status}`);
+  const payload = await response.json();
+  if (!payload || typeof payload !== "object" || !Array.isArray(payload.data)) {
+    throw new Error("OpenRouter models response has no data array");
+  }
+  return payload.data;
+}
+
+const items = await loadOpenRouter();
+const catalog = readCatalogFiles(root);
+const plan = planModelCatalogRefresh({
+  ...catalog,
+  openRouterItems: items,
+  references: loadCatalogReferences(root),
+  date,
+  openRouterUrl: process.env.KXM_OPENROUTER_MODELS_URL?.trim() || OPENROUTER_MODELS_URL,
+});
+
+if (!dryRun && plan.changed) {
+  writeFileSync(resolve(root, ".kxm", "models", "inventory.yaml"), plan.inventoryText);
+  writeFileSync(resolve(root, ".kxm", "prices.yaml"), plan.pricesText);
+}
+
+const report = {
+  ok: !plan.guardFailed,
+  changed: plan.changed,
+  guardFailed: plan.guardFailed,
+  dryRun,
+  date,
+  added: plan.added,
+  removed: plan.removed,
+  repriced: plan.repriced.map((row) => row.id),
+  priceRepriced: plan.priceRepriced.map((row) => row.id),
+  retained: plan.retained.map((row) => row.id),
+  flaggedRepriced: plan.flaggedRepriced.map((row) => row.id),
+  summary: plan.summary,
+};
+
+if (json) console.log(JSON.stringify(report, null, 2));
+else console.log(plan.summary);
+
+process.exitCode = plan.guardFailed ? 2 : 0;