@minniexcode/codex-switch 0.1.0 → 0.1.1

package/docs/cli-usage.md

@@ -1,223 +1,282 @@
-# codex-switch CLI Usage
-
-This document describes the current CLI contract for `@minniexcode/codex-switch` at version `0.1.0`.
-
-Executable command name:
-
-```bash
-codexs
-```
-
-## 1. Version Context
-
-The current package version in this repository is `0.1.0`.
-
-This is the first stable release line. The command surface already exists, and this version focuses on keeping workflow guidance, help text, and implementation behavior aligned.
-
-## 2. Primary Workflows
-
-### 2.1 Direct Providers
-
-```bash
-codexs init
-codexs add <provider> --profile <name> --api-key <key>
-codexs switch <provider>
-codexs status
-codexs doctor
-```
-
-Intent:
-
-- `init` prepares the `codex-switch` tool home.
-- `add` creates a managed provider record.
-- `switch` projects the selected provider into the target Codex runtime.
-- `status` summarizes tool-home, runtime, provider, and health state.
-- `doctor` gives deeper repair-oriented diagnostics.
-
-### 2.2 GitHub Copilot
-
-```bash
-codexs init
-codexs login copilot
-codexs add <provider> --copilot --profile <name>
-codexs switch <provider>
-codexs status
-codexs doctor
-```
-
-Important notes:
-
-- `login copilot` is the upstream onboarding command.
-- The current implementation prefers the bundled Copilot CLI from the managed runtime and falls back to `PATH` when needed.
-- `login copilot` succeeds only after auth readiness is rechecked.
-- `add --copilot` does not install or log in to Copilot for you.
-
-## 3. Advanced Adopt Workflow
-
-Use `migrate` only when you already have Codex runtime state that should be adopted into managed `providers.json` state.
-
-```bash
-codexs init
-codexs migrate
-```
-
-`migrate` is an advanced adopt helper. It is not the default first step for fresh installs.
-
-Current behavior:
-
-- It reads `config.toml` profiles from the target Codex runtime.
-- It can collect missing provider details in TTY mode.
-- It can merge into or overwrite existing managed provider state.
-- It still fails fast in non-TTY and `--json` runs when interactive input would be required.
-
-## 4. Deprecated Entry
-
-```bash
-codexs setup
-```
-
-`setup` is deprecated. It is kept only to direct callers toward `init` or `migrate`, and it no longer performs initialization or migration work.
-
-## 5. Global Contract
-
-### 5.1 Global Flags
-
-```bash
---json
---codex-dir <path>
---help
---version
-```
-
-### 5.2 Environment Variables
-
-```bash
-CODEXS_HOME
-CODEXS_CODEX_DIR
-```
-
-### 5.3 Runtime Model
-
-Tool home:
-
-```text
-~/.config/codex-switch/
-  codex-switch.json
-  providers.json
-  backups/
-  runtime/
-  runtimes/
-```
-
-Target Codex runtime:
-
-```text
-~/.codex/
-  config.toml
-  auth.json
-```
-
-Meaning:
-
-- `providers.json` is the managed provider registry.
-- `codex-switch.json` stores tool-level metadata such as `defaultCodexDir`.
-- `config.toml` remains the active runtime routing file.
-- `auth.json` remains the active auth projection file.
-
-## 6. Command Categories
-
-Read commands:
-
-```bash
-codexs list
-codexs show <provider>
-codexs current
-codexs status
-codexs config show [profile]
-codexs config list-profiles
-codexs bridge status [provider]
-codexs backups list
-codexs doctor
-```
-
-Change commands:
-
-```bash
-codexs init
-codexs login copilot
-codexs migrate
-codexs add <provider>
-codexs edit <provider>
-codexs switch <provider>
-codexs remove <provider>
-codexs import <file>
-codexs export <file>
-codexs bridge start [provider]
-codexs bridge stop [provider]
-codexs rollback [backup-id]
-```
-
-## 7. Selected Command Semantics
-
-### `init`
-
-- Creates `codex-switch.json` and `providers.json` under the tool home when they do not exist yet.
-- Does not create or validate `config.toml`, `auth.json`, or the target Codex directory.
-- When `--codex-dir` is passed explicitly during first-time initialization, it can persist `defaultCodexDir`.
-
-### `login copilot`
-
-- Supports `copilot` and `github-copilot` as the current upstream name.
-- Installs the local Copilot SDK under the tool home when needed.
-- Invokes the official Copilot CLI for login when readiness is not already present.
-- Requires a real TTY and does not support `--json`.
-
-### `status`
-
-- Reports the target Codex runtime and the tool-home root.
-- Reports the current profile and whether it maps to a managed provider.
-- Adds bridge, Copilot SDK, and upstream auth signals when the active provider uses a local runtime bridge.
-- Does not mutate any files.
-
-### `list`
-
-- Lists managed providers together with their linked profile.
-- Distinguishes provider type using the public values `direct` and `copilot`.
-- Marks the current provider only when the active runtime can be mapped back to one unique managed provider.
-- When the active profile is shared by multiple providers, it does not invent a single current provider and should instead surface the ambiguity.
-- TTY provider pickers used by commands such as `switch` and `show` follow the same visibility rules for profile, provider type, and current-state hints.
-
-### `doctor`
-
-- Checks expected config files, provider/profile consistency, and Codex CLI availability.
-- Adds bridge and Copilot dependency diagnostics for Copilot-backed providers.
-- Returns repair-oriented issues intended for both human users and AI agents.
-
-### `switch`
-
-- Direct providers rewrite `auth.json` as an API-key projection and update the active runtime profile.
-- Copilot bridge providers also project the local bridge secret into the runtime while managing bridge routing.
-- Managed writes are backed up and rolled back on failure.
-- When `<provider>` is omitted in a TTY, the interactive provider selector should show profile, provider type, and current-state hints using the same rules as `list`.
-
-### `migrate`
-
-- Adopts unmanaged runtime profiles into managed `providers.json` state.
-- Still relies on interactive profile selection and provider-detail collection in this release.
-- Should be treated as an advanced adopt tool, not as the normal onboarding path.
-
-## 8. Automation Boundaries
-
-- Progressive prompts run only in a real TTY and never under `--json`.
-- Human write commands may prompt for missing inputs or dangerous-action confirmation.
-- Automation should pass explicit arguments and prefer `--json`.
-- `login copilot` is TTY-only.
-- `migrate` is not yet a complete non-interactive workflow.
-
-## 9. Related Docs
-
-- [README](../README.md)
-- [Chinese README](../README.CN.md)
-- [AI README](../README.AI.md)
-- [Product Overview](./codex-switch-product-overview.md)
-- [Release PRD 0.1.0](./PRD/codex-switch-prd-v0.1.0.md)
+# codex-switch CLI Usage
+
+This document describes the current CLI contract for `@minniexcode/codex-switch` at version `0.1.1`.
+
+Executable command name:
+
+```bash
+codexs
+```
+
+## 1. Version Context
+
+The current package version in this repository is `0.1.1`.
+
+This release line targets Codex `0.134.0+`. The public contract assumes runtime routing is selected by top-level `model` plus `model_provider`, while legacy `profile` and `[profiles.*]` remain inspect-and-adopt inputs instead of the recommended runtime path.
+
+## 2. Primary Workflows
+
+### 2.1 Direct Providers
+
+```bash
+codexs init
+codexs add <provider> --model <model> --api-key <key> [--base-url <url>]
+codexs switch <provider>
+codexs status
+codexs doctor
+```
+
+Intent:
+
+- `init` prepares the `codex-switch` tool home.
+- `add` creates a managed provider record with a target model and provider route identity.
+- `switch` projects the selected provider into the target Codex runtime.
+- `status` summarizes tool-home, runtime, provider, and health state.
+- `doctor` gives deeper repair-oriented diagnostics.
+
+### 2.2 GitHub Copilot
+
+```bash
+codexs init
+codexs login copilot
+codexs add <provider> --copilot --model <model>
+codexs switch <provider>
+codexs status
+codexs doctor
+```
+
+Important notes:
+
+- `login copilot` is the upstream onboarding command.
+- The current implementation prefers the bundled Copilot CLI from the managed runtime and falls back to `PATH` when needed.
+- `login copilot` succeeds only after auth readiness is rechecked.
+- `add --copilot` does not install or log in to Copilot for you.
+
+## 3. Runtime Route Contract
+
+For Codex `0.134.0+`, the active runtime route is selected through top-level `model` and `model_provider` in `config.toml`.
+
+`codex-switch` writes that route as its primary runtime projection:
+
+- top-level `model`
+- top-level `model_provider`
+- `[model_providers.<id>]`
+- `auth.json` when direct auth projection is required
+
+Managed provider projection intentionally avoids these legacy fields:
+
+- `model_providers.<id>.env_key`
+- `model_providers.<id>.env_key_instructions`
+
+Managed provider projection fixes these fields for OpenAI-compatible direct routes:
+
+- `wire_api = "responses"`
+- `requires_openai_auth = true`
+
+Compatibility notes:
+
+- `--profile` is accepted as an alias for the managed `model_provider` id.
+- legacy top-level `profile` and `[profiles.*]` may still appear in existing runtime state
+- `migrate`, `config show`, `config list-profiles`, and `doctor` can still inspect those legacy structures
+- new managed runtime projection should be described as route-first, not profile-first
+
+Example managed direct-provider projection:
+
+```toml
+model = "gpt-5.5"
+model_provider = "proxy"
+
+[model_providers.proxy]
+name = "proxy"
+base_url = "https://proxy.example.com/v1"
+wire_api = "responses"
+requires_openai_auth = true
+```
+
+Authentication projection for the direct path remains:
+
+```json
+{
+  "OPENAI_API_KEY": "sk-xxx"
+}
+```
+
+## 4. Advanced Adopt Workflow
+
+Use `migrate` only when you already have Codex runtime state that should be adopted into managed `providers.json` state.
+
+```bash
+codexs init
+codexs migrate
+```
+
+`migrate` is an advanced adopt helper. It is not the default first step for fresh installs.
+
+Current behavior:
+
+- It can inspect legacy runtime `profile` and `[profiles.*]` state from the target Codex runtime.
+- It can collect missing provider details in TTY mode.
+- It can merge into or overwrite existing managed provider state.
+- It still fails fast in non-TTY and `--json` runs when interactive input would be required.
+
+## 5. Deprecated Entry
+
+```bash
+codexs setup
+```
+
+`setup` is deprecated. It is kept only to direct callers toward `init` or `migrate`, and it no longer performs initialization or migration work.
+
+## 6. Global Contract
+
+### 6.1 Global Flags
+
+```bash
+--json
+--codex-dir <path>
+--help
+--version
+```
+
+### 6.2 Environment Variables
+
+```bash
+CODEXS_HOME
+CODEXS_CODEX_DIR
+```
+
+### 6.3 Runtime Model
+
+Tool home:
+
+```text
+~/.config/codex-switch/
+  codex-switch.json
+  providers.json
+  backups/
+  runtime/
+  runtimes/
+```
+
+Target Codex runtime:
+
+```text
+~/.codex/
+  config.toml
+  auth.json
+```
+
+Meaning:
+
+- `providers.json` is the managed provider registry.
+- `codex-switch.json` stores tool-level metadata such as `defaultCodexDir`.
+- `config.toml` remains the active runtime routing file.
+- `auth.json` remains the active auth projection file.
+
+## 7. Command Categories
+
+Read commands:
+
+```bash
+codexs list
+codexs show <provider>
+codexs current
+codexs status
+codexs config show [profile]
+codexs config list-profiles
+codexs bridge status [provider]
+codexs backups list
+codexs doctor
+```
+
+Change commands:
+
+```bash
+codexs init
+codexs login copilot
+codexs migrate
+codexs add <provider>
+codexs edit <provider>
+codexs switch <provider>
+codexs remove <provider>
+codexs import <file>
+codexs export <file>
+codexs bridge start [provider]
+codexs bridge stop [provider]
+codexs rollback [backup-id]
+```
+
+## 8. Selected Command Semantics
+
+### `init`
+
+- Creates `codex-switch.json` and `providers.json` under the tool home when they do not exist yet.
+- Does not create or validate `config.toml`, `auth.json`, or the target Codex directory.
+- When `--codex-dir` is passed explicitly during first-time initialization, it can persist `defaultCodexDir`.
+
+### `login copilot`
+
+- Supports `copilot` and `github-copilot` as the current upstream name.
+- Installs the local Copilot SDK under the tool home when needed.
+- Invokes the official Copilot CLI for login when readiness is not already present.
+- Requires a real TTY and does not support `--json`.
+
+### `status`
+
+- Reports the target Codex runtime and the tool-home root.
+- Reports the active model and active `model_provider` route.
+- Can still surface legacy profile-derived observations when inspecting older runtime state.
+- Adds bridge, Copilot SDK, and upstream auth signals when the active provider uses a local runtime bridge.
+- Does not mutate any files.
+
+### `list`
+
+- Lists managed providers together with their linked route identity.
+- Distinguishes provider type using the public values `direct` and `copilot`.
+- Marks the current provider only when the active runtime can be mapped back to one unique managed provider.
+- When the active route is shared by multiple providers, it does not invent a single current provider and should instead surface the ambiguity.
+- TTY provider pickers used by commands such as `switch` and `show` follow the same visibility rules for route, provider type, and current-state hints.
+
+### `doctor`
+
+- Checks expected config files, managed-provider consistency, and Codex CLI availability.
+- Inspects both route-first runtime state and legacy profile state when needed.
+- Adds bridge and Copilot dependency diagnostics for Copilot-backed providers.
+- Returns repair-oriented issues intended for both human users and AI agents.
+
+### `switch`
+
+- Projects direct providers by rewriting top-level `model`, top-level `model_provider`, the managed `[model_providers.<id>]` block, and `auth.json`.
+- Cleans legacy projected `env_key` and `env_key_instructions` fields before writing the managed provider route.
+- Copilot bridge providers also project the local bridge secret into the runtime while managing bridge routing.
+- Managed writes are backed up and rolled back on failure.
+- When `<provider>` is omitted in a TTY, the interactive provider selector should show route, provider type, and current-state hints using the same rules as `list`.
+
+### `add` and `edit`
+
+- Create or update managed provider records rather than editing runtime files directly.
+- Treat `--profile` only as an alias for the managed `model_provider` id.
+- Clean old `env_key` and `env_key_instructions` fields from managed projection during subsequent switching.
+
+### `migrate`
+
+- Adopts unmanaged runtime route or legacy profile state into managed `providers.json` state.
+- Still relies on interactive route/profile selection and provider-detail collection in this release.
+- Should be treated as an advanced adopt tool, not as the normal onboarding path.
+
+## 9. Automation Boundaries
+
+- Progressive prompts run only in a real TTY and never under `--json`.
+- Human write commands may prompt for missing inputs or dangerous-action confirmation.
+- Automation should pass explicit arguments and prefer `--json`.
+- `login copilot` is TTY-only.
+- `migrate` is not yet a complete non-interactive workflow.
+
+## 10. Related Docs
+
+- [README](../README.md)
+- [Chinese README](../README.CN.md)
+- [AI README](../README.AI.md)
+- [Product Overview](./codex-switch-product-overview.md)
+- [Release PRD 0.1.1](./PRD/codex-switch-prd-v0.1.1.md)
+- [Release Design 0.1.1](./Design/codex-switch-v0.1.1-design.md)

