fix(providers): address review on the Command Code preset

Wibias · Wibias · commit 11a0e095e30d · 2026-08-03T06:32:03.000+02:00
- Seed the default model so discovery failure never empties the catalog
- Correct preset counts in all locales (69: 58 key, 7 OAuth, 3 local, 1 forward)
- State key validation is provider-specific (Command Code: unverifiable)
- Drop the not-yet-available CLI auth bridge claim; add docs URL + verification date
diff --git a/docs-site/src/content/docs/getting-started/quickstart.md b/docs-site/src/content/docs/getting-started/quickstart.md
@@ -13,7 +13,7 @@ ocx init
 
 `ocx init` walks you through:
 
-1. **Pick a provider** — choose one of the 67 built-in registry presets or `custom` to type a base
+1. **Pick a provider** — choose one of the 69 built-in registry presets or `custom` to type a base
    URL and adapter.
 2. **API key** — paste a key, or reference an environment variable like `${ANTHROPIC_API_KEY}`.
 3. **Default model** — for key, local, and custom providers, accept the preset or enter a model id.
diff --git a/docs-site/src/content/docs/guides/providers.md b/docs-site/src/content/docs/guides/providers.md
@@ -190,9 +190,10 @@ selectors, then retry. Signing in from a machine with no existing `kiro-cli` ses
 
 ## 3. API-key catalog
 
-opencodex ships 67 built-in presets: 59 key-based, four OAuth, three local, and the default
+opencodex ships 69 built-in presets: 58 key-based, seven OAuth, three local, and the default
 ChatGPT-forward preset. The dashboard's **Add provider** picker opens a key provider's dashboard,
