@minniexcode/codex-switch 0.1.1 → 0.1.2

package/dist/runtime/copilot-bridge.js

@@ -138,13 +138,13 @@ async function probeCopilotBridgeRuntime(provider, persistedState, runtimeDir) {
 /**
  * Starts or reuses a Copilot bridge worker, then verifies its health before returning.
  */
-async function ensureCopilotBridge(providerName, provider, runtimeDir) {
-    return startOrReuseCopilotBridge(providerName, provider, runtimeDir);
+async function ensureCopilotBridge(providerName, provider, runtimeDir, runtimesDir) {
+    return startOrReuseCopilotBridge(providerName, provider, runtimeDir, runtimesDir);
 }
 /**
  * Starts or reuses a Copilot bridge worker and reports the chosen port.
  */
-async function startOrReuseCopilotBridge(providerName, provider, runtimeDir) {
+async function startOrReuseCopilotBridge(providerName, provider, runtimeDir, runtimesDir) {
     if (!(0, providers_1.isCopilotBridgeProvider)(provider)) {
         throw (0, errors_1.cliError)("RUNTIME_PROVIDER_INVALID", "Provider is not backed by a Copilot bridge runtime.", {
             provider: providerName,
@@ -208,6 +208,8 @@ async function startOrReuseCopilotBridge(providerName, provider, runtimeDir) {
                 CODEX_SWITCH_BRIDGE_PORT: String(selectedPort),
                 CODEX_SWITCH_BRIDGE_API_KEY: provider.apiKey,
                 CODEX_SWITCH_BRIDGE_BASE_URL: selectedBaseUrl,
+                CODEX_SWITCH_RUNTIME_DIR: runtimeDir ?? "",
+                CODEX_SWITCH_RUNTIMES_DIR: runtimesDir ?? "",
             },
         });
     }
@@ -285,19 +287,35 @@ function createCopilotBridgeRequestHandler(context) {
             }
             if (method === "POST" && url === "/v1/chat/completions") {
                 const body = await readJsonBody(request);
+                const timeoutMs = parseBridgeRequestTimeoutMs(body, "/v1/chat/completions");
                 const stream = Boolean(body.stream);
-                const payload = await context.executeChatCompletion(body);
                 if (stream) {
                     response.writeHead(200, {
                         "content-type": "text/event-stream",
                         "cache-control": "no-cache",
                         connection: "keep-alive",
                     });
-                    response.write(`data: ${JSON.stringify(payload)}\n\n`);
+                    const heartbeat = startSseHeartbeat(response);
+                    const payload = await context.executeChatCompletion(body, {
+                        timeoutMs,
+                        onTextDelta: (delta) => {
+                            response.write(`data: ${JSON.stringify({
+                                choices: [
+                                    {
+                                        index: 0,
+                                        delta: { content: delta },
+                                        finish_reason: null,
+                                    },
+                                ],
+                            })}\n\n`);
+                        },
+                    });
+                    clearInterval(heartbeat);
                     response.write("data: [DONE]\n\n");
                     response.end();
                     return;
                 }
+                const payload = await context.executeChatCompletion(body, { timeoutMs });
                 response.writeHead(200, { "content-type": "application/json" });
                 response.end(JSON.stringify(payload));
                 return;
@@ -305,20 +323,43 @@ function createCopilotBridgeRequestHandler(context) {
             if (method === "POST" && url === "/v1/responses") {
                 const body = await readJsonBody(request);
                 const normalized = normalizeResponsesRequest(body);
-                const payload = await context.executeChatCompletion({
+                const chatPayload = {
                     model: normalized.model,
                     messages: normalized.messages,
-                });
+                };
                 if (normalized.stream) {
                     response.writeHead(200, {
                         "content-type": "text/event-stream",
                         "cache-control": "no-cache",
                         connection: "keep-alive",
                     });
-                    writeResponsesStream(response, payload);
+                    const responseId = `resp_${Date.now()}`;
+                    const messageId = buildResponsesMessageId(responseId);
+                    writeResponsesStreamStart(response, responseId, normalized.model, messageId);
+                    const heartbeat = startSseHeartbeat(response);
+                    let text = "";
+                    const payload = await context.executeChatCompletion(chatPayload, {
+                        timeoutMs: normalized.timeoutMs,
+                        onTextDelta: (delta) => {
+                            text += delta;
+                            writeResponsesTextDelta(response, messageId, delta);
+                        },
+                        onTextDone: (doneText) => {
+                            if (text.length === 0) {
+                                text = doneText;
+                                writeResponsesTextDelta(response, messageId, doneText);
+                            }
+                        },
+                    });
+                    clearInterval(heartbeat);
+                    const outputText = text || getChatCompletionText(payload);
+                    writeResponsesStreamDone(response, responseId, normalized.model, messageId, outputText);
                     response.end();
                     return;
                 }
+                const payload = await context.executeChatCompletion(chatPayload, {
+                    timeoutMs: normalized.timeoutMs,
+                });
                 response.writeHead(200, { "content-type": "application/json" });
                 response.end(JSON.stringify(buildResponsesPayload(payload)));
                 return;
@@ -332,9 +373,9 @@ function createCopilotBridgeRequestHandler(context) {
             response.end(JSON.stringify({ error: { message: "Not found" } }));
         }
         catch (error) {
-            const statusCode = isCliError(error) && error.code === "BRIDGE_UNSUPPORTED_REQUEST" ? 400 : 500;
+            const statusCode = mapBridgeErrorStatus(error);
             response.writeHead(statusCode, { "content-type": "application/json" });
-            response.end(JSON.stringify({ error: { message: error instanceof Error ? error.message : String(error) } }));
+            response.end(JSON.stringify({ error: { message: error instanceof Error ? error.message : String(error), code: isCliError(error) ? error.code : "BRIDGE_RUNTIME_FAILURE" } }));
         }
     };
 }
@@ -354,8 +395,22 @@ function normalizeResponsesRequest(body) {
         model: payload.model,
         messages,
         stream: payload.stream === true,
+        timeoutMs: parseBridgeRequestTimeoutMs(body, "/v1/responses"),
     };
 }
+/**
+ * Extracts one optional request timeout for bridge-backed completions.
+ */
+function parseBridgeRequestTimeoutMs(body, endpoint) {
+    const timeoutMsValue = body.timeout_ms ?? body.timeoutMs;
+    if (timeoutMsValue === undefined) {
+        return undefined;
+    }
+    if (typeof timeoutMsValue !== "number" || !Number.isFinite(timeoutMsValue) || timeoutMsValue <= 0) {
+        throw (0, errors_1.cliError)("BRIDGE_UNSUPPORTED_REQUEST", `Copilot bridge ${endpoint} timeout must be a positive number when provided.`);
+    }
+    return timeoutMsValue;
+}
 function normalizeResponsesInput(input) {
     if (typeof input === "string") {
         return [{ role: "user", content: input }];
@@ -575,6 +630,118 @@ function writeResponsesStream(response, payload) {
         },
     });
 }
+function writeResponsesStreamStart(response, responseId, model, messageId) {
+    const createdAt = Math.floor(Date.now() / 1000);
+    const inProgressResponse = {
+        id: responseId,
+        object: "response",
+        created_at: createdAt,
+        model,
+        status: "in_progress",
+        output: [],
+        output_text: "",
+    };
+    writeSseEvent(response, "response.created", {
+        type: "response.created",
+        response: inProgressResponse,
+    });
+    writeSseEvent(response, "response.in_progress", {
+        type: "response.in_progress",
+        response: inProgressResponse,
+    });
+    writeSseEvent(response, "response.output_item.added", {
+        type: "response.output_item.added",
+        output_index: 0,
+        item: {
+            id: messageId,
+            type: "message",
+            status: "in_progress",
+            role: "assistant",
+            content: [],
+        },
+    });
+    writeSseEvent(response, "response.content_part.added", {
+        type: "response.content_part.added",
+        item_id: messageId,
+        output_index: 0,
+        content_index: 0,
+        part: {
+            type: "output_text",
+            text: "",
+            annotations: [],
+        },
+    });
+}
+function writeResponsesTextDelta(response, messageId, delta) {
+    if (delta.length === 0) {
+        return;
+    }
+    writeSseEvent(response, "response.output_text.delta", {
+        type: "response.output_text.delta",
+        item_id: messageId,
+        output_index: 0,
+        content_index: 0,
+        delta,
+    });
+}
+function writeResponsesStreamDone(response, responseId, model, messageId, outputText) {
+    const completedMessage = {
+        id: messageId,
+        type: "message",
+        status: "completed",
+        role: "assistant",
+        content: [
+            {
+                type: "output_text",
+                text: outputText,
+                annotations: [],
+            },
+        ],
+    };
+    writeSseEvent(response, "response.output_text.done", {
+        type: "response.output_text.done",
+        item_id: messageId,
+        output_index: 0,
+        content_index: 0,
+        text: outputText,
+    });
+    writeSseEvent(response, "response.content_part.done", {
+        type: "response.content_part.done",
+        item_id: messageId,
+        output_index: 0,
+        content_index: 0,
+        part: {
+            type: "output_text",
+            text: outputText,
+            annotations: [],
+        },
+    });
+    writeSseEvent(response, "response.output_item.done", {
+        type: "response.output_item.done",
+        output_index: 0,
+        item: completedMessage,
+    });
+    writeSseEvent(response, "response.completed", {
+        type: "response.completed",
+        response: {
+            id: responseId,
+            object: "response",
+            created_at: Math.floor(Date.now() / 1000),
+            model,
+            status: "completed",
+            output: [completedMessage],
+            output_text: outputText,
+        },
+    });
+}
+function startSseHeartbeat(response) {
+    return setInterval(() => {
+        response.write(": keep-alive\n\n");
+    }, 15000);
+}
+function getChatCompletionText(payload) {
+    return payload.choices?.[0]?.message?.content ?? "";
+}
 /**
  * Formats and writes one server-sent event frame.
  */
@@ -594,6 +761,21 @@ function buildResponsesMessageId(responseId) {
 function isCliError(error) {
     return Boolean(error && typeof error === "object" && typeof error.code === "string");
 }
+function mapBridgeErrorStatus(error) {
+    if (!isCliError(error)) {
+        return 500;
+    }
+    if (error.code === "BRIDGE_UNSUPPORTED_REQUEST") {
+        return 400;
+    }
+    if (error.code === "COPILOT_AUTH_REQUIRED") {
+        return 401;
+    }
+    if (error.code === "BRIDGE_UPSTREAM_TIMEOUT") {
+        return 504;
+    }
+    return 500;
+}
 /**
  * Returns a stable build identifier for the compiled bridge worker bundle.
  */

package/dist/runtime/copilot-cli.js

@@ -36,6 +36,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.setCopilotCliSpawnImplementation = setCopilotCliSpawnImplementation;
 exports.resetCopilotCliSpawnImplementation = resetCopilotCliSpawnImplementation;
 exports.checkCopilotCliAvailable = checkCopilotCliAvailable;
+exports.resolveCopilotCliInvocation = resolveCopilotCliInvocation;
 exports.runCopilotLogin = runCopilotLogin;
 const fs = __importStar(require("node:fs"));
 const path = __importStar(require("node:path"));
@@ -78,6 +79,12 @@ function checkCopilotCliAvailable(runtimesDir) {
         command: formatInvocation(invocation),
     };
 }
+/**
+ * Resolves the Copilot CLI invocation used by SDK clients and command probes.
+ */
+function resolveCopilotCliInvocation(args = [], runtimesDir) {
+    return getCopilotInvocation(args, runtimesDir);
+}
 /**
  * Launches the official `copilot login` flow in the current terminal.
  */

package/dist/runtime/copilot-installer.js

@@ -37,6 +37,10 @@ exports.setCopilotInstallerSpawnImplementation = setCopilotInstallerSpawnImpleme
 exports.resetCopilotInstallerSpawnImplementation = resetCopilotInstallerSpawnImplementation;
 exports.getCopilotRuntimeInstallDir = getCopilotRuntimeInstallDir;
 exports.getCopilotSdkPackageName = getCopilotSdkPackageName;
+exports.getSupportedCopilotSdkVersion = getSupportedCopilotSdkVersion;
+exports.getCopilotNodeRuntimeStatus = getCopilotNodeRuntimeStatus;
+exports.assertCopilotNodeRuntimeSupported = assertCopilotNodeRuntimeSupported;
+exports.isSupportedCopilotSdkVersion = isSupportedCopilotSdkVersion;
 exports.probeCopilotSdkInstall = probeCopilotSdkInstall;
 exports.installCopilotSdk = installCopilotSdk;
 const fs = __importStar(require("node:fs"));
@@ -45,7 +49,8 @@ const node_child_process_1 = require("node:child_process");
 const errors_1 = require("../domain/errors");
 const codex_paths_1 = require("../storage/codex-paths");
 const COPILOT_SDK_PACKAGE = "@github/copilot-sdk";
-const COPILOT_SDK_VERSION = "latest";
+const COPILOT_SDK_VERSION = "1.0.2";
+const COPILOT_MIN_NODE_MAJOR = 20;
 let spawnImplementation = node_child_process_1.spawnSync;
 /**
  * Overrides the spawn implementation for runtime installer tests.
@@ -76,6 +81,47 @@ function getCopilotRuntimeInstallDir(runtimesDir) {
 function getCopilotSdkPackageName() {
     return COPILOT_SDK_PACKAGE;
 }
+/**
+ * Returns the supported Copilot SDK package version installed by this release.
+ */
+function getSupportedCopilotSdkVersion() {
+    return COPILOT_SDK_VERSION;
+}
+/**
+ * Returns whether the active Node.js runtime can run the Copilot SDK path.
+ */
+function getCopilotNodeRuntimeStatus(version = process.versions.node) {
+    const major = Number(version.split(".")[0]);
+    if (Number.isInteger(major) && major >= COPILOT_MIN_NODE_MAJOR) {
+        return { ok: true, version };
+    }
+    return {
+        ok: false,
+        version,
+        required: `>=${String(COPILOT_MIN_NODE_MAJOR)}`,
+    };
+}
+/**
+ * Fails early when a command path requires the Copilot SDK runtime under Node.js <20.
+ */
+function assertCopilotNodeRuntimeSupported(version = process.versions.node) {
+    const status = getCopilotNodeRuntimeStatus(version);
+    if (!status.ok) {
+        throw (0, errors_1.cliError)("COPILOT_RUNTIME_NODE_UNSUPPORTED", "Copilot runtime support requires Node.js >=20. Direct providers continue to support Node.js >=18.", {
+            nodeVersion: status.version,
+            requiredNode: status.required,
+        });
+    }
+}
+/**
+ * Returns whether an installed Copilot SDK version is supported by this release.
+ */
+function isSupportedCopilotSdkVersion(version) {
+    if (!version || version.includes("-")) {
+        return false;
+    }
+    return compareSemver(version, COPILOT_SDK_VERSION) >= 0;
+}
 /**
  * Reports whether the optional Copilot SDK runtime is currently installed.
  */
@@ -153,6 +199,18 @@ function resolveNpmInstallCommand() {
         args: installArgs,
     };
 }
+function compareSemver(left, right) {
+    const leftParts = left.split(".").map((part) => Number(part));
+    const rightParts = right.split(".").map((part) => Number(part));
+    for (let index = 0; index < 3; index += 1) {
+        const leftPart = Number.isFinite(leftParts[index]) ? leftParts[index] : 0;
+        const rightPart = Number.isFinite(rightParts[index]) ? rightParts[index] : 0;
+        if (leftPart !== rightPart) {
+            return leftPart > rightPart ? 1 : -1;
+        }
+    }
+    return 0;
+}
 /**
  * Finds a locally available npm CLI script near the active Node runtime.
  */

package/dist/runtime/copilot-sdk-loader.js

@@ -36,6 +36,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.getCopilotSdkEntrypoint = getCopilotSdkEntrypoint;
 exports.loadCopilotSdk = loadCopilotSdk;
 const path = __importStar(require("node:path"));
+const node_module_1 = require("node:module");
 const errors_1 = require("../domain/errors");
 const copilot_installer_1 = require("./copilot-installer");
 /**
@@ -55,5 +56,7 @@ async function loadCopilotSdk(runtimesDir) {
             packageName: status.packageName,
         });
     }
-    return Promise.resolve(`${getCopilotSdkEntrypoint(runtimesDir)}`).then(s => __importStar(require(s)));
+    const runtimePackageJson = path.join(status.installDir, "package.json");
+    const runtimeRequire = (0, node_module_1.createRequire)(runtimePackageJson);
+    return runtimeRequire("@github/copilot-sdk");
 }

package/docs/Design/codex-switch-v0.1.0-design.md

@@ -1,152 +1,32 @@
-# codex-switch `0.1.0` Design
-
-## 文档信息
-
-- 文档类型：实现约束设计文档
-- 适用版本：`0.1.0`
-- 当前定位：release-hardening only
-- 关联 PRD：[`../PRD/codex-switch-prd-v0.1.0.md`](../PRD/codex-switch-prd-v0.1.0.md)
-- 关联 beta 设计：[`./codex-switch-v0.0.12-design.md`](./codex-switch-v0.0.12-design.md)
-
-## 1. 设计原则
-
-`0.1.0` 的实现只做 release-hardening，不新增命令面，不改 JSON envelope，不引入兼容层，也不把历史草案继续扩成平台设想。
-
-这个版本的实现目标是收口，不是扩张：
-
-- 把用户看见的主路径讲清楚。
-- 把 `list`、`status`、`doctor` 的可读语义讲清楚。
-- 把 `migrate` 和 `setup` 的产品定位讲清楚。
-- 把文档、help、输出、测试和包内容收口成同一套事实。
-
-## 2. 当前阻塞项
-
-实现收口前必须先正视以下阻塞项：
-
-1. `tests/` 仍被忽略，导致回归测试无法稳定版本化。
-2. README 仍引用不存在的 `docs/Tests/testing.md`，说明文档入口还未收口。
-3. 版本叙事仍以 `0.0.12` 为中心，`0.1.0` 还没有被写成稳定发布线。
-4. 主工作流、`migrate` 定位、`setup` 定位和真实实现状态还没有完全对齐。
-
-只要这些阻塞项还存在，就不应把当前实现视为 `0.1.0` ready。
-
-## 3. 收口矩阵
-
-以下子系统必须完成对应收口。
-
-| 子系统 | 必须稳定的内容 | 约束 |
-| --- | --- | --- |
-| 文档 | PRD、design、README、CLI usage、product overview、changelog、testing guide | 所有面向用户的文档必须与 `0.1.0` 事实一致 |
-| 帮助 | 顶层 help、命令 help、示例顺序 | direct/Copilot 主路径优先，`migrate` 降级，`setup` 仅保留 deprecated 语义 |
-| 输出 | `init`、`list`、`status`、`doctor`、`login` 的 human-readable 文案 | 只收口语义，不改 JSON envelope |
-| 读路径 | tool home / runtime separation、dual-path model、ambiguous active profile 处理 | 不新增兼容层，不伪造 current 状态 |
-| 测试 | release gate、回归测试、fixture 检查 | 回归测试必须落仓库，不能继续停留在忽略状态 |
-
-## 4. 必须稳定的用户可见语义
-
-### 4.1 `list`
-
-`list` 必须能让用户直接看出：
-
-- provider 属于 `direct` 还是 `copilot`
-- 哪个 provider 是 current
-- 当前 active profile 是否可唯一解析
-
-如果当前 active profile 对应多个 provider，就必须显式表现为 ambiguous，而不是把任何一个 provider 假装成 current。
-
-`list --json` 仍然使用既有 envelope，只允许追加字段，不允许改顶层契约。
-
-### 4.2 `status`
-
-`status` 必须把以下内容讲清楚：
-
-- tool home 是什么
-- target runtime 是什么
-- 当前 active provider 是什么
-- 当前路径是 direct 还是 Copilot
-- 下一步应该做什么
-
-`status` 是摘要，不是字段堆叠。输出顺序必须围绕“当前状态 -> 影响 -> 下一步”组织。
-
-### 4.3 `doctor`
-
-`doctor` 必须先给整体健康结论，再列 issue，再给修复建议。
-
-每条 issue 至少要表达：
-
-- 问题是什么
-- 为什么重要
-- 下一步怎么修
-
-`doctor` 的目标不是罗列内部数据结构，而是把用户推到下一步修复动作。
-
-### 4.4 provider picker
-
-list 和 provider picker 必须一致处理 ambiguous active profile。
-
-选择器提示至少要包含：
-
-- `profile`
-- `providerType`
-- `current` 标记，仅在唯一解析时出现
-
-### 4.5 命令定位
-
-`0.1.0` 还必须稳定以下产品定位：
-
-- 稳定命令面以 `init`、`login`、`list`、`show`、`current`、`status`、`doctor`、`config`、`add`、`edit`、`switch`、`remove`、`import`、`export`、`bridge`、`backups`、`rollback` 为准。
-- `migrate` 只能被表述为高级 adopt helper。
-- `setup` 只能被表述为 deprecated entry。
-- `--json` 顶层 envelope 继续固定为 `ok / command / data / warnings / error`。
-
-## 5. 文档同步要求
-
-以下面向用户的文档必须与 `0.1.0` 事实一致：
-
-- `README.md`
-- `README.CN.md`
-- `README.AI.md`
-- `docs/cli-usage.md`
-- `docs/codex-switch-product-overview.md`
-- `docs/PRD/codex-switch-prd-v0.1.0.md`
-- `docs/Design/codex-switch-v0.1.0-design.md`
-- `CHANGELOG.md`
-- `docs/Tests/testing.md`
-
-历史大文档不需要在本版全文重写，但必须明确它们只是历史参考，不是当前 release contract。
-
-## 6. 最小测试计划
-
-`0.1.0` 的最小测试计划必须包含以下内容：
-
-1. `npm run build`
-2. `npm test`
-3. `npx tsc --noEmit`
-4. `npm pack --dry-run`
-5. built CLI `--help`
-6. built CLI `--version`
-7. fresh direct provider flow
-8. fresh Copilot provider flow
-9. `list/status/doctor` 输出语义检查
-10. `migrate` 高级 adopt helper 检查
-11. `setup` deprecated entry 检查
-
-测试结论必须落在仓库中的正式测试内容里，不能继续依赖忽略目录或口头约定。
-
-## 7. 明确不做
-
-本版不做以下事情：
-
-- 新 upstream
-- GUI / TUI
-- daemon
-- plugin system
-- auto migration
-- 兼容层
-- dual-read / dual-write
-- 重新设计公开 JSON envelope
-- 重新扩张命令面
-
-## 8. 结论
-
-`0.1.0` 设计的核心不是“再造一个版本叙事”，而是把已存在的实现收口成稳定合同。实现只要偏离这条线，就不应被视为 `0.1.0` 的合理内容。
+# codex-switch v0.1.0 Design
+
+## Purpose
+
+`0.1.0` freezes the stable CLI shape and documents the current architecture instead of introducing a new runtime model.
+
+## Architecture
+
+- `src/commands/` parses and dispatches public commands.
+- `src/app/` owns use cases such as add, switch, status, doctor, bridge, and rollback.
+- `src/domain/` owns provider, config, setup, and error contracts.
+- `src/storage/` owns filesystem persistence for tool home and target Codex state.
+- `src/runtime/` owns Codex CLI and optional Copilot runtime integrations.
+
+## State Separation
+
+The tool home stores managed state and backups. The target Codex home receives runtime projections. This keeps provider registry edits transactional and makes rollback meaningful without claiming ownership of unrelated Codex files.
+
+## Projection
+
+Switching a provider projects:
+
+- top-level `model`
+- top-level `model_provider`
+- `[model_providers.<id>]`
+- `auth.json` with `OPENAI_API_KEY`
+
+Direct providers project the provider API key. Copilot providers project only the local bridge bearer secret; upstream GitHub/Copilot auth remains in the official runtime.
+
+## Error Model
+
+Command errors use stable CLI error codes and optional `details`. Command-specific errors may remain close to the command implementation when that keeps the public contract clearer than forcing every case into a shared diagnostic taxonomy.

package/docs/Design/codex-switch-v0.1.1-design.md

@@ -1,33 +1,22 @@
 # codex-switch v0.1.1 Design
 
-## Scope
+## Purpose
 
-- Support Codex `0.134.0+` only.
-- Treat top-level `model` and `model_provider` as the runtime routing source of truth.
-- Treat legacy top-level `profile` and legacy `[profiles.*]` sections as adopt-only and diagnostic inputs.
-- Project provider auth through `auth.json` with `OPENAI_API_KEY`.
-- Do not write `env_key` or `env_key_instructions` into managed `[model_providers.<id>]` sections.
+`0.1.1` is a documentation alignment release. The design work is to make the active docs tree match the stable implementation and remove obsolete development-version transition docs from the current fact surface.
 
-## Command Contract
+## Documentation Structure
 
-- `--profile <name>` remains a CLI alias for the stored `model_provider` id.
-- `--model <name>` stores the provider default switch model in `providers.json`.
-- `switch` writes top-level `model` and `model_provider`, repairs `[model_providers.<id>]`, rewrites `auth.json`, and removes the targeted legacy route selector/profile section.
-- `add` and `edit` repair `[model_providers.<id>]` and scrub `env_key` / `env_key_instructions`.
-- `remove --switch-to <provider-name>` switches by managed provider name, not by profile id.
+- `README.md`, `README.CN.md`, and `README.AI.md` describe the user-facing product.
+- `docs/cli-usage.md` is the command reference.
+- `docs/codex-switch-product-overview.md` is the product-level summary.
+- `docs/codex-switch-technical-architecture.md` is the implementation map.
+- `docs/PRD/` contains active version fact sources for `0.1.0`, `0.1.1`, and planned `0.1.2`.
+- `docs/Design/` contains matching design fact sources.
+- `docs/Reference/` keeps Codex configuration references.
+- `docs/Tests/testing.md` keeps the current verification contract.
 
-## Persistence
+## Rules
 
-- `providers.json` keeps `profile` as the persisted `model_provider` id alias.
-- `providers.json` adds `model` for default route projection.
-- Managed `[model_providers.<id>]` sections write:
-  - `base_url`
-  - `name`
-  - `requires_openai_auth = true`
-  - `wire_api = "responses"`
-
-## Legacy Handling
-
-- `config show` and `config list-profiles` expose legacy profile inspection views.
-- `migrate` remains a legacy adoption helper and does not modify the active top-level route.
-- `doctor` flags missing top-level route fields, legacy selectors/sections, and legacy `env_key` wiring in the active model provider section.
+- Public links should not point to removed `0.0.x` development documents.
+- The active documentation set should describe current behavior, not historical migration intent.
+- Copilot documentation should explicitly mark the bridge as local, bearer-protected, and backed by official GitHub Copilot runtime state.