@minniexcode/codex-switch 0.2.0 → 0.2.2

package/docs/cli-usage.md

@@ -1,298 +1,130 @@
-# codex-switch CLI Usage
+# CLI Usage
 
-This document describes the current `0.1.5` repository development-line CLI contract for `@minniexcode/codex-switch`, including the Copilot Bridge process-visibility boundary.
+This document describes the current `0.2.1` repository development-line CLI contract for `@minniexcode/codex-switch`.
 
-Executable command name:
+`codex-switch` is a local-first provider/model-provider management CLI for Codex. It manages local provider records and projects the active Codex route into `config.toml` and `auth.json`.
 
-```bash
-codexs
-```
-
-## 1. Version Context
-
-The current package version in this repository is `0.1.5`.
-
-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. The current `0.1.5` development line adds Copilot Bridge process visibility, defensive SDK-event normalization, and unknown-event redaction hardening without expanding the provider command surface.
-
-## 2. Primary Workflows
-
-### 2.1 Direct Providers
-
-```bash
-codexs init
-codexs add <provider> --profile <model-provider-id> --model <model> --api-key <key> [--base-url <url>]
-codexs switch <provider>
-codexs status
-codexs doctor
-```
+## Version
 
-Intent:
+Current package version: `0.2.1`
 
-- `init` prepares the `codex-switch` tool home.
-- `add` creates a managed provider record with a target model and provider route identity.
-- Non-interactive runs should pass `--profile` explicitly; TTY mode can prompt for missing required fields.
-- `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.
+This line targets Codex `0.134.0+`, where the active route is selected by top-level `model` plus `model_provider`. Legacy top-level `profile` and `[profiles.*]` sections may still be inspected for migration/adoption, but they are not the recommended managed route.
 
-### 2.2 GitHub Copilot
+## Primary Workflow
 
 ```bash
 codexs init
-codexs login copilot
-codexs add <provider> --copilot --profile <model-provider-id> --model <model>
-codexs switch <provider>
+codexs add packycode --profile packycode --model gpt-5 --api-key sk-xxx --base-url https://api.example/v1
+codexs switch packycode
 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.
-- Non-interactive Copilot adds should also pass `--profile` explicitly; TTY mode can still collect missing required fields.
-- Copilot runtime paths require Node.js `>=20`; direct providers remain supported on Node.js `>=18`.
-- The Copilot bridge is experimental and targets simple text-oriented turns through the local OpenAI-compatible bridge.
-
-## 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`.
+`--profile` is a CLI alias for the managed `model_provider` id.
 
-`codex-switch` writes that route as its primary runtime projection:
+## Commands
 
-- 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`
-
-Copilot bridge projection also writes:
-
-- `stream_idle_timeout_ms = 300000`
-
-Compatibility notes:
-
-- `--profile` is accepted as an alias for the managed `model_provider` id.
-- automation should still pass `--profile` explicitly instead of relying on prompts
-- 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:
+### `init`
 
-```toml
-model = "gpt-5.5"
-model_provider = "proxy"
+Initializes the `codex-switch` tool home. It creates `codex-switch.json` and `providers.json` when missing. It does not require a target Codex `config.toml`.
 
-[model_providers.proxy]
-name = "proxy"
-base_url = "https://proxy.example.com/v1"
-wire_api = "responses"
-requires_openai_auth = true
-```
+### `migrate`
 
-Authentication projection for the direct path remains:
+Advanced adopt helper for existing Codex config. Use it only when existing route/profile state should be copied into managed `providers.json`.
 
-```json
-{
-  "OPENAI_API_KEY": "sk-xxx"
-}
-```
-
-## 4. Advanced Adopt Workflow
+### `list`
 
-Use `migrate` only when you already have Codex runtime state that should be adopted into managed `providers.json` state.
+Lists managed providers with their model-provider ids, model hints, tags, notes, and current-state mapping. Human output does not expose a provider-type column because `0.2.1` has only the provider-management path.
 
-```bash
-codexs init
-codexs migrate
-```
+### `show <provider>`
 
-`migrate` is an advanced adopt helper. It is not the default first step for fresh installs.
+Shows one provider record. Human output masks the API key; JSON output returns the local provider payload.
 
-Current behavior:
+### `current`
 
-- 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.
+Reads the current top-level `model` and `model_provider` from `config.toml` and maps it back to a managed provider when possible.
 
-## 5. Deprecated Entry
+### `status`
 
-```bash
-codexs setup
-```
+Reports target Codex directory, tool-home root, current model route, mapping state, auth projection state, warnings, and next step. It does not report bridge runtime health.
 
-`setup` is deprecated. It is kept only to direct callers toward `init` or `migrate`, and it no longer performs initialization or migration work.
+### `config show`
 
-## 6. Global Contract
+Shows the current route summary and recognizable legacy profile view.
 
-### 6.1 Global Flags
+### `config list-profiles`
 
-```bash
---json
---codex-dir <path>
---help
---version
-```
+Lists recognizable legacy config profiles with managed-state hints for adoption and diagnostics.
 
-### 6.2 Environment Variables
+### `add`
 
 ```bash
