feat(gui,docs): Claude Desktop connection-mode selector and first-party docs

docs-site/src/content/docs/fr/guides/claude-code.md

@@ -121,7 +121,34 @@ Sur macOS, l'intégration automatique (`claudeCode.systemEnv`) suit la même ré
 `claude` lancée sans passer par `ocx` se comporte donc de la même manière. Le fichier d'environnement est un instantané actualisé au
 démarrage du proxy ou lors de l'enregistrement des paramètres, tandis que `ocx claude` effectue toujours une résolution immédiate.
 
-## Profil Claude Desktop
+## Modes Claude Desktop : first-party (par défaut) et passerelle
+
+Claude Desktop utilise OpenCodex dans l'un de deux modes mutuellement exclusifs. Choisissez-le dans
+**Claude → Bureau → Mode de connexion** du tableau de bord ou avec
+`ocx claude desktop apply --first-party|--gateway`.
+
+- **First-party (par défaut)** : Desktop lui-même n'est pas reconfiguré. La connexion claude.ai,
+  l'onglet Chat, les connecteurs et le contrôle à distance continuent de fonctionner. OpenCodex
+  n'écrit que deux valeurs dans le bloc `env` de `~/.claude/settings.json` :
+  `HTTPS_PROXY=http://127.0.0.1:<port public+100>` et
+  `NODE_EXTRA_CA_CERTS=~/.opencodex/claude-intercept/ca.pem`. Seuls Claude Code lancé par Desktop
+  pour l'onglet Code (sous-agents compris) et la CLI `claude` du terminal les lisent et passent par le
+  proxy d'interception local ; seuls `POST /v1/messages` et `count_tokens` sont traités par OpenCodex,
+  les autres chemins de `api.anthropic.com` sont relayés tels quels vers Anthropic. L'AC n'est jamais
+  installée dans le magasin de confiance du système.
+- **Passerelle (tiers)** : l'ancien mode ; le profil ci-dessous fait basculer toute l'application sur
+  OpenCodex comme passerelle. Sélectionnez-le explicitement (`--gateway`, ou les anciens
+  `--static`/`--hybrid`/`--discovery-only`).
+
+Le mode est enregistré dans `claudeCode.desktopMode`. Les installations ayant déjà appliqué un profil
+passerelle le conservent après mise à jour ; seules les nouvelles installations démarrent en
+first-party. Changer de mode supprime la configuration de l'autre mode (uniquement les valeurs
+écrites par OpenCodex) ; un `HTTPS_PROXY`/`NODE_EXTRA_CA_CERTS` étranger (proxy d'entreprise) n'est
+jamais écrasé et l'application est refusée. Quittez complètement Desktop puis rouvrez-le après un
+changement. Les détails et la compatibilité de la CLI Claude Code sont décrits dans la documentation
+anglaise.
+
+## Profil Claude Desktop (mode passerelle)
 
 Claude Desktop utilise un profil distinct de Claude Code. Ouvrez **Claude → Bureau** dans le
 tableau de bord afin de placer chaque route disponible dans l'une des quatre familles : Opus, Fable, Sonnet ou Haiku.

docs-site/src/content/docs/guides/claude-code.md

@@ -135,9 +135,73 @@ the proxy starts or you save settings, while `ocx claude` always resolves live.
 
 ## System environment integration (macOS)
 
-## Claude Desktop profile
+## Claude Desktop modes: first-party (default) and gateway
 
-Claude Desktop uses a separate profile from Claude Code. Open **Claude → Desktop** in the
+Claude Desktop can use OpenCodex in one of two mutually exclusive modes. Pick it in
+**Claude → Desktop → Connection mode** in the dashboard or with `ocx claude desktop apply
+--first-party|--gateway`.
+
+**First-party** is the default for new installs. Desktop itself is not reconfigured: it stays
+signed in to claude.ai, and the Chat tab, connectors, cloud sessions and remote control keep
+working. OpenCodex only writes two variables into the `env` block of `~/.claude/settings.json`
+(honoured by `CLAUDE_CONFIG_DIR`):
+
+```json
+{
+  "env": {
+    "HTTPS_PROXY": "http://127.0.0.1:10200",
+    "NODE_EXTRA_CA_CERTS": "<home>/.opencodex/claude-intercept/ca.pem"
+  }
+}
+```
+
+Claude Code — the process Desktop spawns for its Code tab, every subagent it launches, and the
+standalone `claude` CLI — reads that env and sends its `api.anthropic.com` traffic through the
+local intercept proxy. The proxy listens on the public port + 100 (`claudeCode.intercept.port`
+overrides it), terminates TLS with a per-install CA stored under `~/.opencodex/claude-intercept/`
+(never installed into the OS trust store; only Node processes that read `NODE_EXTRA_CA_CERTS`
+trust it), and hands `POST /v1/messages` and `POST /v1/messages/count_tokens` to the same
+Messages handler `ocx claude` uses. Every other path on `api.anthropic.com` (OAuth, profile,
+usage) is relayed byte-for-byte to Anthropic, and unrelated hosts are tunnelled untouched, so your
+subscription login keeps working. Existing OpenCodex features — `modelMap`, aliases, native
+passthrough, sidecars, auto-context — apply the same way they do for `ocx claude`.
+
+**Gateway** is the previous third-party mode: the profile described in the next section switches
+the whole app to OpenCodex as its inference gateway. Chat runs locally through OpenCodex and the
+claude.ai-only features are unavailable. Select it explicitly (`--gateway`, the dashboard
+selector, or the legacy `--static` / `--hybrid` / `--discovery-only` flags, which imply it).
+
+Mode is persisted as `claudeCode.desktopMode`. Installs that already applied a gateway profile
+keep gateway after updating; nothing is switched silently. Switching in either direction removes
+the other mode's configuration (only values OpenCodex wrote — a foreign `HTTPS_PROXY` or
+`NODE_EXTRA_CA_CERTS`, for example a corporate proxy, is never overwritten and the apply is
+refused instead). Fully quit and reopen Desktop after switching. `ocx ensure` refreshes a stale
+first-party env when the integration is ON and removes it when OFF. Set
+`claudeCode.intercept.enabled: false` to disable the proxy entirely; first-party then cannot be
+applied and an implicit apply falls back to gateway. On a connected client the proxy runs on the
+hub, so `ocx claude desktop apply` there uses the gateway profile.
+
+### Claude Code CLI compatibility
+
+The same `settings.json` env drives the standalone `claude` CLI, so a first-party apply also
+covers terminal sessions, `claude -p`, and subagents without `ocx claude`'s
+`ANTHROPIC_BASE_URL` / `ANTHROPIC_AUTH_TOKEN` shell env. Differences from `ocx claude`:
+
+- Model discovery (`/model` → "From gateway") is not available; Claude Code only queries
+  `GET /v1/models` on a configured gateway. Use `modelMap` to route the built-in Anthropic model
+  ids, or type an alias directly.
+- `ANTHROPIC_SMALL_FAST_MODEL` and `CLAUDE_CODE_SUBAGENT_MODEL` are chosen by the CLI before the
+  request is sent; set them in `settings.json` yourself if a sidecar or subagent should use a
+  mapped id.
+- `ocx claude` and first-party coexist: a session started with `ocx claude` talks to
+  `ANTHROPIC_BASE_URL` (plain HTTP on loopback), which `HTTPS_PROXY` does not cover, so that
+  process reaches OpenCodex directly and the proxy simply sees no traffic from it.
+- Claude Code honours `HTTPS_PROXY`/`NODE_EXTRA_CA_CERTS` as documented for corporate proxies;
+  a CLI release that stops doing so would stop routing, not break login.
+
+## Claude Desktop profile (gateway mode)
+
+The profile below is written only in gateway mode. Claude Desktop uses a separate profile from Claude Code. Open **Claude → Desktop** in the
 dashboard to place each available route in one of four families: Opus, Fable, Sonnet, or Haiku.
 All routes start in Opus on a new profile. The first Opus route becomes the initial overall
 default, and every non-empty family always has one family default.
