feat(onboarding): guide registrations to model selection

devlog/_plan/260905_provider_registration_selection/010_initial_selection.md

@@ -14,6 +14,7 @@ Persisted provider field:
 ```ts
 initialModelSelection?: {
   version: 1;
+  registrationId: string; // new UUID on first creation only; preserved on overwrite
   status: "pending" | "ready" | "all-off";
   modelCount?: number;
 };
@@ -84,6 +85,10 @@ No change to explicit model-ID routing.
 ### NEW src/providers/initial-model-selection-runtime.ts
 
 Own the ordinary-discovery completion write, independent of Codex integration.
+Match registration UUID as well as normalized inventory-producing configuration
+(including custom rows, combos and provider dependencies). Equal field values
+after delete/re-add are not the same registration. Schema-default normalization
+and order-independent comparison avoid spurious mismatches after load/save.
 Capture pending provider config and disabledModels before gather; use existing
 authoritative outcome metadata and the pure transition after discovery. Re-read
 under mutatePersistedConfig, compare the captured provider/selection identity,
@@ -103,16 +108,16 @@ no pending provider keep the existing fast path, with no writes/new discovery.
 catalog evidence; never insert config writes inside an already sealed gather.
 The evidence-only gather entry point remains mutation-free.
 
-### MODIFY src/codex/convergence.ts
+### MODIFY src/codex/management-convergence.ts and src/codex/convergence.ts
 
-Before prepareCatalog, clone snapshot config as now, run initial-selection
-reconciliation using authoritative providerModelOutcomes (static included), then
-run existing successful-discovery reconciliation; execute BOTH, do not short-circuit
-one in an `a || b` call expression. Carry projected config if either changed.
-After successful admitted commit, adopt state with disabledModels/modelDiscovery
-and use existing coordinated save. A failed/stale/busy commit must not publish
-state or OFF decisions. Snapshot identity already hashes complete config, so the
-new provider field is covered without a second fingerprint implementation.
+Implementation refinement: the management wrapper resolves pending initialization
+BEFORE capturing catalog admission, just as retained sync does before its evidence
+read. This avoids coupling durable initial selection to a later catalog-file write
+or exposing an in-memory completed marker after a failed config save. The evidence
+gather stays read-only; convergence only carries pending-provider names into final
+visibility filtering. Existing later-arrival projection is untouched. Registration
+choices commit independently of optional Codex catalog success. Snapshot identity
+already hashes complete config, so no second fingerprint implementation is needed.
 
 ### MODIFY src/server/management/model-rows.ts and model-routes.ts
 

devlog/_plan/260905_provider_registration_selection/020_registration_guidance.md

@@ -41,14 +41,40 @@ toast for new registration). Capture whether provider existed before add/login.
 Wire modal-local OAuth and catalog OAuth completion through the same notice owner;
 existing account management/relogin continues Accounts navigation and does not
 reset selections. For initial Codex provider creation, onCodexAdded also shows
-Models guidance; avoid showing it merely for every added pool account.
+Models guidance. Explicit account/login completion also receives generic guidance
+(including the pre-seeded OpenAI provider); it never resets model choices. Existing
+Accounts navigation remains underneath the notice. Historical all-OFF copy is
+shown only for a newly created provider, not as a claim that re-login reset switches.
+
+Implementation owners after source recheck: NEW
+gui/src/pages/use-provider-models-notice.ts owns the operation token and render-local
+notice lifecycle. ProviderWorkspaceShell's existing /api/selected-models completion
+invokes a stable onModelsSettled callback; only an active notice triggers a later
+config refresh. Reuse its existing refresh token for Retry, with no duplicate model
+fetch and no new poll timer. useProvidersFetch adds a latest-request guard so an
+earlier pending config response cannot overwrite the post-discovery snapshot.
+The refresh result is explicit (applied/failed/superseded), with one bounded retry
+for supersession. Failed config reads never become success guidance. API-base
+changes clear both the active operation and render state, including A→B→A.
 
 ### MODIFY gui/src/pages/use-providers-oauth.ts as needed
 
 Forward an existing new-provider boolean/name at completion through its callback,
 without touching credential polling, reauth identity rules or secrets. Code
 submission is not success; popup waits for existing login-settled signal.
 
+Embedded/standalone Codex account add/reauth is a separate completion owner.
+Reuse the same ProviderModelsNotice renderer directly in CodexAccountPool for
+generic forward-auth guidance, preserving its pool state and catalog-refresh
+warning. It does not need a model-count fetch or four callback-prop forwarding
+layers. Cover this path as well as Providers' top-level modal completion.
+
+The JSON editor reports newly added provider names to Providers after successful
+save; show one generic notice for a batch and the normal per-provider notice for
+a single new row. It also strips initialModelSelection from editor payloads; that
+two-line compatibility fix is carried in core c5ad48c19, already an ancestor of
+this branch. Core final CI must validate that updated head before merge.
+
 ### MODIFY gui/src/pages/providers-shared.ts
 
 Add the sanitized initialModelSelection read-only field to ProvidersConfig. Keep
@@ -76,10 +102,13 @@ ocx models disable <provider/model-id>
 ocx models provider <provider> on
 ```
 