-CODEXS_HOME
-CODEXS_CODEX_DIR
+codexs add <provider> --profile <model-provider-id> --model <model> --api-key <key> [--base-url <url>] [--note <text>] [--tag <tag> ...]
 ```
 
-### 6.3 Runtime Model
+Adds a provider to `providers.json`, creates or updates the matching `[model_providers.<id>]` section, and backs up managed files before writing.
 
-Tool home:
+### `edit`
 
-```text
-~/.config/codex-switch/
-  codex-switch.json
-  providers.json
-  backups/
-  runtime/
-  runtimes/
-```
+Updates selected fields on a provider record and repairs the matching model-provider projection when needed.
 
-Target Codex runtime:
+### `switch`
 
-```text
-~/.codex/
-  config.toml
-  auth.json
-```
+Switches the active Codex route to a managed provider by writing top-level `model` and `model_provider`, updating the matching model-provider section, and projecting API-key auth.
 
-Meaning:
+### `remove`
 
-- `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.
+Removes a provider from `providers.json`. Non-interactive and JSON runs require `--force`. Removing a provider that owns the active route may require `--switch-to` first.
 
-## 7. Command Categories
+### `import`
 
-Read commands:
+Replaces or merges `providers.json` from an explicit JSON file under backup flow.
 
-```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
-```
+### `export`
 
-Change commands:
+Exports current `providers.json` to an explicit file. Use `--force` to overwrite in automation.
 
-```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]
-```
+### `backups list`
 
-## 8. Selected Command Semantics
+Lists managed backup manifests newest first.
 
-### `init`
+### `rollback`
 
-- 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`.
+Restores the latest managed backup or a specific backup id.
 
-### `login copilot`
+### `doctor`
 
-- 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`.
+Runs issue-first diagnostics across config, providers, auth projection, route drift, and Codex CLI availability.
 
-### `status`
+### `setup`
 
-- 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.
+Deprecated. It exists only to point users to `init` for fresh state or `migrate` for adoption.
 
-### `list`
+## Current Non-Goals
 
-- 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.
+`0.2.1` does not provide `login copilot`, `add --copilot`, `bridge start`, `bridge status`, `bridge stop`, Copilot SDK integration, GitHub device-flow login, HTTP proxy bridge, local bridge workers, background runtime services, bridge logs, or automatic migration of old bridge state.
 
-### `doctor`
+## JSON Contract
 
-- 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.
+`--json` renders the standard envelope:
 
-### `switch`
+```json
+{
+  "ok": true,
+  "command": "status",
+  "data": {},
+  "warnings": [],
+  "error": null
+}
+```
 
