@oh-my-pi/pi-catalog 17.2.1 → 17.2.3

package/CHANGELOG.md

@@ -2,6 +2,31 @@
 
 ## [Unreleased]
 
+### Fixed
+
+- Fixed `gen:models` Codex discovery to union models across every stored OAuth account and fail closed on partial resolution, matching runtime discovery ([#6265](https://github.com/can1357/oh-my-pi/issues/6265)); restored the bundled `gpt-5.4`, `gpt-5.6-sol`, and `gpt-5.3-codex-spark` entries a single-account regen had dropped.
+
+## [17.2.3] - 2026-08-01
+
+### Added
+
+- Added support for the ai& provider (`aiand`), an OpenAI-compatible inference API with dynamic model discovery (context windows, capabilities, reasoning efforts, and USD pricing from `/v1/models`) and API-key authentication via the `AIAND_API_KEY` environment variable.
+
+## [17.2.2] - 2026-07-31
+
+### Added
+
+- Added support for the GMI Cloud provider (`gmi-cloud`), an OpenAI-compatible inference gateway with dynamic model discovery and API-key authentication via the `GMI_API_KEY` environment variable.
+- Added optional authoritative context occupancy to usage records for providers with separate checkpoint telemetry and billable token buckets.
+
+### Fixed
+
+- Fixed classification of dynamically discovered Cursor Kimi K3 effort variants as non-reasoning models when `thinkingDetails` is omitted.
+- Fixed Google AI Studio OpenAI-compatible requests failing with HTTP 400 by omitting the unsupported `store` field.
+- Fixed Synthetic models losing capabilities (such as reasoning/thinking selectors, vision input, output limits, and pricing) by correcting how the discovery mapper parses Synthetic's advertised features, effort vocabularies, and pricing structures.
+- Fixed Cursor model discovery to correctly expose the 1M-token context window for supported models (including Claude, GPT, Kimi K3, and GLM 5.2+ families) instead of defaulting to 200k.
+- Fixed GitHub Copilot routing for `grok-4.5` to use the correct Responses endpoint instead of the unsupported Chat Completions endpoint.
+
 ## [17.2.1] - 2026-07-30
 
 ### Fixed

package/README.md

@@ -4,24 +4,24 @@ Model catalog for [oh-my-pi](https://github.com/can1357/oh-my-pi): bundled model
 
 ## What's inside
 
-| Module | Purpose |
-| --- | --- |
-| `models.json` + `models` | Bundled model database (pricing, context windows, modalities, thinking support) |
-| `provider-models` | Provider catalog descriptors (`CATALOG_PROVIDERS`), per-provider model resolution rules |
-| `discovery` | Runtime model discovery for OpenAI-compatible endpoints, Gemini, Codex, Cursor, Antigravity, Ollama |
-| `identity` | Model id parsing and classification (family/version), reference resolution, equivalence, selection priority |
-| `model-thinking` | Thinking/reasoning metadata and generated per-model policies |
-| `model-manager` / `model-cache` | Runtime model registry with discovery refresh and on-disk caching |
-| `variant-collapse` | Collapsing provider-specific variants of the same underlying model |
-| `compat` | Request/response compatibility fixups for OpenAI- and Anthropic-shaped APIs |
-| `wire` | Wire-level helpers: Codex, Gemini headers, GitHub Copilot |
-| `effort` | Reasoning-effort level definitions |
+| Module                          | Purpose                                                                                                     |
+| ------------------------------- | ----------------------------------------------------------------------------------------------------------- |
+| `models.json` + `models`        | Bundled model database (pricing, context windows, modalities, thinking support)                             |
+| `provider-models`               | Provider catalog descriptors (`CATALOG_PROVIDERS`), per-provider model resolution rules                     |
+| `discovery`                     | Runtime model discovery for OpenAI-compatible endpoints, Gemini, Codex, Cursor, Antigravity, Ollama         |
+| `identity`                      | Model id parsing and classification (family/version), reference resolution, equivalence, selection priority |
+| `model-thinking`                | Thinking/reasoning metadata and generated per-model policies                                                |
+| `model-manager` / `model-cache` | Runtime model registry with discovery refresh and on-disk caching                                           |
+| `variant-collapse`              | Collapsing provider-specific variants of the same underlying model                                          |
+| `compat`                        | Request/response compatibility fixups for OpenAI- and Anthropic-shaped APIs                                 |
+| `wire`                          | Wire-level helpers: Codex, Gemini headers, GitHub Copilot                                                   |
+| `effort`                        | Reasoning-effort level definitions                                                                          |
 
 Import from subpaths (`@oh-my-pi/pi-catalog/<module>`) or the root barrel.
 
 ## models.json is generated
 
-Never edit `src/models.json` by hand — it is produced from upstream sources (models.dev, provider catalog discovery, OpenCode docs) by `scripts/generate-models.ts` and the resolvers in `src/provider-models/`. Regenerate with:
+Never edit `src/models.json` by hand — it is produced from upstream sources (stencil.so, provider catalog discovery, OpenCode docs) by `scripts/generate-models.ts` and the resolvers in `src/provider-models/`. Regenerate with:
 
 ```sh
 bun run gen:models

package/dist/types/hosts.d.ts

@@ -115,6 +115,11 @@ export declare const KNOWN_HOSTS: {
         readonly providers: readonly ["moonshot", "kimi-code"];
         readonly urlMarkers: readonly ["api.moonshot.ai", "api.kimi.com"];
     };
+    /** Google AI Studio's OpenAI-compatible shim (`/v1beta/openai`) — a subset of chat-completions; rejects `store` with a 400. Native Gemini uses `google-generative-ai` api instead. */
+    readonly googleAistudio: {
+        readonly providers: readonly [];
+        readonly urlMarkers: readonly ["generativelanguage.googleapis.com"];
+    };
     readonly opencode: {
         readonly providers: readonly ["opencode-go", "opencode-zen"];
         readonly urlMarkers: readonly ["opencode.ai"];

package/dist/types/model-manager.d.ts

@@ -4,10 +4,10 @@ import type { Api, Model, ModelSpec, Provider } from "./types.js";
  */
 export type ModelRefreshStrategy = "online" | "offline" | "online-if-uncached";
 /**
- * Hook for loading and mapping models.dev fallback data into canonical model objects.
+ * Hook for loading and mapping stencil.so fallback data into canonical model objects.
  */
 export interface ModelsDevFallback<TApi extends Api = Api, TPayload = unknown> {
-    /** Fetches raw fallback payload (for example from models.dev). */
+    /** Fetches raw fallback payload (for example from stencil.so). */
     fetch(): Promise<TPayload>;
     /** Maps payload into provider models. */
     map(payload: TPayload, providerId: Provider): readonly ModelSpec<TApi>[];
@@ -28,7 +28,7 @@ export interface ModelManagerOptions<TApi extends Api = Api, TModelsDevPayload =
     cacheTtlMs?: number;
     /** When true, a successful dynamic fetch is the complete provider catalog and prunes static-only models. */
     dynamicModelsAuthoritative?: boolean;
-    /** Cached model ids to ignore when the cache was written against a different static catalog fingerprint. */
+    /** Cached model ids whose presence forces refresh when the static or migration-policy fingerprint changes. */
     dropCachedModelIdsOnStaticMismatch?: readonly string[];
     /**
      * Trusted, provider-wide request headers (compile-time constants, never
@@ -40,7 +40,7 @@ export interface ModelManagerOptions<TApi extends Api = Api, TModelsDevPayload =
     restorableHeaderFallback?: Record<string, string>;
     /** Optional dynamic endpoint fetcher. */
     fetchDynamicModels?: () => Promise<readonly ModelSpec<TApi>[] | null>;
-    /** Optional models.dev fallback hook. */
+    /** Optional stencil.so fallback hook. */
     modelsDev?: ModelsDevFallback<TApi, TModelsDevPayload>;
     /** Clock override for deterministic tests. */
     now?: () => number;
@@ -70,7 +70,7 @@ export interface ModelManager<TApi extends Api = Api> {
 export declare function createModelManager<TApi extends Api = Api, TModelsDevPayload = unknown>(options: ModelManagerOptions<TApi, TModelsDevPayload>): ModelManager<TApi>;
 /**
  * Resolves provider models with source precedence:
- * static -> models.dev -> cache -> dynamic.
+ * static -> stencil.so -> cache -> dynamic.
  *
  * Later sources override earlier ones by model id.
  */

package/dist/types/provider-models/descriptors.d.ts

@@ -7,6 +7,15 @@
  */
 import type { ModelManagerConfig, ProviderCatalogEntry, ProviderDescriptor } from "./descriptor-types.js";
 export declare const CATALOG_PROVIDERS: readonly [{
+    readonly id: "aiand";
+    readonly defaultModel: "moonshotai/kimi-k2.7-code";
+    readonly envVars: readonly ["AIAND_API_KEY"];
+    readonly createModelManagerOptions: (config: ModelManagerConfig) => import("../index.js").ModelManagerOptions<"openai-completions", unknown>;
+    readonly dynamicModelsAuthoritative: true;
+    readonly catalogDiscovery: {
+        readonly label: "ai&";
+    };
+}, {
     readonly id: "aimlapi";
     readonly defaultModel: "gpt-5.5-2026-04-23";
     readonly envVars: readonly ["AIMLAPI_API_KEY"];
@@ -129,6 +138,15 @@ export declare const CATALOG_PROVIDERS: readonly [{
     readonly envVars: readonly ["GITLAB_TOKEN"];
     readonly createModelManagerOptions: (config: ModelManagerConfig) => import("../index.js").ModelManagerOptions<"gitlab-duo-agent", unknown>;
     readonly dynamicModelsAuthoritative: true;
+}, {
+    readonly id: "gmi-cloud";
+    readonly defaultModel: "deepseek-ai/DeepSeek-V4-Flash";
+    readonly envVars: readonly ["GMI_API_KEY"];
+    readonly createModelManagerOptions: (config: ModelManagerConfig) => import("../index.js").ModelManagerOptions<"openai-completions", unknown>;
+    readonly dynamicModelsAuthoritative: true;
+    readonly catalogDiscovery: {
+        readonly label: "GMI Cloud";
+    };
 }, {
     readonly id: "google";
     readonly defaultModel: "gemini-3.1-pro-preview";

package/dist/types/provider-models/openai-compat.d.ts

@@ -25,6 +25,17 @@ export interface ModelsDevModel {
         npm?: string;
     };
 }
+/**
+ * Fetches the models.dev catalog via catalog.stencil.so, which serves a
+ * field-pruned copy precompressed as a zstd blob (~93 KB vs ~3.3 MB raw).
+ * The frame magic is sniffed rather than trusting content-type so plain-JSON
+ * responses (test stubs, fallback mirrors) parse identically.
+ *
+ * Fetched fully once per process: concurrent callers share the in-flight
+ * request, repeat callers send a conditional GET that the server answers
+ * (and deliberately does not log) with `304`.
+ */
+export declare function fetchWellKnownModels(fetchImpl?: FetchImpl, signal?: AbortSignal): Promise<unknown>;
 /**
  * Curated Anthropic models that are live or limited-availability on the
  * first-party `/v1/models` endpoint but that models.dev has not catalogued yet.
@@ -67,6 +78,26 @@ export declare function openaiModelManagerOptions(config?: OpenAIModelManagerCon
  * upstream model that occupies an alias id wins and suppresses the projection.
  */
 export declare function projectOpenAIProReasoningAliases(models: readonly ModelSpec<Api>[]): ModelSpec<Api>[];
+/**
+ * Bundled seed for GMI Cloud. Generation has no `GMI_API_KEY`, so a regen
+ * without credentials would leave the provider slice empty and the declared
+ * `defaultModel` unresolvable on a fresh install before the async runtime
+ * discovery fires. Live `/v1/models` discovery is authoritative for the model
+ * ID set and overrides context/max-token limits, but `mapWithBundledReference`
+ * keeps the reference's cost/reasoning/thinking — so these fields carry GMI's
+ * direct-tariff values: V4-Flash at $0.14/$0.28 per 1M with Think High/Max
+ * modes per GMI's launch post
+ * (https://www.gmicloud.ai/en/blog/deepseek-v4-is-here-we-tested-it), not
+ * discounted gateway-route pricing. GMI publishes no cache-read tariff, so
+ * cacheRead stays 0 until a direct source confirms cached-token billing.
+ */
+export declare const GMI_CLOUD_STATIC_MODELS: readonly ModelSpec<"openai-completions">[];
+export interface GmiCloudModelManagerConfig {
+    apiKey?: string;
+    baseUrl?: string;
+    fetch?: FetchImpl;
+}
+export declare function gmiCloudModelManagerOptions(config?: GmiCloudModelManagerConfig): ModelManagerOptions<"openai-completions">;
 export interface GroqModelManagerConfig {
     apiKey?: string;
     baseUrl?: string;
@@ -412,6 +443,23 @@ export interface SakanaModelManagerConfig {
     fetch?: FetchImpl;
 }
 export declare function sakanaModelManagerOptions(config?: SakanaModelManagerConfig): ModelManagerOptions<"openai-responses">;
+/**
+ * Documented ai& catalog (docs.aiand.com/models/catalog, 2026-08) bundled so
+ * the provider is usable when generation and first boot have no live key.
+ * The org-scoped `/v1/models` response is authoritative once discovery runs.
+ */
+export declare const AIAND_STATIC_MODELS: readonly ModelSpec<"openai-completions">[];
+export interface AiandModelManagerConfig {
+    apiKey?: string;
+    baseUrl?: string;
+    fetch?: FetchImpl;
+}
+/**
+ * ai& (aiand.com) model manager: OpenAI-compatible chat completions with an
+ * org-scoped `/v1/models` catalog carrying context, capability, effort, and
+ * pricing metadata, so discovery is authoritative over the bundled seed.
+ */
+export declare function aiandModelManagerOptions(config?: AiandModelManagerConfig): ModelManagerOptions<"openai-completions">;
 export interface QwenPortalModelManagerConfig {
     apiKey?: string;
     baseUrl?: string;

package/dist/types/types.d.ts

@@ -75,6 +75,8 @@ export interface Usage {
     cacheWrite: number;
     /** Sum of input + output + cacheRead + cacheWrite plus provider-side orchestration tokens when reported. */
     totalTokens: number;
+    /** Provider-reported occupied context tokens when the value is authoritative but not a billable input/output bucket. */
+    contextTokens?: number;
     /** Provider-side orchestration tokens, billed but not part of the conversation prompt/cache buckets. */
     orchestration?: {
         /** Non-cached orchestration input tokens. */

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/pi-catalog",
-	"version": "17.2.1",
+	"version": "17.2.3",
 	"description": "Model catalog for omp: bundled model database, provider discovery descriptors, model identity, classification, and equivalence",
 	"homepage": "https://omp.sh",
 	"author": "Can Boluk",
@@ -35,12 +35,12 @@
 	},
 	"dependencies": {
 		"@bufbuild/protobuf": "^2.12.1",
-		"@oh-my-pi/pi-utils": "17.2.1",
+		"@oh-my-pi/pi-utils": "17.2.3",
 		"arktype": "2.2.3",
 		"zod": "^4"
 	},
 	"devDependencies": {
-		"@oh-my-pi/pi-ai": "17.2.1",
+		"@oh-my-pi/pi-ai": "17.2.3",
 		"@types/bun": "^1.3.14"
 	},
 	"engines": {

package/src/compat/openai.ts

@@ -322,10 +322,14 @@ export function buildOpenAICompat(spec: ModelSpec<"openai-completions">): Resolv
 	const isGrok = modelMatchesHost(hostModel, "xai");
 	const isMistral = modelMatchesHost(hostModel, "mistral");
 	const isOpenCodeHost = modelMatchesHost(hostModel, "opencode");
+	// Google AI Studio's OpenAI-compat shim (`generativelanguage.googleapis.com/v1beta/openai`)
+	// implements a subset of chat-completions and 400s on `store` ("Unknown name \"store\"").
+	const isGoogleAistudioOpenAI = hostMatchesUrl(baseUrl, "googleAistudio");
 	const isNonStandard =
 		isCerebras ||
 		isGrok ||
 		isMistral ||
+		isGoogleAistudioOpenAI ||
 		hostMatchesUrl(baseUrl, "chutes") ||
 		hostMatchesUrl(baseUrl, "deepseekFamily") ||
 		hostMatchesUrl(baseUrl, "fireworks") ||

package/src/discovery/cursor.ts

@@ -1,6 +1,8 @@
 import * as http2 from "node:http2";
 import { create, fromBinary, toBinary } from "@bufbuild/protobuf";
 import { type } from "arktype";
+import { isKimiK3ModelId } from "../identity";
+import { bareModelId, parseGlmModel, semverGte } from "../identity/classify";
 import { getBundledModels } from "../models";
 import { toModelSpec } from "../provider-models/bundled-references";
 import type { Model, ModelSpec } from "../types";
@@ -13,6 +15,19 @@ const CURSOR_GET_USABLE_MODELS_PATH = "/agent.v1.AgentService/GetUsableModels";
 const DEFAULT_CONTEXT_WINDOW = 200_000;
 const DEFAULT_MAX_TOKENS = 64_000;
 
+/**
+ * `GetUsableModels` carries no context-window field, so the 1M ceiling is
+ * recovered from the signals Cursor does send:
+ * - display-name labels ("Opus 5 1M", "GPT-5.5 1M High") across families,
+ * - natively 1M families Cursor serves unlabeled (Kimi K3, GLM 5.2+),
+ * - the max-mode flag on Claude/Gemini ids, whose max-mode ceiling is 1M.
+ */
+const CURSOR_1M_CONTEXT_WINDOW = 1_000_000;
+const CURSOR_1M_NAME_PATTERN = /\b1m\b/i;
+const CURSOR_MAX_MODE_1M_ID_PATTERN = /claude|gemini/;
+/** Kimi's official bare K3 id (`k3`, `kimi/k3`); `k3-256k` is the 256k SKU and stays out. */
+const CURSOR_KIMI_K3_BARE_ID_PATTERN = /(^|\/)k3$/i;
+
 /**
  * Model-id families whose native catalogs (anthropic, openai/openai-codex,
  * google) are multimodal. Cursor-only or text-only families (`composer-*`,
@@ -282,7 +297,7 @@ function normalizeCursorModel(
 
 	const name = pickModelDisplayName(details, id);
 	const reference = references.get(id);
-	const reasoning = Boolean(details.thinkingDetails) || reference?.reasoning === true;
+	const reasoning = isKimiK3ModelId(id) || Boolean(details.thinkingDetails) || reference?.reasoning === true;
 
 	if (reference) {
 		return {
@@ -291,6 +306,7 @@ function normalizeCursorModel(
 			name,
 			baseUrl: baseUrlOverride ?? reference.baseUrl,
 			reasoning,
+			contextWindow: resolveCursorContextWindow(details, id, reference.contextWindow),
 			cursorMaxMode: details.maxMode,
 		};
 	}
@@ -303,12 +319,53 @@ function normalizeCursorModel(
 		reasoning,
 		input: inferInputFromCursorId(id),
 		cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
-		contextWindow: DEFAULT_CONTEXT_WINDOW,
+		contextWindow: resolveCursorContextWindow(details, id, DEFAULT_CONTEXT_WINDOW),
 		maxTokens: DEFAULT_MAX_TOKENS,
 		cursorMaxMode: details.maxMode,
 	};
 }
 
+/**
+ * Context window for a discovered Cursor model: the 1M ceiling when any 1M
+ * signal fires (never below a larger bundled reference), else the fallback.
+ */
+function resolveCursorContextWindow(
+	model: CursorModelDetailsValue,
+	id: string,
+	fallback: number | null,
+): number | null {
+	const labeled1M =
+		CURSOR_1M_NAME_PATTERN.test(id) ||
+		[model.displayName, model.displayNameShort, model.displayModelId, ...model.aliases].some(
+			candidate => typeof candidate === "string" && CURSOR_1M_NAME_PATTERN.test(candidate),
+		);
+	if (labeled1M || isCursorNative1MModelId(id) || (model.maxMode && CURSOR_MAX_MODE_1M_ID_PATTERN.test(id))) {
+		return Math.max(fallback ?? 0, CURSOR_1M_CONTEXT_WINDOW);
+	}
+	return fallback;
+}
+
+/**
+ * Natively 1M-context families Cursor serves without a "1M" label: Kimi K3 and
+ * GLM 5.2+ coding SKUs. The shared family parsers cover namespace forms
+ * (`moonshotai/kimi-k3`, `z-ai/glm-5.2`) and future GLM versions (`glm-5.10`,
+ * `glm-6`); vision and sub-1M variants stay out via the same gates as
+ * `isGlm52ReasoningEffortModelId`.
+ */
+function isCursorNative1MModelId(id: string): boolean {
+	if (isKimiK3ModelId(id) || CURSOR_KIMI_K3_BARE_ID_PATTERN.test(id)) {
+		return true;
+	}
+	const glm = parseGlmModel(bareModelId(id));
+	if (!glm || glm.vision) {
+		return false;
+	}
+	if (glm.variant !== "base" && glm.variant !== "air" && glm.variant !== "turbo") {
+		return false;
+	}
+	return semverGte(glm.version, "5.2");
+}
+
 function pickModelDisplayName(model: CursorModelDetailsValue, fallbackId: string): string {
 	const candidates = [model.displayName, model.displayNameShort, model.displayModelId, ...model.aliases, fallbackId];
 	for (const candidate of candidates) {

package/src/hosts.ts

@@ -62,6 +62,8 @@ export const KNOWN_HOSTS = {
 	/** NVIDIA NIM (`integrate.api.nvidia.com`). Qwen NIM endpoints take `chat_template_kwargs.enable_thinking`, never top-level `enable_thinking`. */
 	nvidia: { providers: ["nvidia"], urlMarkers: ["integrate.api.nvidia.com"] },
 	moonshotNative: { providers: ["moonshot", "kimi-code"], urlMarkers: ["api.moonshot.ai", "api.kimi.com"] },
+	/** Google AI Studio's OpenAI-compatible shim (`/v1beta/openai`) — a subset of chat-completions; rejects `store` with a 400. Native Gemini uses `google-generative-ai` api instead. */
+	googleAistudio: { providers: [], urlMarkers: ["generativelanguage.googleapis.com"] },
 	opencode: { providers: ["opencode-go", "opencode-zen"], urlMarkers: ["opencode.ai"] },
 	/** ZenMux's Anthropic-compatible proxy (`zenmux.ai/api/anthropic`) forwards to signature-enforcing Anthropic. */
 	zenmux: { providers: ["zenmux"], urlMarkers: ["zenmux.ai"] },

package/src/model-manager.ts

@@ -14,10 +14,10 @@ const NON_AUTHORITATIVE_RETRY_MS = 5 * 60 * 1000;
 export type ModelRefreshStrategy = "online" | "offline" | "online-if-uncached";
 
 /**
- * Hook for loading and mapping models.dev fallback data into canonical model objects.
+ * Hook for loading and mapping stencil.so fallback data into canonical model objects.
  */
 export interface ModelsDevFallback<TApi extends Api = Api, TPayload = unknown> {
-	/** Fetches raw fallback payload (for example from models.dev). */
+	/** Fetches raw fallback payload (for example from stencil.so). */
 	fetch(): Promise<TPayload>;
 	/** Maps payload into provider models. */
 	map(payload: TPayload, providerId: Provider): readonly ModelSpec<TApi>[];
@@ -39,7 +39,7 @@ export interface ModelManagerOptions<TApi extends Api = Api, TModelsDevPayload =
 	cacheTtlMs?: number;
 	/** When true, a successful dynamic fetch is the complete provider catalog and prunes static-only models. */
 	dynamicModelsAuthoritative?: boolean;
-	/** Cached model ids to ignore when the cache was written against a different static catalog fingerprint. */
+	/** Cached model ids whose presence forces refresh when the static or migration-policy fingerprint changes. */
 	dropCachedModelIdsOnStaticMismatch?: readonly string[];
 	/**
 	 * Trusted, provider-wide request headers (compile-time constants, never
@@ -51,7 +51,7 @@ export interface ModelManagerOptions<TApi extends Api = Api, TModelsDevPayload =
 	restorableHeaderFallback?: Record<string, string>;
 	/** Optional dynamic endpoint fetcher. */
 	fetchDynamicModels?: () => Promise<readonly ModelSpec<TApi>[] | null>;
-	/** Optional models.dev fallback hook. */
+	/** Optional stencil.so fallback hook. */
 	modelsDev?: ModelsDevFallback<TApi, TModelsDevPayload>;
 	/** Clock override for deterministic tests. */
 	now?: () => number;
@@ -171,7 +171,7 @@ function restoreCachedModelHeaders<TApi extends Api>(
 
 /**
  * Resolves provider models with source precedence:
- * static -> models.dev -> cache -> dynamic.
+ * static -> stencil.so -> cache -> dynamic.
  *
  * Later sources override earlier ones by model id.
  */
@@ -199,10 +199,24 @@ export async function resolveProviderModels<TApi extends Api = Api, TModelsDevPa
 	const usableCachedModels = restoredCache.models.filter(model => !restoredCache.unresolvedModelIds.has(model.id));
 	const cacheHasUnresolvedHeaders = restoredCache.unresolvedModelIds.size > 0;
 	const dynamicModelsAuthoritative = options.dynamicModelsAuthoritative ?? false;
-	const staticFingerprint = fingerprintStatic(staticModels, dynamicModelsAuthoritative);
+	const cacheDropIds = options.dropCachedModelIdsOnStaticMismatch;
+	const staticCatalogFingerprint = fingerprintStatic(staticModels, dynamicModelsAuthoritative);
+	// Endpoint-migration policy is cache identity: adding an id must invalidate
+	// matching-static-catalog caches written by the prior resolver.
+	const staticFingerprint =
+		cacheDropIds && cacheDropIds.length > 0
+			? `${staticCatalogFingerprint}:drop:${Bun.hash(cacheDropIds.join("\0")).toString(36)}`
+			: staticCatalogFingerprint;
 	const cacheFingerprintMatches = cache?.staticFingerprint === staticFingerprint && staticFingerprint.length > 0;
+	const cacheNeedsModelMigration =
+		!cacheFingerprintMatches &&
+		cacheDropIds !== undefined &&
+		usableCachedModels.some(model => cacheDropIds.includes(model.id));
 	const hasUsableFreshCache =
-		(cache?.fresh ?? false) && !cacheHasUnresolvedHeaders && (!dynamicModelsAuthoritative || cacheFingerprintMatches);
+		(cache?.fresh ?? false) &&
+		!cacheHasUnresolvedHeaders &&
+		!cacheNeedsModelMigration &&
+		(!dynamicModelsAuthoritative || cacheFingerprintMatches);
 	const dynamicFetcher = options.fetchDynamicModels;
 	const hasDynamicFetcher = typeof dynamicFetcher === "function";
 	const hasAuthoritativeCache = ((cache?.authoritative ?? false) && hasUsableFreshCache) || !hasDynamicFetcher;
@@ -484,13 +498,25 @@ function mergeDynamicModel<TApi extends Api>(existingModel: Model<TApi>, dynamic
 	const supportsImage = dynamicInputAuthoritative
 		? dynamicModel.input.includes("image")
 		: existingModel.input.includes("image") || dynamicModel.input.includes("image");
+	// Synthetic's discovery is authoritative (`dynamicModelsAuthoritative`) and
+	// its per-model `reasoning_parameters.efforts` vocabulary is the route's
+	// whole truth: when the wire advertises only the `none` off-state the
+	// mapper emits `reasoning: false`, and OR-ing the bundled reference's
+	// stale `reasoning: true` back would re-arm an effort dial the route
+	// doesn't expose. Other providers keep the OR so a bundled reasoning flag
+	// survives a discovery row that simply omits the capability.
+	const dynamicReasoningAuthoritative =
+		existingModel.provider === "synthetic" && dynamicModel.provider === "synthetic";
+	const reasoning = dynamicReasoningAuthoritative
+		? dynamicModel.reasoning
+		: existingModel.reasoning || dynamicModel.reasoning;
 	// Re-build from spec stage: sparse compat comes from `compatConfig` (the
 	// verbatim override vocabulary), never the resolved `compat` record.
 	return buildModel({
 		...existingModel,
 		...dynamicModel,
 		name: preferDiscoveryName(dynamicModel.name, existingModel.name, dynamicModel.id),
-		reasoning: existingModel.reasoning || dynamicModel.reasoning,
+		reasoning,
 		input: supportsImage ? ["text", "image"] : ["text"],
 		cost: {
 			input: preferDiscoveryCost(dynamicModel.cost.input, existingModel.cost.input),