package/docs/codex-switch-command-design.md

@@ -1,7 +1,7 @@
 # codex-switch 命令设计说明
 
 > 状态说明：这份文档是历史跨版本参考，不是当前 release contract。
-> 当前事实源请改看 [`docs/cli-usage.md`](./cli-usage.md)、[`docs/PRD/codex-switch-prd-v0.1.0.md`](./PRD/codex-switch-prd-v0.1.0.md)、[`docs/Design/codex-switch-v0.1.0-design.md`](./Design/codex-switch-v0.1.0-design.md)。
+> 当前事实源请改看 [`docs/cli-usage.md`](./cli-usage.md)、[`docs/PRD/codex-switch-prd-v0.1.1.md`](./PRD/codex-switch-prd-v0.1.1.md)、[`docs/Design/codex-switch-v0.1.1-design.md`](./Design/codex-switch-v0.1.1-design.md)。
 
 ## 文档信息
 

package/docs/codex-switch-product-overview.md

@@ -4,15 +4,15 @@
 
 这份文档介绍当前活跃产品事实源下的 `codex-switch` 产品定位。
 
-当前 release contract 以这些文档为准：
+当前 release contract 以这些文档为准：
 
 - [`cli-usage.md`](./cli-usage.md)
-- [`PRD/codex-switch-prd-v0.1.0.md`](./PRD/codex-switch-prd-v0.1.0.md)
-- [`Design/codex-switch-v0.1.0-design.md`](./Design/codex-switch-v0.1.0-design.md)
+- [`PRD/codex-switch-prd-v0.1.1.md`](./PRD/codex-switch-prd-v0.1.1.md)
+- [`Design/codex-switch-v0.1.1-design.md`](./Design/codex-switch-v0.1.1-design.md)
 
 ## 产品概述
 
