feat(vision): add chat and Google sidecars

README.md

@@ -146,8 +146,9 @@ see the [installation docs](https://opencodex.me/getting-started/installation/).
   [sub-agent guide](https://opencodex.me/guides/sub-agent-surface/).
 - **Log in once, skip the API key** — OAuth for xAI, Anthropic, and Kimi; or forward
   `codex login`, paste a key, or use `${ENV_VAR}` references.
-- **Web search & vision sidecars** — non-OpenAI models get real web search and image understanding
-  through a sidecar over your ChatGPT login.
+- **Web search & vision sidecars** — routed models get real web search through an OpenAI/Anthropic
+  sidecar, while image understanding can also use an explicit provider-backed Chat vision sidecar.
+  Chat vision targets use `provider/model`; see the [sidecar guide](https://opencodex.me/guides/sidecars/).
 - **See what's happening** — the dashboard shows providers, OAuth status, model selection, and a
   live request log with cache token counts.
 - **Clean exit, zero residue** — `ocx stop` restores Codex to its original configuration.

docs-site/src/content/docs/fr/getting-started/how-it-works.mdx

@@ -71,8 +71,9 @@ le modèle et l’effort de raisonnement à utiliser. Les requêtes v2 conserven
    de transfert direct refuse de poursuivre si les informations d’identification requises sont indisponibles.
 
 4. **Service auxiliaire de vision (facultatif)** — si le modèle routé figure dans `provider.noVisionModels` et que
-   la requête contient une image, opencodex fait décrire chaque image par le service auxiliaire de vision ChatGPT
-   configuré, puis la remplace par du texte afin qu’un modèle textuel puisse tout de même la traiter.
+   la requête contient une image, opencodex utilise le backend de vision configuré — OpenAI via la connexion
+   ChatGPT, Anthropic via OAuth ou le backend Chat réservé à la vision avec une cible explicite `provider/model` —
+   puis remplace chaque image par du texte afin qu’un modèle textuel puisse tout de même la traiter.
    Voir [Services auxiliaires](/fr/guides/sidecars/).
 
 5. **Transfert direct rapide** — si l’adaptateur transfère directement les Responses (`openai-responses` ou

docs-site/src/content/docs/fr/getting-started/installation.md

@@ -5,8 +5,8 @@ description: Installez le proxy opencodex (ocx), ses prérequis et vérifiez qu'
 
 opencodex installe deux commandes équivalentes, `ocx` et `opencodex`. Toutes deux lancent le même petit
 serveur HTTP local, fondé sur Bun. Les requêtes de modèles sont envoyées au fournisseur choisi par le
-routage. Les services auxiliaires facultatifs de vision et de recherche web peuvent également utiliser votre connexion
-ChatGPT lorsqu’un modèle routé en a besoin.
+routage. La vision peut utiliser OpenAI via votre connexion ChatGPT, Anthropic via OAuth ou le backend Chat
+réservé à la vision avec une cible explicite `provider/model` ; la recherche web utilise les backends dédiés.
 
 ## Prérequis
 

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

@@ -368,8 +368,6 @@ La recherche web et la description d'images avec OAuth Anthropic réutilisent le
 d'empreintes précédent. Testez néanmoins ces fonctions avec votre compte et votre charge de travail avant de vous y fier
 pour de longues exécutions sans surveillance.
 
-<!-- TODO(WP5 GUI): Add the sidecar settings-screen walkthrough after the GUI controls ship. -->
-
 ## Effort de raisonnement
 
 Le paramètre `/effort` de Claude Code est conservé sur l'ensemble de l'adaptateur :

docs-site/src/content/docs/getting-started/how-it-works.mdx

@@ -71,8 +71,9 @@ effort to use; v2 requests keep Codex's native multi-agent guidance.
    to continue if the required pool credential is unavailable.
 
 4. **Vision sidecar (optional)** — if the routed model is listed in `provider.noVisionModels` and the
-   request carries an image, opencodex describes each image with the configured ChatGPT vision
-   sidecar and replaces it with text, so a text-only model can still reason about it.
+   request carries an image, opencodex uses the configured vision backend — OpenAI via ChatGPT login,
+   Anthropic via OAuth, or the vision-only Chat backend with an explicit `provider/model` target —
+   then replaces each image with text so a text-only model can still reason about it.
    See [Sidecars](/guides/sidecars/).
 
 5. **Passthrough fast path** — if the adapter is a Responses passthrough (`openai-responses` or

docs-site/src/content/docs/getting-started/installation.md

@@ -5,7 +5,7 @@ description: Install the opencodex (ocx) proxy, its prerequisites, and verify it
 
 opencodex installs two equivalent command names, `ocx` and `opencodex`. Both launch the same small
 local HTTP server (built on Bun). Model requests go to the provider selected by routing; optional
-vision and web-search sidecars can also use your ChatGPT login when a routed model needs them.
+Vision sidecars can use OpenAI via your ChatGPT login, Anthropic via OAuth, or the vision-only Chat backend with an explicit `provider/model` target. See the [sidecar guide](/guides/sidecars/).
 
 ## Prerequisites
 

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

@@ -326,12 +326,19 @@ before the main model answers:
 - The **vision sidecar** describes an attached image before calling a model listed in
   `noVisionModels`, then replaces the image with that description.
 
-Both sidecars can use either backend:
+The web-search sidecar accepts only `openai` and `anthropic`; the vision sidecar also accepts
+`chat`. Chat is vision-only and never runs web search.
 
 | Backend | How it runs | What it requires |
 | --- | --- | --- |
 | `openai` | A small GPT model through the ChatGPT `forward` provider | A ChatGPT login and an enabled `authMode: "forward"` provider |
 | `anthropic` | Claude through stored Anthropic OAuth; web search uses `web_search_20250305` and vision sends the image to Claude for description | An enabled `adapter: "anthropic"`, `authMode: "oauth"` provider whose active stored account is not marked `needsReauth` |
+| `chat` (vision only) | An OpenAI-compatible Chat Completions request through the selected configured provider | An enabled `openai-chat` or `google` provider with an API key/key pool or supported active OAuth account; keyless is limited to `openai-chat` local/key-optional providers |
+
+For `chat`, set `visionSidecar.model` to a provider-qualified `provider/model` value to select
+exactly one provider. A bare model is accepted only when one usable provider's configured
+`defaultModel`/`models` list matches it; ambiguous and live-only matches fail closed. Google is never
+keyless.
 
 An explicit `backend` always wins. When it is omitted, the **web-search** sidecar always selects
 `openai` (`anthropic` runs only when explicitly configured), while the **vision** sidecar selects
@@ -365,13 +372,13 @@ images are cached by backend, model, detail, image bytes, and request context, s
 image-and-context pair is not described again on every replay. Remote `https:` images are never
 cached because their contents can change.
 
-See the [configuration reference](/reference/configuration/#sidecars) for every key.
+See the [configuration reference](/reference/configuration/#sidecars) for every key. The Dashboard
+sidecar card exposes the same vision backend/model selection, **Off**, and advanced settings; Claude's
+page adds separate overrides with **Use main setting** and **Auto** inheritance controls.
 Anthropic-OAuth web search and image description reuse the repository's existing Claude Code OAuth
 fingerprint precedent, but should still be soak-tested with your account and workload before you
 depend on them for long unattended runs.
 
-<!-- TODO(WP5 GUI): Add the sidecar settings-screen walkthrough after the GUI controls ship. -->
-
 ## Reasoning effort
 
 Claude Code's `/effort` setting is preserved across the adapter:
@@ -484,8 +491,11 @@ the search but Claude Code still counted zero.
 
 **A sidecar does not activate** — For `backend: "openai"`, confirm you are logged into ChatGPT and
 have an enabled `authMode: "forward"` provider. For `backend: "anthropic"`, confirm the active stored
-Anthropic OAuth account is not marked `needsReauth`. An explicit Anthropic selection without that
-credential intentionally fails closed.
+Anthropic OAuth account is not marked `needsReauth`. For vision `backend: "chat"`, use a provider-qualified
+`provider/model` and confirm that the selected enabled `openai-chat` or `google` provider has a key,
+key pool, or supported active OAuth account (keyless is only for local/key-optional `openai-chat`).
+Ambiguous bare models and live-only bare matches intentionally fail closed. An explicit Anthropic
+selection without its credential also fails closed.
 
 **"claude.ai connectors are disabled"** — An `ANTHROPIC_API_KEY` or `ANTHROPIC_AUTH_TOKEN` is set
 in your shell. `ocx claude` deliberately does NOT set `ANTHROPIC_API_KEY`; if you have it exported,

docs-site/src/content/docs/guides/sidecars.md

@@ -1,21 +1,25 @@
 ---
 title: "Sidecars: Web Search & Vision"
-description: Give routed models real web search and text-only models image understanding through native ChatGPT sidecars.
+description: Give routed models real web search and text-only models image understanding through explicit, provider-backed sidecars.
 ---
 
 Routed models do not all expose hosted **web search** or native **image input**. opencodex backfills
 those capabilities with two sidecars. Both support a ChatGPT-login (`forward`) provider or stored
 Anthropic OAuth provider; web search can additionally use stored Grok OAuth through the explicit
-`xai` backend. Sidecar errors become bounded tool results or image markers instead of failing the
-whole turn.
+`xai` backend. Vision can additionally use the `chat` backend, which sends the image to a configured
+chat-compatible provider. Sidecar errors become bounded tool results or image markers instead of
+failing the whole turn.
 
 :::note[Automatic backend selection]
 Explicit `backend` config wins. The two sidecars default differently when `backend` is unset:
 **web search** always defaults to `openai` — `anthropic` runs only when explicitly configured.
 **Vision** defaults to `anthropic` if an enabled Anthropic OAuth provider has an active account not
 marked `needsReauth`, otherwise `openai`. Explicit `anthropic` without that credential fails
 closed. Explicit `xai` requires a usable stored Grok OAuth account and does not fall back. `openai`
-requires both ChatGPT login auth and an enabled `forward` provider.
+requires both ChatGPT login auth and an enabled `forward` provider. The `chat` backend is vision-only:
+its model should be written as `provider/model` and must resolve to an enabled `openai-chat` or
+`google` provider with usable credentials. Keyless operation is allowed only for local/key-optional
+`openai-chat` providers; Google is never keyless.
 :::
 
 ### Additional web-search backends (explicit-only)
@@ -124,20 +128,41 @@ failures after response headers have started are delivered as `response.failed`
 ## Vision sidecar
 
 When the routed model is listed in its provider's `noVisionModels` and a request carries an image,
-opencodex describes each image **before** the main call and replaces it with text. When
-`visionSidecar.model` is absent or blank, the OpenAI execution path, Dashboard, and management API
-use the `gpt-5.4-mini` fallback. Startup still migrates an explicitly persisted legacy
-`gpt-5.4-mini` value to `gpt-5.6-luna`; that migration applies to a stored value, not to an absent
-model field.
+opencodex describes each image **before** the main call and replaces it with text. Vision is explicit:
+choose a model and backend, or select **Off**. The `chat` backend is vision-only and uses the configured
+provider-qualified `provider/model` target; it does not run web search.
+
+For `openai`/`anthropic`, when `visionSidecar.model` is absent or blank, the OpenAI execution path,
+Dashboard, and management API use the `gpt-5.4-mini` fallback. Startup still migrates an explicitly
+persisted legacy `gpt-5.4-mini` value to `gpt-5.6-luna`; that migration applies to a stored value, not
+to an absent model field.
+
+For `chat`, the model is resolved as follows:
+
+- `provider/model` selects exactly that configured provider. The provider must be enabled, use
+  `openai-chat` or `google`, and have a usable API key/key pool or supported active OAuth account.
+- A bare model id is accepted only when exactly one usable provider's configured `defaultModel` or
+  `models` list matches it. Bare matches are not inferred from live-only discovery, and ambiguous
+  matches fail closed rather than choosing an arbitrary provider.
+- The selected provider's published model id is sent upstream. Keyless operation is limited to
+  `openai-chat` providers marked `authMode: "local"` or `keyOptional: true`; Google requires usable
+  credentials, either an API key/key pool or supported OAuth with a healthy active account.
+
+The provider-qualified form is recommended whenever more than one chat-compatible provider could
+serve the same model id.
 
 - Images can come from user, developer, and tool-result messages, including Codex's `view_image`.
 - On the OpenAI path (ChatGPT-login passthrough), each image is sent to the configured vision model
   over the Responses endpoint with the selected `reasoning.effort` (`low` by default), and its
   description replaces the image part inline. The Anthropic path uses the Messages endpoint with its
-  own thinking-budget mapping and ignores this OpenAI-specific setting.
+  own thinking-budget mapping and ignores this OpenAI-specific setting. The chat path uses the
+  selected provider's wire: `openai-chat` sends OpenAI-compatible `POST /chat/completions`, while
+  `google` uses the native Gemini `streamGenerateContent` adapter (AI Studio, Vertex, or Cloud Code
+  Assist as configured).
 - For native models with known capability metadata, unsupported reasoning is normalized to the
   highest supported rung at or below the requested level; if none exists, the lowest supported rung
   is used. Unknown or custom models remain permissive when reliable capability metadata is absent.
+  The chat backend uses the selected provider/model's effective reasoning ladder.
 - Descriptions run with bounded concurrency (3 at a time, input order preserved). User context sent
   to the describer is capped at 800 characters, and each injected description is capped at 2,000
   characters. The request does not send `max_output_tokens`, which the ChatGPT backend rejects.
@@ -156,8 +181,11 @@ model field.
 
 The management API and Dashboard picker now list models that can actually accept image input.
 When the matching backend is available, `gpt-5.6-luna` (OpenAI) and `claude-haiku-4-5` (Anthropic)
-are always offered as baseline options. `PUT /api/sidecar-settings` rejects a model known to be
-text-only, but still accepts an unknown id so custom or ahead-of-catalog names keep working.
+are always offered as baseline options. Chat options come from usable configured `openai-chat` or
+`google` providers and are displayed as provider-qualified values such as `google/gemini-flash`.
+`PUT /api/sidecar-settings` rejects a model known to be text-only, but still accepts an unknown id so
+custom or ahead-of-catalog names keep working; a chat target that cannot resolve to a usable provider
+is not executed.
 
 ```json
 {
@@ -188,11 +216,16 @@ A model is marked text-only per provider:
 
 ## Dashboard controls and disabling
 
-The Dashboard Vision sidecar card can enable or disable the sidecar, set
-`maxDescriptionsPerTurn`, and set `timeoutMs`, along with the existing model,
-backend, and reasoning controls. Disabling the sidecar does not delete those
-settings; turning it back on keeps the previous model, backend, reasoning,
-timeout, and limit.
+The Dashboard Vision sidecar card uses the model picker as the activation control: choose a listed
+OpenAI, Anthropic, or provider-qualified Chat model, or choose **Off**. The backend is inferred from
+an eligible model; the advanced settings popover contains reasoning, `maxDescriptionsPerTurn`, and
+`timeoutMs`. Web Search has its own model/backend controls and does not offer Chat, because Chat is
+vision-only. Changes apply on the next request.
+
+Disabling the Vision sidecar does not delete its settings; turning it back on keeps the previous model,
+backend, reasoning, timeout, and limit. The Claude Code page has separate per-surface overrides: **Use
+main setting** inherits the global setting, **Auto** leaves backend selection unset, and an explicit
+backend/model override is saved only for Claude-originated requests.
 
 `PUT /api/sidecar-settings` accepts the same fields. Partial updates leave
 omitted keys unchanged. `timeoutMs` uses the runtime integer bounds

docs-site/src/content/docs/guides/web-dashboard.md

@@ -40,7 +40,7 @@ the browser or password manager's decision.
 | --- | --- |
 | **Dashboard summary** | Multi-agent mode, online state, version, uptime, provider count, 30-day token total, active providers, and available native/routed models. |
 | **Sub-agent delegation** | Choose a native or routed model and optional reasoning effort shared by OpenCodex delegation guidance and the separate native-default opt-in. This is not a proxy-side per-spawn router; see below. |
-| **Sidecars** | Choose the web-search model and effort plus the vision-description model. Changes apply on the next request. |
+| **Sidecars** | Choose the web-search backend/model and effort plus the vision backend/model. Web search offers OpenAI or Anthropic; vision also offers provider-backed Chat, and **Off** disables vision without deleting its settings. Advanced vision controls include reasoning, description limit, and timeout. Changes apply on the next request. |
 | **Maintenance** | Resync the Codex model catalog, inspect project-local config bypass warnings, check the latest or preview release, and run an update with optional proxy restart. |
 | **Startup safety** | Show whether injected Codex routing survives a restart, with separate service and launcher-shim health plus exact repair commands. |
 | **Windows tray** | Install a per-user login tray for one-click proxy start, stop, restart, dashboard access, and status. The tray is a controller, not a proxy restart service. |
@@ -203,7 +203,7 @@ The GUI is a thin client over the proxy's JSON management API. Useful endpoints
 | `GET` / `POST /api/windows-tray` | Read or change the Windows tray installation and visible-process state. POST accepts `install`, `start`, `stop`, or `uninstall`. |
 | `POST /api/sync` | Rebuild the shared model catalog and stale the Codex model cache. |
 | `GET /api/update/check` · `POST /api/update/run` · `GET /api/update/status` | Check, run, and monitor self-update jobs. Worker PIDs are persisted so a crashed job recovers automatically; legacy no-PID jobs recover after ten minutes. |
-| `GET` / `PUT /api/sidecar-settings` | Read or set search/vision sidecar model settings. |
+| `GET` / `PUT /api/sidecar-settings` | Read or set search/vision sidecar backend, model, and vision advanced settings. Web search accepts only OpenAI/Anthropic; vision may use provider-qualified Chat. |
 | `GET` / `PUT /api/injection-model` | Read or set the shared sub-agent model/effort selection and the independent guidance/native-default switches. |
 | `GET` / `PUT /api/v2` | Read or set the surface mode, Codex feature flag, and v2 thread limit. |
 | `GET /api/providers` · `POST /api/providers` · `PATCH /api/providers?name=...` · `DELETE /api/providers?name=...` | List, add/replace, enable/disable, set the default, or remove providers. `PATCH` uses standalone `{ "setDefault": true }` on an enabled provider; `POST` may include `setDefault` when creating/replacing (also enabled-only). Deleting the current default reassigns to the first remaining enabled provider when one exists; otherwise the API returns `409` with `code: "last_provider"` and keeps the current default. |