-Use a real ID from a trustworthy result where available; otherwise an explicitly
-labeled placeholder. Include `ocx start` prerequisite when the proxy is absent,
+Use the exact ID printed by `live` (native or namespaced), represented in examples
+by an explicitly labeled, quoted placeholder. Include `ocx start` prerequisite when the proxy is absent,
 and `ocx sync` retry guidance when discovery remains pending. No credentials in
 commands or messages. No shell execution from the builder.
+Rows marked native also receive explicit enable/disable --native command variants
+in both human and JSON output, so account-qualified native IDs containing a slash
+are not misparsed as routed provider/model selectors.
 
 ### MODIFY CLI completion owners
 
@@ -120,6 +149,11 @@ commands or messages. No shell execution from the builder.
 - NEW tests/cli/model-selection-guidance.test.ts with both layout manifests.
 - Preserve existing auth URL/credential tests; no network/API-key requirements.
 
+P recheck: core state shape is version1 + registrationId + status + modelCount;
+safeConfigDTO exposes it read-only. Public threshold docs already landed in the core
+layer, so this phase adds only registration-guidance text, not a second policy rewrite.
+Core exact-head CI33947171242 passed at2cc90b447 before this cycle began.
+
 Local checks: TypeScript, GUI lint/i18n, GUI build, docs build, whitespace. All
 test suites run remotely in GitHub CI, not locally. Runtime UI proof is a manual
 isolated fake-provider scenario, not a repository test suite: new 20-model key

devlog/_plan/260905_provider_registration_selection/023_onboarding_verification.md

@@ -0,0 +1,20 @@
+# Onboarding verification
+
+Source: wp2 on top of core c5ad48c19. No local test suites were executed.
+
+- Root TypeScript, GUI build, lint and i18n lint passed.
+- New dialog/hook regression file passed static TypeScript checking.
+- Independent source review PASS after fixing explicit config-refresh results and
+  API-target A→B→A notice lifetime; no remaining blocking findings.
+- Isolated source backend, fake 20-model upstream and separate temporary
+  OPENCODEX_HOME/CODEX_HOME. The user's running proxy/config were not changed.
+- Real browser Add Provider → custom registration → completed all-OFF notice
+  with count 20 → Open Models → registration-demo 0/20 visible, all 20 switches
+  unchecked. Existing native OpenAI rows remained 8/8 visible.
+- Enabled demo-model-1 in the real UI and reloaded: 1/20 remained visible, its
+  checkbox stayed checked, and the other 19 stayed OFF.
+- Screenshots 021 and 022 are actual built dashboard captures, not mockups.
+
+Full behavioral regression execution and final landing evidence are supplied by
+the exact-head GitHub CI runs and stacked pull requests; static/manual evidence
+does not substitute for those gates.