-- 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`.
+Failures render the same envelope to stderr with `ok: false` and a structured error.
 
-### `add` and `edit`
+## Fact Sources
 
-- Create or update managed provider records rather than editing runtime files directly.
-- Treat `--profile` only as an alias for the managed `model_provider` id.
-- Require explicit `--profile` in non-interactive usage; allow TTY prompts to fill it when omitted.
-- Clean old `env_key` and `env_key_instructions` fields from managed projection during subsequent switching.
+Current:
 
-### `migrate`
+- [PRD 0.2.1](./PRD/codex-switch-prd-v0.2.1.md)
+- [Design 0.2.1](./Design/codex-switch-v0.2.1-design.md)
 
-- 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)
-- [PRD 0.1.0](./PRD/codex-switch-prd-v0.1.0.md)
-- [PRD 0.1.1](./PRD/codex-switch-prd-v0.1.1.md)
-- [PRD 0.1.2](./PRD/codex-switch-prd-v0.1.2.md)
-- [PRD 0.1.3](./PRD/codex-switch-prd-v0.1.3.md)
-- [PRD 0.1.5](./PRD/codex-switch-prd-v0.1.5.md)
-- [Design 0.1.2](./Design/codex-switch-v0.1.2-design.md)
-- [Design 0.1.3](./Design/codex-switch-v0.1.3-design.md)
-- [Design 0.1.5](./Design/codex-switch-v0.1.5-design.md)
+Historical `0.1.x` and `0.2.0` docs remain archived for context only.

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.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)。
+> 当前事实源请改看 [`docs/cli-usage.md`](./cli-usage.md)、[`docs/PRD/codex-switch-prd-v0.2.1.md`](./PRD/codex-switch-prd-v0.2.1.md)、[`docs/Design/codex-switch-v0.2.1-design.md`](./Design/codex-switch-v0.2.1-design.md)。
 
 ## 文档信息
 

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

@@ -1,96 +1,49 @@
-# codex-switch 产品文档
-
-## 文档定位
-
-这份文档介绍当前活跃产品事实源下的 `codex-switch` 产品定位。
-
-当前仓库开发线 fact source 以这些文档为准：
-
-- [`cli-usage.md`](./cli-usage.md)
-- [`PRD/codex-switch-prd-v0.1.0.md`](./PRD/codex-switch-prd-v0.1.0.md)
-- [`PRD/codex-switch-prd-v0.1.1.md`](./PRD/codex-switch-prd-v0.1.1.md)
-- [`PRD/codex-switch-prd-v0.1.2.md`](./PRD/codex-switch-prd-v0.1.2.md)
-- [`PRD/codex-switch-prd-v0.1.3.md`](./PRD/codex-switch-prd-v0.1.3.md)
-- [`PRD/codex-switch-prd-v0.1.5.md`](./PRD/codex-switch-prd-v0.1.5.md)
-- [`Design/codex-switch-v0.1.2-design.md`](./Design/codex-switch-v0.1.2-design.md)
-- [`Design/codex-switch-v0.1.3-design.md`](./Design/codex-switch-v0.1.3-design.md)
-- [`Design/codex-switch-v0.1.5-design.md`](./Design/codex-switch-v0.1.5-design.md)
-
-## 产品概述
-
-`codex-switch` 是一个本地 provider 管理 CLI，用于管理和切换目标 Codex runtime 的 provider/model-provider 路由配置，同时把工具自己的管理态保存在独立 tool home 下。
-
-它不是旧 `setup` 小工具，也不是围绕单目录 `~/.codex` 组织全部状态的脚本集合。
-
-## 产品工作方式
-
-`codex-switch` 使用 dual-path model。
-
-tool home：
-
-```text
-~/.config/codex-switch/
-  codex-switch.json
-  providers.json
-  backups/
-  runtime/
-  runtimes/
-```
-
-target Codex runtime：
-
-```text
-~/.codex/
-  config.toml
-  auth.json
-```
-
-说明：
-
-- `providers.json` 不位于 `~/.codex`
-- `backups/` 不位于 `~/.codex`
-- tool home 承担管理态 SSOT
-- target runtime 承担受管运行态投影
-
-## 核心使用流程
-
-Direct 主路径：
-
-```bash
-codexs init
-codexs add <provider> --profile <model-provider-id> --model <model> --api-key <key> [--base-url <url>]
-codexs switch <provider>
-codexs status
-codexs doctor
-```
-
-Copilot 主路径：
-
-```bash
-codexs init
-codexs login copilot
-codexs add <provider> --copilot --profile <model-provider-id> --model <model>
-codexs switch <provider>
-codexs status
-codexs doctor
-```
-
-Advanced adopt helper：
-
-```bash
-codexs init
-codexs migrate
-```
-
-## 当前产品判断
-
-`0.1.1` 的重点不是再加新命令，而是让用户在 README、help 和输出第一屏就能理解：
-
-- fresh install 应先走什么
-- Copilot 路径和 direct 路径有什么区别
-- 非交互命令为什么应显式传 `--profile`，以及 TTY 模式下哪些缺失项可以补问
-- `migrate` 何时才该使用
-- `status` / `doctor` 如何帮助定位下一步
-- 当前运行态是用顶层 `model` 与 `model_provider` 选择活动路由
-
-`0.1.5` 是当前仓库开发线，重点不是扩展 provider 面，而是让已有 Copilot bridge 实验路径具备过程可见性：SDK 事件被归一化为稳定运行态事件，Responses 流可以显示 commentary/reasoning 信号，未知事件摘要会被脱敏和截断。当前实现边界仍然是：Copilot 路径要求 Node.js `>=20`，受管安装默认固定到 `@github/copilot-sdk@1.0.2`，本地 bridge 仍然只是面向 simple text-oriented turns 的 experimental bridge；Direct provider 路径继续支持 Node.js `>=18`。
+# codex-switch Product Overview
+
+Current version: `0.2.1`
+
+Current fact sources:
+
+- [`PRD/codex-switch-prd-v0.2.1.md`](./PRD/codex-switch-prd-v0.2.1.md)
+- [`Design/codex-switch-v0.2.1-design.md`](./Design/codex-switch-v0.2.1-design.md)
+- [`cli-usage.md`](./cli-usage.md)
+
+## Product
+
+`codex-switch` is a local-first provider/model-provider management CLI for Codex. It is for users who switch between OpenAI-compatible provider endpoints and want the switch to be explicit, backed up, and inspectable.
+
+The product owns three jobs:
+
+- Maintain managed provider records in `providers.json`.
+- Project Codex `model_provider` entries plus active top-level `model` / `model_provider` route.
+- Provide diagnostics, import/export, backups, and rollback for local state.
+
+## Current Workflow
+
+```bash
+codexs init
+codexs add <provider> --profile <model-provider-id> --model <model> --api-key <key> --base-url <url>
+codexs switch <provider>
+codexs status
+codexs doctor
+```
+
+`migrate` is an advanced adopt helper for existing Codex config, not the fresh-install default.
+
+## Current Boundary
+
+`0.2.1` deliberately narrows the product to provider management. It does not include account onboarding, hosted services, local proxy bridges, or background runtime orchestration. A future third-party-router integration may be considered separately, but no workflow or runtime code path is part of `0.2.1`.
+
+## Users
+
+- Developers who maintain several Codex-compatible provider endpoints.
+- AI agents that need a stable JSON command envelope and deterministic local state.
+- Operators who want backups and diagnostics before changing Codex config.
+
+## Non-Goals
+
+- Copilot SDK or GitHub login flows.
+- `login copilot`, `add --copilot`, or `bridge *` commands.
+- HTTP proxy bridge or local bridge worker runtime.
+- Account systems, cloud sync, or background services.
+- Automatic migration of old experimental runtime state.

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

@@ -1,35 +1,30 @@
 # codex-switch Technical Architecture
 
-## Current Fact Sources
+Current version: `0.2.1`
 
+Current fact sources:
+
+- [`PRD/codex-switch-prd-v0.2.1.md`](./PRD/codex-switch-prd-v0.2.1.md)
+- [`Design/codex-switch-v0.2.1-design.md`](./Design/codex-switch-v0.2.1-design.md)
 - [`cli-usage.md`](./cli-usage.md)
-- [`PRD/codex-switch-prd-v0.1.0.md`](./PRD/codex-switch-prd-v0.1.0.md)
-- [`PRD/codex-switch-prd-v0.1.1.md`](./PRD/codex-switch-prd-v0.1.1.md)
-- [`PRD/codex-switch-prd-v0.1.2.md`](./PRD/codex-switch-prd-v0.1.2.md)
-- [`PRD/codex-switch-prd-v0.1.3.md`](./PRD/codex-switch-prd-v0.1.3.md)
-- [`PRD/codex-switch-prd-v0.1.5.md`](./PRD/codex-switch-prd-v0.1.5.md)
-- [`Design/codex-switch-v0.1.0-design.md`](./Design/codex-switch-v0.1.0-design.md)
-- [`Design/codex-switch-v0.1.1-design.md`](./Design/codex-switch-v0.1.1-design.md)
-- [`Design/codex-switch-v0.1.2-design.md`](./Design/codex-switch-v0.1.2-design.md)
-- [`Design/codex-switch-v0.1.3-design.md`](./Design/codex-switch-v0.1.3-design.md)
-- [`Design/codex-switch-v0.1.5-design.md`](./Design/codex-switch-v0.1.5-design.md)
 
 ## Layers
 
 ```text
