fix(pi): keep loopback models visible

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

@@ -9,12 +9,15 @@ file, and removes it again. Six clients work this way, each with a switch:
 | Client | Config file | Format | When the change takes effect | Credential |
 |---|---|---|---|---|
 | OpenCode | `~/.config/opencode/opencode.json` | JSON | next direct launch | `OPENCODEX_OPENCODE_API_KEY` |
-| Pi | `~/.pi/agent/models.json` | JSON | new sessions | `OPENCODEX_API_KEY` |
+| Pi | `~/.pi/agent/models.json` | JSON | new sessions | non-secret `opencodex-loopback` placeholder |
 | Hermes | `~/.hermes/config.yaml` | YAML | new sessions | `OPENCODEX_HERMES_API_KEY` |
 | OpenClaw | `~/.openclaw/openclaw.json` | JSON5 | immediately, on a running gateway | `OPENCODEX_OPENCLAW_API_KEY` |
 | Kimi Code | `~/.kimi-code/config.toml` | TOML | on restart, or `/reload` | loopback placeholder |
 | Gajae Code | `~/.gjc/agent/models.yml` | YAML | new sessions, or when you open `/model` |`OPENCODEX_GAJAE_API_KEY` |
 
+Pi's loopback connection normally needs no real admission key. Configure credentials
+for upstream providers in opencodex, not in Pi's generated provider block.
+
 Paths honor each client's own environment override where it has one, so a relocated
 `HERMES_HOME`, `KIMI_CODE_HOME` or `XDG_CONFIG_HOME` is followed rather than guessed
 at. The table lists each client's default; an override always wins.

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

@@ -5,8 +5,7 @@ description: Use any routed model from Pi — ocx export writes a custom provide
 
 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.
+base URL, model list, and a non-secret literal `apiKey` placeholder — and you merge it into your own config.
 
 ## Quickstart
 
@@ -17,16 +16,19 @@ 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.
+The output leads with the JSON, then prints the destination path, the merge warning, Pi-specific
+pre-launch guidance, the total model count, and how many rows omit context limits.
+
+In Pi's schema, `openai-completions` names the Chat Completions-compatible API; the
+corresponding opencodex adapter name is `openai-chat`.
 
 ```json
 {
   "providers": {
     "opencodex": {
       "baseUrl": "http://127.0.0.1:10100/v1",
       "api": "openai-completions",
-      "apiKey": "$OPENCODEX_API_KEY",
+      "apiKey": "opencodex-loopback",
       "models": [
         {
           "id": "anthropic/claude-opus-5",
@@ -68,29 +70,19 @@ ocx export --client pi --json > ~/opencodex-pi-models.json   # or redirect the b
 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 Pi `apiKey` placeholder
 
-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>
-```
+Pi normally calls `/chat/completions` and sends its configured `apiKey` as a Bearer authorization
+value. The generated block therefore includes the non-secret literal `opencodex-loopback` in Pi's
+normal `apiKey` field.
 
-That name is Pi's alone. opencode uses a different variable
-(`OPENCODEX_OPENCODE_API_KEY`, in `{env:…}` form) — see the [opencode guide](/guides/opencode/).
+That literal is neither a proxy admission credential nor an upstream provider key. The loopback
+proxy ignores it and requires no credential at all. It is still load-bearing for discovery: Pi
+resolves `apiKey` while building its model list and hides the whole provider when the value is an
+unset env reference, so a literal keeps every routed model visible.
 
-**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).
+Your provider keys are separate — the Anthropic / OpenAI / OpenRouter key lives in opencodex's own
+config, per [Providers](/guides/providers/), and never appears in this file.
 
 ## Model metadata
 
@@ -109,10 +101,10 @@ 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
+:::note[Verified against a real install]
+The shape above has been verified against Pi 0.83.0 on a real `~/.pi/agent/models.json`: the block
+validates, and every exported routed model with a Pi-supported input modality appears in Pi's
+picker. If a newer 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.
 :::
 

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

@@ -3,7 +3,7 @@ title: 円周率
 description: Pi からルーティングされたモデルを使用します。ocx エクスポートは、実行中のプロキシに接続された Pi の models.json のカスタム プロバイダー ブロックを書き込みます。
 ---
 
-Pi は環境変数ではなく単一のグローバル JSON ファイルからプロバイダーを読み取るため、opencodex はそれを起動しません。代わりに、`ocx export` は `opencodex` プロバイダー ブロック (ベース URL、モデル リスト、Pi が補間する環境参照) をシリアル化し、それを独自の設定にマージします。
+Pi は環境変数ではなく単一のグローバル JSON ファイルからプロバイダーを読み取るため、opencodex はそれを起動しません。代わりに、`ocx export` は `opencodex` プロバイダー ブロック (ベース URL、モデル リスト、秘密ではないリテラル `apiKey` プレースホルダー) をシリアル化し、それを独自の設定にマージします。
 
 ## クイックスタート
 