docs-site/src/content/docs/fr/reference/configuration/providers.md

@@ -6,6 +6,21 @@ description: Entrées du fournisseur, authentification, points de terminaison, c
 Un fournisseur indique à opencodex où se trouve un modèle, quel adaptateur de protocole il utilise et comment les requêtes sont
 authentifiées.
 
+## Sélection des modèles à l’inscription
+
+Une nouvelle connexion sans OAuth attend une liste de modèles fiable avant de les exposer. Si l’onglet Models contient au moins 20 lignes distinctes, tous les interrupteurs de modèles sont initialement OFF ; le fournisseur reste ACTIVE. Les connexions utilisant effectivement OAuth ou la connexion ChatGPT conservent leurs valeurs par défaut.
+
+Cette règle ne s’applique qu’à l’inscription d’un nouveau fournisseur. Les mises à jour, reconnexions et remplacements de clé préservent les choix existants. Après l’initialisation, activez les modèles souhaités dans Models ou avec les commandes ci-dessous. La politique distincte concernant les nouveaux modèles reste inchangée. Remplacez `<model-id>` par un ID de la liste.
+
+```sh
+ocx models live --provider openrouter
+ocx models enable '<model-id>'
+ocx models disable '<model-id>'
+ocx models provider openrouter on
+```
+
+Après une inscription ou une connexion OAuth dans l’interface, une boîte de dialogue permet d’ouvrir Models. La CLI affiche les commandes de gestion des modèles, aussi présentes dans les étapes suivantes du JSON. `--no-wait` indique une connexion en attente, pas terminée. Lancez le proxy avec `ocx start` avant les commandes de modèles en direct.
+
 ## Champs de premier niveau liés aux fournisseurs
 
 | Champ | Type | Par défaut | Signification |

docs-site/src/content/docs/ja/reference/configuration/providers.md

@@ -5,6 +5,21 @@ description: プロバイダー エントリ、認証、エンドポイント、
 
 プロバイダーは、opencodex に、モデルが存在する場所、モデルが通信するワイヤー アダプター、およびリクエストの認証方法を伝えます。
 
+## 初回登録時のモデル選択
+
+新しい非 OAuth 接続では、信頼できるモデル一覧の取得が完了するまでモデルの公開を保留します。Models タブの重複しないモデル行が20個以上なら、モデルのスイッチをすべて OFF にします。プロバイダー自体は ACTIVE のままです。実際の認証方式が OAuth または ChatGPT ログインなら既定値を維持します。
+
+初回のプロバイダー登録にのみ適用され、更新、再ログイン、キー交換で既存の選択をリセットしません。初期設定後は Models または以下の CLI で必要なモデルを有効にできます。後から追加されるモデルのポリシーは変更しません。`<model-id>` を一覧の ID に置き換えてください。
+
+```sh
+ocx models live --provider openrouter
+ocx models enable '<model-id>'
+ocx models disable '<model-id>'
+ocx models provider openrouter on
+```
+
+GUI で登録または OAuth ログインが完了すると、Models ページへ移動できる案内が表示されます。CLI はモデル管理コマンドを出力し、JSON にも次の操作を含めます。`--no-wait` は完了ではなくログイン待機を示します。ライブモデルのコマンドを使う前に `ocx start` でプロキシを起動してください。
+
 ## プロバイダー関連のトップレベルフィールド
 
 |フィールド |タイプ |デフォルト |意味 |

docs-site/src/content/docs/ko/reference/configuration/providers.md

@@ -5,6 +5,21 @@ description: 공급자 항목, 인증, 엔드포인트, 모델 카탈로그, 할
 
 공급자는 opencodex에 모델의 위치, 사용하는 와이어 어댑터, 요청 인증 방식을 알려줍니다.
 
