feat(docs): brand logo + Korean & Chinese localization

- Logo: use the provided mark. Generated transparent light (black) + dark (white)
  variants so it stays visible on both Starlight themes, plus a rounded favicon.png
  (replaces the old placeholder favicon.svg). Wired via Starlight `logo`/`favicon`.
- i18n: add Korean (/ko) and Simplified Chinese (/zh-cn) locales with a fully
  translated sidebar; English stays at the root. Adds a language switcher.
- Translated all 14 pages into ko + zh-cn (28 files) — prose + frontmatter values
  translated; code, component syntax, product/adapter/field names preserved; internal
  links localized per locale. Build green: 43 pages, no broken links.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: lidge-jun

docs-site/astro.config.mjs

@@ -13,43 +13,58 @@ export default defineConfig({
       description:
         "Universal provider proxy for OpenAI Codex — use any LLM with Codex CLI, App, and SDK.",
       tagline: "Use any LLM with OpenAI Codex.",
-      favicon: "/favicon.svg",
+      logo: {
+        light: "./src/assets/logo-light.png",
+        dark: "./src/assets/logo-dark.png",
+        replacesTitle: false,
+      },
+      favicon: "/favicon.png",
       social: [
         { icon: "github", label: "GitHub", href: "https://github.com/lidge-jun/opencodex" },
       ],
       editLink: {
         baseUrl: "https://github.com/lidge-jun/opencodex/edit/main/docs-site/",
       },
       lastUpdated: true,
+      // English at the site root; Korean under /ko, Simplified Chinese under /zh-cn.
+      defaultLocale: "root",
+      locales: {
+        root: { label: "English", lang: "en" },
+        ko: { label: "한국어", lang: "ko" },
+        "zh-cn": { label: "简体中文", lang: "zh-CN" },
+      },
       sidebar: [
         {
           label: "Getting Started",
+          translations: { ko: "시작하기", "zh-CN": "开始使用" },
           items: [
-            { label: "Installation", slug: "getting-started/installation" },
-            { label: "Quickstart", slug: "getting-started/quickstart" },
-            { label: "How It Works", slug: "getting-started/how-it-works" },
+            { label: "Installation", translations: { ko: "설치", "zh-CN": "安装" }, slug: "getting-started/installation" },
+            { label: "Quickstart", translations: { ko: "빠른 시작", "zh-CN": "快速开始" }, slug: "getting-started/quickstart" },
+            { label: "How It Works", translations: { ko: "동작 원리", "zh-CN": "工作原理" }, slug: "getting-started/how-it-works" },
           ],
         },
         {
           label: "Guides",
+          translations: { ko: "가이드", "zh-CN": "指南" },
           items: [
-            { label: "Providers", slug: "guides/providers" },
-            { label: "Model Routing", slug: "guides/model-routing" },
-            { label: "Codex Integration", slug: "guides/codex-integration" },
-            { label: "Sidecars: Web Search & Vision", slug: "guides/sidecars" },
-            { label: "Web Dashboard", slug: "guides/web-dashboard" },
+            { 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: "Sidecars: Web Search & Vision", translations: { ko: "사이드카: 웹 검색 & 비전", "zh-CN": "边车：网络搜索与视觉" }, slug: "guides/sidecars" },
+            { label: "Web Dashboard", translations: { ko: "웹 대시보드", "zh-CN": "网页控制台" }, slug: "guides/web-dashboard" },
           ],
         },
         {
           label: "Reference",
+          translations: { ko: "레퍼런스", "zh-CN": "参考" },
           items: [
-            { label: "CLI", slug: "reference/cli" },
-            { label: "Configuration", slug: "reference/configuration" },
-            { label: "Adapters", slug: "reference/adapters" },
-            { label: "Architecture", slug: "reference/architecture" },
+            { label: "CLI", translations: { ko: "CLI", "zh-CN": "命令行" }, slug: "reference/cli" },
+            { label: "Configuration", translations: { ko: "설정", "zh-CN": "配置" }, slug: "reference/configuration" },
+            { label: "Adapters", translations: { ko: "어댑터", "zh-CN": "适配器" }, slug: "reference/adapters" },
+            { label: "Architecture", translations: { ko: "아키텍처", "zh-CN": "架构" }, slug: "reference/architecture" },
           ],
         },
-        { label: "Contributing", slug: "contributing" },
+        { label: "Contributing", translations: { ko: "기여하기", "zh-CN": "贡献" }, slug: "contributing" },
       ],
     }),
   ],

