docs: refresh opencodex documentation

Author: lidge-jun

README.ko.md

@@ -77,8 +77,13 @@ codex -m "ollama-cloud/glm-5.2"      "Write a SQL migration"
 - **OAuth, API 키, 또는 ChatGPT forward.** xAI / Anthropic / Kimi 계정으로 로그인하거나(토큰은
   자동 갱신됩니다), `codex login`을 forward 하거나, 키를 붙여넣으세요(`${ENV_VARS}` 지원). 18개 프로바이더의
   API 키 카탈로그(**Ollama Cloud** 포함)가 기본 내장되어 있습니다.
-- **Codex에 바로 통합.** `$CODEX_HOME/config.toml`(기본값 `~/.codex/config.toml`)에 `[model_providers.opencodex]` 테이블을 주입하고
-  라우팅된 모델을 Codex의 카탈로그와 서브에이전트 선택기에 병합합니다 — 완전히 되돌릴 수 있습니다.
+- **Codex CLI, TUI, App, SDK에 바로 통합.** `$CODEX_HOME/config.toml`(기본값 `~/.codex/config.toml`)에
+  `[model_providers.opencodex]` 테이블을 주입하고 공유 Codex 모델 카탈로그를 작성하여 라우팅된 모델이
+  Codex 모델 선택기에 표시되게 합니다.
+- **서브에이전트 제어.** `subagentModels` 또는 웹 대시보드에서 최대 5개의 라우팅/네이티브 모델을
+  Codex `spawn_agent` 선택기에 우선 노출할 수 있습니다.
+- **기본은 HTTP/SSE, WebSocket은 opt-in.** 프록시는 Responses WebSocket 엔드포인트를 갖고 있지만,
+  `"websockets": true`일 때만 `supports_websockets`를 광고합니다.
 - **Sidecar.** OpenAI가 아닌 모델에도 ChatGPT 로그인을 통한 `gpt-5.4-mini`를 사용해 실제 **웹 검색**과
   **이미지 이해** 기능을 제공합니다.
 - 프로바이더, OAuth 로그인, 모델 선택, 요청 로그를 위한 **웹 대시보드**.
@@ -111,6 +116,7 @@ ocx login <xai|anthropic|kimi> # OAuth login
 ocx logout <provider>          # remove a stored login
 ocx gui                        # open the web dashboard
 ocx service <install|start|stop|status|uninstall>   # run as a background service
+ocx update                     # update opencodex to the latest published version
 ```
 
 ## 설정
@@ -138,15 +144,21 @@ ocx service <install|start|stop|status|uninstall>   # run as a background servic
 }
 ```
 