-src/commands/     CLI command registry, parsing helpers, dispatch handlers
-src/interaction/  TTY prompts and interactive input collection
-src/app/          application use cases and mutation orchestration
-src/domain/       provider/config/error contracts and pure planning logic
-src/storage/      filesystem persistence for tool home and Codex runtime files
-src/runtime/      external Codex and optional Copilot runtime adapters
-src/cli/          output rendering and compatibility entry helpers
-src/infra/        compatibility re-exports for older internal paths
+src/cli.ts          process entrypoint
+src/commands/      argument parsing, command registry, help, dispatch
+src/cli/           output rendering and CLI helpers
+src/interaction/   prompt collection for TTY workflows
+src/app/           command use cases
+src/domain/        provider/config/backup types and pure rules
+src/storage/       filesystem repositories and TOML/auth helpers
+src/runtime/       Codex CLI probing and invocation helpers
+src/infra/         compatibility facades for storage/runtime helpers
 ```
 
-Dependency direction should remain command/interaction -> app -> domain/storage/runtime. Domain code should not depend on CLI, storage, or runtime modules.
+`dist/` is generated by `npm run build`.
 
-## State Model
+## State Boundary
 
 Tool home stores managed state:
 
@@ -37,52 +32,42 @@ Tool home stores managed state:
 codex-switch.json
 providers.json
 backups/
-runtime/
-runtimes/
 ```
 
