lukealvoeiro · Oct 17, 2026
diff --git a/docs/cli/byok/ollama.mdx b/docs/cli/byok/ollama.mdx
@@ -123,5 +123,5 @@ For a full list of available cloud models, visit: [ollama.com/search?c=cloud](ht
 
 ## Notes
 
-- Local API doesn't require authentication (use any placeholder for `api_key`)
+- Local API doesn't require authentication (use any placeholder for `apiKey`)
 - Models are stored in `~/.ollama/models/`
diff --git a/docs/cli/byok/overview.mdx b/docs/cli/byok/overview.mdx
@@ -43,7 +43,22 @@ Add custom models to `~/.factory/settings.json` under the `customModels` array:
 </Tip>
 
 <Note>
-  **Legacy support**: Custom models in `~/.factory/config.json` using snake_case field names (`custom_models`, `base_url`, etc.) are still supported for backwards compatibility. Both files are loaded and merged, with `settings.json` taking priority. Env var expansion for `apiKey` applies to `settings.json`/`settings.local.json` and not to legacy `config.json`.
+  **Migrating from `config.json`**: The CLI no longer reads `custom_models` from `~/.factory/config.json`. Models defined there do not appear in `/model` and are rejected by `droid exec -m`. Move each entry into the `customModels` array in `~/.factory/settings.json` and rename its fields to camelCase:
+
+  | Old `config.json` field | `settings.json` field |
+  |-------------------------|-----------------------|
+  | `model`, `provider`, `bedrock` | unchanged |
+  | `model_display_name` | `displayName` |
+  | `base_url` | `baseUrl` |
+  | `api_key` | `apiKey` |
+  | `max_tokens` | `maxOutputTokens` |
+  | `max_context_limit` | `maxContextLimit` |
+  | `enable_thinking` | `enableThinking` |
+  | `thinking_max_tokens` | `thinkingMaxTokens` |
+  | `reasoning_effort` | `reasoningEffort` |
+  | `extra_args` | `extraArgs` |
+  | `extra_headers` | `extraHeaders` |
+  | `supports_images: false` | `noImageSupport: true` |
 </Note>
 
 ### Supported Fields
@@ -238,7 +253,8 @@ Custom models display with the name you set in `displayName`, making it easy to
 ## Troubleshooting
 
 ### Model not appearing in selector
-- Check JSON syntax in `~/.factory/settings.json` (or `config.json` if using legacy format)
+- Check JSON syntax in `~/.factory/settings.json`
+- Custom models in `~/.factory/config.json` are no longer read; move them to `customModels` in `settings.json` (see the migration note above)
 - Settings changes are detected automatically via file watching
 - Verify all required fields are present
 

diff --git a/docs/cli/configuration/custom-droids.mdx b/docs/cli/configuration/custom-droids.mdx
@@ -121,7 +121,7 @@ Each subagent's model is resolved from its droid config plus the parent's comple
 
 1. **Droid config `model`** – set `model` in the droid's frontmatter to pin a specific model, or `inherit` (the default) to defer to the parent.
    - Built-in model IDs: e.g., `claude-sonnet-4-5-20250929`. See [Available Models](/models).
-   - Custom (BYOK) models: use `custom:` + the `model` field from your config (e.g., `custom:gpt-4o-mini`), **not** the `model_display_name`.
+   - Custom (BYOK) models: use `custom:` + the `model` field from your config (e.g., `custom:gpt-4o-mini`), **not** the `displayName`.
 2. **Complexity → model routing** – when the droid's model is `inherit` and the parent passes a `complexity` tier, Droid maps that tier to a model using the routing you configure in `/settings` → **Subagents**:
    - **Light task model**, **Medium task model**, and **Heavy task model** each map a complexity tier to a specific model (with an optional reasoning effort), or leave it on **Inherit** to use the spawning session's model. You can point a tier at a concrete model or at the Auto model router.
 3. **Inherit fallback** – if no explicit routing applies, the subagent uses the parent session's active model and reasoning effort.
@@ -229,7 +229,7 @@ Key metadata fields:
 | ----------------- | ------------------------------------------------------------------------------------------------------------------------------ |
 | `name`            | Required. Lowercase letters, digits, `-`, `_`. Drives the `subagent_type` value and filename.                                  |
 | `description`     | Optional. Shown in the UI list. Keep ≤500 chars.                                                                               |
-| `model`           | `inherit` (use parent session's model), or specify a model identifier. For built-in models, use values like `claude-sonnet-4-5-20250929`. For custom models (BYOK), use `custom:` + the `model` field from your config (e.g., `custom:gpt-4o-mini`), **not** the `model_display_name`. See the [Available Models](/models) for model IDs. |
+| `model`           | `inherit` (use parent session's model), or specify a model identifier. For built-in models, use values like `claude-sonnet-4-5-20250929`. For custom models (BYOK), use `custom:` + the `model` field from your config (e.g., `custom:gpt-4o-mini`), **not** the `displayName`. See the [Available Models](/models) for model IDs. |
 | `reasoningEffort` | Optional. Set reasoning effort for models that support it (e.g., `low`, `medium`, `high`). Ignored when `model` is `inherit`. Must be compatible with the selected model. |
 | `tools`           | Tool selection: omit for all tools, use a category string (e.g., `read-only`), or specify an array of tool IDs like `["Read", "Edit", "Execute"]`. Case-sensitive. To restrict a droid to specific MCP tools, list their exact registered tool IDs here. |
 | `mcpServers`      | Optional. Array of configured [MCP server](/cli/configuration/mcp) names (e.g., `["linear", "github"]`) whose tools should be available to this droid. When set, only tools from the listed servers are exposed to the subagent; omit to fall back to your global MCP tool availability. See [Selecting MCP servers](#selecting-mcp-servers). |

diff --git a/docs/cli/getting-started/video-walkthrough.mdx b/docs/cli/getting-started/video-walkthrough.mdx
@@ -247,8 +247,7 @@ Access your configuration directory by pressing `Cmd + Shift + H` to show your r
 
 ```
 ~/.factory/
-├── config.json          # Model configuration and BYOK
-├── settings.json        # CLI settings and allow/deny lists
+├── settings.json        # CLI settings, allow/deny lists, and custom models (BYOK)
 ├── mcp.json            # MCP integrations
 ├── droids/             # Custom sub-agents
 ├── commands/           # Custom slash commands
@@ -260,18 +259,19 @@ Access your configuration directory by pressing `Cmd + Shift + H` to show your r
   Learn more: [Settings](/cli/configuration/settings) | [Custom Slash Commands](/cli/configuration/custom-slash-commands) | [Custom Droids](/cli/configuration/custom-droids) | [MCP Configuration](/cli/configuration/mcp)
 </Tip>
 
-### config.json - Bring Your Own Key
+### Custom models - Bring Your Own Key
 
-Configure custom models using your own API keys:
+Configure custom models using your own API keys by adding them to the `customModels` array in `~/.factory/settings.json`:
 
 ```json
 {
-  "models": [
+  "customModels": [
     {
-      "provider": "openrouter",
-      "name": "anthropic/claude-3.5-sonnet",
-      "apiKey": "your-api-key-here",
-      "displayName": "Claude 3.5 Sonnet (OpenRouter)"
+      "model": "anthropic/claude-sonnet-4.5",
+      "displayName": "Claude Sonnet 4.5 (OpenRouter)",
+      "baseUrl": "https://openrouter.ai/api/v1",
+      "apiKey": "${OPENROUTER_API_KEY}",
+      "provider": "generic-chat-completion-api"
     }
   ]
 }
@@ -286,8 +286,8 @@ Configure custom models using your own API keys:
     Copy the JSON configuration for your chosen provider
   </Step>
 
-  <Step title="Add to config.json">
-    Paste the configuration into `~/.factory/config.json` and add your API key
+  <Step title="Add to settings.json">
+    Paste the entry into the `customModels` array in `~/.factory/settings.json` and add your API key. Custom models in `~/.factory/config.json` are no longer read.
   </Step>
 
   <Step title="Select Model">

diff --git a/docs/enterprise/models-llm-gateways-and-integrations.mdx b/docs/enterprise/models-llm-gateways-and-integrations.mdx
@@ -37,7 +37,7 @@ Factory works with gateways in two ways:
 1. **Directly configured gateway endpoints**
    - `.factory/settings.json` can specify gateway base URLs for specific providers.
    - Environment variables can route calls (for example, `ANTHROPIC_BASE_URL`, `OPENAI_BASE_URL`).
-   - Custom models configured via [BYOK](/cli/byok/overview) can point to gateway endpoints using `base_url` and provider‑specific settings, so the same gateway policy applies whether models are built‑in or custom.
+   - Custom models configured via [BYOK](/cli/byok/overview) can point to gateway endpoints using `baseUrl` and provider‑specific settings, so the same gateway policy applies whether models are built‑in or custom.
 
 2. **Org‑level gateway policy**
    - Org admins can require that all model traffic go through specific gateways.

diff --git a/docs/jp/cli/byok/ollama.mdx b/docs/jp/cli/byok/ollama.mdx
@@ -123,5 +123,5 @@ Ollamaを使用してローカルハードウェアでモデルを実行する
 
 ## 注意事項
 
-- ローカルAPIは認証不要（`api_key` には任意のプレースホルダーを使用）
+- ローカルAPIは認証不要（`apiKey` には任意のプレースホルダーを使用）
 - モデルは `~/.ollama/models/` に保存されます
diff --git a/docs/jp/cli/byok/overview.mdx b/docs/jp/cli/byok/overview.mdx
@@ -43,7 +43,22 @@ Factory管理モデルと倍率については、[利用可能なモデル](/jp/
 </Tip>
 
 <Note>
-  **レガシーサポート**: 後方互換性のため、`~/.factory/config.json`内でsnake_caseフィールド名（`custom_models`、`base_url`など）を使うカスタムモデルは引き続きサポートされます。両方のファイルが読み込まれてマージされ、`settings.json`が優先されます。`apiKey`の環境変数展開は`settings.json`/`settings.local.json`に適用され、レガシーの`config.json`には適用されません。
+  **`config.json`からの移行**: CLIは`~/.factory/config.json`の`custom_models`を読み込まなくなりました。そこに定義されたモデルは`/model`に表示されず、`droid exec -m`でも無効なモデルとして拒否されます。各エントリを`~/.factory/settings.json`の`customModels`配列に移動し、フィールド名をcamelCaseに変更してください：
+
+  | 旧`config.json`のフィールド | `settings.json`のフィールド |
+  |-------------------------|-----------------------|
+  | `model`、`provider`、`bedrock` | 変更なし |
+  | `model_display_name` | `displayName` |
+  | `base_url` | `baseUrl` |
+  | `api_key` | `apiKey` |
+  | `max_tokens` | `maxOutputTokens` |
+  | `max_context_limit` | `maxContextLimit` |
+  | `enable_thinking` | `enableThinking` |
+  | `thinking_max_tokens` | `thinkingMaxTokens` |
+  | `reasoning_effort` | `reasoningEffort` |
+  | `extra_args` | `extraArgs` |
+  | `extra_headers` | `extraHeaders` |
+  | `supports_images: false` | `noImageSupport: true` |
 </Note>
 
 ### サポートされているフィールド
@@ -176,7 +191,8 @@ Droid CLIは利用可能な場合にプロンプトキャッシングを自動
 ## トラブルシューティング
 
 ### セレクターにモデルが表示されない
-- `~/.factory/settings.json`（レガシー形式を使用している場合は`config.json`）でJSON構文を確認
+- `~/.factory/settings.json`でJSON構文を確認
+- `~/.factory/config.json`内のカスタムモデルは読み込まれなくなりました。`settings.json`の`customModels`に移動してください（上記の移行に関する注記を参照）
 - 設定変更はファイル監視により自動的に検出されます
 - すべての必須フィールドが存在することを確認
 

diff --git a/docs/jp/cli/configuration/custom-droids.mdx b/docs/jp/cli/configuration/custom-droids.mdx
@@ -109,7 +109,7 @@ Perform deep analysis of the code or problem presented...
 | ----------------- | ------------------------------------------------------------------------------------------------------------------------------ |
 | `name`            | 必須。小文字、数字、`-`、`_`。`subagent_type` 値とファイル名を決定します。                                  |
 | `description`     | 任意。UI リストに表示されます。≤500文字に抑えてください。                                                                               |
-| `model`           | `inherit` （親セッションのモデルを使用）、またはモデル識別子を指定します。組み込みモデルの場合、`claude-sonnet-4-5-20250929` のような値を使用します。カスタムモデル（BYOK）の場合、`custom:` + 設定の `model` フィールドを使用します（例：`custom:gpt-4o-mini`）。`model_display_name` では**ありません**。モデルIDについては [利用可能なモデル](/jp/models) を参照してください。 |
+| `model`           | `inherit` （親セッションのモデルを使用）、またはモデル識別子を指定します。組み込みモデルの場合、`claude-sonnet-4-5-20250929` のような値を使用します。カスタムモデル（BYOK）の場合、`custom:` + 設定の `model` フィールドを使用します（例：`custom:gpt-4o-mini`）。`displayName` では**ありません**。モデルIDについては [利用可能なモデル](/jp/models) を参照してください。 |
 | `reasoningEffort` | 任意。対応するモデル（例：`low`、`medium`、`high`）の推論努力を設定します。`model` が `inherit` の場合は無視されます。選択したモデルと互換性が必要です。 |
 | `tools`           | ツール選択：すべてのツールを使用する場合は省略、カテゴリ文字列を使用（例：`read-only`）、または `["Read", "Edit", "Execute"]` のようなツールIDの配列を指定します。大文字小文字を区別します。droid を特定の MCP ツールのみに制限したい場合は、ここにその登録済みツールIDを正確に列挙します。 |
 | `mcpServers`      | 任意。設定済みの [MCP サーバー](/jp/cli/configuration/mcp) 名の配列です（例：`["linear", "github"]`）。設定すると、列挙したサーバーのツールだけがこの droid で利用可能になります。省略すると、グローバルな MCP ツールの可用性にフォールバックします。詳しくは [MCP サーバーの選択](#selecting-mcp-servers) を参照してください。 |

diff --git a/docs/jp/cli/getting-started/video-walkthrough.mdx b/docs/jp/cli/getting-started/video-walkthrough.mdx
@@ -247,8 +247,7 @@ droid
 
 ```
 ~/.factory/
-├── config.json          # Model configuration and BYOK
-├── settings.json        # CLI settings and allow/deny lists
+├── settings.json        # CLI settings, allow/deny lists, and custom models (BYOK)
 ├── mcp.json            # MCP integrations
 ├── droids/             # Custom sub-agents
 ├── commands/           # Custom slash commands
@@ -260,18 +259,19 @@ droid
   詳しく見る: [設定](/jp/cli/configuration/settings) | [カスタムスラッシュコマンド](/jp/cli/configuration/custom-slash-commands) | [カスタムDroid](/jp/cli/configuration/custom-droids) | [MCP設定](/jp/cli/configuration/mcp)
 </Tip>
 
-### config.json - 独自キーの使用
+### カスタムモデル - 独自キーの使用
 
-独自のAPIキーを使用してカスタムモデルを構成：
+独自のAPIキーを使用してカスタムモデルを構成するには、`~/.factory/settings.json`の`customModels`配列に追加します：
 
 ```json
 {
-  "models": [
+  "customModels": [
     {
-      "provider": "openrouter",
-      "name": "anthropic/claude-3.5-sonnet",
-      "apiKey": "your-api-key-here",
-      "displayName": "Claude 3.5 Sonnet (OpenRouter)"
+      "model": "anthropic/claude-sonnet-4.5",
+      "displayName": "Claude Sonnet 4.5 (OpenRouter)",
+      "baseUrl": "https://openrouter.ai/api/v1",
+      "apiKey": "${OPENROUTER_API_KEY}",
+      "provider": "generic-chat-completion-api"
     }
   ]
 }
@@ -286,8 +286,8 @@ droid
     選択したプロバイダーのJSON設定をコピーします
   </Step>
 
-  <Step title="config.jsonに追加">
-    設定を`~/.factory/config.json`に貼り付け、APIキーを追加します
+  <Step title="settings.jsonに追加">
+    エントリを`~/.factory/settings.json`の`customModels`配列に貼り付け、APIキーを追加します。`~/.factory/config.json`内のカスタムモデルは読み込まれなくなりました。
   </Step>
 
   <Step title="モデルを選択">

diff --git a/docs/jp/enterprise/models-llm-gateways-and-integrations.mdx b/docs/jp/enterprise/models-llm-gateways-and-integrations.mdx
@@ -37,7 +37,7 @@ Factory は2つの方法でゲートウェイと連携します：
 1. **直接設定されたゲートウェイエンドポイント**
    - `.factory/settings.json` は特定のプロバイダー向けにゲートウェイベース URL を指定できます。
    - 環境変数で呼び出しをルーティングできます（例：`ANTHROPIC_BASE_URL`、`OPENAI_BASE_URL`）。
-   - [BYOK](/jp/cli/byok/overview) 経由で設定されたカスタムモデルは、`base_url` とプロバイダー固有の設定を使用してゲートウェイエンドポイントを指すことができるため、モデルが内蔵かカスタムかに関係なく同じゲートウェイポリシーが適用されます。
+   - [BYOK](/jp/cli/byok/overview) 経由で設定されたカスタムモデルは、`baseUrl` とプロバイダー固有の設定を使用してゲートウェイエンドポイントを指すことができるため、モデルが内蔵かカスタムかに関係なく同じゲートウェイポリシーが適用されます。
 
 2. **組織レベルのゲートウェイポリシー**
    - 組織管理者は、すべてのモデルトラフィックが特定のゲートウェイを経由することを要求できます。