@@ -14,15 +14,17 @@ ocx start
 ocx export --client pi
 ```
 
-出力は JSON で始まり、宛先パス、マージ警告、env エクスポート行、および権威コンテキスト制限を持つモデルの数を出力します。
+出力は JSON で始まり、宛先パス、マージ警告、Pi 固有の起動前ガイダンス、モデルの総数、およびコンテキスト制限を省略した行数を出力します。
+
+Pi スキーマの `openai-completions` は Chat Completions 互換 API を指し、対応する opencodex アダプター名は `openai-chat` です。
 
 ```json
 {
   "providers": {
     "opencodex": {
       "baseUrl": "http://127.0.0.1:10100/v1",
       "api": "openai-completions",
-      "apiKey": "$OPENCODEX_API_KEY",
+      "apiKey": "opencodex-loopback",
       "models": [
         {
           "id": "anthropic/claude-opus-5",
@@ -58,24 +60,13 @@ ocx export --client pi --json > ~/opencodex-pi-models.json   # or redirect the b
 
 エクスポートされたブロックは静的なスナップショットであり、ライブ ビューではありません。プロバイダーを追加するかモデルの可視性を変更した後、`ocx export` を再実行し、新しいブロックを古いブロックにマージします。
 
-## アドミッションキー
-
-ここでは 2 つの異なるキーが混同されやすいため、このファイルには最初のキーのみが表示されます。
-
-|キー |それは何ですか |それが住んでいる場所 |
-| --- | --- | --- |
-|プロキシ アドミッション キー | opencodex 自身の認証情報。ダッシュボードの **API** タブで生成されます。 `apiKey` では `$OPENCODEX_API_KEY` として参照されます。値は環境内に残ります。
-|プロバイダーキー | Anthropic / OpenAI / OpenRouter キー | opencodex 独自の設定、[プロバイダー](/guides/providers/) ごと |
+## Pi の `apiKey` プレースホルダー
 
-エクスポートされた設定には参照のみが含まれ、シークレットは含まれません。 Pi は裸の `$NAME` を補間するため、変数は次のようになります。
-
-```bash
-export OPENCODEX_API_KEY=<your key>
-```
+Pi は通常 `/chat/completions` を呼び出し、設定された `apiKey` を Bearer 認証値として送信します。そのため、生成されるブロックでは、Pi の通常の `apiKey` フィールドに非シークレットのリテラル `opencodex-loopback` を入れます。
 
-その名前はパイだけです。 opencode は別の変数 (`OPENCODEX_OPENCODE_API_KEY`、`{env:…}` 形式) を使用します。[オープンコードガイド](/guides/opencode/) を参照してください。
+このリテラルは、プロキシのアドミッション認証情報でも上流プロバイダーのキーでもありません。ループバック プロキシはこの値を無視し、認証情報を一切要求しません。ただしモデル検出には必須です。Pi はモデル リストを構築する際に `apiKey` を解決し、その値が未設定の環境変数参照である場合はプロバイダー全体を隠すため、リテラルであればルーティングされたすべてのモデルが表示されます。
 
-**ループバック プロキシにはキーはまったく必要ありません。** opencodex はデフォルトで `127.0.0.1` をバインドし、そこでは何も認証しないため、`$OPENCODEX_API_KEY` 参照は不活性であり、変数を設定しないままにすることができます。これは、`hostname` がループバックを超えて設定されている場合にのみ問題になります。これは、プロキシがトークンなしでの開始を拒否する場合でもあります。[リモートアクセス](/reference/configuration/#remote-access) を参照してください。
+プロバイダー キーは別のものです。Anthropic / OpenAI / OpenRouter のキーは opencodex 自身の設定にあり ([プロバイダー](/guides/providers/) を参照)、このファイルには決して現れません。
 
 ## モデルのメタデータ
 
@@ -87,8 +78,8 @@ export OPENCODEX_API_KEY=<your key>
 
 ## スキーマのステータス
 
-:::note[実際のインストールに対して未検証]
-上の形状は、Pi が公開しているカスタム プロバイダーのドキュメントに従っています。 Pi がインストールされたマシン上の実際の `~/.pi/agent/models.json` に対して検証されていません**。 Pi がエクスポートされたブロックを拒否した場合、不一致は私たちの側にあります。Pi が報告した内容を [問題を開く](https://github.com/lidge-jun/opencodex/issues) してください。
+:::note[実際のインストールで検証済み]
+上の形状は、Pi 0.83.0 がインストールされたマシン上の実際の `~/.pi/agent/models.json` に対して検証されています。ブロックは検証を通過し、Pi がサポートする入力モダリティを持つ、エクスポートされたすべてのルーティング モデルが Pi のピッカーに表示されます。より新しい Pi がエクスポートされたブロックを拒否した場合、不一致は私たちの側にあります。Pi が報告した内容を添えて [問題を開く](https://github.com/lidge-jun/opencodex/issues) してください。
 :::
 
 ## 要件

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

@@ -127,7 +127,7 @@ Grok Build モデル フェンスを管理および適用します。
 
 ### `ocx export --client <opencode|pi>`
 
-実行中のプロキシに接続されているクライアント設定を出力します。 opencode と [円周率](/guides/pi/) は環境変数ではなく独自の JSON 設定からプロバイダーを読み取るため、このコマンドは `opencodex` プロバイダー ブロック (ベース URL、モデル リスト、クライアントの環境参照) をシリアル化し、そのファイルにマージできるようにします。
+実行中のプロキシに接続されているクライアント設定を出力します。 opencode と [Pi](/guides/pi/) は環境変数ではなく独自の JSON 設定からプロバイダーを読み取るため、このコマンドは `opencodex` プロバイダー ブロック (ベース URL、モデル リスト、クライアント固有の認証情報参照またはループバック プレースホルダー) をシリアル化し、そのファイルにマージできるようにします。
 
 プロキシが実行されている必要があります。このコマンドはライブ ポートを解決し、`/api/models` を読み取り、Codex が現在認識できるモデルのみを出力します。
 
@@ -144,20 +144,20 @@ ocx export --client pi --json > pi-models.json   # byte-exact JSON for a pipe or
 ocx export --client opencode --out ~/opencodex-opencode.json
 ```
 
-`--json` がない場合、JSON が先頭に続き、正規の宛先パス、マージ警告、環境エクスポート行、およびコンテキスト制限を省略する行数を含むモデル数が続きます (クライアントはこれらに対して独自のデフォルトを適用します)。
+`--json` がない場合、JSON が先頭に続き、正規の宛先パス、マージ警告、クライアント固有の起動前ガイダンス、およびモデル数が続きます。モデルごとのコンテキスト制限を持つ形式では、それを省略した行数を表示します。セレクターのみを保存する形式では、コンテキスト制限が表現されないことを明示します。
 
 |クライアント |正規の宛先 |ダウンロードファイル名 |環境変数 |
 | --- | --- | --- | --- |
 | `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` |
+| `pi` | `~/.pi/agent/models.json` | `pi-models.json` | なし - ブロックにリテラル `opencodex-loopback` が入ります |
 
-2 つの環境変数名は異なり、各クライアントは独自の名前のみを補間します。 opencode は `{env:OPENCODEX_OPENCODE_API_KEY}` を読み取ります。 Pi は `$OPENCODEX_API_KEY` を読み取ります。
+opencode は `{env:OPENCODEX_OPENCODE_API_KEY}` を補間します。opencodex が生成する Pi のエクスポートには環境変数が不要で、リテラルのプレースホルダー `opencodex-loopback` が入ります。この値は必須です。Pi はモデル リストを構築する際に `apiKey` を解決し、既存の設定に未設定の環境変数参照がある場合はプロバイダー全体を隠すためです。ループバックでは、生成されたプレースホルダーをプロキシが検査することはありません。
 
 :::caution[マージし、決して置き換えないでください]
 `ocx export` は実際のクライアント設定を書き込むことはありません。宛先は手動でマージできるように出力されます。`--out` は、`--force` なしで既存のファイルを上書きすることを拒否します。これは、設定を置き換えると、その中にすでに含まれている他のプロバイダー、エージェント、および MCP エントリが破壊されるためです。
 :::
 
-キーはシリアル化されません。設定にはクライアントの環境参照のみが含まれるため、シークレットは環境内に残ります。ループバック プロキシ (`127.0.0.1`、デフォルト) にはアドミッション キーはまったく必要ありません。参照は単に使用されないだけです。プロキシがループバックを超えてバインドする場合にのみ変数を設定します。アドミッションキーの発行方法については、[リモートアクセス](/reference/configuration/#remote-access) を参照してください。上流プロバイダー自体のキーは完全に別のものであり、[プロバイダー](/guides/providers/) ごとに構成されます。
+キーはシリアル化されません。opencode の設定には環境参照のみが含まれるためシークレットは環境内に残り、Pi の設定には認証情報ではなくプレースホルダーが入ります。ループバック プロキシ (`127.0.0.1`、デフォルト) にはアドミッション キーはまったく必要ありません。opencode の変数は、プロキシがループバックを超えてバインドする場合にのみ設定します。アドミッションキーの発行方法については、[リモートアクセス](/reference/configuration/#remote-access) を参照してください。上流プロバイダー自体のキーは完全に別のものであり、[プロバイダー](/guides/providers/) ごとに構成されます。
 
 同じペイロードが `GET /api/client-config` によって提供され、ダッシュボードの [API] タブにレンダリングされるため、CLI、API、および GUI は同じバイトを使用します。