@juspay/neurolink 12.5.0 → 12.5.1

package/dist/providers/openaiCompatCatalog.js

@@ -1,11 +1,4 @@
-import { AIProviderName } from "../constants/enums.js";
-import { CerebrasModels, SambanovaModels, CloudflareModels, FireworksModels, GroqModels, MistralModels, PerplexityModels, TogetherAIModels, XaiModels, } from "../constants/enums.js";
-import { AuthenticationError, InvalidModelError, ProviderError, } from "../types/index.js";
-import { DEFAULT_ERROR_RULES } from "../utils/errorClassifier.js";
-import { createCerebrasConfig, createSambanovaConfig, createCloudflareConfig, createFireworksConfig, createGroqConfig, createMistralConfig, createPerplexityConfig, createTogetherAIConfig, createXaiConfig, } from "../utils/providerConfig.js";
-function buildCloudflareBaseURL(accountId) {
-    return `https://api.cloudflare.com/client/v4/accounts/${accountId}/ai/v1`;
-}
+import { buildCatalogEntries } from "./catalog/loader.js";
 /**
  * Config-driven catalog of the 9 zero-quirk OpenAI-compatible providers.
  * Each entry fully replaces what used to be a hand-written
@@ -13,323 +6,19 @@ function buildCloudflareBaseURL(accountId) {
  * for the class that reads these entries, and providerRegistry.ts for the
  * registration loop that consumes this array.
  *
- * `errorRules` mirrors each provider's LIVE `formatProviderError` rule array
- * (post plan-07/wave-2 migration), not the original hand-rolled ladder these
- * providers had when plan 05 was first drafted: every provider below now
- * keeps only its bespoke rule(s) — auth, plus Groq's model_decommissioned and
- * xAI's insufficient_quota — before spreading the SAME exported
- * `DEFAULT_ERROR_RULES` constant that the live subclasses spread (never an
- * inlined copy, so this catalog cannot drift from that table independently).
- * See plan-05/progress.md Ruling R4 for the full rationale.
+ * The entries themselves are derived from the JSON catalog
+ * (src/lib/providers/catalog/<id>.json) via buildCatalogEntries() — that
+ * JSON is now the single source of truth for these 9 providers' identity,
+ * models, error rules and wire config. See
+ * src/lib/providers/catalog/loader.ts for the derivation logic and
+ * docs/superpowers/plans/2026-08-28-provider-json-catalog-spec.md for the
+ * authoring format.
  *
- * To add a new zero-quirk OpenAI-compatible provider: add one entry here.
- * Do NOT add a provider here if it needs any hook override beyond the 3
- * mandatory ones (getProviderName/getDefaultModel/formatProviderError) —
- * write a dedicated subclass instead (see deepseek.ts, azureOpenai.ts, and
- * Task 14's docs task for the deciding criteria).
+ * To add a new zero-quirk OpenAI-compatible provider: add one JSON file
+ * under src/lib/providers/catalog/ (see provider-catalog.schema.json) and
+ * run `pnpm run codegen:catalog`. Do NOT add a provider here if it needs
+ * any hook override beyond the 3 mandatory ones
+ * (getProviderName/getDefaultModel/formatProviderError) — write a
+ * dedicated subclass instead (see deepseek.ts, azureOpenai.ts).
  */