+WebSocket 전송은 기본적으로 꺼져 있습니다. Codex가 HTTP/SSE 대신 Responses WebSocket 경로를 광고하고
+사용하게 하려면 `"websockets": true`를 명시하세요.
+
 모든 필드에 대한 자세한 내용은 **[설정 레퍼런스](https://lidge-jun.github.io/opencodex/ko/reference/configuration/)**
 를 참고하세요.
 
 ## 문서
 
-전체 개발자 문서 — 아키텍처, 모든 adapter, 요청 라이프사이클, sidecar,
-Codex 통합, CLI/설정 레퍼런스 — 는 [`docs-site/`](./docs-site) 아래의 Astro 사이트이며
+공개 문서 — 설치, 프로바이더, 라우팅, sidecar, Codex 통합, Codex App 모델 선택기,
+CLI/설정 레퍼런스 — 는 [`docs-site/`](./docs-site) 아래의 Astro 사이트이며
 **[lidge-jun.github.io/opencodex](https://lidge-jun.github.io/opencodex/ko/)**에 게시됩니다.
 
+유지보수용 source of truth는 [`structure/`](./structure)에 있고, 과거 조사/진단 노트는
+[`docs/`](./docs)에 남아 있습니다.
+
 ## 개발
 
 ```bash

README.md

@@ -87,9 +87,13 @@ codex -m "ollama-cloud/glm-5.2"      "Write a SQL migration"
 - **OAuth, API key, or ChatGPT forward.** Log in with your xAI / Anthropic / Kimi account (tokens
   auto-refresh), forward your `codex login`, or paste a key (`${ENV_VARS}` supported). An 18-provider
   API-key catalog (incl. **Ollama Cloud**) is built in.
-- **Drops into Codex.** Injects a `[model_providers.opencodex]` table into
-  `$CODEX_HOME/config.toml` (default `~/.codex/config.toml`) and merges routed models into Codex's
-  catalog and subagent picker — fully reversible.
+- **Drops into Codex CLI, TUI, App, and SDK.** Injects a `[model_providers.opencodex]` table into
+  `$CODEX_HOME/config.toml` (default `~/.codex/config.toml`) and writes a shared Codex model catalog
+  so routed models appear in Codex model pickers.
+- **Subagent control.** Feature up to five routed or native models in Codex's `spawn_agent` picker
+  from `subagentModels` or the web dashboard.
+- **HTTP/SSE by default, WebSocket opt-in.** The proxy has a Responses WebSocket endpoint, but it
+  only advertises `supports_websockets` when `"websockets": true` is set.
 - **Sidecars.** Give non-OpenAI models real **web search** and **image understanding** via a
   `gpt-5.4-mini` over your ChatGPT login.
 - **Web dashboard** for providers, OAuth login, model selection, and request logs.
@@ -104,7 +108,7 @@ codex -m "ollama-cloud/glm-5.2"      "Write a SQL migration"
 | xAI Grok | `openai-chat` | oauth / key |
 | Kimi (Moonshot) | `openai-chat` | oauth / key |
 | Google Gemini | `google` | key |
-| Azure OpenAI | `azure-openai` | key |
+| Azure OpenAI | `azure` | key |
 | Ollama Cloud + 17-provider catalog | `openai-chat` | key |
 | Ollama / vLLM / LM Studio (local) | `openai-chat` | key (usually blank) |
 | Any OpenAI-compatible endpoint | `openai-chat` | key |
@@ -150,16 +154,20 @@ Config lives at `~/.opencodex/config.json`. Minimal example:
 }
 ```
 
+WebSocket transport is off by default. Set `"websockets": true` only if you want Codex to advertise
+and use the Responses WebSocket path instead of HTTP/SSE.
+
 See the **[Configuration reference](https://lidge-jun.github.io/opencodex/reference/configuration/)**
 for every field.
 
 ## Documentation
 
-The full developer documentation — architecture, every adapter, the request lifecycle, the sidecars,
-Codex integration, and the CLI/config reference — is an Astro site under [`docs-site/`](./docs-site)
-and published to **[lidge-jun.github.io/opencodex](https://lidge-jun.github.io/opencodex/)**.
-Deep implementation notes live under [`docs/`](./docs), including the Codex App/model catalog path
-that makes routed opencodex models appear in the Codex App picker.
+The public docs — install, providers, routing, sidecars, Codex integration, Codex App model picker,
+and CLI/config reference — are built from [`docs-site/`](./docs-site) and published to
+**[lidge-jun.github.io/opencodex](https://lidge-jun.github.io/opencodex/)**.
+
+Maintainer source-of-truth notes live under [`structure/`](./structure). Historical investigations
+remain under [`docs/`](./docs).
 
 ## Development
 

README.zh-CN.md

@@ -77,8 +77,13 @@ codex -m "ollama-cloud/glm-5.2"      "Write a SQL migration"
 - **OAuth、API key 或 ChatGPT 转发（forward）。** 用你的 xAI / Anthropic / Kimi 账户登录（token
   自动刷新）、转发你的 `codex login`，或直接粘贴一个 key（支持 `${ENV_VARS}`）。内置一份 18 家 provider 的
   API-key 目录（含 **Ollama Cloud**）。
-- **无缝接入 Codex。** 向 `$CODEX_HOME/config.toml`（默认 `~/.codex/config.toml`）注入一个 `[model_providers.opencodex]` 表，并
-  将已路由的模型合并进 Codex 的目录和 subagent 选择器 —— 完全可逆。
+- **无缝接入 Codex CLI、TUI、App 和 SDK。** 向 `$CODEX_HOME/config.toml`（默认 `~/.codex/config.toml`）
+  注入一个 `[model_providers.opencodex]` 表，并写入共享的 Codex 模型目录，让已路由的模型出现在
+  Codex 模型选择器中。
+- **Subagent 控制。** 通过 `subagentModels` 或 Web 仪表盘，将最多 5 个路由或原生模型优先展示在
+  Codex 的 `spawn_agent` 选择器中。
+- **默认 HTTP/SSE，WebSocket 需要显式开启。** 代理有 Responses WebSocket 端点，但只有设置
+  `"websockets": true` 时才会广告 `supports_websockets`。
 - **Sidecars。** 通过基于你 ChatGPT 登录的 `gpt-5.4-mini`，为非 OpenAI 模型提供真正的**网页搜索**和**图像理解**能力。
 - **Web 仪表盘**，用于管理 provider、OAuth 登录、模型选择和请求日志。
 
@@ -110,6 +115,7 @@ ocx login <xai|anthropic|kimi> # OAuth login
 ocx logout <provider>          # remove a stored login
 ocx gui                        # open the web dashboard
 ocx service <install|start|stop|status|uninstall>   # run as a background service
+ocx update                     # update opencodex to the latest published version
 ```
 
 ## 配置
@@ -137,14 +143,19 @@ ocx service <install|start|stop|status|uninstall>   # run as a background servic
 }
 ```
 
+WebSocket 传输默认关闭。只有当你希望 Codex 广告并使用 Responses WebSocket 路径而不是 HTTP/SSE 时，
+才需要设置 `"websockets": true`。
+
 每个字段的说明请参阅 **[配置参考](https://lidge-jun.github.io/opencodex/zh-cn/reference/configuration/)**。
 
 ## 文档
 
-完整的开发者文档 —— 架构、每个 adapter、请求生命周期、sidecars、
-Codex 集成，以及 CLI/配置参考 —— 是位于 [`docs-site/`](./docs-site) 下的一个 Astro 站点，
+公开文档 —— 安装、providers、路由、sidecars、Codex 集成、Codex App 模型选择器，
+以及 CLI/配置参考 —— 是位于 [`docs-site/`](./docs-site) 下的一个 Astro 站点，
 并发布于 **[lidge-jun.github.io/opencodex](https://lidge-jun.github.io/opencodex/zh-cn/)**。
 
+维护者 source of truth 位于 [`structure/`](./structure)，历史调查/诊断笔记保留在 [`docs/`](./docs)。
+
 ## 开发
 
 ```bash

docs-site/astro.config.mjs

@@ -50,6 +50,7 @@ export default defineConfig({
             { label: "Providers", translations: { ko: "프로바이더", "zh-CN": "提供商" }, slug: "guides/providers" },
             { label: "Model Routing", translations: { ko: "모델 라우팅", "zh-CN": "模型路由" }, slug: "guides/model-routing" },
             { label: "Codex Integration", translations: { ko: "Codex 통합", "zh-CN": "Codex 集成" }, slug: "guides/codex-integration" },
+            { label: "Codex App Model Picker", translations: { ko: "Codex App 모델 선택기", "zh-CN": "Codex App 模型选择器" }, slug: "guides/codex-app-models" },
             { label: "Sidecars: Web Search & Vision", translations: { ko: "사이드카: 웹 검색 & 비전", "zh-CN": "边车：网络搜索与视觉" }, slug: "guides/sidecars" },
             { label: "Web Dashboard", translations: { ko: "웹 대시보드", "zh-CN": "网页控制台" }, slug: "guides/web-dashboard" },
           ],

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

@@ -25,15 +25,28 @@ The docs site you're reading lives in `docs-site/` (Astro + Starlight):
 cd docs-site && bun install && bun dev
 ```
 
+## Docs publishing
+
+The public docs publish to GitHub Pages at <https://lidge-jun.github.io/opencodex/>. The
+`.github/workflows/deploy-docs.yml` workflow runs on `main` pushes that touch `docs-site/**` or the
+workflow itself, builds `docs-site`, and deploys the generated site. Before pushing docs changes,
+run:
+
+```bash
+cd docs-site
+bun install --frozen-lockfile
+bun run build
+```
+
 ## Conventions
 
 - **ES Modules only** (`import`/`export`), TypeScript, `strict` mode. Keep `bun x tsc --noEmit` clean.
 - **~500 lines per file max** — split by responsibility (the `web-search/` and `vision/` sidecars are
   good examples of small, focused modules behind a single `index.ts`).
 - **Handle async errors at boundaries** — sidecars never throw into the request path; they degrade to
   a graceful marker.
-- **Devlog** — design notes live in `devlog/NN_slug/` with decade-range numbering (`00–09` research,
-  `10–19` phase 1, …). New work gets the next decade.
+- **Structure SOT** — current maintainer invariants live in `structure/`. Keep public user workflows
+  in `docs-site/` and historical investigation notes in `docs/`.
 - **Preserve exports** — other modules may depend on them.
 
 ## Adding a provider to the catalog

docs-site/src/content/docs/guides/codex-app-models.md

@@ -36,6 +36,9 @@ wire_api = "responses"
 requires_openai_auth = true
 ```
 
+`websockets` is off by default. opencodex only advertises `supports_websockets = true` in the
+provider table and catalog entries when `"websockets": true` is set.
+
 ## Why routed models show up
 
 Codex's model picker expects Codex-shaped catalog entries. opencodex builds those entries by cloning
@@ -71,6 +74,12 @@ opencodex preserves that split. Native OpenAI passthrough models keep fast suppo
 non-OpenAI models strip service-tier metadata so the fast option is not advertised where it cannot
 be honored.
 
+## Subagent selection
+
+Codex's `spawn_agent` advertises the highest-priority first 5 catalog models. Pick up to five
+`provider/model` or native ids through `subagentModels` or the web dashboard; opencodex sorts those
+entries to the front of the shared catalog.
+
 ## Refreshing model state
 
 If the picker still shows stale entries, refresh the catalog and restart the target Codex surface:

docs-site/src/content/docs/guides/codex-integration.md

@@ -14,12 +14,15 @@ idempotent and reversible.
 ```toml
 # at the document root — Codex reads this as the active provider
 model_provider = "opencodex"
+model_catalog_json = "/absolute/path/to/opencodex-catalog.json"
 
 # appended at end of file (TOML tables are position-independent)
 [model_providers.opencodex]
 name = "OpenCodex Proxy"
 base_url = "http://localhost:10100/v1"
 wire_api = "responses"
+requires_openai_auth = true
+# supports_websockets = true   # only when config.websockets is true
 ```
 
 It also writes an optional profile at `$CODEX_HOME/opencodex.config.toml` so you can opt in explicitly:
@@ -34,6 +37,22 @@ part of a table and ignores it. The injector guarantees this placement and strip
 duplicate copies before re-writing — so re-running `ocx init` / `ocx sync` never produces duplicates.
 :::
 
+## Shared model catalog
+
+Codex CLI, TUI, App, and SDK all read the same Codex home. opencodex resolves that directory from
+`CODEX_HOME`, falling back to `~/.codex`, and manages:
+
+```text
+$CODEX_HOME/config.toml
+$CODEX_HOME/opencodex.config.toml
+$CODEX_HOME/opencodex-catalog.json
+$CODEX_HOME/models_cache.json
+```
+
+`requires_openai_auth = true` keeps Codex App/TUI account-gated surfaces aligned with native Codex.
+WebSocket transport is different: opencodex serves `/v1/responses` over WebSocket, but only advertises
+`supports_websockets = true` when `"websockets": true` is set in `~/.opencodex/config.json`.
+
 ## Model catalog sync
 
 Codex shows models from an on-disk catalog (`$CODEX_HOME/opencodex-catalog.json` by default). On

docs-site/src/content/docs/index.mdx

@@ -45,9 +45,14 @@ Codex CLI / App / SDK ──/v1/responses──▶ opencodex ──▶ Any provi
   </Card>
   <Card title="Drops into Codex" icon="rocket">
     `ocx init` injects a provider into `$CODEX_HOME/config.toml` (default
-    `~/.codex/config.toml`) and merges routed models into Codex's catalog and subagent picker.
+    `~/.codex/config.toml`) and writes a shared Codex catalog, so Codex CLI, TUI, App, and SDK
+    all see the same routed models and subagent picks.
     `ocx stop` restores native Codex cleanly.
   </Card>
+  <Card title="Subagents and transports" icon="puzzle">
+    Pin up to five routed or native models for Codex `spawn_agent`. HTTP/SSE stays the default;
+    Responses WebSocket support is advertised only when `websockets: true`.
+  </Card>
   <Card title="Sidecars" icon="magnifier">
     Give non-OpenAI models real **web search** and **image understanding** by routing those
     capabilities through a `gpt-5.4-mini` sidecar over your ChatGPT login.
@@ -58,7 +63,7 @@ Codex CLI / App / SDK ──/v1/responses──▶ opencodex ──▶ Any provi
 
 ```bash
 # Install
-bun install -g opencx      # or: npm install -g opencx
+bun install -g @bitkyc08/opencodex      # or: npm install -g @bitkyc08/opencodex
 
 # Interactive setup (writes config + injects into Codex)
 ocx init
@@ -76,5 +81,7 @@ codex "Write a hello world in Rust"
   <LinkCard title="Installation" href="/opencodex/getting-started/installation/" description="Install ocx, prerequisites, and verification." />
   <LinkCard title="How It Works" href="/opencodex/getting-started/how-it-works/" description="The full request lifecycle: parse → route → adapter → bridge → SSE." />
   <LinkCard title="Providers" href="/opencodex/guides/providers/" description="OAuth, API-key catalog, forward/passthrough, and the full provider table." />
+  <LinkCard title="Codex App Model Picker" href="/opencodex/guides/codex-app-models/" description="How routed opencodex models show up in Codex App through the shared catalog." />
+  <LinkCard title="Web Dashboard" href="/opencodex/guides/web-dashboard/" description="Manage providers, OAuth, model visibility, subagents, and logs." />
   <LinkCard title="CLI Reference" href="/opencodex/reference/cli/" description="Every ocx command and flag." />
 </CardGrid>

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

@@ -25,6 +25,19 @@ cd gui && bun install && bun dev
 cd docs-site && bun install && bun dev
 ```
 
+## 문서 배포
+
+공개 문서는 GitHub Pages의 <https://lidge-jun.github.io/opencodex/ko/>에 게시됩니다.
+`.github/workflows/deploy-docs.yml` 워크플로는 `main` 브랜치에서 `docs-site/**` 또는 워크플로
+자체가 바뀔 때 실행되며, `docs-site`를 빌드한 뒤 배포합니다. 문서 변경을 푸시하기 전에 다음을
+실행하세요:
+
+```bash
+cd docs-site
+bun install --frozen-lockfile
+bun run build
+```
+
 ## 컨벤션
 
 - **ES Modules 전용**(`import`/`export`), TypeScript, `strict` 모드. `bun x tsc --noEmit`을 깨끗하게
@@ -33,8 +46,8 @@ cd docs-site && bun install && bun dev
   `index.ts` 뒤에 작고 집중된 모듈을 둔 좋은 예입니다).
 - **비동기 에러는 경계에서 처리** — 사이드카는 요청 경로로 절대 throw하지 않으며, 우아한 마커로
   성능을 낮춥니다.
-- **Devlog** — 설계 노트는 10단위 범위 번호를 사용해 `devlog/NN_slug/`에 둡니다(`00–09` 리서치,
-  `10–19` 1단계, …). 새 작업은 다음 10단위를 받습니다.
+- **Structure SOT** — 현재 유지보수 불변식은 `structure/`에 둡니다. 공개 사용자 워크플로는
+  `docs-site/`, 과거 조사/진단 노트는 `docs/`에 둡니다.
 - **익스포트 보존** — 다른 모듈이 이에 의존할 수 있습니다.
 
 ## 카탈로그에 프로바이더 추가하기