+## 처음 등록할 때의 모델 선택
+
+신규 비-OAuth 연결은 신뢰할 수 있는 모델 목록을 확보할 때까지 모델 노출을 보류합니다. Models 탭의 중복 없는 모델 행이 20개 이상이면 모델 스위치를 모두 OFF로 설정합니다. 프로바이더는 활성 상태를 유지합니다. 실제 인증 방식이 OAuth나 ChatGPT 로그인인 연결은 기존 기본값을 유지합니다.
+
+처음 등록할 때만 적용하며 업데이트, 재로그인, 키 교체로 기존 선택을 초기화하지 않습니다. 초기 설정이 끝나면 Models 탭이나 아래 CLI 명령으로 필요한 모델을 켤 수 있습니다. 이후 새 모델이 추가될 때의 정책은 별도입니다. `<model-id>`는 목록에 나온 ID로 바꾸세요.
+
+```sh
+ocx models live --provider openrouter
+ocx models enable '<model-id>'
+ocx models disable '<model-id>'
+ocx models provider openrouter on
+```
+
+GUI에서 등록이나 OAuth 로그인을 마치면 Models 페이지로 이동하는 안내 팝업이 뜹니다. CLI는 모델 관리 명령을 출력하며 JSON 응답에도 다음 단계가 포함됩니다. `--no-wait`는 로그인 완료가 아닌 대기 상태를 표시합니다. 실시간 모델 명령을 쓰기 전에 `ocx start`로 프록시를 시작하세요.
+
 ## 공급자 관련 최상위 필드
 
 | 필드 | 타입 | 기본값 | 의미 |

docs-site/src/content/docs/reference/configuration/providers.md

@@ -6,6 +6,21 @@ description: Provider entries, authentication, endpoints, model catalogs, quotas
 A provider tells opencodex where a model lives, which wire adapter it speaks, and how requests are
 authenticated.
 
+## Initial model selection
+
+New non-OAuth connections wait for a reliable model list before exposing models. If that list contains at least 20 distinct Models-tab rows, all model switches start OFF; the provider itself stays ACTIVE. OAuth and ChatGPT-login connections keep their defaults, based on the effective authentication mode.
+
+This runs only for a new provider registration. Existing selections survive updates, re-login and key replacement. After initialization, enable the models you need in Models or with the CLI below; the separate new-model-arrival policy is unchanged. Replace `<model-id>` with an ID from the list.
+
+```sh
+ocx models live --provider openrouter
+ocx models enable '<model-id>'
+ocx models disable '<model-id>'
+ocx models provider openrouter on
+```
+
+After GUI registration or OAuth login, the confirmation dialog opens the Models page. CLI registration and login print model-management commands; JSON includes structured next steps. `--no-wait` reports pending login, not completion. Start the proxy with `ocx start` before using live model commands.
+
 ## Provider-related top-level fields
 
 | Field | Type | Default | Meaning |

docs-site/src/content/docs/ru/reference/configuration/providers.md

@@ -6,6 +6,21 @@ description: Записи провайдеров, аутентификация,
 Провайдер сообщает opencodex, где живёт модель, на каком wire-adapter'е она работает и как
 аутентифицируются запросы.
 
+## Выбор моделей при первой регистрации
+
+Новое подключение без OAuth не публикует модели до получения достоверного списка. Если в Models не менее 20 уникальных строк моделей, все переключатели моделей изначально OFF, но сам провайдер остаётся ACTIVE. Подключения, фактически использующие OAuth или вход ChatGPT, сохраняют настройки по умолчанию.
+
+Правило действует только при регистрации нового провайдера. Обновления, повторный вход и смена ключа не сбрасывают существующий выбор. После инициализации включите нужные модели в Models или командами ниже. Отдельная политика появления новых моделей не меняется. Замените `<model-id>` на ID из списка.
+
+```sh
+ocx models live --provider openrouter
+ocx models enable '<model-id>'
+ocx models disable '<model-id>'
+ocx models provider openrouter on
+```
+
+После регистрации или входа OAuth в интерфейсе диалог предлагает открыть Models. CLI выводит команды управления моделями; JSON содержит следующие шаги. `--no-wait` означает ожидание входа, а не завершение. Перед командами для актуального списка моделей запустите прокси через `ocx start`.
+
 ## Верхнеуровневые поля, связанные с провайдерами
 
 | Поле | Тип | По умолчанию | Значение |

