docs: document ocx export and the Pi client

Phase 050 of devlog/_plan/260731_client_config_export.

The export command shipped in the previous four commits with nothing in
docs-site pointing at it, and Pi had no page at all.

Adds the ocx export section to the CLI reference (English plus the four
translated copies), a section in the opencode guide on getting the
provider block into your own config, and a Pi guide.

Three things the docs have to get right, each verified against the code
while writing: the two clients use DIFFERENT env vars
(OPENCODEX_OPENCODE_API_KEY vs OPENCODEX_API_KEY), a loopback bind needs
no admission key at all since shouldInjectApiAuthHeader is just
!isLoopbackHostname, and an exported config must be merged rather than
replace an existing file.

BYOK is split rather than restated: the proxy admission key is what the
exported config references, provider keys stay in providers.<name>.apiKey
and keep their existing home in the providers guide.

The Pi schema is still unverified against a real install and the guide
says so.

Author: lidge-jun

devlog/_plan/260731_client_config_export/050_docs_and_hardening.md

@@ -0,0 +1,93 @@
+# 050 — Phase 5: user-facing docs + hardening
+
+Second work-phase of this unit, appended after the four implementation phases
+closed (LOOP-UNIT-CHAIN-01). The feature ships; nothing tells a user it exists.
+
+## Why this phase exists
+
+`ocx export` and the GUI panel landed in `f7ac037e0`. A grep of `docs-site/`
+finds:
+
+- `reference/cli.md` — the command table lists `ocx access`, `ocx config`,
+  `ocx observe`. There is no `ocx export` row and no subcommand section.
+- `guides/opencode.md` — 106 lines about `ocx opencode`. It states "your own
+  config is never modified", which is still true, but there is now a supported
+  way to GET the block into your own config and the guide does not mention it.
+- Pi — no guide, no mention anywhere in the repo.
+- BYOK — the term appears nowhere in `src/`, `gui/`, or `docs-site/`.
+
+A feature a user cannot discover is not shipped.
+
+## The BYOK question
+
+The user asked for "byok 같은 곳 설정하는 법". Read against the tree, BYOK here
+is not a new subsystem — it is the **credential half** of the export story, and
+it spans two different keys that are easy to confuse:
+
+| Key | What it is | Where it goes |
+|-----|-----------|---------------|
+| Proxy admission (`ocx_…`) | opencodex's own key, generated on the API tab | the exported config's env reference |
+| Provider key (`sk-…`, etc.) | your Anthropic/OpenAI/OpenRouter key | `providers.<name>.apiKey` in opencodex config |
+
+The export flow only ever references the FIRST. The second is what "bring your
+own key" normally means, is documented in `guides/providers.md` §Auth modes and
+`reference/configuration.md` (`apiKey`, `apiKeyPool`, `${ENV_VAR}`), and is NOT
+re-documented here — this phase links to it instead of forking a second
+explanation that would drift.
+
+What is genuinely missing is the seam: a reader who exports a config has no
+page telling them which key the `{env:...}` reference wants, how to generate
+it, or that a loopback proxy does not require one at all.
+
+## Scope
+
+IN
+- MODIFY `docs-site/src/content/docs/reference/cli.md` — command table row +
+  an `ocx export` subcommand section.
+- MODIFY `docs-site/src/content/docs/guides/opencode.md` — a section on taking
+  the provider block into your own config, pointing at `ocx export`.
+- NEW `docs-site/src/content/docs/guides/pi.md` — the Pi guide, including the
+  credential seam.
+- Locale sync for any translated page whose English source changed, per
+  AGENTS.md ("keep translated locales from contradicting the English source").
+
+OUT
+- No `src/` or `gui/` behavior change. This phase is docs + whatever hardening
+  the docs review exposes, and a code change discovered here becomes its own
+  amendment rather than a silent edit.
+- No re-documentation of provider auth modes; link to `guides/providers.md`.
+- No new BYOK subsystem. BYOK is an existing capability, not a feature to add.
+
+## Hardening review (the docs pass doubles as an adversarial read)
+
+Writing the docs forces every claim to be checked against the shipped code.
+Four claims to verify while writing, each a real failure if wrong:
+
+1. **The destination path we print is the one Pi/OpenCode actually reads.**
+   `EXPORT_CLIENTS.*.destination` honors `XDG_CONFIG_HOME` for OpenCode.
+   Pi's path is still UNVERIFIED against a real install (`001` §2) — the guide
+   must say so rather than assert it.
+2. **The env var name in the docs matches the one in the emitted config.**
+   `OPENCODEX_OPENCODE_API_KEY` for OpenCode, `OPENCODEX_API_KEY` for Pi. Two
+   different names; a doc that mixes them sends the reader in a circle.
+3. **A loopback-only user needs no key at all.** `shouldInjectApiAuthHeader`
+   decides this. If the docs tell every reader to generate a key, most readers
+   do unnecessary work; if they tell nobody, non-loopback binds break.
+4. **The merge warning is in the docs, not just the CLI.** The download and the
+   `--out` refusal both exist because replacing an existing config destroys
+   other providers. The docs must carry the same warning.
+
+## Accept criteria
+
+1. `ocx export` appears in the `reference/cli.md` command table AND has a
+   subcommand section documenting `--client`, `--json`, `--out`, `--force`.
+   **Activation:** grep the built page for `ocx export`.
+2. The Pi guide states the exact destination path, the exact env var, and marks
+   the Pi schema as unverified against a real install.
+3. Every env var name in the new docs matches the string the code emits.
+   **Activation:** grep `OPENCODEX_OPENCODE_API_KEY` / `OPENCODEX_API_KEY` in
+   both `src/clients/config-export.ts` and the new docs; the sets must agree.
+4. The docs state that loopback binds need no admission key, and that a config
+   must be merged rather than used to replace an existing file.
+5. `bun run privacy:scan` green — the new docs use `~/…`, never a real home path.
+6. Docs build passes.