docs-site/public/favicon.png

@@ -0,0 +1,69 @@
+---
+title: 기여하기
+description: opencodex 개발하기 — 설정, 구조, 컨벤션, 그리고 프로바이더나 어댑터를 추가하는 방법.
+---
+
+## 설정
+
+```bash
+git clone https://github.com/lidge-jun/opencodex.git
+cd opencodex
+bun install
+bun run dev          # proxy in dev mode
+bun x tsc --noEmit   # typecheck (must be clean)
+```
+
+웹 대시보드는 별도의 앱입니다:
+
+```bash
+cd gui && bun install && bun dev
+```
+
+지금 읽고 있는 문서 사이트는 `docs-site/`에 있습니다(Astro + Starlight):
+
+```bash
+cd docs-site && bun install && bun dev
+```
+
+## 컨벤션
+
+- **ES Modules 전용**(`import`/`export`), TypeScript, `strict` 모드. `bun x tsc --noEmit`을 깨끗하게
+  유지하세요.
+- **파일당 최대 약 500줄** — 책임별로 분할하세요(`web-search/`와 `vision/` 사이드카가 단일
+  `index.ts` 뒤에 작고 집중된 모듈을 둔 좋은 예입니다).
+- **비동기 에러는 경계에서 처리** — 사이드카는 요청 경로로 절대 throw하지 않으며, 우아한 마커로
+  성능을 낮춥니다.
+- **Devlog** — 설계 노트는 10단위 범위 번호를 사용해 `devlog/NN_slug/`에 둡니다(`00–09` 리서치,
+  `10–19` 1단계, …). 새 작업은 다음 10단위를 받습니다.
+- **익스포트 보존** — 다른 모듈이 이에 의존할 수 있습니다.
+
+## 카탈로그에 프로바이더 추가하기
+
+대부분의 프로바이더는 API 키 카탈로그(`src/oauth/key-providers.ts`)의 항목 하나에 불과합니다:
+
+```ts
+"my-provider": {
+  label: "My Provider",
+  baseUrl: "https://api.example.com/v1",
+  adapter: "openai-chat",
+  dashboardUrl: "https://example.com/keys",
+  models: ["model-a", "model-b"],
+  defaultModel: "model-a",
+  noVisionModels: ["model-a"],   // text-only models → vision sidecar describes images
+}
+```
+
+`enrichProviderFromCatalog()`는 `models` / `noVisionModels` / `noReasoningModels`를 생성된
+프로바이더 설정으로 복사하므로 분류가 자동으로 적용됩니다. OAuth 프로바이더의 경우 대신
+`src/oauth/index.ts`의 `OAUTH_PROVIDERS`에 추가하세요.
+
+## 어댑터 추가하기
+
+`src/adapters/`에 `ProviderAdapter`([어댑터](/opencodex/ko/reference/adapters/) 참조)를 구현하고,
+어댑터 리졸버에 등록한 뒤, 그 출력을 내부 `AdapterEvent`로 브리징하세요. 이미지 처리에는
+`image.ts`를 재사용하고, 스트리밍 + 툴 호출의 레퍼런스로 `openai-chat.ts`를 따르세요.
+
+## 완료를 주장하기 전에 검증하기
+
+변경 사항을 증명하는 가장 좁은 명령을 실행하세요 — 타입에는 `bun x tsc --noEmit`, 동작에는 집중된
+런타임 프로브. opencodex는 큰 배치보다 작고 검증 가능한 커밋을 선호합니다.

docs-site/public/favicon.svg