-Target Codex home stores runtime projection:
+Target Codex directory stores active Codex runtime files:
 
 ```text
 config.toml
 auth.json
 ```
 
-`providers.json` is the managed provider source of truth. `config.toml` and `auth.json` are projections for the selected target Codex runtime.
+The app layer should pass explicit paths into storage functions and avoid hidden global filesystem access beyond path resolution.
 
-## Switch Transaction
+## Provider Model
 
-`switch` is the central write workflow:
+`providers.json` stores provider records keyed by local provider name. Each provider points to a managed Codex `model_provider` id through its `profile` field. In current docs and UI, `--profile` is explained as this model-provider id alias.
 
-1. Read provider registry.
-2. Resolve the target provider and model.
-3. For Copilot providers, verify SDK install, Node runtime, upstream auth, and bridge health.
-4. Create a mutation backup.
-5. Project `model`, `model_provider`, and `[model_providers.<id>]`.
-6. Write `auth.json` with the Codex-facing bearer secret.
-7. Roll back touched files if a mutation step fails.
+Managed projection writes:
 
-Direct providers project their actual upstream API key as `OPENAI_API_KEY`. Copilot providers project only the local bridge bearer secret; GitHub/Copilot upstream tokens remain in the official Copilot runtime.
+- top-level `model`
+- top-level `model_provider`
+- `[model_providers.<id>]` with `name`, `base_url`, `wire_api = "responses"`, and `requires_openai_auth = true`
+- `auth.json` API-key projection
 
-## Copilot Runtime
+New managed writes do not create legacy `[profiles.*]` sections.
 
-The Copilot path is implemented as an experimental local bridge:
+## Mutations And Backups
 
-- SDK runtime is installed under the managed `runtimes/copilot` directory.
-- The managed installer defaults to `@github/copilot-sdk@1.0.2`.
-- Copilot paths require Node.js `>=20`; direct providers continue to support Node.js `>=18`.
-- Runtime validation separately rejects older or prerelease SDK installs, and SDK API shape is validated when creating the client or session.
-- The bridge exposes a minimal OpenAI-compatible `/v1/chat/completions` and `/v1/responses` surface for simple text-oriented turns.
-- The worker keeps one long-lived `CopilotClient`, creates one session per request, serializes requests, requires `abort()`, and treats `disconnect()` as best-effort cleanup rather than a compatibility gate.
-- Responses streaming emits initial SSE events before upstream completion and uses heartbeat comments while waiting.
+Mutating app services run through `runMutation`, acquire the lock, create backups for affected files, perform writes, and roll back when the mutation fails.
 
-## Testing
+Commands that mutate local state include `init`, `migrate`, `add`, `edit`, `switch`, `remove`, `import`, `export`, and `rollback`.
 
-Tests are plain Node specs run by `tests/run-tests.js`. The main verification commands are:
+## Diagnostics
 
-```bash
-npm run build
-npm test
-npx tsc --noEmit
-npm pack --dry-run
-```
+`status` is a lightweight current-state view. `doctor` is issue-first and checks config existence, providers existence, model-provider consistency, auth projection validity, route drift, and Codex CLI availability.
+
+Optional bridge or account-runtime checks are not part of `0.2.1` diagnostics.
+
+## Removed Runtime Experiments
+
+`0.2.1` removes current runtime code paths for Copilot SDK integration, GitHub device-flow login, HTTP proxy bridge, local bridge workers, bridge logs, and bridge runtime state. Historical docs describe those experiments, but current architecture does not expose them.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@minniexcode/codex-switch",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Local-first CLI for managing and switching Codex provider/model-provider routing.",
   "license": "MIT",
   "type": "commonjs",