@@ -161,9 +225,10 @@ ocx claude desktop export <path|->
 ocx claude desktop import <path> [--apply]
 ```
 
-`ocx claude desktop` and `apply` both write the current profile to Claude Desktop. `show` gives a
-readable summary; `status` reports the applied profile, drift, request activity, and Windows
-managed-policy health. Add `--json` for scripts. `export -` writes versioned JSON to standard output.
+`ocx claude desktop` and `apply` apply the selected mode: first-party writes the Claude Code proxy
+env, gateway writes the current profile to Claude Desktop. `show` gives a
+readable summary; `status` reports the effective mode, the applied profile or proxy env, drift,
+request activity, and (gateway mode only) Windows managed-policy health. Add `--json` for scripts. `export -` writes versioned JSON to standard output.
 Import validates the complete file before saving, so an invalid file leaves the current profile
 unchanged. Add `--apply` to write a valid imported profile to Desktop immediately. Use `none` only
 for an empty family; every non-empty family must keep one default.
@@ -637,6 +702,9 @@ Claude debug immediately clears the ring.
 The dashboard sidebar has a dedicated **Claude** page (below API) and a **Claude ON** toggle
 (label intentionally identical in every language). The page shows:
 
+- Desktop tab: **Connection mode** selector — first-party (default) or gateway — with the
+  running proxy port in first-party mode. Only **Save & apply** switches modes; **Save** alone
+  stores the gateway profile lanes for a later gateway apply and leaves the current mode as is
 - Inbound kill switch (enabled toggle)
 - Quickstart (`ocx claude`) and manual env block
 - Fast Mode selector (Auto / ON / OFF)

docs-site/src/content/docs/ja/guides/claude-code.md

@@ -95,6 +95,29 @@ hook を削除します。Claude Desktop は独立した profile を使用し、
 `claudeCode.nativePassthrough: false` でオフにでき、`claudeCode.anthropicBaseUrl` で別のアドレスを
 指定できます。
 
+## Claude Desktop のモード: 1P（デフォルト）とゲートウェイ
+
+Claude Desktop は排他的な 2 つのモードのどちらかで OpenCodex を使います。ダッシュボードの
+**Claude → Desktop → 接続モード**、または `ocx claude desktop apply --first-party|--gateway` で選びます。
+
+- **1P（ファーストパーティ、デフォルト）**: Desktop 本体は変更しません。claude.ai のログイン、
+  チャットタブ、コネクタ、リモート操作はそのまま動きます。OpenCodex は `~/.claude/settings.json` の
+  `env` に `HTTPS_PROXY=http://127.0.0.1:<公開ポート+100>` と
+  `NODE_EXTRA_CA_CERTS=~/.opencodex/claude-intercept/ca.pem` の 2 つだけを書きます。Desktop が
+  Code タブ用に起動する Claude Code（サブエージェント含む）とターミナルの `claude` CLI だけがこれを読み、
+  ローカルのインターセプトプロキシを通ります。`POST /v1/messages` と `count_tokens` のみ OpenCodex が
+  処理し、他の `api.anthropic.com` パスはそのまま Anthropic に中継されます。CA は OS の信頼ストアには
+  インストールされません。
+- **ゲートウェイ（3P）**: 従来の方式で、下記のプロファイルによりアプリ全体が OpenCodex を
+  ゲートウェイとして使います。`--gateway`（または従来の `--static`/`--hybrid`/`--discovery-only`）で
+  明示的に選びます。
+
+モードは `claudeCode.desktopMode` に保存されます。すでにゲートウェイプロファイルを適用済みの環境は
+更新後もゲートウェイのままで、新規インストールだけが 1P になります。切り替えると他方のモードの設定
+（OpenCodex が書いた値のみ）が削除され、社内プロキシなど外部の `HTTPS_PROXY`/`NODE_EXTRA_CA_CERTS`
+は上書きせず適用を拒否します。切り替え後は Desktop を完全に終了して再起動してください。詳細と
+Claude Code CLI 互換性は英語版ドキュメントを参照してください。
+
 ## リモートハブに接続した Claude Desktop
 
 接続中のマシンで `ocx claude desktop apply` または `ocx claude desktop` を実行すると、

