diff --git a/README.ja.md b/README.ja.md
index c55d0115..067dff84 100644
--- a/README.ja.md
+++ b/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 が
diff --git a/README.md b/README.md
index 99417e77..5d6ca4b2 100644
--- a/README.md
+++ b/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
diff --git a/README.ru.md b/README.ru.md
index 3005abd7..e32bab36 100644
--- a/README.ru.md
+++ b/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, просмотр сессий и
diff --git a/README.zh-Hans.md b/README.zh-Hans.md
index 0dbe9061..2a0abd43 100644
--- a/README.zh-Hans.md
+++ b/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。
diff --git a/README.zh-Hant.md b/README.zh-Hant.md
index 97d29e40..40cb3d19 100644
--- a/README.zh-Hant.md
+++ b/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。
diff --git a/docs/configuration.ja.md b/docs/configuration.ja.md
index 62018b2e..45d70cc1 100644
--- a/docs/configuration.ja.md
+++ b/docs/configuration.ja.md
@@ -13,7 +13,7 @@
 認証情報は `DEVO_HOME/auth.json` に分離して保存されます。
 `config.toml` には API key を直接保存せず、credential id を参照させてください。
 
-最小構成:
+最小構成（組み込みモデル + provider バインディング）:
 
 ```toml
 [defaults]
@@ -41,103 +41,168 @@ default_reasoning_effort = "high"
 - `model_slug` は slug で Devo のローカルモデルメタデータを選択します。
 - binding の `provider` は `[providers.<id>]` 接続レコードを選択します。
 - `request_model` はプロバイダーへ送信されるモデル id です。
-- `invocation_method` は実際に使うプロバイダープロトコルを選択します。例:
-  [`openai_chat_completions`](https://developers.openai.com/api/reference/chat-completions/overview)、
-  [`openai_responses`](https://developers.openai.com/api/reference/responses/overview)、
-  [`anthropic_messages`](https://platform.claude.com/docs/en/api/messages)。
+- `invocation_method` は実際に使うプロバイダープロトコルを選択します。詳細は
+  [呼び出し方式（Invocation methods）](#呼び出し方式invocation-methods) を参照してください。
 
 モデルメタデータにも `provider` フィールドがあり、モデルが期待する wire API を
 表します。binding の `invocation_method` は実行時の接続方法を選ぶため、両者を一致
 させてください。API key は引き続き `auth.json` に保存し、provider の `credential`
 参照で接続します。
 
-## モデルメタデータとカスタムモデル
+既存の `model_name` 設定は引き続き読み取れます。次回その binding を保存すると、
+Devo は `request_model` として書き出します。
 
-ユーザーまたは workspace の `config.toml` の `[model.<slug>]` で設定します。
-組み込み slug は部分上書きで、省略したフィールドは組み込み値を保持します。新しい
-slug は安全なデフォルトを持つカスタムモデルを作成し、`[providers.<id>]` と
-`[model_bindings.<id>]` の両方で接続します。
+## 自分の API key を使う
 
-組み込みモデルの部分上書き例:
+Devo は API key を `config.toml` に保存しません。自分の key を使う場合:
 
-```toml
-[model.qwen3-coder-next]
-context_window = 262144
-effective_context_window_percent = 90
-```
+1. シークレットをユーザースコープの `DEVO_HOME/auth.json` に保存します。
+2. `config.toml` の `[providers.<id>].credential` からその credential id を参照します。
 
-有効なコンテキストウィンドウの正確な式は
-`context_window * effective_context_window_percent / 100` です。その結果がモデルで
-利用可能なコンテキストであり、自動 compaction の境界でもあります。完全な例:
+`devo onboard` と Desktop/TUI の provider フローが両ファイルを書き込みます。
+
+### エンドツーエンド例: カスタムモデルパラメータ + 自分の API key
+
+次の例は、カスタム DeepSeek モデル（Anthropic Messages）、provider
+エンドポイント、および `auth.json` のみに置く credential を組み合わせます。
+
+`~/.devo/config.toml`（Windows では `C:\Users\yourname\.devo\config.toml`）:
 
 ```toml
 [defaults]
-model_binding = "my-coding-model-example"
+model_binding = "deepseek-example"
 
-[model.my-coding-model]
-display_name = "My Coding Model"
-description = "Custom OpenAI-compatible coding model."
+[model.my-deepseek]
+display_name = "DeepSeek V4 Flash"
+description = "Custom Anthropic Messages coding model for DeepSeek."
 channel = "Custom"
-provider = "openai_chat_completions"
+# このモデルが期待する wire API。binding の invocation_method と一致させる。
+provider = "anthropic_messages"
 context_window = 200000
 effective_context_window_percent = 95
-max_tokens = 4096
+max_tokens = 8192
 temperature = 0.2
-top_p = 0.9
-top_k = 40.0
-reasoning_capability = { levels = ["low", "medium", "high"] }
+reasoning_capability = { togglewithlevels = ["high", "max"] }
 reasoning_implementation = "request_parameter"
-default_reasoning_effort = "medium"
-base_instructions = "You are Devo, a coding agent."
+base_instructions = "(optional) You are Devo, a coding agent."
 input_modalities = ["text", "image"]
-truncation_policy = { mode = "tokens", limit = 12000 }
-supports_image_detail_original = true
 
-[providers.my-provider]
+[providers.deepseek]
 enabled = true
-name = "My Provider"
-base_url = "https://api.example.com/v1"
-credential = "my_provider_api_key"
-wire_apis = ["openai_chat_completions"]
+name = "DeepSeek Anthropic Compatible"
+base_url = "https://api.deepseek.com/anthropic"
+# credential id のみ — シークレットは auth.json に置く。
+credential = "deepseek_compatible_api_key"
+wire_apis = ["anthropic_messages"]
 
-[model_bindings.my-coding-model-example]
+[model_bindings.deepseek-example]
 enabled = true