-validates the key, and stores it. Notable entries:
+validates the key, and stores it; validation is provider-specific, and Command Code's public
+catalog reports keys as unverifiable. Notable entries:
 
 **ClinePass** uses a Cline API key with the [official subscription catalog](https://docs.cline.bot/getting-started/clinepass)
 and [Chat Completions endpoint](https://docs.cline.bot/api/chat-completions), operated by Cline Bot Inc. under
@@ -278,7 +279,7 @@ are out of scope. Create keys at [Hyperbolic](https://app.hyperbolic.ai).
 the fixed Provider API host, preserves provider-native ids, and caps discovery at 256 KiB and 256 raw
 rows. The model catalog is unauthenticated, so the CLI login flow reports the key as unverifiable
 instead of a false positive. Chat requests use the configured Bearer key; API access requires the
-Provider plan, while Go/Pro subscription holders can use the CLI auth bridge. Create keys at
+Provider plan, and CLI auth bridging for Go/Pro subscriptions is not yet available. Create keys at
 [Command Code Studio](https://commandcode.ai/studio/).
 
 > **Baseten scope:** The preset covers Baseten's shared [Model APIs](https://docs.baseten.co/inference/model-apis/overview)
diff --git a/docs-site/src/content/docs/ja/getting-started/quickstart.md b/docs-site/src/content/docs/ja/getting-started/quickstart.md
@@ -13,7 +13,7 @@ ocx init
 
 `ocx init` では次の手順を説明します。
 
-1. **プロバイダーを選択してください** — 67 の組み込みレジストリ プリセットのいずれか、または `custom` を選択してベースを入力します
+1. **プロバイダーを選択してください** — 69 の組み込みレジストリ プリセットのいずれか、または `custom` を選択してベースを入力します
 URLとアダプター。
 2. **API キー** — キーを貼り付けるか、`${ANTHROPIC_API_KEY}` のような環境変数を参照します。
 3. **デフォルト モデル** — キー、ローカル、カスタム プロバイダーの場合は、プリセットを受け入れるか、モデル ID を入力します。
diff --git a/docs-site/src/content/docs/ja/guides/providers.md b/docs-site/src/content/docs/ja/guides/providers.md
@@ -119,9 +119,10 @@ Kiro のログインには Kiro CLI が必要です。Unix では `curl -fsSL ht
 
 ## 3. API キーカタログ
 
-opencodex には組み込みプリセットが 67 個含まれています。キー方式 59、OAuth 4、ローカル 3、
+opencodex には組み込みプリセットが 69 個含まれています。キー方式 58、OAuth 7、ローカル 3、
 デフォルト ChatGPT 転送プリセット 1 です。ダッシュボードの **Add provider** ピッカーはキー発行ページを開き、
-入力したキーを検証した後保存します。主な項目は以下のとおりです:
+入力したキーを検証した後保存します(検証はプロバイダー固有で、Command Code の公開カタログはキーを
+検証不能として報告します)。主な項目は以下のとおりです:
 
 **ClinePass** は Cline API キーで[公式サブスクリプションカタログ](https://docs.cline.bot/getting-started/clinepass)と
 [Chat Completions エンドポイント](https://docs.cline.bot/api/chat-completions)に接続します。運営主体は
@@ -201,7 +202,7 @@ vision-language chat のみを対象とし、別系統の image、audio、GPU en
 Provider API ホストから読み、スラッシュを含むネイティブモデル ID を保持し、live discovery を
 256 KiB と raw 256 行に制限します。モデルカタログは未認証のため、CLI ログインフローはキーを
 誤って有効と報告せず、検証不能として報告します。チャットリクエストは設定済みの bearer キーを使います。
-API アクセスには Provider プランが必要です(Go/Pro サブスクリプション利用者は CLI 認証ブリッジを使用できます)。
+API アクセスには Provider プランが必要で、Go/Pro サブスクリプション向けの CLI 認証ブリッジはまだ利用できません。
 キーは [Command Code Studio](https://commandcode.ai/studio/) で作成します。
 
 > **Baseten の対象範囲:** このプリセットは Baseten の共有 [Model APIs](https://docs.baseten.co/inference/model-apis/overview)
diff --git a/docs-site/src/content/docs/ko/getting-started/quickstart.md b/docs-site/src/content/docs/ko/getting-started/quickstart.md
@@ -13,7 +13,7 @@ ocx init
 
 `ocx init`은 다음 과정을 안내합니다:
 
-1. **프로바이더 선택** — 내장 레지스트리 프리셋 67개 중 하나를 고르거나 `custom`을 선택해 base URL과 adapter를 직접 입력합니다.
+1. **프로바이더 선택** — 내장 레지스트리 프리셋 69개 중 하나를 고르거나 `custom`을 선택해 base URL과 adapter를 직접 입력합니다.
 2. **API 키** — 키를 붙여넣거나 `${ANTHROPIC_API_KEY}` 같은 환경 변수를 참조합니다.
 3. **기본 모델** — 키, 로컬, custom 프로바이더에서는 프리셋을 그대로 쓰거나 모델 ID를 직접 입력합니다.
 4. **프록시 포트** — 기본값은 `10100`입니다.
diff --git a/docs-site/src/content/docs/ko/guides/providers.md b/docs-site/src/content/docs/ko/guides/providers.md
@@ -119,9 +119,10 @@ Kiro 로그인에는 Kiro CLI가 필요합니다. Unix에서는 `curl -fsSL http
 
 ## 3. API 키 카탈로그
 
-opencodex에는 빌트인 프리셋이 67개 들어 있습니다. 키 방식 59개, OAuth 4개, 로컬 3개,
+opencodex에는 빌트인 프리셋이 69개 들어 있습니다. 키 방식 58개, OAuth 7개, 로컬 3개,
 기본 ChatGPT 포워드 프리셋 1개입니다. 대시보드의 **Add provider** 선택기는 키 발급 페이지를 열고,
-입력한 키를 검증한 뒤 저장합니다. 주요 항목은 다음과 같습니다:
+입력한 키를 검증한 뒤 저장합니다(검증은 프로바이더별로 다르며, Command Code의 공개 카탈로그는 키를
+검증 불가로 보고합니다). 주요 항목은 다음과 같습니다:
 
 **ClinePass**는 Cline API 키로 [공식 구독 카탈로그](https://docs.cline.bot/getting-started/clinepass)와
 [Chat Completions 엔드포인트](https://docs.cline.bot/api/chat-completions)에 연결합니다. 운영 주체는
@@ -201,7 +202,7 @@ Bearer API 키를 사용합니다. registry가 소유하는 DeepInfra 모델 목
 호스트에서 읽고, 슬래시가 포함된 네이티브 모델 ID를 보존하며 live discovery를 256 KiB와 raw 행
 256개로 제한합니다. 모델 카탈로그는 인증이 없으므로 CLI 로그인 흐름은 키를 유효하다고 잘못 보고하지
 않고 검증 불가로 보고합니다. 채팅 요청은 설정된 bearer 키를 사용하며, API 액세스에는 Provider 플랜이
-필요합니다(Go/Pro 구독자는 CLI 인증 브리지를 사용할 수 있음). 키는
+필요하고 Go/Pro 구독자용 CLI 인증 브리지는 아직 제공되지 않습니다. 키는
 [Command Code Studio](https://commandcode.ai/studio/)에서 생성합니다.
 
 > **Baseten 범위:** 이 프리셋은 Baseten의 공유 [Model APIs](https://docs.baseten.co/inference/model-apis/overview)만
diff --git a/docs-site/src/content/docs/ru/getting-started/quickstart.md b/docs-site/src/content/docs/ru/getting-started/quickstart.md
@@ -13,7 +13,7 @@ ocx init
 
 `ocx init` проведёт вас по следующим шагам:
 
-1. **Выбор провайдера** — выберите один из 67 встроенных пресетов реестра или `custom`, чтобы
+1. **Выбор провайдера** — выберите один из 69 встроенных пресетов реестра или `custom`, чтобы
    ввести базовый URL и адаптер вручную.
 2. **API-ключ** — вставьте ключ или сошлитесь на переменную окружения вида `${ANTHROPIC_API_KEY}`.
 3. **Модель по умолчанию** — для провайдеров с ключом, локальных и `custom` примите значение из
diff --git a/docs-site/src/content/docs/ru/guides/providers.md b/docs-site/src/content/docs/ru/guides/providers.md
@@ -126,9 +126,10 @@ OAuth-провайдеры, чьи учётные данные содержат
 
 ## 3. Каталог API-ключей
 
-opencodex поставляется с 67 встроенными пресетами: 59 на основе ключей, четыре OAuth, три локальных и
+opencodex поставляется с 69 встроенными пресетами: 58 на основе ключей, семь OAuth, три локальных и
 пресет ChatGPT-форварда по умолчанию. Селектор **Add provider** в дашборде открывает страницу
-выдачи ключей провайдера, проверяет ключ и сохраняет его. Наиболее заметные записи:
+выдачи ключей провайдера, проверяет ключ и сохраняет его; проверка зависит от провайдера, а публичный
+каталог Command Code сообщает ключ как непроверенный. Наиболее заметные записи:
 
 **ClinePass** подключается с помощью Cline API key к [официальному каталогу подписки](https://docs.cline.bot/getting-started/clinepass)
 и [Chat Completions endpoint](https://docs.cline.bot/api/chat-completions). Оператор — Cline Bot Inc., указанный в
@@ -210,8 +211,8 @@ endpoint в него не входят. Ключи создаются в [Hyperb
 хоста Provider API, сохраняет нативные id моделей со знаком `/` и ограничивает live discovery размером
 256 KiB и 256 исходными строками. Каталог моделей не требует аутентификации, поэтому CLI-флоу входа
 сообщает ключ как непроверенный, а не как ложноположительно действительный. Запросы чата используют
-настроенный bearer-ключ; для доступа к API требуется план Provider (подписчики Go/Pro могут использовать
-CLI-мост аутентификации). Ключи создаются в [Command Code Studio](https://commandcode.ai/studio/).
+настроенный bearer-ключ; для доступа к API требуется план Provider, а CLI-мост аутентификации для
+подписок Go/Pro пока недоступен. Ключи создаются в [Command Code Studio](https://commandcode.ai/studio/).
 
 > **Область Baseten:** пресет поддерживает только общие [Model APIs](https://docs.baseten.co/inference/model-apis/overview)
 > Baseten. Для локальной работы используйте личный [API-ключ](https://docs.baseten.co/organization/api-keys),
diff --git a/docs-site/src/content/docs/zh-cn/getting-started/quickstart.md b/docs-site/src/content/docs/zh-cn/getting-started/quickstart.md
@@ -13,7 +13,7 @@ ocx init
 
 `ocx init` 会引导你完成：
 
-1. **选择 provider** — 从内置 registry 的 67 个预设中选择一个，或选择 `custom` 手动输入 base URL 和 adapter。
+1. **选择 provider** — 从内置 registry 的 69 个预设中选择一个，或选择 `custom` 手动输入 base URL 和 adapter。
 2. **API key** — 粘贴一个 key，或引用一个环境变量，例如 `${ANTHROPIC_API_KEY}`。
 3. **默认模型** — 对于 key、本地和 custom provider，接受预设值或输入模型 id。
 4. **代理端口** — 默认为 `10100`。
diff --git a/docs-site/src/content/docs/zh-cn/guides/providers.md b/docs-site/src/content/docs/zh-cn/guides/providers.md
@@ -111,9 +111,9 @@ Kiro 登录需要 Kiro CLI：Unix 使用 `curl -fsSL https://cli.kiro.dev/instal
 
 ## 3. API 密钥目录
 
-opencodex 内置 67 个预设：59 个密钥预设、4 个 OAuth 预设、3 个本地预设，以及默认的
+opencodex 内置 69 个预设：58 个密钥预设、7 个 OAuth 预设、3 个本地预设，以及默认的
 ChatGPT 转发预设。仪表盘的 **Add provider** 选择器会打开密钥提供商的控制台，验证并保存密钥。
-主要条目包括：
+验证因提供商而异，Command Code 的公开目录会将密钥报告为无法验证。主要条目包括：
 
 **ClinePass** 使用 Cline API 密钥连接[官方订阅目录](https://docs.cline.bot/getting-started/clinepass)和
 [Chat Completions 端点](https://docs.cline.bot/api/chat-completions)。运营主体是
@@ -188,7 +188,7 @@ image、audio 和 GPU 端点不在范围内。密钥可在 [Hyperbolic](https://
 **Command Code 发现：**该预设从固定的 Provider API 主机读取 Command Code 公开的
 `/provider/v1/models` 列表，保留含 `/` 的原生模型 id，并将实时发现限制为 256 KiB 和 256 条原始记录。
 模型目录无需认证，因此 CLI 登录流程会将密钥报告为无法验证，而不是误报为有效。聊天请求使用已配置的
-bearer 密钥；API 访问需要 Provider 套餐（Go/Pro 订阅用户可使用 CLI 认证桥接）。
+bearer 密钥；API 访问需要 Provider 套餐，Go/Pro 订阅用户的 CLI 认证桥接尚不可用。
 密钥可在 [Command Code Studio](https://commandcode.ai/studio/) 创建。
 
 > **Baseten 范围：**该预设仅覆盖 Baseten 的共享 [Model APIs](https://docs.baseten.co/inference/model-apis/overview)。
diff --git a/src/providers/registry.ts b/src/providers/registry.ts
@@ -1183,6 +1183,9 @@ export const PROVIDER_REGISTRY: readonly ProviderRegistryEntry[] = [
     liveModels: true,
     preserveCustomDestination: true,
     defaultModel: "deepseek/deepseek-v4-flash",
+    // The default is also the cold-start seed: live discovery failure must not empty the catalog
+    // for a freshly configured provider with no stale cache (issue #308 pattern).
+    models: ["deepseek/deepseek-v4-flash"],
     // The public model catalog is unauthenticated, so a Bearer probe cannot prove key validity.
     apiKeyValidation: "unknown",
     // The public catalog reports ids/context windows only; no trustworthy reasoning contract.
@@ -1192,7 +1195,9 @@ export const PROVIDER_REGISTRY: readonly ProviderRegistryEntry[] = [
       maxResponseBytes: 256 * 1024,
       maxModels: 256,
     },
-    note: "Command Code Provider API (OpenAI-compatible); subscription holders without a Provider plan need the CLI auth bridge for API access.",
+    // Verified 2026-08-03: public /provider/v1/models returns 51 rows; /chat/completions returns
+    // 401 UNAUTHORIZED without a Bearer key. Primary source: https://commandcode.ai/docs/provider.
+    note: "Command Code Provider API (OpenAI-compatible); API access requires the Provider plan. CLI auth bridging for Go/Pro subscriptions is not yet available. Docs: https://commandcode.ai/docs/provider.",
   },
   // FREEZE 2026-07-10: exact serverless ids remain auth-gated/unverified. Evidence: devlog/_plan/260710_provider_hardening/003_research_aggregators.md.
   { id: "together", label: "Together", baseUrl: "https://api.together.xyz/v1", adapter: "openai-chat", authKind: "key", dashboardUrl: "https://api.together.xyz/settings/api-keys" },
diff --git a/tests/commandcode-provider.test.ts b/tests/commandcode-provider.test.ts
@@ -75,8 +75,9 @@ describe("Command Code provider", () => {
       },
     });
     expect(providerModelDiscoverySpecError(entry.modelDiscovery!)).toBeNull();
-    // The public catalog lists ids/context windows only; no static per-model claims are seeded.
-    expect(entry.models).toBeUndefined();
+    // The public catalog lists ids/context windows only, so the only static seed is the default
+    // model itself — it stays callable when live discovery fails on a fresh config (no cache).
+    expect(entry.models).toEqual(["deepseek/deepseek-v4-flash"]);
   });
 
   test("derives key-login, init, and dashboard presets without persisting trust policy", () => {
@@ -88,6 +89,7 @@ describe("Command Code provider", () => {
       liveModels: true,
       defaultModel: "deepseek/deepseek-v4-flash",
       apiKeyValidation: "unknown",
+      models: ["deepseek/deepseek-v4-flash"],
     });
     expect(buildInitProviders()).toEqual(deriveInitProviders());
     expect(buildInitProviders().find(row => row.id === "commandcode")).toMatchObject({
@@ -110,6 +112,7 @@ describe("Command Code provider", () => {
       liveModels: true,
       reasoningEfforts: [],
       defaultModel: "deepseek/deepseek-v4-flash",
+      models: ["deepseek/deepseek-v4-flash"],
     });
     expect(seed).not.toHaveProperty("modelDiscovery");
     expect(seed).not.toHaveProperty("preserveCustomDestination");
@@ -204,4 +207,19 @@ describe("Command Code provider", () => {
     expect(routeModel(config, "commandcode/deepseek-deepseek-v4-flash").modelId)
       .toBe("deepseek/deepseek-v4-flash");
   });
+
+  test("keeps the default model callable when live discovery fails on a fresh config", async () => {
+    globalThis.fetch = (async () => new Response("upstream down", {
+      status: 500,
+      headers: { "content-type": "text/plain" },
+    })) as typeof fetch;
+
+    const config = withStubbedProviderFetch(commandcodeConfig());
+    const models = (await gatherRoutedModels(config)).filter(row => row.provider === "commandcode");
+
+    // No stale cache exists on a fresh config, so the seeded default must survive the failure.
+    expect(models.map(row => row.id)).toEqual(["deepseek/deepseek-v4-flash"]);
+    expect(routeModel(config, "commandcode/deepseek/deepseek-v4-flash").modelId)
+      .toBe("deepseek/deepseek-v4-flash");
+  });
 });