docs-site/src/content/docs/ko/guides/claude-code.md

@@ -118,6 +118,27 @@ hook을 제거해요. Claude Desktop은 별도 profile을 사용하며 shell hoo
 `claudeCode.nativePassthrough: false`로 끌 수 있고, `claudeCode.anthropicBaseUrl`로 다른 주소를
 지정할 수 있어요.
 
+## Claude Desktop 모드: 1P(기본값)와 게이트웨이
+
+Claude Desktop은 서로 배타적인 두 모드 중 하나로 OpenCodex를 사용해요. 대시보드의
+**Claude → Desktop → 연결 모드** 또는 `ocx claude desktop apply --first-party|--gateway`로 선택합니다.
+
+- **1P(퍼스트파티, 기본값)**: Desktop 자체는 건드리지 않아요. claude.ai 로그인, 채팅 탭, 커넥터,
+  원격 제어가 그대로 유지됩니다. OpenCodex는 `~/.claude/settings.json`의 `env`에
+  `HTTPS_PROXY=http://127.0.0.1:<공개 포트+100>`과 `NODE_EXTRA_CA_CERTS=~/.opencodex/claude-intercept/ca.pem`
+  두 값만 씁니다. Desktop이 Code 탭용으로 실행하는 Claude Code(서브에이전트 포함)와 터미널의
+  `claude` CLI만 이 값을 읽어 로컬 인터셉트 프록시를 거치고, `POST /v1/messages`·`count_tokens`만
+  OpenCodex가 처리하며 나머지 `api.anthropic.com` 경로는 그대로 Anthropic으로 전달돼요. CA는 OS
+  신뢰 저장소에 설치되지 않습니다.
+- **게이트웨이(3P)**: 기존 방식으로, 아래 프로필을 써서 앱 전체가 OpenCodex를 게이트웨이로
+  사용해요. `--gateway`(또는 기존 `--static`/`--hybrid`/`--discovery-only`)로 명시적으로 선택합니다.
+
+모드는 `claudeCode.desktopMode`에 저장돼요. 이미 게이트웨이 프로필을 적용한 설치는 업데이트 후에도
+게이트웨이를 유지하고, 새 설치만 1P가 기본이에요. 모드를 바꾸면 다른 모드의 설정(OpenCodex가 쓴
+값만)이 제거되며, 회사 프록시 같은 외부 `HTTPS_PROXY`/`NODE_EXTRA_CA_CERTS` 값은 덮어쓰지 않고 적용을
+거부해요. 전환 후에는 Desktop을 완전히 종료하고 다시 열어 주세요. 자세한 내용과 Claude Code CLI
+호환성은 영어 문서를 참고하세요.
+
 ## 원격 허브에 연결된 Claude Desktop
 
 허브에 연결된 컴퓨터에서 `ocx claude desktop apply` 또는 `ocx claude desktop`을 실행하면