-`codex-switch` 是一个本地 provider 管理 CLI，用于管理和切换目标 Codex runtime 的 provider/profile 配置，同时把工具自己的管理态保存在独立 tool home 下。
+`codex-switch` 是一个本地 provider 管理 CLI，用于管理和切换目标 Codex runtime 的 provider/model-provider 路由配置，同时把工具自己的管理态保存在独立 tool home 下。
 
 它不是旧 `setup` 小工具，也不是围绕单目录 `~/.codex` 组织全部状态的脚本集合。
 
@@ -48,11 +48,11 @@ target Codex runtime：
 
 ## 核心使用流程
 
-Direct 主路径：
+Direct 主路径：
 
 ```bash
 codexs init
-codexs add <provider> --profile <name> --api-key <key>
+codexs add <provider> --model <model> --api-key <key> [--base-url <url>]
 codexs switch <provider>
 codexs status
 codexs doctor
@@ -63,7 +63,7 @@ Copilot 主路径：
 ```bash
 codexs init
 codexs login copilot
-codexs add <provider> --copilot --profile <name>
+codexs add <provider> --copilot --model <model>
 codexs switch <provider>
 codexs status
 codexs doctor
@@ -78,9 +78,10 @@ codexs migrate
 
 ## 当前产品判断
 