-export const OPENAI_COMPAT_CATALOG = [
-    {
-        providerName: AIProviderName.SAMBANOVA,
-        aliases: ["sambanova"],
-        apiKeyEnvVar: "SAMBANOVA_API_KEY",
-        baseURLEnvVar: "SAMBANOVA_BASE_URL",
-        defaultBaseURL: "https://api.sambanova.ai/v1",
-        configOptions: createSambanovaConfig(),
-        modelEnvVar: "SAMBANOVA_MODEL",
-        defaultModel: SambanovaModels.META_LLAMA_3_3_70B_INSTRUCT,
-        registryDefaultModel: SambanovaModels.META_LLAMA_3_3_70B_INSTRUCT,
-        registryDefaultModelChecksEnvVar: true,
-        fallbackModelName: SambanovaModels.GPT_OSS_120B,
-        fallbackModels: [
-            SambanovaModels.META_LLAMA_3_3_70B_INSTRUCT,
-            SambanovaModels.GPT_OSS_120B,
-        ],
-        errorRules: [
-            {
-                // Probed live 2026-08-27: a bad key gets HTTP 401 with an
-                // OpenAI-shaped body {"error":{"message":"Incorrect API key
-                // provided: ...","type":"authentication_error","code":
-                // "invalid_api_key"}}.
-                match: (ctx) => ctx.statusCode === 401 ||
-                    /invalid_api_key|Incorrect API key|authentication_error/i.test(ctx.message),
-                errorClass: AuthenticationError,
-                message: "Invalid SambaNova API key. Check SAMBANOVA_API_KEY. Get one at https://cloud.sambanova.ai/apis",
-            },
-            {
-                // Probed live 2026-08-27: a zero-balance account gets HTTP 402 with
-                // {"error":{"balance_units":0,"code":"PAYMENT_METHOD_REQUIRED",
-                //  "billing_portal_url":"https://cloud.sambanova.ai/plans/billing"}}.
-                // New accounts have NO free allowance — credits must be purchased.
-                match: (ctx) => ctx.statusCode === 402 ||
-                    /PAYMENT_METHOD_REQUIRED|balance_units/i.test(ctx.message),
-                errorClass: ProviderError,
-                message: "SambaNova account has no credits (new accounts have no free allowance). Add a payment method and purchase credits at https://cloud.sambanova.ai/plans/billing",
-            },
-            ...DEFAULT_ERROR_RULES,
-        ],
-    },
-    {
-        providerName: AIProviderName.CEREBRAS,
-        aliases: ["cerebras"],
-        apiKeyEnvVar: "CEREBRAS_API_KEY",
-        baseURLEnvVar: "CEREBRAS_BASE_URL",
-        defaultBaseURL: "https://api.cerebras.ai/v1",
-        configOptions: createCerebrasConfig(),
-        modelEnvVar: "CEREBRAS_MODEL",
-        defaultModel: CerebrasModels.GPT_OSS_120B,
-        registryDefaultModel: CerebrasModels.GPT_OSS_120B,
-        registryDefaultModelChecksEnvVar: true,
-        fallbackModelName: CerebrasModels.GEMMA_4_31B,
-        fallbackModels: [CerebrasModels.GPT_OSS_120B, CerebrasModels.GEMMA_4_31B],
-        errorRules: [
-            {
-                // Probed live 2026-08-26: a bad key gets HTTP 401 with body
-                // {"message":"Wrong API Key","type":"invalid_request_error",
-                //  "param":"api_key","code":"wrong_api_key"}.
-                match: (ctx) => ctx.statusCode === 401 ||
-                    /wrong_api_key|Wrong API Key|invalid_api_key/i.test(ctx.message),
-                errorClass: AuthenticationError,
-                message: "Invalid Cerebras API key. Check CEREBRAS_API_KEY. Get one at https://cloud.cerebras.ai",
-            },
-            ...DEFAULT_ERROR_RULES,
-        ],
-    },
-    {
-        providerName: AIProviderName.GROQ,
-        aliases: ["groq"],
-        apiKeyEnvVar: "GROQ_API_KEY",
-        baseURLEnvVar: "GROQ_BASE_URL",
-        defaultBaseURL: "https://api.groq.com/openai/v1",
-        configOptions: createGroqConfig(),
-        modelEnvVar: "GROQ_MODEL",
-        defaultModel: GroqModels.LLAMA_3_3_70B_VERSATILE,
-        registryDefaultModel: GroqModels.LLAMA_3_3_70B_VERSATILE,
-        registryDefaultModelChecksEnvVar: true,
-        fallbackModelName: GroqModels.LLAMA_3_1_8B_INSTANT,
-        fallbackModels: [
-            GroqModels.LLAMA_3_3_70B_VERSATILE,
-            GroqModels.LLAMA_3_1_8B_INSTANT,
-            GroqModels.GEMMA_2_9B_IT,
-            GroqModels.MIXTRAL_8X7B_32768,
-            GroqModels.LLAMA_3_2_90B_VISION_PREVIEW,
-            GroqModels.LLAMA_3_2_11B_VISION_PREVIEW,
-        ],
-        // Groq's pre-migration subclass intercepted TimeoutError itself and
-        // returned a plain ProviderError, ahead of classifyProviderError's own
-        // non-overridable TimeoutError -> NetworkError default. Expressed here
-        // as data — see OpenAICompatCatalogEntry.timeoutErrorClass and
-        // ConfiguredOpenAICompatProvider.formatProviderError, which consults
-        // this field before ever delegating to the shared classifier. No other
-        // entry in this catalog sets it, so every other provider still gets
-        // the classifier's unmodified default.
-        timeoutErrorClass: ProviderError,
-        errorRules: [
-            {
-                match: (ctx) => ctx.statusCode === 401 ||
-                    /Invalid API key|Authentication|invalid_api_key/i.test(ctx.message),
-                errorClass: AuthenticationError,
-                message: "Invalid Groq API key. Check GROQ_API_KEY. Get one at https://console.groq.com/keys",
-            },
-            {
-                match: (ctx) => /model_decommissioned/i.test(ctx.message),
-                errorClass: InvalidModelError,
-                message: (ctx) => `Groq model '${ctx.modelName}' was decommissioned. Pick a current model from https://console.groq.com/docs/models.`,
-            },
-            ...DEFAULT_ERROR_RULES,
-        ],
-    },
-    {
-        providerName: AIProviderName.XAI,
-        aliases: ["xai", "grok"],
-        apiKeyEnvVar: "XAI_API_KEY",
-        baseURLEnvVar: "XAI_BASE_URL",
-        defaultBaseURL: "https://api.x.ai/v1",
-        configOptions: createXaiConfig(),
-        modelEnvVar: "XAI_MODEL",
-        defaultModel: XaiModels.GROK_3,
-        registryDefaultModel: XaiModels.GROK_3,
-        registryDefaultModelChecksEnvVar: true,
-        fallbackModelName: XaiModels.GROK_3_MINI,
-        fallbackModels: [
-            XaiModels.GROK_3,
-            XaiModels.GROK_3_MINI,
-            XaiModels.GROK_2_LATEST,
-            XaiModels.GROK_2_VISION_LATEST,
-            XaiModels.GROK_BETA,
-        ],
-        errorRules: [
-            {
-                match: (ctx) => ctx.statusCode === 401 ||
-                    /Invalid API key|Authentication|invalid_api_key/i.test(ctx.message),
-                errorClass: AuthenticationError,
-                message: "Invalid xAI API key. Please check your XAI_API_KEY environment variable. Get one at https://console.x.ai/",
-            },
-            {
-                match: (ctx) => /insufficient_quota|quota exceeded/i.test(ctx.message),
-                errorClass: ProviderError,
-                message: "xAI account has insufficient quota. Top up at https://console.x.ai/",
-            },
-            ...DEFAULT_ERROR_RULES,
-        ],
-    },
-    {
-        providerName: AIProviderName.TOGETHER_AI,
-        aliases: ["together-ai", "together"],
-        apiKeyEnvVar: "TOGETHER_API_KEY",
-        baseURLEnvVar: "TOGETHER_BASE_URL",
-        defaultBaseURL: "https://api.together.xyz/v1",
-        configOptions: createTogetherAIConfig(),
-        modelEnvVar: "TOGETHER_MODEL",
-        defaultModel: TogetherAIModels.LLAMA_3_3_70B_INSTRUCT_TURBO,
-        registryDefaultModel: TogetherAIModels.LLAMA_3_3_70B_INSTRUCT_TURBO,
-        registryDefaultModelChecksEnvVar: true,
-        fallbackModelName: TogetherAIModels.LLAMA_3_1_8B_INSTRUCT_TURBO,
-        fallbackModels: [
-            TogetherAIModels.LLAMA_3_3_70B_INSTRUCT_TURBO,
-            TogetherAIModels.LLAMA_3_1_405B_INSTRUCT_TURBO,
-            TogetherAIModels.LLAMA_3_1_70B_INSTRUCT_TURBO,
-            TogetherAIModels.LLAMA_3_1_8B_INSTRUCT_TURBO,
-            TogetherAIModels.MIXTRAL_8X22B_INSTRUCT,
-            TogetherAIModels.QWEN_2_5_72B_INSTRUCT_TURBO,
-            TogetherAIModels.DEEPSEEK_R1,
-            TogetherAIModels.DEEPSEEK_V3,
-        ],
-        errorRules: [
-            {
-                match: (ctx) => ctx.statusCode === 401 ||
-                    /Invalid API key|Authentication/i.test(ctx.message),
-                errorClass: AuthenticationError,
-                message: "Invalid Together AI API key. Get one at https://api.together.xyz/settings/api-keys",
-            },
-            ...DEFAULT_ERROR_RULES,
-        ],
-    },
-    {
-        providerName: AIProviderName.FIREWORKS,
-        aliases: ["fireworks"],
-        apiKeyEnvVar: "FIREWORKS_API_KEY",
-        baseURLEnvVar: "FIREWORKS_BASE_URL",
-        defaultBaseURL: "https://api.fireworks.ai/inference/v1",
-        configOptions: createFireworksConfig(),
-        modelEnvVar: "FIREWORKS_MODEL",
-        defaultModel: FireworksModels.DEEPSEEK_V4_PRO,
-        registryDefaultModel: FireworksModels.DEEPSEEK_V4_PRO,
-        registryDefaultModelChecksEnvVar: true,
-        fallbackModelName: FireworksModels.DEEPSEEK_V4_PRO,
-        fallbackModels: [
-            FireworksModels.DEEPSEEK_V4_PRO,
-            FireworksModels.GLM_5P1,
-            FireworksModels.GLM_5,
-            FireworksModels.KIMI_K2P6,
-            FireworksModels.KIMI_K2P5,
-            FireworksModels.GPT_OSS_120B,
-        ],
-        errorRules: [
-            {
-                match: (ctx) => ctx.statusCode === 401 ||
-                    /Invalid API key|Authentication/i.test(ctx.message),
-                errorClass: AuthenticationError,
-                message: "Invalid Fireworks API key. Get one at https://fireworks.ai/account/api-keys",
-            },
-            ...DEFAULT_ERROR_RULES,
-        ],
-    },
-    {
-        providerName: AIProviderName.PERPLEXITY,
-        aliases: ["perplexity", "pplx"],
-        apiKeyEnvVar: "PERPLEXITY_API_KEY",
-        baseURLEnvVar: "PERPLEXITY_BASE_URL",
-        defaultBaseURL: "https://api.perplexity.ai",
-        configOptions: createPerplexityConfig(),
-        modelEnvVar: "PERPLEXITY_MODEL",
-        defaultModel: PerplexityModels.SONAR,
-        registryDefaultModel: PerplexityModels.SONAR,
-        registryDefaultModelChecksEnvVar: true,
-        // Perplexity's live class does NOT override getFallbackModelName() — it
-        // inherits the base class default "gpt-3.5-turbo". Preserved here
-        // verbatim, not "fixed" to a Perplexity model — that's a real,
-        // pre-existing quirk this plan is not authorized to change.
-        fallbackModelName: "gpt-3.5-turbo",
-        fallbackModels: [
-            PerplexityModels.SONAR,
-            PerplexityModels.SONAR_PRO,
-            PerplexityModels.SONAR_REASONING,
-            PerplexityModels.SONAR_REASONING_PRO,
-            PerplexityModels.SONAR_DEEP_RESEARCH,
-        ],
-        errorRules: [
-            {
-                match: (ctx) => ctx.statusCode === 401 ||
-                    /Invalid API key|Authentication/i.test(ctx.message),
-                errorClass: AuthenticationError,
-                message: "Invalid Perplexity API key. Get one at https://www.perplexity.ai/settings/api",
-            },
-            ...DEFAULT_ERROR_RULES,
-        ],
-    },
-    {
-        providerName: AIProviderName.MISTRAL,
-        aliases: ["mistral"],
-        apiKeyEnvVar: "MISTRAL_API_KEY",
-        baseURLEnvVar: "MISTRAL_BASE_URL",
-        defaultBaseURL: "https://api.mistral.ai/v1",
-        configOptions: createMistralConfig(),
-        modelEnvVar: "MISTRAL_MODEL",
-        defaultModel: MistralModels.MISTRAL_SMALL_2506,
-        // The one documented registry-vs-class default-model quirk (see this
-        // plan's "Design reference" section): the registry passes the bare
-        // literal MISTRAL_LARGE_LATEST with no env-var check, while
-        // MistralProvider.getDefaultModel() checks MISTRAL_MODEL and defaults to
-        // MISTRAL_SMALL_2506. Preserved exactly, not reconciled.
-        registryDefaultModel: MistralModels.MISTRAL_LARGE_LATEST,
-        registryDefaultModelChecksEnvVar: false,
-        fallbackModelName: MistralModels.MISTRAL_SMALL_2506,
-        fallbackModels: [
-            MistralModels.MISTRAL_SMALL_2506,
-            MistralModels.MISTRAL_LARGE_LATEST,
-        ],
-        errorRules: [
-            {
-                match: (ctx) => ctx.statusCode === 401 ||
-                    /API_KEY_INVALID|Invalid API key|Unauthorized/i.test(ctx.message),
-                errorClass: AuthenticationError,
-                message: "Invalid Mistral API key. Please check your MISTRAL_API_KEY environment variable.",
-            },
-            ...DEFAULT_ERROR_RULES,
-        ],
-    },
-    {
-        providerName: AIProviderName.CLOUDFLARE,
-        aliases: ["cloudflare", "workers-ai", "cf-ai"],
-        apiKeyEnvVar: "CLOUDFLARE_API_KEY",
-        computedBaseURL: {
-            envVar: "CLOUDFLARE_ACCOUNT_ID",
-            missingValueMessage: "CLOUDFLARE_ACCOUNT_ID is required (or pass credentials.cloudflare.accountId). Get the account id from https://dash.cloudflare.com/",
-            build: buildCloudflareBaseURL,
-        },
-        configOptions: createCloudflareConfig(),
-        modelEnvVar: "CLOUDFLARE_MODEL",
-        defaultModel: CloudflareModels.LLAMA_3_3_70B_FAST,
-        registryDefaultModel: CloudflareModels.LLAMA_3_3_70B_FAST,
-        registryDefaultModelChecksEnvVar: true,
-        fallbackModelName: CloudflareModels.LLAMA_3_1_8B_FAST,
-        fallbackModels: [
-            CloudflareModels.LLAMA_3_3_70B_FAST,
-            CloudflareModels.LLAMA_3_1_70B_INSTRUCT,
-            CloudflareModels.LLAMA_3_1_8B_FAST,
-            CloudflareModels.LLAMA_3_2_11B_VISION,
-            CloudflareModels.MISTRAL_7B_INSTRUCT_V0_2,
-            CloudflareModels.QWEN_1P5_14B_CHAT_AWQ,
-        ],
-        errorRules: [
-            {
-                match: (ctx) => ctx.statusCode === 401 ||
-                    /Invalid API key|Authentication/i.test(ctx.message),
-                errorClass: AuthenticationError,
-                message: "Invalid Cloudflare API key. Use a token with Workers AI Read+Write scope. Get one at https://dash.cloudflare.com/profile/api-tokens",
-            },
-            ...DEFAULT_ERROR_RULES,
-        ],
-    },
-];
+export const OPENAI_COMPAT_CATALOG = buildCatalogEntries();