docs-site/src/content/docs/tr/reference/configuration/providers.md

@@ -6,6 +6,21 @@ description: Sağlayıcı girdileri, kimlik doğrulama, uç noktalar, model kata
 Bir sağlayıcı, opencodex'e bir modelin nerede yaşadığını, hangi hat adaptörünü
 konuştuğunu ve isteklerin nasıl doğrulandığını söyler.
 
+## İlk kayıtta model seçimi
+
+Yeni OAuth dışı bağlantılar, modelleri göstermeden önce güvenilir bir model listesini bekler. Models sekmesinde en az 20 benzersiz model satırı varsa tüm model anahtarları başlangıçta OFF olur; sağlayıcının kendisi ACTIVE kalır. Gerçekte OAuth veya ChatGPT girişi kullanan bağlantılar varsayılanlarını korur.
+
+Bu kural yalnızca yeni sağlayıcı kaydında uygulanır. Güncellemeler, yeniden giriş ve anahtar değişimi mevcut seçimleri sıfırlamaz. İlk ayardan sonra gerekli modelleri Models üzerinden veya aşağıdaki CLI komutlarıyla açın. Sonradan gelen yeni modellerin ayrı politikası değişmez. `<model-id>` yerine listedeki bir ID yazın.
+
+```sh
+ocx models live --provider openrouter
+ocx models enable '<model-id>'
+ocx models disable '<model-id>'
+ocx models provider openrouter on
+```
+
+Arayüzde kayıt veya OAuth girişi tamamlanınca Models sayfasını açan bir bilgilendirme penceresi gösterilir. CLI model yönetimi komutlarını yazdırır; JSON sonraki adımları içerir. `--no-wait` tamamlanmış değil, bekleyen girişi bildirir. Canlı model komutlarından önce proxy’yi `ocx start` ile başlatın.
+
 ## Sağlayıcı ile ilgili üst düzey alanlar
 
 | Alan | Tip | Varsayılan | Anlamı |

docs-site/src/content/docs/zh-cn/reference/configuration/providers.md

@@ -5,6 +5,21 @@ description: 提供者条目、身份验证、端点、模型目录、配额、
 
 提供者用于告诉 opencodex 模型位于哪里、使用哪种线协议适配器，以及请求如何进行身份验证。
 
+## 首次注册时的模型选择
+
+新的非 OAuth 连接会等待可靠的模型列表，再公开模型。如果 Models 标签页中去重后的模型行达到20个，所有模型开关初始为 OFF，但提供者本身保持 ACTIVE。实际认证方式为 OAuth 或 ChatGPT 登录的连接保留默认设置。
+
+仅在首次注册提供者时应用；更新、重新登录和更换密钥不会重置已有选择。初始化后，可在 Models 或使用以下 CLI 命令启用所需模型。后续新增模型的独立策略不变。请将 `<model-id>` 替换为列表中的 ID。
+
+```sh
+ocx models live --provider openrouter
+ocx models enable '<model-id>'
+ocx models disable '<model-id>'
+ocx models provider openrouter on
+```
+
+在界面中完成注册或 OAuth 登录后，提示框可打开 Models 页面。CLI 会输出模型管理命令，JSON 也包含后续步骤。`--no-wait` 表示登录仍在等待中，并非已完成。使用实时模型命令前，请先运行 `ocx start` 启动代理。
+
 ## 提供者相关顶级字段
 
 | 字段 | 类型 | 默认值 | 含义 |