-model_slug = "my-coding-model"
-provider = "my-provider"
-request_model = "provider-specific-model-name"
-display_name = "My Coding Model"
-invocation_method = "openai_chat_completions"
+model_slug = "my-deepseek"
+provider = "deepseek"
+request_model = "deepseek-v4-flash"
+display_name = "DeepSeek V4 Flash"
+invocation_method = "anthropic_messages"
+```
+
+対応する `~/.devo/auth.json`（Windows では `C:\Users\yourname\.devo\auth.json`）:
+
+```json
+{
+  "version": 1,
+  "credentials": {
+    "deepseek_compatible_api_key": {
+      "kind": "api_key",
+      "value": "sk-deepseek-your-api-key"
+    }
+  }
+}
 ```
 
-設定可能なメタデータには、picker に表示するモデル名 `display_name`、ユーザー向け
-説明文 `description`、モデルのグループラベル `channel` があります。
-`context_window` と `effective_context_window_percent` は有効なコンテキストを決め、
-`max_tokens` は既定の response output 上限です。sampling の既定値では、
-`temperature` がランダム性、`top_p` が nucleus probability mass、`top_k` が候補 token
-数の上限を制御します。`provider` wire API は `openai_chat_completions`、
-`openai_responses`、`anthropic_messages` のいずれかです。
-reasoning メタデータは型付きです。`reasoning_capability` は `unsupported`、
-`toggle`、`{ levels = [...] }`、`{ togglewithlevels = [...] }`、
+ルール:
+
+- 現時点でサポートされるのは `api_key` 認証情報のみです。
+- credential id は `[providers.<id>].credential` と完全に一致する必要があります。
+- `auth.json` は `DEVO_HOME` 配下に置き、プロジェクトリポジトリへコミットしないでください。
+- ワークスペース `<workspace>/.devo/config.toml` は credential id を参照できますが、
+  シークレット値はユーザースコープの `auth.json` にのみ置きます。
+- key だけ更新する場合は `auth.json` を編集します。credential id が同じなら
+  `config.toml` は変更不要です。
+
+## 呼び出し方式（Invocation methods）
+
+binding の `invocation_method` と provider の `wire_apis` が、Devo が使う HTTP API
+を決めます。モデルメタデータの `provider` も同じ値にして、カタログ能力と実行時接続を
+揃えてください。
+
+| 値 | プロトコル | 典型的なエンドポイント |
+| --- | --- | --- |
+| `openai_chat_completions` | [OpenAI Chat Completions](https://developers.openai.com/api/reference/chat-completions/overview) | 多くの OpenAI 互換ゲートウェイ（DeepSeek、Qwen、Kimi、OpenRouter、ローカルプロキシなど） |
+| `openai_responses` | [OpenAI Responses](https://developers.openai.com/api/reference/responses/overview) | Responses API を提供するサービス |
+| `anthropic_messages` | [Anthropic Messages](https://platform.claude.com/docs/en/api/messages) | Anthropic 互換 Messages エンドポイント |
+
+## モデルメタデータとカスタムモデル
+
+ユーザーまたは workspace の `config.toml` の `[model.<slug>]` で設定します。
+組み込み slug は部分上書きで、省略したフィールドは組み込み値を保持します。新しい
+slug は安全なデフォルトを持つカスタムモデルを作成し、
+[エンドツーエンド例](#エンドツーエンド例-カスタムモデルパラメータ--自分の-api-key)
+のように `[providers.<id>]` と `[model_bindings.<id>]` で接続します。
+
+組み込みモデルの部分上書き例:
+
+```toml
+[model.qwen3-coder-next]
+context_window = 262144
+effective_context_window_percent = 90
+```
+
+有効なコンテキストウィンドウの正確な式は
+`context_window * effective_context_window_percent / 100` です。その結果がモデルで
+利用可能なコンテキストであり、自動 compaction の境界でもあります。
+
+設定可能なメタデータには、ピッカー向けの `display_name`、説明文の `description`、
+グループ用の `channel` があります。`context_window` と
+`effective_context_window_percent` が有効コンテキストを決め、`max_tokens` は既定の
+出力上限です。サンプリング既定値は `temperature`（乱数性）、`top_p`（核サンプリング）、
+`top_k`（候補トークン上限）です。`provider` wire API は
+`openai_chat_completions`、`openai_responses`、`anthropic_messages` のいずれかです。
+推論メタデータは型付きで、`reasoning_capability` は `unsupported`、`toggle`、
+`{ levels = [...] }`、`{ togglewithlevels = [...] }`、
 `reasoning_implementation` は `disabled`、`request_parameter`、または型付き
-`model_variant` table です。model variant は同じモデルの request parameter を変える
-代わりに、論理 reasoning selection を別の provider-facing model id、任意の effective
-effort、任意の extra request body に対応付けます。`default_reasoning_effort` は既定の
-effort を表します。`input_modalities` は `text` と `image`、`truncation_policy` は
-大きすぎる tool result を model request に含める前に切り詰める byte または token
-上限、`supports_image_detail_original` は original image detail を制御します。
+`model_variant` テーブルです。`model_variant` は論理的な推論選択を別の
+provider 向けモデル id、任意の有効 effort、任意の追加リクエスト本文へ写像します。
+`default_reasoning_effort` は既定の effort を選びます。`input_modalities` は
+`text` と `image` を受け付け、`truncation_policy` は大きすぎるツール結果の
+バイト/トークン上限を選び、`supports_image_detail_original` は元解像度の画像詳細を
+有効にします。
+
+`base_instructions` を省略すると、組み込みモデルは組み込み指示を、カスタムモデルは
+Devo の既定指示を使います。明示的な空文字（`base_instructions = ""`）は指示なしを
+意味します。
 
-`base_instructions` を省略すると、組み込みモデルは組み込み値を保持し、カスタム
-モデルは Devo のデフォルトを使います。明示的な空文字列
-（`base_instructions = ""`）は base instructions なしを意味します。
+レガシーのスカラー `model = "slug"` は引き続き読み取れます。`[model.<slug>]` が
+トップレベル `model` テーブル名前空間を占有するため、新しい設定では
+`[defaults].model_binding` でアクティブ接続を選んでください。
+
+### TUI 設定
+
+`DEVO_HOME/config.toml` のトップレベルには UI 設定も保存されます:
+
+```toml
+theme = "aurora"
+collapse_reasoning = true
+```
 
-従来の `model = "slug"` scalar は引き続き読み取れます。ただし
-`[model.<slug>]` がトップレベルの `model` table namespace を使うため、新しい設定は
-`[defaults].model_binding` で有効な接続を選択してください。
+- `theme` は TUI の配色テーマを選びます（`/theme` でも設定可）。
+- `collapse_reasoning` は推論表示を制御します（`/show-reasoning` でも設定可）:
+  - `true`（既定）: ストリーミング中は最新 3 行のみ。完了後は短い推論を全文表示し、
+    長い推論は 1 行の `Thought · …` 要約に折りたたみます（全文は Ctrl+T で確認可）。
+  - `false`: ストリーミング中も完了後も全文を表示します。
 
 ### `models.json` からの移行
 
 古い `~/.devo/models.json` と `<workspace>/.devo/models.json` は無視されます。
 必要なフィールドをユーザーまたは workspace の `config.toml` の
-`[model.<slug>]` に手動でコピーし、対応する provider と model binding を追加または
-保持してください。API key は `auth.json` に置き、`[providers.<id>].credential` から
-参照します。
+`[model.<slug>]` へ手動でコピーし、対応する provider と model binding を追加または
+保持してください。API key は `auth.json` に置き、`[providers.<id>].credential`
+から参照します。
diff --git a/docs/configuration.md b/docs/configuration.md
index 9f40df20..a7f13c6c 100644
--- a/docs/configuration.md
+++ b/docs/configuration.md
@@ -14,7 +14,7 @@ merges settings in this order:
 Credentials live separately in `DEVO_HOME/auth.json`; `config.toml` should refer
 to credential ids instead of storing API keys directly.
 
-Minimal shape:
+Minimal shape (built-in model + provider binding):
 
 ```toml
 [defaults]
@@ -42,10 +42,8 @@ The important separation is:
 - `model_slug` selects Devo's local model metadata by slug.
 - The binding's `provider` selects a `[providers.<id>]` connection record.
 - `request_model` is the provider-facing model id sent on the wire.
