docs: refresh guides and localized site

Author: lidge-jun

README.md

@@ -212,8 +212,7 @@ Provider picker as a local config with Cursor's static public model catalog. Liv
 HTTP/2 transport is enabled when a Cursor access token is configured. Cursor server-driven native
 read/write/delete/ls/grep/shell/fetch execution is disabled by default because it bypasses Codex's
 approval and sandbox path; set `unsafeAllowNativeLocalExec: true` only for trusted local
-experiments. The older `allowNativeLocalExec` spelling is accepted as a deprecated transition
-alias.
+experiments.
 MCP, screen recording, and computer-use are exposed through executor hooks; when no local executor
 is configured, opencodex returns typed no-executor results instead of policy-blocking the request.
 Cursor OAuth and live model discovery are enabled for the experimental Cursor adapter.

docs-site/src/assets/hero-route-dark.png

@@ -15,8 +15,8 @@ import {
 import demo from '../assets/demo.gif';
 import dashboard from '../assets/dashboard.png';
 import picker from '../assets/codex-app-picker.png';
-import heroFieldLight from '../assets/hero-field-light.png';
-import heroFieldDark from '../assets/hero-field-dark.png';
+import heroFieldLight from '../assets/hero-route-light.png';
+import heroFieldDark from '../assets/hero-route-dark.png';
 
 interface Props {
 	locale?: 'ko' | 'zh-cn';

docs-site/src/assets/hero-route-light.png

@@ -11,12 +11,32 @@ cd opencodex
 bun install
 bun run dev:proxy    # proxy API in dev mode
 bun run dev:gui      # dashboard dev server (another terminal)
-bun x tsc --noEmit   # typecheck (must be clean)
+bun run typecheck    # bun x tsc --noEmit
+bun run test         # bun test ./tests/
 ```
 
 `bun run dev` remains an alias for `bun run dev:proxy`. The dashboard dev server is `bun run dev:gui`;
 the packaged dashboard at `GET /` is produced by `bun run build:gui` (`gui/dist`).
 
+## Build and test commands
+
+The root package is Bun-native TypeScript; there is no separate server compile step. Use the checked-in
+scripts so local commands match CI:
+
+```bash
+bun run typecheck                 # strict TypeScript check
+bun run test                      # complete tests/ suite
+bun test tests/router.test.ts     # focused test file
+bun run build:gui                 # Vite GUI build + package preparation
+bun run privacy:scan              # credential/privacy scan used by CI
+bun run prepare:package           # refresh package launchers/assets
+```
+
+Most tests are flat `tests/*.test.ts` Bun tests. `tests/helpers/` contains shared fixtures and
+`tests/e2e-style/` contains broader native-parity scenarios. Keep a focused regression near the
+existing tests for the subsystem you change; run the full suite for shared routing, adapters, config,
+or server behavior.
+
 The docs site you're reading lives in `docs-site/` (Astro + Starlight):
 
 ```bash
@@ -41,8 +61,10 @@ bun run build
 GitHub Actions intentionally stay small:
 
 - **Cross-platform CI** (`.github/workflows/ci.yml`) runs on pull requests and `main` pushes that
-  touch runtime, tests, package, script, TypeScript, or workflow files. It verifies Linux and Windows
-  with install, typecheck, tests, a release-helper build smoke, and `ocx help`.
+  touch runtime, tests, package, script, TypeScript, or workflow files. Its Bun matrix covers Linux,
+  Windows, and macOS with install, typecheck, tests, privacy scan, a release-helper build smoke, GUI
+  build, and `ocx help`. A second three-OS lane proves npm global install works without a separately
+  installed Bun by using the package's bundled runtime.
 - **Release** (`.github/workflows/release.yml`) is manual. It does not act as a second full CI
   pipeline; before dry-run or publish it requires the exact release commit (`GITHUB_SHA`) to already
   have a successful Cross-platform CI run.
@@ -68,31 +90,38 @@ bun run release:watch               # watch the newest Release workflow run
 
 ## Adding a provider to the catalog
 
-Most providers are just an entry in the API-key catalog (`src/oauth/key-providers.ts`):
+All provider pickers and seeds derive from the canonical registry (`src/providers/registry.ts`):
 
 ```ts
-"my-provider": {
+{
+  id: "my-provider",
   label: "My Provider",
   baseUrl: "https://api.example.com/v1",
   adapter: "openai-chat",
+  authKind: "key",
   dashboardUrl: "https://example.com/keys",
   models: ["model-a", "model-b"],
   defaultModel: "model-a",
   noVisionModels: ["model-a"],   // text-only models → vision sidecar describes images
-}
+},
 ```
 
-`enrichProviderFromCatalog()` copies `models` / `noVisionModels` / `noReasoningModels` onto the
-created provider config, so classifications take effect automatically. For OAuth providers, add to
-`OAUTH_PROVIDERS` in `src/oauth/index.ts` instead.
+`src/providers/derive.ts` feeds that entry into `ocx init`, `ocx provider`, dashboard presets,
+API-key login, and OAuth config seeds. `enrichProviderFromCatalog()` copies model metadata and
+capability classifications onto the saved provider config. OAuth protocol implementations still
+live in `src/oauth/`; registry metadata alone is not an OAuth flow.
 
 ## Adding an adapter
 
 Implement `ProviderAdapter` (see [Adapters](/opencodex/reference/adapters/)) in `src/adapters/`,
-register it in the adapter resolver, and bridge its output to internal `AdapterEvent`s. Reuse
-`image.ts` for image handling and follow `openai-chat.ts` as the reference for streaming + tool calls.
+register its name in `src/server/adapter-resolve.ts`, and bridge its output to internal
+`AdapterEvent`s. Reuse `image.ts` for image handling and follow `openai-chat.ts` for ordinary
+streaming/tool calls; use `fetchResponse` only when the adapter owns transport retries, or `runTurn`
+for a genuinely bidirectional transport such as Cursor. Add focused tests under `tests/` and export
+the factory from `src/index.ts` when it belongs to the public package API.
 
 ## Verify before you claim done
 
-Run the narrowest command that proves your change — `bun x tsc --noEmit` for types, a focused runtime
-probe for behavior. opencodex favors small, verifiable commits over large batches.
+Run the narrowest command that proves your change — `bun run typecheck` for types, a focused
+`bun test tests/<name>.test.ts` or runtime probe for behavior, then the broader gates appropriate to
+the affected surface. opencodex favors small, verifiable commits over large batches.

docs-site/src/components/Landing.astro

@@ -5,15 +5,16 @@ description: The full opencodex request lifecycle — parse, route, adapt, bridg
 
 import { Steps } from '@astrojs/starlight/components';
 
-Codex speaks exactly one protocol: the OpenAI **Responses API** (`POST /v1/responses`, Server-Sent
-Events). opencodex accepts that request, translates it to your provider's wire format, and translates
-the streamed answer back into Responses events — so Codex never knows it isn't talking to OpenAI.
+Codex speaks the OpenAI **Responses API**. opencodex accepts `POST /v1/responses` over HTTP with
+Server-Sent Events, plus an opt-in WebSocket upgrade on the same path. It translates the request to
+your provider's wire format and the answer back into Responses events — so Codex never knows it
+isn't talking to OpenAI.
 
 ```
             ┌──────────────────────────── opencodex ────────────────────────────┐
             │                                                                     │
  Codex ──▶  │  parser ──▶ router ──▶ [vision] ──▶ adapter ──▶ provider           │  ──▶ Codex
- (/v1/      │     │          │          │            │           │                │     (SSE)
+ (/v1/      │     │          │          │            │           │                │   (SSE / WS)
   responses)│   OcxParsed  provider   describe    buildRequest  parseStream       │
             │   Request    +adapter   images       + fetch      AdapterEvent[]    │
             │                                          │           │              │
@@ -38,6 +39,14 @@ account before the request is forwarded upstream. The rule is intentionally spli
   `GET /api/codex-auth/accounts?refresh=1`; successful upstream responses capture quota headers,
   429 puts an account in cooldown, and 401/403 marks it for reauthentication.
 
+## Sub-agent model selection
+
+On a fresh install, `subagentModels` features `gpt-5.5`, the GPT-5.6 Sol/Terra/Luna trio, and
+`gpt-5.4-mini` in Codex's sub-agent picker. The dashboard can reorder or replace up to five entries
+with native or routed models. For v1 collaboration requests, optional `injectionModel` and
+`injectionEffort` settings add developer guidance that tells `spawn_agent` which model and reasoning
+effort to use; v2 requests keep Codex's native multi-agent guidance.
+
 ## The lifecycle
 
 <Steps>
@@ -50,8 +59,8 @@ account before the request is forwarded upstream. The rule is intentionally spli
    base64 text.
 
 2. **Route** — `router.ts` maps the requested model id to a configured provider using a fixed
-   precedence: explicit `provider/model` → a provider's `defaultModel` → a provider's `models[]` →
-   built-in prefix patterns (`claude-`, `gpt-`, `o1-`/`o3-`/`o4-`, `llama-`/`mixtral-`/`gemma-`) →
+   precedence: explicit `provider/model` → a provider's `defaultModel` → built-in prefix patterns
+   (`claude-`, `gpt-`, `o1-`/`o3-`/`o4-`, `llama-`/`mixtral-`/`gemma-`) → a provider's `models[]` →
    the `defaultProvider` fallback. See [Model Routing](/opencodex/guides/model-routing/).
 
 3. **Authenticate** — for an `oauth` provider, opencodex swaps in a fresh, auto-refreshed access
@@ -60,26 +69,31 @@ account before the request is forwarded upstream. The rule is intentionally spli
    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 a `gpt-5.4-mini` vision model over
-   your ChatGPT login and replaces it with text, so a text-only model can still reason about it.
+   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.
    See [Sidecars](/opencodex/guides/sidecars/).
 
-5. **Passthrough fast path** — if the adapter is a passthrough (`openai-responses` in `forward` mode,
-   or `azure-openai`), the raw request body is piped straight to the provider and the response streamed back
-   untouched. No translation happens.
+5. **Passthrough fast path** — if the adapter is a Responses passthrough (`openai-responses` or
+   `azure-openai`), opencodex keeps the Responses body, applies targeted routing and compatibility
+   rewrites, then relays the provider's response without converting it through `AdapterEvent`s.
 
 6. **Web-search sidecar (optional)** — if Codex enabled hosted `web_search` but the routed model is
    non-OpenAI, opencodex exposes a synthetic `web_search` function tool and runs the model in a small
-   agentic loop, executing real searches through `gpt-5.4-mini` over your ChatGPT login and injecting
-   the results back as tool results.
+   agentic loop, executing real searches through `gpt-5.6-luna` by default over your ChatGPT login
+   and injecting the results back as tool results.
+
+7. **Compact (when requested)** — Codex v1 calls `POST /v1/responses/compact`; v2 adds a
+   `compaction_trigger` to a Responses turn. Native passthrough routes compaction upstream, while a
+   routed model runs as a tool-free summarizer and returns the replacement history shape Codex expects.
 
-7. **Adapt** — otherwise the chosen adapter's `buildRequest()` produces the upstream HTTP request
+8. **Adapt** — otherwise the chosen adapter's `buildRequest()` produces the upstream HTTP request
    (URL, headers, body) in the provider's native format, and opencodex `fetch`es it.
 
-8. **Bridge** — the adapter's `parseStream()` (or `parseResponse()`) yields internal `AdapterEvent`s
+9. **Bridge** — the adapter's `parseStream()` (or `parseResponse()`) yields internal `AdapterEvent`s
    (text, reasoning, tool-call start/delta/end, done, error). `bridge.ts` converts that stream back
    into Responses SSE events — `response.output_text.delta`, `response.reasoning_summary_text.delta`,
-   `response.function_call_arguments.delta`, `response.completed`, and so on — which Codex consumes.
+   `response.function_call_arguments.delta`, `response.completed`, and so on. The optional WebSocket
+   transport sends the same event payloads as text frames.
 
 </Steps>
 

docs-site/src/content/docs/contributing.md

@@ -3,8 +3,9 @@ title: Installation
 description: Install the opencodex (ocx) proxy, its prerequisites, and verify it runs.
 ---
 
-opencodex ships as a single CLI, `ocx`. It runs as a small local HTTP server (built on Bun) and never
-sends your traffic anywhere except the provider you configure.
+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.
 
 ## Prerequisites
 
@@ -20,25 +21,25 @@ sends your traffic anywhere except the provider you configure.
 npm install -g @bitkyc08/opencodex
 ```
 
-Verify the binary is on your `PATH`:
+Verify both command aliases are on your `PATH`:
 
 ```bash
-ocx --help
+ocx --version
+opencodex --version
 ```
 
-### Preview channel
+### Release channels
 
-GPT-5.6 Sol/Terra/Luna support is preview-gated until the rollout graduates. Install the preview tag
-for a fresh setup, or keep an existing preview install on the preview channel:
+The stable `latest` channel already includes GPT-5.6 Sol/Terra/Luna catalog support for ChatGPT,
+OpenAI API-key, OpenRouter, and experimental Cursor routes. Upstream access is still account-gated;
+the catalog entries do not grant access by themselves. Use the preview channel only to test
+unreleased opencodex builds:
 
 ```bash
 npm install -g @bitkyc08/opencodex@preview
 ocx update --tag preview
 ```
 
-Preview builds seed the GPT-5.6 model ids and Codex catalog metadata; they do not grant upstream
-model access by themselves.
-
 ## Run from source
 
 To hack on opencodex itself:
@@ -58,13 +59,19 @@ has produced `gui/dist`. While hacking on the dashboard, run the frontend separa
 
 ## What gets created
 
+opencodex state lives under `$OPENCODEX_HOME` (default `~/.opencodex`). Codex integration files live
+under `$CODEX_HOME` (default `~/.codex`).
+
 | Path | Purpose |
 | --- | --- |
-| `~/.opencodex/config.json` | Your providers, default provider, port, and options. |
-| `~/.opencodex/ocx.pid` | PID of the running proxy (single-instance guard). |
-| `~/.opencodex/auth.json` | Stored OAuth credentials (when you `ocx login`). |
-| `~/.opencodex/catalog-backup.json` | Pristine Codex model catalog, backed up before any edit. |
-| `$CODEX_HOME/config.toml` | opencodex appends a `[model_providers.opencodex]` table here on `ocx init` (defaults to `~/.codex/config.toml`). |
+| `$OPENCODEX_HOME/config.json` | Your providers, default provider, port, and options. |
+| `$OPENCODEX_HOME/ocx.pid` | PID of the running proxy (single-instance guard). |
+| `$OPENCODEX_HOME/runtime-port.json` | The live PID, hostname, and port, including an automatically selected fallback port. |
+| `$OPENCODEX_HOME/auth.json` | Stored OAuth credentials (when you `ocx login`). |
+| `$OPENCODEX_HOME/catalog-backup*.json` | Codex model catalog backups made before opencodex edits it. |
+| `$CODEX_HOME/config.toml` | On loopback, opencodex adds a marker-owned root `openai_base_url`; non-loopback binds use `model_provider = "opencodex"` plus `[model_providers.opencodex]` so Codex can send the API-auth header. |
+| `$CODEX_HOME/opencodex.config.toml` | Fallback/reference profile written alongside the main Codex config. |
+| `$CODEX_HOME/opencodex-catalog.json` | Synced native and routed model catalog used by Codex. |
 
 :::note
 opencodex never deletes your Codex config. Every injection is reversible — `ocx stop`, `ocx restore`,

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

@@ -13,21 +13,23 @@ ocx init
 
 `ocx init` walks you through:
 
-1. **Pick a provider** — choose a preset (opencode zen, Anthropic, OpenAI, OpenRouter, Groq, Google,
-   Azure) or `custom` to type a base URL and adapter.
+1. **Pick a provider** — choose one of the 50 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** — the model used when a request doesn't match another provider.
+3. **Default model** — for key, local, and custom providers, accept the preset or enter a model id.
 4. **Proxy port** — defaults to `10100`.
-5. **Inject into Codex?** — when you accept, opencodex writes the `[model_providers.opencodex]` table
-   into `$CODEX_HOME/config.toml` (default `~/.codex/config.toml`) and sets
-   `model_provider = "opencodex"` so Codex routes through the proxy.
-
-The result is saved to `~/.opencodex/config.json`.
-
-:::note[GPT-5.6 preview]
-On the preview channel, the wizard/catalog presets know about GPT-5.6 Sol/Terra/Luna. Use ChatGPT
-passthrough, OpenAI (API key), or OpenRouter only when that upstream account already has access; the
-synced Codex entries include `max` reasoning and 372,000 usable-token context metadata.
+5. **Inject into Codex?** — on a normal loopback setup, opencodex adds a root `openai_base_url` to
+   `$CODEX_HOME/config.toml` (default `~/.codex/config.toml`) so Codex's built-in `openai` provider
+   targets the proxy. Remote/LAN binds use a dedicated provider entry with an API-auth header instead.
+6. **Install the autostart shim?** — when enabled, launching `codex` runs `ocx ensure` first.
+
+The result is saved to `$OPENCODEX_HOME/config.json` (default `~/.opencodex/config.json`).
+
+:::note[GPT-5.6 rollout entries]
+Stable v2.7.1 seeds GPT-5.6 Sol/Terra/Luna for ChatGPT passthrough, OpenAI API-key, OpenRouter, and
+the experimental Cursor adapter. They work only when that upstream account has access. The OpenAI
+API-key and OpenRouter presets advertise a 372,000-token usable context window; Cursor keeps its own
+adapter metadata.
 :::
 
 ## 2. Start the proxy
@@ -40,13 +42,18 @@ ocx start --port 8080
 On start, opencodex:
 
 - writes its PID to `~/.opencodex/ocx.pid` (and refuses to start twice),
-- fetches each provider's live model list and **syncs them into Codex's model catalog**, and
+- discovers live models where the provider supports it and **syncs native and routed entries into
+  Codex's model catalog**,
 - listens on `http://localhost:<port>/v1`.
 
+If the requested port is busy, `ocx start` selects a free port, records it in `runtime-port.json`,
+and updates Codex to use the live listener.
+
 Check it:
 
 ```bash
 ocx status
+ocx gui       # open the dashboard on the live port
 ```
 
 ## 3. Use Codex
@@ -64,12 +71,19 @@ codex -m "anthropic/claude-opus-4-8" "Explain this stack trace"
 codex -m "ollama-cloud/glm-5.2"      "Write a SQL migration"
 ```
 
+## Choose sub-agent models (optional)
+
+A fresh config features five native models in Codex's sub-agent picker: `gpt-5.5`,
+`gpt-5.6-sol`, `gpt-5.6-terra`, `gpt-5.6-luna`, and `gpt-5.4-mini`. Open `ocx gui` to replace or
+reorder up to five native or routed models. The dashboard can also set one preferred sub-agent model
+and reasoning effort; opencodex adds that guidance to v1 collaboration requests.
+
 ## Logging in instead of pasting a key
 
 Some providers support real account login (OAuth, auto-refreshed):
 
 ```bash
-ocx login xai          # or: anthropic, kimi
+ocx login xai          # or: anthropic, kimi, kiro, google-antigravity, cursor
 ocx logout xai
 ```
 
@@ -79,8 +93,9 @@ credentials straight through (see [Providers](/opencodex/guides/providers/)).
 ## Stopping & restoring
 
 ```bash
-ocx stop      # stop the proxy and restore native Codex
-ocx restore   # restore native Codex without stopping (alias: ocx eject)
+ocx stop          # stop the proxy and restore native Codex
+ocx restore       # restore native Codex without stopping (alias: ocx eject)
+ocx restore back  # route Codex through the still-running proxy again
 ```
 
 ## Next