package/dist/types/index.d.ts

@@ -48,6 +48,8 @@ export * from "./observability.js";
 export * from "./openaiCompatible.js";
 export * from "./ppt.js";
 export * from "./processor.js";
+export * from "./providerCatalog.js";
+export * from "./providerCatalog.generated.js";
 export * from "./providers.js";
 export * from "./proxy.js";
 export * from "./proxyClient.js";

package/dist/types/index.js

@@ -52,6 +52,8 @@ export * from "./observability.js";
 export * from "./openaiCompatible.js";
 export * from "./ppt.js";
 export * from "./processor.js";
+export * from "./providerCatalog.js";
+export * from "./providerCatalog.generated.js";
 export * from "./providers.js";
 export * from "./proxy.js";
 export * from "./proxyClient.js";

package/dist/types/providerCatalog.d.ts

@@ -0,0 +1,149 @@
+/**
+ * Single-JSON provider catalog — the authoring format for Tier-2
+ * (zero-quirk OpenAI-compatible) providers. One
+ * src/lib/providers/catalog/<id>.json file per provider is the single
+ * source of truth; see docs/superpowers/plans/2026-08-28-provider-json-catalog-spec.md.
+ */
+export type CatalogPricingPerMTok = {
+    input: number;
+    output: number;
+    cachedInput?: number;
+};
+export type CatalogModelStatus = "production" | "preview" | "retired";
+export type CatalogModelSpec = {
+    contextWindow?: number;
+    maxOutputTokens?: number;
+    pricingPerMTok?: CatalogPricingPerMTok;
+    vision: boolean;
+    status: CatalogModelStatus;
+    description: string;
+    /**
+     * Enum member name override. Default is the derived constant-case of the
+     * model id; REQUIRED where the derived name differs from a pre-existing
+     * exported member (public-surface compatibility).
+     */
+    enumMember?: string;
+};
+export type CatalogWire = {
+    baseURL?: string;
+    baseURLTemplate?: string;
+    extraCredentials?: string[];
+    missingCredentialMessage?: string;
+    envOverrides?: {
+        apiKey?: string;
+        baseURL?: string;
+        model?: string;
+    };
+};
+export type CatalogErrorRuleClass = "authentication" | "rate-limit" | "invalid-model" | "network" | "provider";
+export type CatalogErrorRuleJson = {
+    status?: number;
+    pattern?: string;
+    class: CatalogErrorRuleClass;
+    message: string;
+};
+export type CatalogQuirks = {
+    timeoutErrorClass?: "provider";
+    registryDefaultIgnoresModelEnvVar?: boolean;
+};
+export type CatalogBillingPolicy = "free-tier" | "free-with-card" | "no-free-tier";
+export type CatalogSetup = {
+    url: string;
+    apiKeyFormat: string | null;
+    billingPolicy: CatalogBillingPolicy;
+    instructions: string[];
+    /**
+     * Config-options description shown to callers for this credential.
+     * Default: "API key". Set explicitly where the legacy entry's
+     * description carries real information a generic "API key" loses
+     * (e.g. Cloudflare's "API token (Workers AI Read+Write scope)").
+     */
+    description?: string;
+};
+export type CatalogProbeEvidence = {
+    date: string;
+    status?: number;
+    code?: string;
+    method?: string;
+};
+export type CatalogEvidence = {
+    rosterVerified: CatalogProbeEvidence;
+    authProbe?: CatalogProbeEvidence;
+    billingProbe?: CatalogProbeEvidence;
+    liveMatrix: {
+        date: string;
+        result: string;
+    } | null;
+    addedInPR: string;
+};
+export type CatalogCapabilities = {
+    text: boolean;
+    streaming: boolean;
+    tools: boolean;
+    toolsWithStreaming: boolean;
+    structuredOutput: boolean;
+    structuredOutputWithTools: boolean;
+    embeddings: boolean;
+    thinking: boolean;
+};
+export type ProviderCatalogJson = {
+    /** Editor-only pointer to provider-catalog.schema.json — accepted and ignored. */
+    $schema?: string;
+    id: string;
+    displayName: string;
+    /**
+     * Exported <Name>Models enum name override. Default: PascalCase(id) +
+     * "Models". REQUIRED where the derived name differs from a pre-existing
+     * export ("together-ai" derives "TogetherAiModels"; the legacy export is
+     * "TogetherAIModels").
+     */
+    enumTypeName?: string;
+    /**
+     * NeurolinkCredentials key override. Default: toCamelCase(id). REQUIRED
+     * where the derived key differs from a pre-existing public credential
+     * field ("together-ai" derives "togetherAi"; the shipped public key is
+     * "together" — renaming it would break any caller passing
+     * `credentials: { together: {...} } }`, a public API break rule 5
+     * forbids).
+     */
+    credentialsKey?: string;
+    aliases: string[];
+    tier: 2;
+    wire: CatalogWire;
+    models: {
+        default: string;
+        fallbacks: string[];
+        /** Default: fallbacks[1] ?? fallbacks[0]. Set explicitly where the
+         *  legacy entry differs (behavior preservation — e.g. Groq). */
+        fallbackModelName?: string;
+        /** Default: models.default. Set explicitly where the legacy entry's
+         *  registry-level default differs (behavior preservation — Mistral's
+         *  registryDefaultModel is MISTRAL_LARGE_LATEST while its defaultModel
+         *  is not). Must be a models.catalog key (validated). */
+        registryDefaultModel?: string;
+        defaultContextWindow: number;
+        defaultMaxOutputTokens: number;
+        catalog: Record<string, CatalogModelSpec>;
+        /** Ordered curated subset of `catalog` keys for wizard/choice surfaces
+         *  (e.g. the CLI setup wizard's top-N model picker). When absent, choice
+         *  surfaces fall back to the full catalog in file order. */
+        topModels?: string[];
+        /** The live-verified vision-capable model for capability tests, for
+         *  providers whose `default` model is text-only. Must be a
+         *  models.catalog key with vision: true (validated). When absent, the
+         *  first vision:true model in `catalog` file order is used. */
+        visionModel?: string;
+        /** The live-verified model the capability matrix drives, for providers
+         *  whose `default` is retired upstream or gated off the testing account
+         *  (Fireworks serverless deployment, Groq's roster purges). May name a
+         *  model outside `catalog` — current account reality, not transcribed
+         *  history. When absent, the matrix drives `default`. Never affects the
+         *  runtime default. */
+        testModel?: string;
+    };
+    capabilities: CatalogCapabilities;
+    errorRules: CatalogErrorRuleJson[];
+    quirks?: CatalogQuirks;
+    setup: CatalogSetup;
+    evidence: CatalogEvidence;
+};

