docs: document bring-your-own API key setup

README.ja.md

@@ -204,9 +204,22 @@ devo resume <session-id>
 
 ## 設定
 
-`devo onboard` が推奨されるセットアップ方法です。手動の `config.toml`
-パス、provider/model binding フィールド、カスタムモデルカタログの例は
-[設定](./docs/configuration.ja.md) を参照してください。
+`devo onboard` が推奨されるセットアップ方法です。provider/model binding を
+`config.toml` に書き、API key をユーザースコープの `auth.json` に保存します。
+
+自分の API key とカスタムモデルを手動で設定する場合:
+
+1. `config.toml` で `[model.<slug>]` パラメータ、`[providers.<id>]`、
+   `[model_bindings.<id>]` を定義します。
+2. シークレットを `DEVO_HOME/auth.json` に置き、`[providers.<id>].credential`
+   からその credential id を参照します — API key 自体を `config.toml` に
+   書かないでください。
+3. エンドポイントのプロトコルに合わせて `invocation_method` を
+   `openai_chat_completions`、`openai_responses`、`anthropic_messages` の
+   いずれかに設定します。
+
+完全な作業例（カスタムモデルパラメータ + API key）とプロトコルの説明は
+[設定](./docs/configuration.ja.md#自分の-api-key-を使う) を参照してください。
 
 ## Docs
 
@@ -226,6 +239,12 @@ Devo は pre-1.0 で、活発に開発されています。ローカル評価、
 OpenAI 互換 Chat Completions、OpenAI 互換 Responses、または Anthropic Messages API をサポートするモデルエンドポイントであれば、
 provider/model binding を通じて接続できます。
 
+### 自分の API key を使うには?
+
+`devo onboard` を使うか、ユーザースコープの `auth.json` を編集し、
+`config.toml` の `[providers.<id>].credential` からその credential id を参照します。
+詳細は [設定](./docs/configuration.ja.md#自分の-api-key-を使う) を参照してください。
+
 ### Desktop app と TUI/CLI のどちらを使うべきですか?
 
 視覚的なオンボーディング、セッション閲覧、グラフィカルな coding workspace が

README.md

@@ -213,9 +213,21 @@ devo resume <session-id>
 
 ## Configuration
 
-`devo onboard` is the recommended setup path. For manual `config.toml` paths,
-provider/model binding fields, and custom model catalog examples, see
-[Configuration](./docs/configuration.md).
+`devo onboard` is the recommended setup path. It writes provider and model
+bindings to `config.toml` and stores your API key in user-scoped `auth.json`.
+
+To bring your own key with a custom model manually:
+
+1. Define `[model.<slug>]` parameters, `[providers.<id>]`, and
+   `[model_bindings.<id>]` in `config.toml`.
+2. Put the secret in `DEVO_HOME/auth.json` and reference that credential id from
+   `[providers.<id>].credential` — never put the API key itself in
+   `config.toml`.
+3. Set `invocation_method` to match the endpoint protocol:
+   `openai_chat_completions`, `openai_responses`, or `anthropic_messages`.
+
+Full worked example (custom model parameters + API key) and protocol details:
+[Configuration](./docs/configuration.md#bring-your-own-api-key).
 
 ## Docs
 
@@ -237,6 +249,14 @@ families. Any model endpoint that supports OpenAI-compatible Chat Completions,
 OpenAI-compatible Responses, or the Anthropic Messages API can be connected through
 provider/model bindings.
 
+### How do I bring my own API key?
+
+Use `devo onboard`, or manually define a custom `[model.<slug>]`, provider, and
+binding in `config.toml`, store the key in user-scoped `auth.json`, and set
+`invocation_method` to `openai_chat_completions`, `openai_responses`, or
+`anthropic_messages`. See
+[Configuration](./docs/configuration.md#bring-your-own-api-key).
+
 ### Should I use the Desktop app or the TUI/CLI?
 
 Use the Desktop app when you want visual onboarding, session browsing, and a

README.ru.md

@@ -217,9 +217,20 @@ devo resume <session-id>
 
 ## Конфигурация
 
-`devo onboard` - рекомендуемый путь настройки. Пути ручного `config.toml`,
-поля provider/model binding и примеры custom model catalog описаны в
-[Конфигурации](./docs/configuration.ru.md).
+`devo onboard` - рекомендуемый путь настройки. Он записывает provider и model
+bindings в `config.toml` и сохраняет API key в пользовательском `auth.json`.
+
+Чтобы вручную подключить свой ключ и кастомную модель:
+
+1. Определите параметры `[model.<slug>]`, `[providers.<id>]` и
+   `[model_bindings.<id>]` в `config.toml`.
+2. Положите секрет в `DEVO_HOME/auth.json` и ссылайтесь на этот credential id из
+   `[providers.<id>].credential` — не пишите сам API key в `config.toml`.
+3. Установите `invocation_method` в соответствии с протоколом endpoint:
+   `openai_chat_completions`, `openai_responses` или `anthropic_messages`.
+
+Полный пример (параметры кастомной модели + API key) и описание протоколов:
+[Конфигурация](./docs/configuration.ru.md#свой-api-key).
 
 ## Docs
 
@@ -241,6 +252,12 @@ GLM и DeepSeek. Любой endpoint модели, который поддерж
 Chat Completions, OpenAI-compatible Responses или Anthropic Messages API, можно
 подключить через provider/model bindings.
 
+### Как подключить свой API key?
+
+Используйте `devo onboard` или отредактируйте пользовательский `auth.json` и
+укажите этот credential id в `[providers.<id>].credential` в `config.toml`. См.
+[Конфигурацию](./docs/configuration.ru.md#свой-api-key).
+
 ### Что выбрать: Desktop app или TUI/CLI?
 
 Используйте Desktop app, если вам нужны visual onboarding, просмотр сессий и

README.zh-Hans.md

@@ -195,9 +195,20 @@ devo resume <session-id>
 
 ## 配置
 
-`devo onboard` 是推荐的设置路径。如需手动 `config.toml` 路径、
-provider/model 绑定字段和自定义模型目录示例，请参阅
-[配置](./docs/configuration.zh-Hans.md)。
+`devo onboard` 是推荐的设置路径。它会把 provider 和 model binding 写入
+`config.toml`，并把 API key 保存在用户级 `auth.json`。
+
+如需手动接入自有 API key 与自定义模型：
+
+1. 在 `config.toml` 中定义 `[model.<slug>]` 参数、`[providers.<id>]` 和
+   `[model_bindings.<id>]`。
+2. 把密钥写入 `DEVO_HOME/auth.json`，并在 `[providers.<id>].credential` 中引用该
+   credential id — 不要把 API key 本身写进 `config.toml`。
+3. 将 `invocation_method` 设为与端点协议一致：`openai_chat_completions`、
+   `openai_responses` 或 `anthropic_messages`。
+
+完整示例（自定义模型参数 + API key）与协议说明见
+[配置](./docs/configuration.zh-Hans.md#接入自有-api-key)。
 
 ## Docs
 
@@ -217,6 +228,13 @@ Devo 仍处于 1.0 之前并在积极开发中。它已经适合本地评估、
 任何支持 OpenAI 兼容 Chat Completions、OpenAI 兼容 Responses 或
 Anthropic Messages API 的模型端点，都可以通过 provider/model 绑定接入。
 
+### 如何接入自有 API key？
+
+使用 `devo onboard`，或在 `config.toml` 中手动定义自定义 `[model.<slug>]`、
+provider 与 binding，把 key 存入用户级 `auth.json`，并将 `invocation_method`
+设为 `openai_chat_completions`、`openai_responses` 或 `anthropic_messages`。详见
+[配置](./docs/configuration.zh-Hans.md#接入自有-api-key)。
+
 ### 应该使用 Desktop app 还是 TUI/CLI？
 
 如果你需要可视化上手、会话浏览和图形化 coding workspace，请使用 Desktop app。

README.zh-Hant.md

@@ -195,9 +195,20 @@ devo resume <session-id>
 
 ## 配置
 
-`devo onboard` 是推薦的設定路徑。如需手動 `config.toml` 路徑、
-provider/model 綁定欄位和自訂模型目錄範例，請參閱
-[配置](./docs/configuration.zh-Hant.md)。
+`devo onboard` 是推薦的設定路徑。它會把 provider 和 model binding 寫入
+`config.toml`，並把 API key 保存在使用者級 `auth.json`。
+
+如需手動接入自有 API key 與自訂模型：
+
+1. 在 `config.toml` 中定義 `[model.<slug>]` 參數、`[providers.<id>]` 和
+   `[model_bindings.<id>]`。
+2. 把密鑰寫入 `DEVO_HOME/auth.json`，並在 `[providers.<id>].credential` 中引用該
+   credential id — 不要把 API key 本身寫進 `config.toml`。
+3. 將 `invocation_method` 設為與端點協議一致：`openai_chat_completions`、
+   `openai_responses` 或 `anthropic_messages`。
+
+完整範例（自訂模型參數 + API key）與協議說明見
+[配置](./docs/configuration.zh-Hant.md#接入自有-api-key)。
 
 ## Docs
 
@@ -217,6 +228,13 @@ Devo 仍處於 1.0 之前並在積極開發中。它已經適合本地評估、
 任何支援 OpenAI 相容 Chat Completions、OpenAI 相容 Responses 或
 Anthropic Messages API 的模型端點，都可以透過 provider/model 綁定接入。
 
+### 如何接入自有 API key？
+
+使用 `devo onboard`，或在 `config.toml` 中手動定義自訂 `[model.<slug>]`、
+provider 與 binding，把 key 存入使用者級 `auth.json`，並將 `invocation_method`
+設為 `openai_chat_completions`、`openai_responses` 或 `anthropic_messages`。詳見
+[配置](./docs/configuration.zh-Hant.md#接入自有-api-key)。
+
 ### 應該使用 Desktop app 還是 TUI/CLI？
 
 如果你需要可視化上手、會話瀏覽和圖形化 coding workspace，請使用 Desktop app。