docs-site/astro.config.mjs

@@ -89,6 +89,7 @@ export default defineConfig({
             { label: "Claude Code", translations: { ko: "Claude Code", "zh-CN": "Claude Code", ru: "Claude Code", ja: "Claude Code" }, slug: "guides/claude-code" },
             { label: "Grok Build", translations: { ko: "Grok Build", "zh-CN": "Grok Build", ru: "Grok Build", ja: "Grok Build" }, slug: "guides/grok-build" },
             { label: "opencode", translations: { ko: "opencode", "zh-CN": "opencode", ru: "opencode", ja: "opencode" }, slug: "guides/opencode" },
+            { label: "Pi", translations: { ko: "Pi", "zh-CN": "Pi", ru: "Pi", ja: "Pi" }, slug: "guides/pi" },
             { label: "Sidecars: Web Search & Vision", translations: { ko: "사이드카: 웹 검색 & 비전", "zh-CN": "边车：网络搜索与视觉", ru: "Сайдкары: веб-поиск и зрение", ja: "サイドカー: ウェブ検索 & ビジョン" }, slug: "guides/sidecars" },
             { label: "Web Dashboard", translations: { ko: "웹 대시보드", "zh-CN": "网页控制台", ru: "Веб-дашборд", ja: "ウェブダッシュボード" }, slug: "guides/web-dashboard" },
             { label: "Sub-agent Surface", translations: { ko: "서브에이전트 서피스", "zh-CN": "子代理界面", ru: "Интерфейс подагентов", ja: "サブエージェントサーフェス" }, slug: "guides/sub-agent-surface" },

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

@@ -47,6 +47,43 @@ and overrides only conflicting keys for the child process.
 If a global or project config also defines `provider.opencodex`, the launcher prints an
 informational note: the runtime layer from `ocx opencode` overrides it for that launch.
 
+## Putting the block into your own config
+
+`ocx opencode` injects the provider block for one launch only, which means plain `opencode` still
+knows nothing about the proxy. When you want routed models available from plain `opencode` — or
+from an editor extension that never goes through the launcher — `ocx export` prints the same
+provider block for you to merge into your own config:
+
+```bash
+ocx export --client opencode
+```
+
+The proxy must be running. The command prints the config, the canonical destination
+(`~/.config/opencode/opencode.json`, or under `XDG_CONFIG_HOME` when that is set), the merge
+warning, and the env export line. It never touches that file — the section above stays true, and
+moving the block into your config is your explicit act.
+
+:::caution[Merge, never replace]
+Merge the `provider.opencodex` block into your existing config. Replacing the whole file with the
+exported one destroys your other providers, agents, keybinds, and MCP entries. `ocx export --out`
+refuses to overwrite an existing file for exactly this reason, so point `--out` at a scratch path
+and copy the block across:
+
+```bash
+ocx export --client opencode --out ~/opencodex-opencode.json
+```
+:::
+
+Unlike the launcher's runtime block, a merged block is a static snapshot: it does not follow your
+catalog. Re-run `ocx export` after you add a provider or change model visibility.
+
+Once merged, export the admission key before launching opencode — unless the proxy is on loopback,
+where none is needed:
+
+```bash
+export OPENCODEX_OPENCODE_API_KEY=<your key>
+```
+
 ## The admission key is not written to disk
 
 When the proxy requires an API key, the inline runtime config carries opencode's
@@ -78,6 +115,12 @@ The real value is passed only through the child process environment.
 `OPENCODEX_API_AUTH_TOKEN` takes precedence, then the hardened service token file, then
 a configured API key — which is what a non-loopback bind requires.
 
+A loopback bind (`127.0.0.1`, the default) authenticates nothing, so the `{env:…}` reference is
+inert and you can leave the variable unset. It matters only when `hostname` is set beyond loopback;
+see [Remote access](/reference/configuration/#remote-access). This admission key is opencodex's
+own, and is unrelated to the upstream provider keys configured under
+[Providers](/guides/providers/).
+
 ## Reverting
 
 Nothing to undo — no generated config file is written under `~/.opencodex`. Run plain

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

@@ -0,0 +1,122 @@
+---
+title: Pi
+description: Use any routed model from Pi — ocx export writes a custom provider block for Pi's models.json, wired to the running proxy.
+---
+
+Pi reads its providers from a single global JSON file rather than environment variables, so
+opencodex does not launch it. Instead, `ocx export` serializes the `opencodex` provider block —
+base URL, model list, and the env reference Pi interpolates — and you merge it into your own
+config.
+
+## Quickstart
+
+Start the proxy, then print the config:
+
+```bash
+ocx start
+ocx export --client pi
+```
+
+The output leads with the JSON, then prints the destination path, the merge warning, the env
+export line, and how many models carry authoritative context limits.
+
+```json
+{
+  "providers": {
+    "opencodex": {
+      "baseUrl": "http://127.0.0.1:10100/v1",
+      "api": "openai-completions",
+      "apiKey": "$OPENCODEX_API_KEY",
+      "models": [
+        {
+          "id": "anthropic/claude-opus-5",
+          "name": "Claude Opus 5 (anthropic)",
+          "input": ["text"],
+          "contextWindow": 200000,
+          "maxTokens": 32000
+        }
+      ]
+    }
+  }
+}
+```
+
+Model ids are the proxy's canonical selectors, so routed models appear as `provider/model`
+(`anthropic/claude-opus-5`) and native OpenAI slugs stay unprefixed (`gpt-5.6-sol`). The `name`
+suffix — `(anthropic)`, `(native)`, `(routed)` — is what makes two same-named models from
+different upstreams distinguishable in Pi's picker.
+
+## Where it goes
+
+Pi's global model config is:
+
+```text
+~/.pi/agent/models.json
+```
+
+:::caution[Merge, never replace]
+`ocx export` never writes that file. Merge the `providers.opencodex` block into it — replacing the
+file destroys every other provider you have configured there. `--out` exists for a scratch path
+and refuses to overwrite an existing file without `--force`:
+
+```bash
+ocx export --client pi --out ~/opencodex-pi-models.json
+ocx export --client pi --json > ~/opencodex-pi-models.json   # or redirect the byte-exact JSON
+```
+:::
+
+The exported block is a static snapshot, not a live view. Re-run `ocx export` after adding a
+provider or changing model visibility, and merge the new block over the old one.
+
+## The admission key
+
+Two different keys are easy to confuse here, and only the first one appears in this file:
+
+| Key | What it is | Where it lives |
+| --- | --- | --- |
+| Proxy admission key | opencodex's own credential, generated on the dashboard's **API** tab | referenced by `apiKey` as `$OPENCODEX_API_KEY`; the value stays in your environment |
+| Provider key | your Anthropic / OpenAI / OpenRouter key | opencodex's own config, per [Providers](/guides/providers/) |
+
+The exported config carries only the reference, never a secret. Pi interpolates a bare `$NAME`, so
+the variable is:
+
+```bash
+export OPENCODEX_API_KEY=<your key>
+```
+
+That name is Pi's alone. opencode uses a different variable
+(`OPENCODEX_OPENCODE_API_KEY`, in `{env:…}` form) — see the [opencode guide](/guides/opencode/).
+
+**A loopback proxy needs no key at all.** opencodex binds `127.0.0.1` by default and authenticates
+nothing there, so the `$OPENCODEX_API_KEY` reference is inert and you can leave the variable unset.
+It matters only when `hostname` is set beyond loopback, which is also the case where the proxy
+refuses to start without a token — see [Remote access](/reference/configuration/#remote-access).
+
+## Model metadata
+
+`contextWindow` and `maxTokens` are emitted only when the catalog reports an authoritative context
+window. When it does not, both fields are omitted for that model and Pi applies its own defaults;
+`ocx export` prints how many rows fell into that case.
+
+`maxTokens` is a schema-satisfying budget of `32000`, clamped down to the context window so a
+small-context model is never given more output than context. It is not a claim about any specific
+model's true maximum.
+
+Two fields are deliberately absent. `cost` requires all four price fields and opencodex has no
+price data for routed models — emitting zeros would assert that every model is free. `reasoning` is
+a boolean in Pi while the catalog carries an effort ladder, and mapping one onto the other would be
+a guess.
+
+## Schema status
+
+:::note[Unverified against a real install]
+The shape above follows Pi's published custom-provider documentation. It has **not** been verified
+against a real `~/.pi/agent/models.json` on a machine with Pi installed. If Pi rejects the exported
+block, the mismatch is on our side — please
+[open an issue](https://github.com/lidge-jun/opencodex/issues) with what Pi reported.
+:::
+
+## Requirements
+
+A running opencodex proxy (`ocx start`) and Pi installed. `ocx export` reads the live catalog
+through the proxy's management API, so a config can never be emitted with an empty model list.

docs-site/src/content/docs/ja/reference/cli.md

@@ -321,6 +321,56 @@ security find-generic-password -w openrouter | ocx account add-key openrouter --
 
 `--json` は `{ ok: true, id: string | null, label?: string }` を返し key を含みません。
 
+### `ocx export --client <opencode|pi>`
+
+実行中のプロキシに接続されたクライアント設定を出力します。opencode と Pi は環境変数ではなく自分の
+JSON 設定ファイルからプロバイダーを読むため、このコマンドが `opencodex` プロバイダーブロック
+(base URL、モデル一覧、クライアントが解釈する環境変数参照) を直列化します。自分のファイルへの
+マージはユーザーが行います。
+
+プロキシが動いている必要があります。実行中のポートを解決して `/api/models` を読み、今 Codex から
+見えるモデルだけを出力します。
+
+| フラグ | 動作 |
+| --- | --- |
+| `--client <opencode\|pi>` | 必須。クライアント方言を選びます。opencode は key 付き `provider` オブジェクト、Pi は `providers` 配列です。 |
+| `--json` | stdout に設定 JSON だけを出力するので、リダイレクトしてもバイト単位で正確です。`--out` の書き込み通知を含むすべての診断は stderr に出ます。 |
+| `--out <path>` | 設定を `<path>` に書きます。既存ファイルの置き換えは拒否します。 |
+| `--force` | `--out` が既存ファイルを置き換えることを許可します。 |
+
+```bash
+ocx export --client opencode                     # 設定に加えて宛先パス、マージ警告、件数
+ocx export --client pi --json > pi-models.json   # パイプや diff 用のバイト正確な JSON
+ocx export --client opencode --out ~/opencodex-opencode.json
+```
+
+`--json` なしでは JSON が先に出て、続いて正規の宛先パス、マージ警告、環境変数の export 行、モデル
+件数とコンテキスト上限を持たない行数 (それらはクライアント側の既定値が使われます) が出力されます。
+
+| クライアント | 正規の宛先 | ダウンロードファイル名 | 環境変数 |
+| --- | --- | --- | --- |
+| `opencode` | `~/.config/opencode/opencode.json` (`XDG_CONFIG_HOME` が設定されていればそちら) | `opencode.json` | `OPENCODEX_OPENCODE_API_KEY` |
+| `pi` | `~/.pi/agent/models.json` | `pi-models.json` | `OPENCODEX_API_KEY` |
+
+2 つの環境変数名は異なり、各クライアントは自分のものだけを解釈します。opencode は
+`{env:OPENCODEX_OPENCODE_API_KEY}`、Pi は `$OPENCODEX_API_KEY` を読みます。
+
+:::caution[置き換えではなくマージ]
+`ocx export` が実際のクライアント設定ファイルを書くことはありません。宛先パスは手動でマージする
+ために表示され、`--out` も `--force` なしでは既存ファイルを上書きしません。設定ファイルを丸ごと
+置き換えると、そこにあった他のプロバイダー、エージェント、MCP エントリが失われるからです。
+:::
+
+key が直列化されることはありません。設定にはクライアントの環境変数参照だけが入り、secret は環境に
+残ります。ループバックのプロキシ (既定の `127.0.0.1`) では admission key 自体が不要で、参照は使わ
+れません。プロキシをループバック外にバインドするときだけ変数を設定してください。admission key の
+発行方法は [リモートアクセス](/ja/reference/configuration/#リモートアクセス) を参照してください。
+上流プロバイダーの key はまったく別物で、[プロバイダー](/ja/guides/providers/) で設定します。Pi
+ガイドは英語のみです: [Pi](/guides/pi/)。
+
+同じペイロードを `GET /api/client-config` が返し、ダッシュボードの API タブが描画するので、CLI と
+API と GUI が異なるバイトを見せることはありません。
+
 ## 認証
 
 ### `ocx login <provider>`