package/dist/types/providerCatalog.generated.d.ts

@@ -0,0 +1,2 @@
+export type CatalogProviderName = "cerebras" | "cloudflare" | "fireworks" | "groq" | "mistral" | "perplexity" | "sambanova" | "together-ai" | "xai";
+export type CatalogCredentialKey = "cerebras" | "cloudflare" | "fireworks" | "groq" | "mistral" | "perplexity" | "sambanova" | "together" | "xai";

package/dist/types/providerCatalog.generated.js

@@ -0,0 +1 @@
+export {};

package/dist/types/providerCatalog.js

@@ -0,0 +1,7 @@
+/**
+ * Single-JSON provider catalog — the authoring format for Tier-2
+ * (zero-quirk OpenAI-compatible) providers. One
+ * src/lib/providers/catalog/<id>.json file per provider is the single
+ * source of truth; see docs/superpowers/plans/2026-08-28-provider-json-catalog-spec.md.
+ */
+export {};

package/dist/types/providers.d.ts

@@ -130,10 +130,6 @@ export type NeurolinkCredentials = {
         apiVersion?: string;
         useMaxCompletionTokens?: boolean;
     };
-    mistral?: {
-        apiKey?: string;
-        baseURL?: string;
-    };
     huggingFace?: {
         apiKey?: string;
         baseURL?: string;
@@ -170,41 +166,45 @@ export type NeurolinkCredentials = {
         apiKey?: string;
         baseURL?: string;
     };
-    xai?: {
+    cerebras?: {
         apiKey?: string;
         baseURL?: string;
     };
-    groq?: {
+    cloudflare?: {
         apiKey?: string;
         baseURL?: string;
+        accountId?: string;
     };
-    cerebras?: {
+    fireworks?: {
         apiKey?: string;
         baseURL?: string;
     };
-    sambanova?: {
+    groq?: {
         apiKey?: string;
         baseURL?: string;
     };
-    cohere?: {
+    mistral?: {
         apiKey?: string;
         baseURL?: string;
     };
-    together?: {
+    perplexity?: {
         apiKey?: string;
         baseURL?: string;
     };
-    fireworks?: {
+    sambanova?: {
         apiKey?: string;
         baseURL?: string;
     };
-    perplexity?: {
+    together?: {
         apiKey?: string;
         baseURL?: string;
     };
-    cloudflare?: {
+    xai?: {
+        apiKey?: string;
+        baseURL?: string;
+    };
+    cohere?: {
         apiKey?: string;
-        accountId?: string;
         baseURL?: string;
     };
     replicate?: {

package/dist/utils/modelChoices.d.ts

@@ -3,11 +3,19 @@
  * Derives choices from model enums to ensure consistency
  */
 import { AIProviderName } from "../constants/enums.js";
-import type { ModelChoice } from "../types/index.js";
+import type { CatalogProviderName, ModelChoice } from "../types/index.js";
 /**
- * Default models per provider (first choice/recommended)
+ * Default models per provider (first choice/recommended).
+ *
+ * Covers every provider EXCEPT the 9 JSON-catalog providers — those default
+ * models come from `models.default` in the catalog JSON, read directly by
+ * `getDefaultModel()` below. (Two of the 9 — cerebras, sambanova — never had
+ * a hand entry here at all; `getDefaultModel()` now resolves them too.)
+ *
+ * AUTO is also excluded — it never had an entry here either (matches
+ * pre-existing behavior: `getDefaultModel(AUTO)` returns `undefined`).
  */
-export declare const DEFAULT_MODELS: Record<string, string>;
+export declare const DEFAULT_MODELS: Record<Exclude<AIProviderName, CatalogProviderName | AIProviderName.AUTO>, string>;
 /**
  * Get top model choices for a provider (for CLI prompts)
  * Returns models formatted for inquirer list prompts