@@ -0,0 +1,74 @@
+---
+title: 작동 방식
+description: opencodex의 전체 요청 수명 주기 — parse, route, adapt, bridge, stream.
+---
+
+import { Steps } from '@astrojs/starlight/components';
+
+Codex는 정확히 하나의 프로토콜만 사용합니다: OpenAI **Responses API**(`POST /v1/responses`, Server-Sent
+Events). opencodex는 이 요청을 받아 프로바이더의 wire 포맷으로 변환하고, 스트리밍되는 응답을 다시
+Responses 이벤트로 변환합니다 — 그래서 Codex는 자신이 OpenAI와 통신하고 있지 않다는 사실을 전혀 알지 못합니다.
+
+```
+            ┌──────────────────────────── opencodex ────────────────────────────┐
+            │                                                                     │
+ Codex ──▶  │  parser ──▶ router ──▶ [vision] ──▶ adapter ──▶ provider           │  ──▶ Codex
+ (/v1/      │     │          │          │            │           │                │     (SSE)
+  responses)│   OcxParsed  provider   describe    buildRequest  parseStream       │
+            │   Request    +adapter   images       + fetch      AdapterEvent[]    │
+            │                                          │           │              │
+            │                                  [web-search loop]  bridge ─▶ SSE   │
+            └─────────────────────────────────────────────────────────────────────┘
+```
+
+## 수명 주기
+
+<Steps>
+
+1. **Parse** — `responses/parser.ts`가 Zod 스키마(`responses/schema.ts`)로 요청을 검증하고
+   이를 내부 `OcxParsedRequest`로 변환합니다: 시스템 프롬프트, 정규화된 메시지 목록
+   (텍스트, 이미지, tool call, tool result), tool 정의, 생성 옵션, 그리고
+   `_webSearch`(호스팅 웹 검색 요청됨)와 `_structuredOutput`(JSON 스키마 /
+   JSON-object `text.format`이 설정됨) 같은 기능 플래그. 이미지는 실제 콘텐츠 파트로 보존되며,
+   절대 base64 텍스트로 인라인되지 않습니다.
+
+2. **Route** — `router.ts`가 고정된 우선순위에 따라 요청된 모델 id를 설정된 프로바이더로
+   매핑합니다: 명시적 `provider/model` → 프로바이더의 `defaultModel` → 프로바이더의 `models[]` →
+   내장 prefix 패턴(`claude-`, `gpt-`, `o1-`/`o3-`/`o4-`, `llama-`/`mixtral-`/`gemma-`) →
+   `defaultProvider` 폴백. [모델 라우팅](/opencodex/ko/guides/model-routing/)을 참고하세요.
+
+3. **Authenticate** — `oauth` 프로바이더의 경우, opencodex가 새로 자동 갱신된 access
+   토큰을 bearer 키로 교체하므로, 기존 adapter들은 변경 없이 인증됩니다.
+
+4. **Vision sidecar(선택)** — 라우팅된 모델이 `provider.noVisionModels`에 나열되어 있고
+   요청에 이미지가 포함된 경우, opencodex는 ChatGPT 로그인을 통한 `gpt-5.4-mini` vision 모델로
+   각 이미지를 설명한 뒤 텍스트로 치환합니다. 덕분에 텍스트 전용 모델도 해당 이미지에 대해 추론할 수 있습니다.
+   [Sidecar](/opencodex/ko/guides/sidecars/)를 참고하세요.
+
+5. **Passthrough 빠른 경로** — adapter가 패스스루(`forward` 모드의 `openai-responses`,
+   또는 `azure`)인 경우, 원본 요청 본문이 프로바이더로 그대로 전달되고 응답도 변환 없이
+   그대로 스트리밍됩니다. 어떤 변환도 일어나지 않습니다.
+
+6. **Web-search sidecar(선택)** — Codex가 호스팅 `web_search`를 활성화했지만 라우팅된 모델이
+   OpenAI가 아닌 경우, opencodex는 합성 `web_search` function tool을 노출하고 모델을 작은
+   에이전트 루프로 실행하면서, ChatGPT 로그인을 통한 `gpt-5.4-mini`로 실제 검색을 수행해
+   그 결과를 tool result로 다시 주입합니다.
+
+7. **Adapt** — 그 외의 경우, 선택된 adapter의 `buildRequest()`가 프로바이더의 네이티브
+   포맷으로 업스트림 HTTP 요청(URL, 헤더, 본문)을 생성하고, opencodex가 이를 `fetch`합니다.
+
+8. **Bridge** — adapter의 `parseStream()`(또는 `parseResponse()`)이 내부 `AdapterEvent`를
+   생성합니다(텍스트, reasoning, tool-call start/delta/end, done, error). `bridge.ts`는 그 스트림을
+   다시 Responses SSE 이벤트로 변환합니다 — `response.output_text.delta`, `response.reasoning_summary_text.delta`,
+   `response.function_call_arguments.delta`, `response.completed` 등 — 그리고 Codex가 이를 소비합니다.
+
+</Steps>
+
+## 왜 Codex 포크가 아니라 프록시인가?
+
+Codex는 Responses API를 하드코딩하고 있습니다. opencodex는 프로토콜 경계에서 변환을 수행함으로써
+Codex **CLI, App, SDK**를 변경 없이 그대로 지원하고, Codex 업데이트에도 영향을 받지 않으며,
+Codex 자체를 건드리지 않고 요청마다 프로바이더를 전환할 수 있게 합니다. 이 변환은 양방향이며
+스트리밍에 충실합니다: reasoning 요약, MCP tool 네임스페이스, freeform(`apply_patch`) tool,
+`tool_search` 발견이 모두 정확히 왕복합니다. 이벤트별 매핑은 [아키텍처 레퍼런스](/opencodex/ko/reference/architecture/)를
+참고하세요.