-`0.1.0` 的重点不是再加新命令，而是让用户在 README、help 和输出第一屏就能理解：
+`0.1.1` 的重点不是再加新命令，而是让用户在 README、help 和输出第一屏就能理解：
 
-- fresh install 应先走什么
-- Copilot 路径和 direct 路径有什么区别
-- `migrate` 何时才该使用
-- `status` / `doctor` 如何帮助定位下一步
+- fresh install 应先走什么
+- Copilot 路径和 direct 路径有什么区别
+- `migrate` 何时才该使用
+- `status` / `doctor` 如何帮助定位下一步
+- 当前运行态是用顶层 `model` 与 `model_provider` 选择活动路由

package/docs/codex-switch-technical-architecture.md

@@ -1,7 +1,7 @@
 # codex-switch 技术架构设计
 
 > 状态说明：这份文档是历史跨版本参考，不是当前 release contract。
-> 当前事实源请改看 [`docs/cli-usage.md`](./cli-usage.md)、[`docs/PRD/codex-switch-prd-v0.1.0.md`](./PRD/codex-switch-prd-v0.1.0.md)、[`docs/Design/codex-switch-v0.1.0-design.md`](./Design/codex-switch-v0.1.0-design.md)。
+> 当前事实源请改看 [`docs/cli-usage.md`](./cli-usage.md)、[`docs/PRD/codex-switch-prd-v0.1.1.md`](./PRD/codex-switch-prd-v0.1.1.md)、[`docs/Design/codex-switch-v0.1.1-design.md`](./Design/codex-switch-v0.1.1-design.md)。
 
 ## 文档信息
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@minniexcode/codex-switch",
-  "version": "0.1.0",
-  "description": "Local-first CLI for managing and switching Codex provider/profile configuration.",
+  "version": "0.1.1",
+  "description": "Local-first CLI for managing and switching Codex provider/model-provider routing.",
   "license": "MIT",
   "type": "commonjs",
   "bin": {