gui/src/i18n/de.ts

@@ -2622,6 +2622,19 @@ export const de: Record<TKey, string> = {
   "claudeDesktop.status.notActiveProfile": "Desktop nutzt ein anderes Profil — erneut anwenden",
   "claudeDesktop.status.disabled": "Die Claude-Desktop-Integration ist deaktiviert. Beende Desktop nach dem Aktivieren vollständig und öffne es erneut.",
   "claudeDesktop.enableApply": "Aktivieren und anwenden",
+  "claudeDesktop.switchModeApply": "Modus wechseln & anwenden",
+  "claudeDesktop.status.appliedFirstParty": "First-Party: Code-Tab läuft über den lokalen Proxy",
+  "claudeDesktop.mode.legend": "Verbindungsmodus",
+  "claudeDesktop.mode.firstParty": "First-Party",
+  "claudeDesktop.mode.gateway": "Gateway (Drittanbieter)",
+  "claudeDesktop.mode.defaultBadge": "Standard",
+  "claudeDesktop.mode.current": "aktuell",
+  "claudeDesktop.mode.firstPartyHint": "Desktop bleibt bei claude.ai angemeldet (Chat, Connectors, Remote Control). Nur der Code-Tab, seine Subagenten und die Claude Code CLI laufen über OpenCodex.",
+  "claudeDesktop.mode.gatewayHint": "Die ganze App wechselt auf OpenCodex als Gateway. Chat läuft lokal; claude.ai-Funktionen sind nicht verfügbar.",
+  "claudeDesktop.mode.switchNote": "Der Wechsel ersetzt die Konfiguration des anderen Modus. Desktop danach vollständig beenden und neu öffnen.",
+  "claudeDesktop.firstParty.proxyRunning": "Lokaler Proxy auf 127.0.0.1:{port}",
+  "claudeDesktop.firstParty.proxyStopped": "Lokaler Proxy 127.0.0.1:{port} läuft nicht — OpenCodex neu starten",
+  "claudeDesktop.firstParty.interceptDisabled": "Intercept-Proxy ist in der Konfiguration deaktiviert (claudeCode.intercept.enabled)",
   "claudeDesktop.health.lastRequest": "Letzte Anfrage",
   "claudeDesktop.health.stats": "{count} Anf. / {errors} Fehl.",
   "claudeDesktop.effort.supported": "effort",

gui/src/i18n/en.ts

@@ -2722,6 +2722,19 @@ export const en = {
   "claudeDesktop.status.notActiveProfile": "Desktop is serving another profile — re-apply",
   "claudeDesktop.status.disabled": "Claude Desktop integration is off. Fully quit and reopen Desktop after enabling it.",
   "claudeDesktop.enableApply": "Enable and apply",
+  "claudeDesktop.switchModeApply": "Switch mode & apply",
+  "claudeDesktop.status.appliedFirstParty": "First-party: Code tab routed through the local proxy",
+  "claudeDesktop.mode.legend": "Connection mode",
+  "claudeDesktop.mode.firstParty": "First-party",
+  "claudeDesktop.mode.gateway": "Gateway (third-party)",
+  "claudeDesktop.mode.defaultBadge": "default",
+  "claudeDesktop.mode.current": "current",
+  "claudeDesktop.mode.firstPartyHint": "Desktop stays signed in to claude.ai (chat, connectors, remote control). Only the Code tab, its subagents and the Claude Code CLI go through OpenCodex.",
+  "claudeDesktop.mode.gatewayHint": "The whole app switches to OpenCodex as its gateway. Chat runs locally; claude.ai features are unavailable.",
+  "claudeDesktop.mode.switchNote": "Switching replaces the other mode's configuration. Fully quit and reopen Desktop afterwards.",
+  "claudeDesktop.firstParty.proxyRunning": "Local proxy on 127.0.0.1:{port}",
+  "claudeDesktop.firstParty.proxyStopped": "Local proxy 127.0.0.1:{port} is not running — restart OpenCodex",
+  "claudeDesktop.firstParty.interceptDisabled": "Intercept proxy is disabled in config (claudeCode.intercept.enabled)",
   "claudeDesktop.health.lastRequest": "Last request",
   "claudeDesktop.health.stats": "{count} req / {errors} err",
   "claudeDesktop.effort.supported": "effort",

gui/src/i18n/fr.ts

@@ -2639,6 +2639,19 @@ export const fr: Record<TKey, string> = {
   "claudeDesktop.status.notActiveProfile": "Desktop utilise un autre profil — appliquer de nouveau",
   "claudeDesktop.status.disabled": "L’intégration Claude Desktop est désactivée. Quittez complètement Desktop et rouvrez-le après l’avoir activée.",
   "claudeDesktop.enableApply": "Activer et appliquer",
+  "claudeDesktop.switchModeApply": "Changer de mode et appliquer",
+  "claudeDesktop.status.appliedFirstParty": "Première partie : l'onglet Code passe par le proxy local",
+  "claudeDesktop.mode.legend": "Mode de connexion",
+  "claudeDesktop.mode.firstParty": "Première partie (first-party)",
+  "claudeDesktop.mode.gateway": "Passerelle (tiers)",
+  "claudeDesktop.mode.defaultBadge": "par défaut",
+  "claudeDesktop.mode.current": "actuel",
+  "claudeDesktop.mode.firstPartyHint": "Desktop reste connecté à claude.ai (chat, connecteurs, contrôle à distance). Seuls l'onglet Code, ses sous-agents et la CLI Claude Code passent par OpenCodex.",
+  "claudeDesktop.mode.gatewayHint": "Toute l'application bascule sur OpenCodex comme passerelle. Le chat tourne en local ; les fonctions claude.ai sont indisponibles.",
+  "claudeDesktop.mode.switchNote": "Le changement remplace la configuration de l'autre mode. Quittez complètement Desktop puis rouvrez-le.",
+  "claudeDesktop.firstParty.proxyRunning": "Proxy local sur 127.0.0.1:{port}",
+  "claudeDesktop.firstParty.proxyStopped": "Le proxy local 127.0.0.1:{port} ne tourne pas — redémarrez OpenCodex",
+  "claudeDesktop.firstParty.interceptDisabled": "Le proxy d'interception est désactivé dans la config (claudeCode.intercept.enabled)",
   "claudeDesktop.health.lastRequest": "Dernière requête",
   "claudeDesktop.health.stats": "{count} req. / {errors} err.",
   "claudeDesktop.effort.supported": "effort",