docs-site/src/assets/logo-dark.png

@@ -0,0 +1,68 @@
+---
+title: 설치
+description: opencodex(ocx) 프록시와 사전 요구 사항을 설치하고, 정상 실행되는지 확인합니다.
+---
+
+opencodex는 단일 CLI인 `ocx`로 제공됩니다. 작은 로컬 HTTP 서버(Bun 기반)로 실행되며, 설정한
+프로바이더 외에는 어디로도 트래픽을 전송하지 않습니다.
+
+## 사전 요구 사항
+
+| 요구 사항 | 이유 |
+| --- | --- |
+| **[Bun](https://bun.sh) ≥ 1.1**(권장) 또는 **Node ≥ 20** | `ocx`는 Bun 런타임에서 실행되며, 서비스 러너가 `bun`을 호출합니다. |
+| **[OpenAI Codex](https://openai.com/codex)**(CLI, App, 또는 SDK) | opencodex가 앞단에 위치하는 클라이언트입니다. opencodex는 `~/.codex/config.toml`에 기록합니다. |
+| 프로바이더 계정 또는 API 키 | Anthropic, xAI, Kimi, Ollama Cloud, OpenRouter, OpenAI 호환 엔드포인트, 또는 ChatGPT 로그인. |
+
+## 설치
+
+```bash
+# With Bun (recommended)
+bun install -g opencodex
+
+# With npm
+npm install -g opencodex
+```
+
+바이너리가 `PATH`에 있는지 확인합니다:
+
+```bash
+ocx --help
+```
+
+## 소스에서 실행
+
+opencodex 자체를 직접 수정하며 작업하려면:
+
+```bash
+git clone https://github.com/lidge-jun/opencodex.git
+cd opencodex
+bun install
+bun run dev      # starts the proxy in dev mode (src/cli.ts start)
+```
+
+웹 대시보드는 `gui/`에 있으며 별도로 실행됩니다:
+
+```bash
+cd gui && bun install && bun dev
+```
+
+## 생성되는 항목
+
+| 경로 | 용도 |
+| --- | --- |
+| `~/.opencodex/config.json` | 프로바이더, 기본 프로바이더, 포트, 옵션. |
+| `~/.opencodex/ocx.pid` | 실행 중인 프록시의 PID(단일 인스턴스 가드). |
+| `~/.opencodex/auth.json` | 저장된 OAuth 자격 증명(`ocx login` 시). |
+| `~/.opencodex/catalog-backup.json` | 변경 전에 백업해 둔 원본 Codex 모델 카탈로그. |
+| `~/.codex/config.toml` | opencodex가 `ocx init` 시 여기에 `[model_providers.opencodex]` 테이블을 추가합니다. |
+
+:::note
+opencodex는 절대 Codex 설정을 삭제하지 않습니다. 모든 주입은 되돌릴 수 있습니다 — `ocx stop`, `ocx restore`,
+또는 `ocx eject`는 opencodex가 추가한 줄만 정확히 제거하고 네이티브 Codex를 복원합니다.
+:::
+
+## 다음
+
+[Quickstart](/opencodex/ko/getting-started/quickstart/)로 이동해 첫 프로바이더를 설정하거나,
+아키텍처를 알아보려면 [작동 방식](/opencodex/ko/getting-started/how-it-works/)을 읽어 보세요.

docs-site/src/assets/logo-light.png

@@ -0,0 +1,83 @@
+---
+title: Quickstart
+description: 첫 프로바이더를 설정하고 명령어 세 개로 OpenAI Codex를 opencodex로 라우팅합니다.
+---
+
+이 가이드는 새로 설치한 상태에서 OpenAI가 아닌 모델로 Codex를 실행하기까지의 과정을 안내합니다.
+
+## 1. 설정 마법사 실행
+
+```bash
+ocx init
+```
+
+`ocx init`은 다음 과정을 안내합니다:
+
+1. **프로바이더 선택** — 프리셋(opencode zen, Anthropic, OpenAI, OpenRouter, Groq, Google,
+   Azure)을 고르거나, `custom`을 선택해 base URL과 adapter를 직접 입력합니다.
+2. **API 키** — 키를 붙여넣거나, `${ANTHROPIC_API_KEY}`와 같은 환경 변수를 참조합니다.
+3. **기본 모델** — 요청이 다른 프로바이더와 매칭되지 않을 때 사용되는 모델입니다.
+4. **프록시 포트** — 기본값은 `10100`입니다.
+5. **Codex에 주입할까요?** — 동의하면 opencodex가 `[model_providers.opencodex]` 테이블을
+   `~/.codex/config.toml`에 기록하고, `model_provider = "opencodex"`로 설정해 Codex가 프록시를 통해 라우팅하도록 합니다.
+
+결과는 `~/.opencodex/config.json`에 저장됩니다.
+
+## 2. 프록시 시작
+
+```bash
+ocx start            # defaults to port 10100
+ocx start --port 8080
+```
+
+시작 시 opencodex는:
+
+- PID를 `~/.opencodex/ocx.pid`에 기록하고(두 번 실행되는 것을 거부),
+- 각 프로바이더의 실시간 모델 목록을 가져와 **Codex의 모델 카탈로그에 동기화**하며,
+- `http://localhost:<port>/v1`에서 수신 대기합니다.
+
+확인:
+
+```bash
+ocx status
+```
+
+## 3. Codex 사용
+
+이제 Codex는 opencodex와 투명하게 통신합니다:
+
+```bash
+codex "Refactor this function for readability"
+```
+
+특정 라우팅 모델을 지정하려면, Codex의 모델 선택기에 표시되는 `provider/model` 형식을 사용하세요:
+
+```bash
+codex -m "anthropic/claude-opus-4-8" "Explain this stack trace"
+codex -m "ollama-cloud/glm-5.2"      "Write a SQL migration"
+```
+
+## 키를 붙여넣는 대신 로그인하기
+
+일부 프로바이더는 실제 계정 로그인을 지원합니다(OAuth, 자동 갱신):
+
+```bash
+ocx login xai          # or: anthropic, kimi
+ocx logout xai
+```
+
+OpenAI 자체는 **키가 필요 없습니다** — 기본 프로바이더가 기존 `codex login`
+자격 증명을 그대로 포워딩합니다([프로바이더](/opencodex/ko/guides/providers/) 참고).
+
+## 중지 및 복원
+
+```bash
+ocx stop      # stop the proxy and restore native Codex
+ocx restore   # restore native Codex without stopping (alias: ocx eject)
+```
+
+## 다음
+
+- [작동 방식](/opencodex/ko/getting-started/how-it-works/) — 각 요청에 무슨 일이 일어나는지.
+- [프로바이더](/opencodex/ko/guides/providers/) — 인증하는 모든 방법.
+- [구성](/opencodex/ko/reference/configuration/) — 전체 `config.json` 레퍼런스.