-- `invocation_method` selects the operational provider protocol, such as
-  [`openai_chat_completions`](https://developers.openai.com/api/reference/chat-completions/overview),
-  [`openai_responses`](https://developers.openai.com/api/reference/responses/overview),
-  or [`anthropic_messages`](https://platform.claude.com/docs/en/api/messages).
+- `invocation_method` selects the operational provider protocol. See
+  [Invocation methods](#invocation-methods).
 
 Model metadata also has a `provider` field. It describes the wire API the model
 expects, while the binding's `invocation_method` chooses the connection used at
@@ -55,66 +53,118 @@ connected through the provider's `credential` reference.
 Existing configuration using `model_name` remains readable. Devo writes the
 field as `request_model` the next time that binding is saved.
 
-## Model Metadata and Custom Models
+## Bring Your Own API Key
 
-Configure model metadata in user or workspace `config.toml` under
-`[model.<slug>]`. A section for a built-in slug is a partial override: omitted
-fields retain their built-in values. A new slug creates a custom model with safe
-defaults, which should then be connected through both `[providers.<id>]` and
-`[model_bindings.<id>]`.
+Devo does not store API keys in `config.toml`. When you bring your own key:
 
-For example, this changes only the built-in context window:
+1. Store the secret in user-scoped `DEVO_HOME/auth.json`.
+2. Point `[providers.<id>].credential` at that credential id from
+   `config.toml`.
 
-```toml
-[model.qwen3-coder-next]
-context_window = 262144
-effective_context_window_percent = 90
-```
+`devo onboard` and the Desktop/TUI provider flows write both files for you.
 
-The exact effective context formula is
-`context_window * effective_context_window_percent / 100`; the result is the
-context available to the model and the automatic-compaction boundary. For a
-custom model and connection:
+### End-to-end example: custom model + your API key
+
+The following pairs a custom DeepSeek model (Anthropic Messages), a provider
+endpoint, and a credential stored only in `auth.json`.
+
+`~/.devo/config.toml` (or `C:\Users\yourname\.devo\config.toml` on Windows):
 
 ```toml
 [defaults]
-model_binding = "my-coding-model-example"
+model_binding = "deepseek-example"
 
-[model.my-coding-model]
-display_name = "My Coding Model"
-description = "Custom OpenAI-compatible coding model."
+[model.my-deepseek]
+display_name = "DeepSeek V4 Flash"
+description = "Custom Anthropic Messages coding model for DeepSeek."
 channel = "Custom"
-provider = "openai_chat_completions"
+# Wire API this model expects. Must match the binding's invocation_method.
+provider = "anthropic_messages"
 context_window = 200000
 effective_context_window_percent = 95
-max_tokens = 4096
+max_tokens = 8192
 temperature = 0.2
-top_p = 0.9
-top_k = 40.0
-reasoning_capability = { levels = ["low", "medium", "high"] }
+reasoning_capability = { togglewithlevels = ["high", "max"] }
 reasoning_implementation = "request_parameter"
-default_reasoning_effort = "medium"
-base_instructions = "You are Devo, a coding agent. Help the user edit and understand code."
-input_modalities = ["text", "image"]
-truncation_policy = { mode = "tokens", limit = 12000 }
-supports_image_detail_original = true
+base_instructions = "(optional) You are Devo, a coding agent."
+input_modalities = ["text"]
+# For multimodalities
+# input_modalities = ["text", "image"] ...
 
-[providers.my-provider]
+[providers.deepseek]
 enabled = true
-name = "My Provider"
-base_url = "https://api.example.com/v1"
-credential = "my_provider_api_key"
-wire_apis = ["openai_chat_completions"]
+name = "DeepSeek Anthropic Compatible"
+base_url = "https://api.deepseek.com/anthropic"
+# Credential id only — the secret lives in auth.json.
+credential = "deepseek_compatible_api_key"
+wire_apis = ["anthropic_messages"]
 
-[model_bindings.my-coding-model-example]
+[model_bindings.deepseek-example]
 enabled = true
-model_slug = "my-coding-model"
-provider = "my-provider"
-request_model = "provider-specific-model-name"
-display_name = "My Coding Model"
-invocation_method = "openai_chat_completions"
+model_slug = "my-deepseek"
+provider = "deepseek"
+request_model = "deepseek-v4-flash"
+display_name = "DeepSeek V4 Flash"
+invocation_method = "anthropic_messages"
 ```
 
+Matching `~/.devo/auth.json` (or `C:\Users\yourname\.devo\auth.json`):
+
+```json
+{
+  "version": 1,
+  "credentials": {
+    "deepseek_compatible_api_key": {
+      "kind": "api_key",
+      "value": "sk-deepseek-your-api-key"
+    }
+  }
+}
+```
+
+Rules:
+
+- Only `api_key` credentials are supported today.
+- The credential id must match `[providers.<id>].credential` exactly.
+- Keep `auth.json` under `DEVO_HOME`. Do not commit it to a project repo.
+- Workspace `<workspace>/.devo/config.toml` may reference credential ids, but
+  secret values stay in user-scoped `auth.json`.
+- Updating only the key means editing `auth.json`; leave `config.toml`
+  unchanged when the credential id stays the same.
+
+## Invocation methods
+
+`invocation_method` (on a model binding) and `wire_apis` (on a provider) select
+which HTTP API Devo uses for that connection. Model metadata `provider` should
+use the same value so catalog capabilities match the runtime connection.
+
+| Value | Protocol | Typical endpoints |
+| --- | --- | --- |
+| `openai_chat_completions` | [OpenAI Chat Completions](https://developers.openai.com/api/reference/chat-completions/overview) | Most OpenAI-compatible gateways (DeepSeek, Qwen, Kimi, OpenRouter, many local proxies) |
+| `openai_responses` | [OpenAI Responses](https://developers.openai.com/api/reference/responses/overview) | Providers that expose the Responses API |
+| `anthropic_messages` | [Anthropic Messages](https://platform.claude.com/docs/en/api/messages) | Anthropic-compatible Messages endpoints |
+
+## Model Metadata and Custom Models
+
+Configure model metadata in user or workspace `config.toml` under
+`[model.<slug>]`. A section for a built-in slug is a partial override: omitted
+fields retain their built-in values. A new slug creates a custom model with safe
+defaults, which should then be connected through both `[providers.<id>]` and
+`[model_bindings.<id>]` as in the
+[end-to-end example](#end-to-end-example-custom-model--your-api-key).
+
+For example, this changes only the built-in context window:
+
+```toml
+[model.qwen3-coder-next]
+context_window = 262144
+effective_context_window_percent = 90
+```
+
+The exact effective context formula is
+`context_window * effective_context_window_percent / 100`; the result is the
+context available to the model and the automatic-compaction boundary.
+
 Configurable metadata includes `display_name`, the picker-facing model name;
 `description`, explanatory text shown to users; and `channel`, the grouping
 label used to organize models. `context_window` and
diff --git a/docs/configuration.ru.md b/docs/configuration.ru.md
index 28775b83..0cd7fb6f 100644
--- a/docs/configuration.ru.md
+++ b/docs/configuration.ru.md
@@ -15,7 +15,7 @@
 Учетные данные хранятся отдельно в `DEVO_HOME/auth.json`; `config.toml` должен
 ссылаться на credential id, а не хранить API key напрямую.
 
-Минимальная структура:
+Минимальная структура (встроенная модель + provider binding):
 
 ```toml
 [defaults]
@@ -43,23 +43,114 @@ default_reasoning_effort = "high"
 - `model_slug` выбирает локальные метаданные модели Devo по slug.
 - `provider` в binding выбирает запись подключения `[providers.<id>]`.
 - `request_model` - id модели, отправляемый поставщику.
-- `invocation_method` выбирает рабочий протокол поставщика, например
-  [`openai_chat_completions`](https://developers.openai.com/api/reference/chat-completions/overview),
-  [`openai_responses`](https://developers.openai.com/api/reference/responses/overview)
-  или [`anthropic_messages`](https://platform.claude.com/docs/en/api/messages).
+- `invocation_method` выбирает рабочий протокол поставщика. См.
+  [Методы вызова (Invocation methods)](#методы-вызова-invocation-methods).
 
 В метаданных модели тоже есть поле `provider`: оно описывает wire API модели.
 `invocation_method` в binding выбирает рабочее подключение; эти значения должны
 соответствовать друг другу. API key остается в `auth.json` и подключается через
 ссылку `credential` поставщика.
 
+Существующая конфигурация с `model_name` по-прежнему читается. При следующем
+сохранении binding Devo запишет поле как `request_model`.
+
+## Свой API key
+
+Devo не хранит API key в `config.toml`. Чтобы подключить свой ключ:
+
+1. Сохраните секрет в пользовательском `DEVO_HOME/auth.json`.
+2. Укажите этот credential id в `[providers.<id>].credential` в `config.toml`.
+
+`devo onboard` и потоки provider в Desktop/TUI записывают оба файла за вас.
+
+### Полный пример: кастомная модель + свой API key
+
+Ниже вместе настраиваются кастомная модель DeepSeek (Anthropic Messages),
+endpoint поставщика и credential, который хранится только в `auth.json`.
+
+`~/.devo/config.toml` (на Windows: `C:\Users\yourname\.devo\config.toml`):
+
+```toml
+[defaults]
+model_binding = "deepseek-example"
+
+[model.my-deepseek]
+display_name = "DeepSeek V4 Flash"
+description = "Custom Anthropic Messages coding model for DeepSeek."
+channel = "Custom"
+# Wire API, который ожидает модель. Должен совпадать с invocation_method binding.
+provider = "anthropic_messages"
+context_window = 200000
+effective_context_window_percent = 95
+max_tokens = 8192
+temperature = 0.2
+reasoning_capability = { togglewithlevels = ["high", "max"] }
+reasoning_implementation = "request_parameter"
+base_instructions = "(optional) You are Devo, a coding agent."
+input_modalities = ["text", "image"]
+
+[providers.deepseek]
+enabled = true
+name = "DeepSeek Anthropic Compatible"
+base_url = "https://api.deepseek.com/anthropic"
+# Только credential id — секрет лежит в auth.json.
+credential = "deepseek_compatible_api_key"
+wire_apis = ["anthropic_messages"]
+
+[model_bindings.deepseek-example]
+enabled = true
+model_slug = "my-deepseek"
+provider = "deepseek"
+request_model = "deepseek-v4-flash"
+display_name = "DeepSeek V4 Flash"
+invocation_method = "anthropic_messages"
+```
+
+Соответствующий `~/.devo/auth.json` (на Windows:
+`C:\Users\yourname\.devo\auth.json`):
+
+```json
+{
+  "version": 1,
+  "credentials": {
+    "deepseek_compatible_api_key": {
+      "kind": "api_key",
+      "value": "sk-deepseek-your-api-key"
+    }
+  }
+}
+```
+
+Правила:
+
+- Сейчас поддерживаются только credentials вида `api_key`.
+- Credential id должен точно совпадать с `[providers.<id>].credential`.
+- Храните `auth.json` в `DEVO_HOME`. Не коммитьте его в репозиторий проекта.
+- Workspace `<workspace>/.devo/config.toml` может ссылаться на credential id, но
+  значения секретов остаются только в пользовательском `auth.json`.
+- Чтобы обновить только ключ, правьте `auth.json`; при том же credential id
+  `config.toml` менять не нужно.
+
+## Методы вызова (Invocation methods)
+
+`invocation_method` на model binding и `wire_apis` на provider выбирают, какой
+HTTP API использует Devo. Поле `provider` в метаданных модели должно совпадать,
+чтобы возможности каталога соответствовали рабочему подключению.
+
+| Значение | Протокол | Типичные endpoints |
+| --- | --- | --- |
+| `openai_chat_completions` | [OpenAI Chat Completions](https://developers.openai.com/api/reference/chat-completions/overview) | Большинство OpenAI-совместимых шлюзов (DeepSeek, Qwen, Kimi, OpenRouter, многие локальные прокси) |
+| `openai_responses` | [OpenAI Responses](https://developers.openai.com/api/reference/responses/overview) | Сервисы с Responses API |
+| `anthropic_messages` | [Anthropic Messages](https://platform.claude.com/docs/en/api/messages) | Anthropic-совместимые Messages endpoints |
+
 ## Метаданные и пользовательские модели
 
 Настройте метаданные в пользовательском или workspace `config.toml` в разделе
 `[model.<slug>]`. Для встроенного slug это частичное переопределение: пропущенные
 поля сохраняют встроенные значения. Новый slug создает модель с безопасными
 значениями по умолчанию; подключите ее через `[providers.<id>]` и
-`[model_bindings.<id>]`.
+`[model_bindings.<id>]`, как в
+[полном примере](#полный-пример-кастомная-модель--свой-api-key).
 
 Пример частичного переопределения встроенной модели:
 
@@ -71,77 +162,54 @@ effective_context_window_percent = 90
 
 Точная формула эффективного контекстного окна:
 `context_window * effective_context_window_percent / 100`; результат является
-доступным модели контекстом и границей автоматической compaction. Полный пример:
+доступным модели контекстом и границей автоматической compaction.
+
+Настраиваемые метаданные включают `display_name` (имя в picker), `description`
+(поясняющий текст) и `channel` (метка группировки). `context_window` и
+`effective_context_window_percent` задают эффективный контекст, а `max_tokens` -
+лимит выходных токенов по умолчанию. Параметры sampling: `temperature`
+(случайность), `top_p` (nucleus sampling), `top_k` (лимит кандидатов). Wire API
+в `provider` - одно из `openai_chat_completions`, `openai_responses` или
+`anthropic_messages`. Метаданные reasoning типизированы: `reasoning_capability`
+может быть `unsupported`, `toggle`, `{ levels = [...] }` или
+`{ togglewithlevels = [...] }`; `reasoning_implementation` - `disabled`,
+`request_parameter` или типизированная таблица `model_variant`. Вариант модели
+отображает логический выбор reasoning в другой provider-facing model id,
+опциональный effective effort и опциональное extra request body;
+`default_reasoning_effort` выбирает effort по умолчанию. `input_modalities`
+принимает `text` и `image`; `truncation_policy` задает лимит байт или токенов для
+слишком больших tool results; `supports_image_detail_original` включает
+оригинальную детализацию изображений.
+
+Если `base_instructions` опущен, встроенная модель сохраняет встроенные
+инструкции, а кастомная использует инструкции Devo по умолчанию. Явная пустая
+строка (`base_instructions = ""`) означает отсутствие базовых инструкций.
+
+Устаревший скаляр `model = "slug"` по-прежнему читается. Поскольку
+`[model.<slug>]` занимает пространство имен таблицы `model`, новая конфигурация
+должна выбирать активное подключение через `[defaults].model_binding`.
+
+### Настройки TUI
+
+Ключевые поля верхнего уровня в `DEVO_HOME/config.toml` также хранят UI-настройки:
 
 ```toml
-[defaults]
-model_binding = "my-coding-model-example"
-
-[model.my-coding-model]
-display_name = "My Coding Model"
-description = "Custom OpenAI-compatible coding model."
-channel = "Custom"
-provider = "openai_chat_completions"
-context_window = 200000
-effective_context_window_percent = 95
-max_tokens = 4096
-temperature = 0.2
-top_p = 0.9
-top_k = 40.0
-reasoning_capability = { levels = ["low", "medium", "high"] }
-reasoning_implementation = "request_parameter"
-default_reasoning_effort = "medium"
-base_instructions = "You are Devo, a coding agent."
-input_modalities = ["text", "image"]
-truncation_policy = { mode = "tokens", limit = 12000 }
-supports_image_detail_original = true
-
-[providers.my-provider]
-enabled = true
-name = "My Provider"
-base_url = "https://api.example.com/v1"
-credential = "my_provider_api_key"
-wire_apis = ["openai_chat_completions"]
-
-[model_bindings.my-coding-model-example]
-enabled = true
-model_slug = "my-coding-model"
-provider = "my-provider"
-request_model = "provider-specific-model-name"
-display_name = "My Coding Model"
-invocation_method = "openai_chat_completions"
+theme = "aurora"
+collapse_reasoning = true
 ```
 
-Настраиваемые поля: `display_name` - имя модели в picker, `description` - пояснение
-для пользователя, `channel` - метка группировки моделей. `context_window` и
-`effective_context_window_percent` определяют эффективный контекст, а `max_tokens`
-является лимитом response output по умолчанию. Среди sampling-настроек
-`temperature` управляет случайностью, `top_p` - nucleus probability mass, а
-`top_k` - числом token-кандидатов. Wire API `provider` принимает
-`openai_chat_completions`, `openai_responses` или `anthropic_messages`.
-Reasoning-метаданные типизированы:
-`reasoning_capability` может быть `unsupported`, `toggle`, `{ levels = [...] }`
-или `{ togglewithlevels = [...] }`; `reasoning_implementation` - `disabled`,
-`request_parameter` или типизированная таблица `model_variant`. Model variant
-сопоставляет логический reasoning selection с другим provider-facing model id,
-необязательным effective effort и extra request body вместо изменения параметра
-того же model; `default_reasoning_effort` задает effort по умолчанию.
-`input_modalities` принимает `text` и `image`, `truncation_policy` выбирает лимит
-bytes или tokens для усечения слишком большого tool result перед включением в
-model request, а `supports_image_detail_original` включает исходную детализацию.
-
-Если `base_instructions` пропущено, встроенная модель сохраняет встроенное
-значение, а пользовательская использует инструкции Devo по умолчанию. Явная
-пустая строка (`base_instructions = ""`) означает отсутствие base instructions.
-
-Старый scalar `model = "slug"` по-прежнему читается. Но `[model.<slug>]` теперь
-занимает namespace таблицы верхнего уровня `model`, поэтому новая конфигурация
-должна выбирать подключение через `[defaults].model_binding`.
-
-### Переход с `models.json`
+- `theme` выбирает цветовую тему TUI (также через `/theme`).
+- `collapse_reasoning` управляет отображением reasoning (также через
+  `/show-reasoning`):
+  - `true` (по умолчанию): при streaming показывать только последние 3 строки;
+    после завершения короткие рассуждения оставлять полностью, длинные сворачивать
+    в одну строку `Thought · …` (полный текст доступен по Ctrl+T).
+  - `false`: показывать полный reasoning и во время streaming, и после него.
+
+### Миграция с `models.json`
 
 Старые `~/.devo/models.json` и `<workspace>/.devo/models.json` игнорируются.
-Вручную скопируйте нужные поля в `[model.<slug>]` пользовательского или workspace
-`config.toml`, затем добавьте или сохраните соответствующие provider и model
+Вручную скопируйте нужные поля в `[model.<slug>]` пользовательского или
+workspace `config.toml`, затем добавьте или сохраните соответствующие provider и
 binding. API key храните в `auth.json` и ссылайтесь на него через
 `[providers.<id>].credential`.
diff --git a/docs/configuration.zh-Hans.md b/docs/configuration.zh-Hans.md
index a8649cea..bf4d923c 100644
--- a/docs/configuration.zh-Hans.md
+++ b/docs/configuration.zh-Hans.md
@@ -13,7 +13,7 @@
 凭据单独保存在 `DEVO_HOME/auth.json`；`config.toml` 应引用 credential id，
 而不是直接存储 API key。
 
-最小结构：
+最小结构（内置模型 + provider 绑定）：
 
 ```toml
 [defaults]
@@ -41,97 +41,159 @@ default_reasoning_effort = "high"
 - `model_slug` 按 slug 选择 Devo 的本地模型元数据。
 - binding 的 `provider` 选择一个 `[providers.<id>]` 连接记录。
 - `request_model` 是发送到 provider 的模型 id。
-- `invocation_method` 选择实际使用的 provider 协议，例如
-  [`openai_chat_completions`](https://developers.openai.com/api/reference/chat-completions/overview)、
-  [`openai_responses`](https://developers.openai.com/api/reference/responses/overview)，
-  或 [`anthropic_messages`](https://platform.claude.com/docs/en/api/messages)。
+- `invocation_method` 选择实际使用的 provider 协议。详见
+  [调用方式（Invocation methods）](#调用方式invocation-methods)。
 
 模型元数据也有 `provider` 字段，它描述模型所需的 wire API；binding 的
 `invocation_method` 则选择运行时连接，二者应保持一致。API key 仍保存在
 `auth.json` 中，并通过 provider 的 `credential` 引用连接。
 
-## 模型元数据与自定义模型
+沿用 `model_name` 的旧配置仍可读取。下次保存该 binding 时，Devo 会写成
+`request_model`。
 
-在用户或工作区 `config.toml` 的 `[model.<slug>]` 下配置模型元数据。内置 slug
-使用部分覆盖，未写字段保留内置值；新 slug 会创建带安全默认值的自定义模型，
-并应通过 `[providers.<id>]` 和 `[model_bindings.<id>]` 连接。
+## 接入自有 API key
 
-内置模型部分覆盖示例：
+Devo 不会把 API key 写进 `config.toml`。接入自有 key 时：
 
-```toml
-[model.qwen3-coder-next]
-context_window = 262144
-effective_context_window_percent = 90
-```
+1. 把密钥保存在用户级 `DEVO_HOME/auth.json`。
+2. 在 `config.toml` 中通过 `[providers.<id>].credential` 引用该 credential id。
 
-有效上下文窗口的精确公式是
-`context_window * effective_context_window_percent / 100`；结果既是模型可用上下文，
-也是自动压缩边界。完整自定义示例：
+`devo onboard` 以及 Desktop/TUI 的 provider 流程会为你写入这两个文件。
+
+### 完整示例：自定义模型参数 + 自有 API key
+
+下面同时配置自定义 DeepSeek 模型（Anthropic Messages）、provider 端点，以及只存放在
+`auth.json` 中的凭据。
+
+`~/.devo/config.toml`（Windows 为 `C:\Users\yourname\.devo\config.toml`）：
 
 ```toml
 [defaults]
-model_binding = "my-coding-model-example"
+model_binding = "deepseek-example"
 
-[model.my-coding-model]
-display_name = "My Coding Model"
-description = "Custom OpenAI-compatible coding model."
+[model.my-deepseek]
+display_name = "DeepSeek V4 Flash"
+description = "Custom Anthropic Messages coding model for DeepSeek."
 channel = "Custom"
-provider = "openai_chat_completions"
+# 该模型期望的 wire API，需与 binding 的 invocation_method 一致。
+provider = "anthropic_messages"
 context_window = 200000
 effective_context_window_percent = 95
-max_tokens = 4096
+max_tokens = 8192
 temperature = 0.2
-top_p = 0.9
-top_k = 40.0
-reasoning_capability = { levels = ["low", "medium", "high"] }
+reasoning_capability = { togglewithlevels = ["high", "max"] }
 reasoning_implementation = "request_parameter"
-default_reasoning_effort = "medium"
-base_instructions = "You are Devo, a coding agent."
+base_instructions = "(optional) You are Devo, a coding agent."
 input_modalities = ["text", "image"]
-truncation_policy = { mode = "tokens", limit = 12000 }
-supports_image_detail_original = true
 
-[providers.my-provider]
+[providers.deepseek]
 enabled = true
-name = "My Provider"
-base_url = "https://api.example.com/v1"
-credential = "my_provider_api_key"
-wire_apis = ["openai_chat_completions"]
+name = "DeepSeek Anthropic Compatible"
+base_url = "https://api.deepseek.com/anthropic"
+# 仅 credential id — 密钥保存在 auth.json。
+credential = "deepseek_compatible_api_key"
+wire_apis = ["anthropic_messages"]
 
-[model_bindings.my-coding-model-example]
+[model_bindings.deepseek-example]
 enabled = true
-model_slug = "my-coding-model"
-provider = "my-provider"
-request_model = "provider-specific-model-name"
-display_name = "My Coding Model"
-invocation_method = "openai_chat_completions"
+model_slug = "my-deepseek"
+provider = "deepseek"
+request_model = "deepseek-v4-flash"
+display_name = "DeepSeek V4 Flash"
+invocation_method = "anthropic_messages"
+```
+
+对应的 `~/.devo/auth.json`（Windows 为 `C:\Users\yourname\.devo\auth.json`）：
+
+```json
+{
+  "version": 1,
+  "credentials": {
+    "deepseek_compatible_api_key": {
+      "kind": "api_key",
+      "value": "sk-deepseek-your-api-key"
+    }
+  }
+}
 ```
 
-可配置元数据包括：`display_name` 是 picker 中显示的模型名，`description` 是面向
-用户的说明文字，`channel` 是模型分组标签；`context_window` 和
-`effective_context_window_percent` 决定有效上下文，`max_tokens` 是默认响应输出上限。
-采样默认值中，`temperature` 控制随机性，`top_p` 控制 nucleus 概率质量，`top_k`
-限制候选 token 数量。`provider` wire API 可为 `openai_chat_completions`、
-`openai_responses` 或 `anthropic_messages`。推理元数据是类型化的：
-`reasoning_capability` 可为
-`unsupported`、`toggle`、`{ levels = [...] }` 或
-`{ togglewithlevels = [...] }`；`reasoning_implementation` 可为 `disabled`、
-`request_parameter` 或类型化 `model_variant` 表。model variant 将逻辑推理选择映射到
-不同的 provider-facing model id、可选有效 effort 和可选额外 request body，而不是修改
-同一模型的请求参数；`default_reasoning_effort` 选择默认推理强度。
-`input_modalities` 支持 `text` 和 `image`；`truncation_policy` 选择 byte 或 token
-上限，在超大 tool result 进入模型请求前将其截断；
+规则：
+
+- 目前只支持 `api_key` 类型凭据。
+- credential id 必须与 `[providers.<id>].credential` 完全一致。
+- 将 `auth.json` 保留在 `DEVO_HOME` 下，不要提交到项目仓库。
+- 工作区 `<workspace>/.devo/config.toml` 可以引用 credential id，但密钥值只存在
+  用户级 `auth.json`。
+- 仅更新 key 时编辑 `auth.json`；credential id 不变时无需改 `config.toml`。
+
+## 调用方式（Invocation methods）
+
+binding 上的 `invocation_method` 与 provider 上的 `wire_apis` 决定 Devo 使用哪种
+HTTP API。模型元数据里的 `provider` 应使用相同值，以便目录能力与运行时连接一致。
+
+| 取值 | 协议 | 典型端点 |
+| --- | --- | --- |
+| `openai_chat_completions` | [OpenAI Chat Completions](https://developers.openai.com/api/reference/chat-completions/overview) | 多数 OpenAI 兼容网关（DeepSeek、Qwen、Kimi、OpenRouter、许多本地代理） |
+| `openai_responses` | [OpenAI Responses](https://developers.openai.com/api/reference/responses/overview) | 提供 Responses API 的服务 |
+| `anthropic_messages` | [Anthropic Messages](https://platform.claude.com/docs/en/api/messages) | Anthropic 兼容 Messages 端点 |
+
+## 模型元数据与自定义模型
+
+在用户或工作区 `config.toml` 的 `[model.<slug>]` 下配置模型元数据。内置 slug
+使用部分覆盖，未写字段保留内置值；新 slug 会创建带安全默认值的自定义模型，
+并应通过 `[providers.<id>]` 和 `[model_bindings.<id>]` 连接，参见
+[完整示例](#完整示例自定义模型参数--自有-api-key)。
+
+内置模型部分覆盖示例：
+
+```toml
+[model.qwen3-coder-next]
+context_window = 262144
+effective_context_window_percent = 90
+```
+
+有效上下文窗口的精确公式是
+`context_window * effective_context_window_percent / 100`；结果既是模型可用上下文，
+也是自动压缩边界。
+
+可配置元数据包括：`display_name`（选择器中的名称）、`description`（说明文字）、
+`channel`（分组标签）。`context_window` 与
+`effective_context_window_percent` 决定有效上下文，`max_tokens` 是默认输出上限。
+采样默认值：`temperature`（随机性）、`top_p`（核采样）、`top_k`（候选 token 上限）。
+`provider` wire API 取值为 `openai_chat_completions`、`openai_responses` 或
+`anthropic_messages`。推理元数据是类型化的：`reasoning_capability` 可为
+`unsupported`、`toggle`、`{ levels = [...] }` 或 `{ togglewithlevels = [...] }`；
+`reasoning_implementation` 可为 `disabled`、`request_parameter` 或类型化的
+`model_variant` 表。`model_variant` 把逻辑推理选择映射到不同的 provider 模型 id、
+可选有效 effort，以及可选额外请求体，而不是在同一模型上改参数；
+`default_reasoning_effort` 选择默认 effort。`input_modalities` 接受 `text` 和
+`image`；`truncation_policy` 为过大的工具结果选择字节或 token 上限；
 `supports_image_detail_original` 启用原始图像细节。
 
-省略 `base_instructions` 时，内置模型保留内置 instructions，自定义模型使用 Devo
-默认 instructions；显式空字符串（`base_instructions = ""`）表示不使用 base instructions。
+省略 `base_instructions` 时，内置模型保留内置指令，自定义模型使用 Devo 默认指令。
+显式空字符串（`base_instructions = ""`）表示无基础指令。
+
+旧版标量 `model = "slug"` 仍可读取。因 `[model.<slug>]` 占用了顶层 `model`
+表命名空间，新配置须用 `[defaults].model_binding` 选择活跃连接。
+
+### TUI 偏好
+
+`DEVO_HOME/config.toml` 顶层还保存部分 UI 偏好：
+
+```toml
+theme = "aurora"
+collapse_reasoning = true
+```
 
-旧的 `model = "slug"` 标量仍可读取。但 `[model.<slug>]` 现在占用顶层 `model`
-表命名空间，因此新配置必须通过 `[defaults].model_binding` 选择活动连接。
+- `theme` 选择 TUI 配色主题（也可通过 `/theme` 设置）。
+- `collapse_reasoning` 控制推理显示（也可通过 `/show-reasoning` 设置）：
+  - `true`（默认）：流式输出时只显示最新 3 行；结束后短推理完整保留，较长推理折叠为
+    一行 `Thought · …` 摘要（完整文本仍可在 Ctrl+T 查看）。
+  - `false`：流式输出与结束后都显示完整推理。
 
 ### 从 `models.json` 迁移
 
-旧的 `~/.devo/models.json` 和 `<workspace>/.devo/models.json` 会被忽略。
+旧的 `~/.devo/models.json` 与 `<workspace>/.devo/models.json` 会被忽略。
 请手动把仍需使用的字段复制到用户或工作区 `config.toml` 的 `[model.<slug>]`
 段，并添加或保留对应 provider 和 model binding。API key 继续放在 `auth.json`，
 通过 `[providers.<id>].credential` 引用。
diff --git a/docs/configuration.zh-Hant.md b/docs/configuration.zh-Hant.md
index 9ef2108c..9c9c4f27 100644
--- a/docs/configuration.zh-Hant.md
+++ b/docs/configuration.zh-Hant.md
@@ -13,7 +13,7 @@
 憑據單獨保存在 `DEVO_HOME/auth.json`；`config.toml` 應引用 credential id，
 而不是直接儲存 API key。
 
-最小結構：
+最小結構（內建模型 + provider 綁定）：
 
 ```toml
 [defaults]
@@ -41,97 +41,159 @@ default_reasoning_effort = "high"
 - `model_slug` 按 slug 選擇 Devo 的本地模型中繼資料。
 - binding 的 `provider` 選擇一個 `[providers.<id>]` 連線記錄。
 - `request_model` 是傳送到 provider 的模型 id。
-- `invocation_method` 選擇實際使用的 provider 協議，例如
-  [`openai_chat_completions`](https://developers.openai.com/api/reference/chat-completions/overview)、
-  [`openai_responses`](https://developers.openai.com/api/reference/responses/overview)，
-  或 [`anthropic_messages`](https://platform.claude.com/docs/en/api/messages)。
+- `invocation_method` 選擇實際使用的 provider 協議。詳見
+  [呼叫方式（Invocation methods）](#呼叫方式invocation-methods)。
 
 模型中繼資料也有 `provider` 欄位，它描述模型所需的 wire API；binding 的
 `invocation_method` 則選擇執行階段連線，兩者應保持一致。API key 仍保存在
 `auth.json` 中，並透過 provider 的 `credential` 參照連線。
 
-## 模型中繼資料與自訂模型
+沿用 `model_name` 的舊配置仍可讀取。下次儲存該 binding 時，Devo 會寫成
+`request_model`。
 
-在使用者或工作區 `config.toml` 的 `[model.<slug>]` 下設定模型中繼資料。內建 slug
-使用部分覆蓋，未寫欄位保留內建值；新 slug 會建立帶安全預設值的自訂模型，
-並應透過 `[providers.<id>]` 和 `[model_bindings.<id>]` 連線。
+## 接入自有 API key
 
-內建模型部分覆蓋範例：
+Devo 不會把 API key 寫進 `config.toml`。接入自有 key 時：
 
-```toml
-[model.qwen3-coder-next]
-context_window = 262144
-effective_context_window_percent = 90
-```
+1. 把密鑰保存在使用者級 `DEVO_HOME/auth.json`。
+2. 在 `config.toml` 中透過 `[providers.<id>].credential` 引用該 credential id。
 
-有效上下文視窗的精確公式是
-`context_window * effective_context_window_percent / 100`；結果既是模型可用上下文，
-也是自動壓縮邊界。完整自訂範例：
+`devo onboard` 以及 Desktop/TUI 的 provider 流程會為你寫入這兩個檔案。
+
+### 完整範例：自訂模型參數 + 自有 API key
+
+下面同時設定自訂 DeepSeek 模型（Anthropic Messages）、provider 端點，以及只存放在
+`auth.json` 中的憑據。
+
+`~/.devo/config.toml`（Windows 為 `C:\Users\yourname\.devo\config.toml`）：
 
 ```toml
 [defaults]
-model_binding = "my-coding-model-example"
+model_binding = "deepseek-example"
 
-[model.my-coding-model]
-display_name = "My Coding Model"
-description = "Custom OpenAI-compatible coding model."
+[model.my-deepseek]
+display_name = "DeepSeek V4 Flash"
+description = "Custom Anthropic Messages coding model for DeepSeek."
 channel = "Custom"
-provider = "openai_chat_completions"
+# 該模型期望的 wire API，需與 binding 的 invocation_method 一致。
+provider = "anthropic_messages"
 context_window = 200000
 effective_context_window_percent = 95
-max_tokens = 4096
+max_tokens = 8192
 temperature = 0.2
-top_p = 0.9
-top_k = 40.0
-reasoning_capability = { levels = ["low", "medium", "high"] }
+reasoning_capability = { togglewithlevels = ["high", "max"] }
 reasoning_implementation = "request_parameter"
-default_reasoning_effort = "medium"
-base_instructions = "You are Devo, a coding agent."
+base_instructions = "(optional) You are Devo, a coding agent."
 input_modalities = ["text", "image"]
-truncation_policy = { mode = "tokens", limit = 12000 }
-supports_image_detail_original = true
 
-[providers.my-provider]
+[providers.deepseek]
 enabled = true
-name = "My Provider"
-base_url = "https://api.example.com/v1"
-credential = "my_provider_api_key"
-wire_apis = ["openai_chat_completions"]
+name = "DeepSeek Anthropic Compatible"
+base_url = "https://api.deepseek.com/anthropic"
+# 僅 credential id — 密鑰保存在 auth.json。
+credential = "deepseek_compatible_api_key"
+wire_apis = ["anthropic_messages"]
 
-[model_bindings.my-coding-model-example]
+[model_bindings.deepseek-example]
 enabled = true
-model_slug = "my-coding-model"
-provider = "my-provider"
-request_model = "provider-specific-model-name"
-display_name = "My Coding Model"
-invocation_method = "openai_chat_completions"
+model_slug = "my-deepseek"
+provider = "deepseek"
+request_model = "deepseek-v4-flash"
+display_name = "DeepSeek V4 Flash"
+invocation_method = "anthropic_messages"
+```
+
+對應的 `~/.devo/auth.json`（Windows 為 `C:\Users\yourname\.devo\auth.json`）：
+
+```json
+{
+  "version": 1,
+  "credentials": {
+    "deepseek_compatible_api_key": {
+      "kind": "api_key",
+      "value": "sk-deepseek-your-api-key"
+    }
+  }
+}
 ```
 
-可設定中繼資料包括：`display_name` 是 picker 中顯示的模型名稱，`description` 是
-面向使用者的說明文字，`channel` 是模型分組標籤；`context_window` 和
-`effective_context_window_percent` 決定有效上下文，`max_tokens` 是預設回應輸出上限。
-取樣預設值中，`temperature` 控制隨機性，`top_p` 控制 nucleus 機率質量，`top_k`
-限制候選 token 數量。`provider` wire API 可為 `openai_chat_completions`、
-`openai_responses` 或 `anthropic_messages`。推理中繼資料是型別化的：
-`reasoning_capability` 可為
-`unsupported`、`toggle`、`{ levels = [...] }` 或
-`{ togglewithlevels = [...] }`；`reasoning_implementation` 可為 `disabled`、
-`request_parameter` 或型別化 `model_variant` 表。model variant 將邏輯推理選擇映射到
-不同的 provider-facing model id、可選有效 effort 和可選額外 request body，而不是修改
-同一模型的請求參數；`default_reasoning_effort` 選擇預設推理強度。
-`input_modalities` 支援 `text` 和 `image`；`truncation_policy` 選擇 byte 或 token
-上限，在超大 tool result 進入模型請求前將其截斷；
+規則：
+
+- 目前只支援 `api_key` 類型憑據。
+- credential id 必須與 `[providers.<id>].credential` 完全一致。
+- 將 `auth.json` 保留在 `DEVO_HOME` 下，不要提交到專案倉庫。
+- 工作區 `<workspace>/.devo/config.toml` 可以引用 credential id，但密鑰值只存在
+  使用者級 `auth.json`。
+- 僅更新 key 時編輯 `auth.json`；credential id 不變時無需改 `config.toml`。
+
+## 呼叫方式（Invocation methods）
+
+binding 上的 `invocation_method` 與 provider 上的 `wire_apis` 決定 Devo 使用哪種
+HTTP API。模型中繼資料裡的 `provider` 應使用相同值，以便目錄能力與執行階段連線一致。
+
+| 取值 | 協議 | 典型端點 |
+| --- | --- | --- |
+| `openai_chat_completions` | [OpenAI Chat Completions](https://developers.openai.com/api/reference/chat-completions/overview) | 多數 OpenAI 相容閘道（DeepSeek、Qwen、Kimi、OpenRouter、許多本地代理） |
+| `openai_responses` | [OpenAI Responses](https://developers.openai.com/api/reference/responses/overview) | 提供 Responses API 的服務 |
+| `anthropic_messages` | [Anthropic Messages](https://platform.claude.com/docs/en/api/messages) | Anthropic 相容 Messages 端點 |
+
+## 模型中繼資料與自訂模型
+
+在使用者或工作區 `config.toml` 的 `[model.<slug>]` 下設定模型中繼資料。內建 slug
+使用部分覆蓋，未寫欄位保留內建值；新 slug 會建立帶安全預設值的自訂模型，
+並應透過 `[providers.<id>]` 和 `[model_bindings.<id>]` 連線，參見
+[完整範例](#完整範例自訂模型參數--自有-api-key)。
+
+內建模型部分覆蓋範例：
+
+```toml
+[model.qwen3-coder-next]
+context_window = 262144
+effective_context_window_percent = 90
+```
+
+有效上下文視窗的精確公式是
+`context_window * effective_context_window_percent / 100`；結果既是模型可用上下文，
+也是自動壓縮邊界。
+
+可設定中繼資料包括：`display_name`（選擇器中的名稱）、`description`（說明文字）、
+`channel`（分組標籤）。`context_window` 與
+`effective_context_window_percent` 決定有效上下文，`max_tokens` 是預設輸出上限。
+取樣預設值：`temperature`（隨機性）、`top_p`（核取樣）、`top_k`（候選 token 上限）。
+`provider` wire API 取值為 `openai_chat_completions`、`openai_responses` 或
+`anthropic_messages`。推理中繼資料是類型化的：`reasoning_capability` 可為
+`unsupported`、`toggle`、`{ levels = [...] }` 或 `{ togglewithlevels = [...] }`；
+`reasoning_implementation` 可為 `disabled`、`request_parameter` 或類型化的
+`model_variant` 表。`model_variant` 把邏輯推理選擇對應到不同的 provider 模型 id、
+可選有效 effort，以及可選額外請求體，而不是在同一模型上改參數；
+`default_reasoning_effort` 選擇預設 effort。`input_modalities` 接受 `text` 和
+`image`；`truncation_policy` 為過大的工具結果選擇位元組或 token 上限；
 `supports_image_detail_original` 啟用原始影像細節。
 
-省略 `base_instructions` 時，內建模型保留內建 instructions，自訂模型使用 Devo
-預設 instructions；明確空字串（`base_instructions = ""`）表示不使用 base instructions。
+省略 `base_instructions` 時，內建模型保留內建指令，自訂模型使用 Devo 預設指令。
+明確空字串（`base_instructions = ""`）表示無基礎指令。
+
+舊版純量 `model = "slug"` 仍可讀取。因 `[model.<slug>]` 佔用了頂層 `model`
+表命名空間，新配置須用 `[defaults].model_binding` 選擇活躍連線。
+
+### TUI 偏好
+
+`DEVO_HOME/config.toml` 頂層還儲存部分 UI 偏好：
+
+```toml
+theme = "aurora"
+collapse_reasoning = true
+```
 
-舊的 `model = "slug"` 純量仍可讀取。但 `[model.<slug>]` 現在占用頂層 `model`
-表命名空間，因此新設定必須透過 `[defaults].model_binding` 選擇作用中連線。
+- `theme` 選擇 TUI 配色主題（也可透過 `/theme` 設定）。
+- `collapse_reasoning` 控制推理顯示（也可透過 `/show-reasoning` 設定）：
+  - `true`（預設）：串流輸出時只顯示最新 3 行；結束後短推理完整保留，較長推理摺疊為
+    一行 `Thought · …` 摘要（完整文字仍可在 Ctrl+T 檢視）。
+  - `false`：串流輸出與結束後都顯示完整推理。
 
 ### 從 `models.json` 遷移
 
-舊的 `~/.devo/models.json` 和 `<workspace>/.devo/models.json` 會被忽略。
+舊的 `~/.devo/models.json` 與 `<workspace>/.devo/models.json` 會被忽略。
 請手動把仍需使用的欄位複製到使用者或工作區 `config.toml` 的 `[model.<slug>]`
 段，並新增或保留對應 provider 和 model binding。API key 繼續放在 `auth.json`，
-透過 `[providers.<id>].credential` 參照。
+透過 `[providers.<id>].credential` 引用。