@minniexcode/codex-switch 0.0.6 → 0.0.7

package/dist/cli/add-interactive.js

@@ -1,9 +1,11 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.promptTags = exports.parseTags = exports.createNonInteractiveAddError = exports.COMMON_TAG_CHOICES = exports.collectAddInput = void 0;
+exports.promptTags = exports.createNonInteractiveAddError = exports.COMMON_TAG_CHOICES = exports.collectAddInput = void 0;
+/**
+ * Compatibility facade that re-exports interactive add helpers for older imports.
+ */
 var add_interactive_1 = require("../interaction/add-interactive");
 Object.defineProperty(exports, "collectAddInput", { enumerable: true, get: function () { return add_interactive_1.collectAddInput; } });
 Object.defineProperty(exports, "COMMON_TAG_CHOICES", { enumerable: true, get: function () { return add_interactive_1.COMMON_TAG_CHOICES; } });
 Object.defineProperty(exports, "createNonInteractiveAddError", { enumerable: true, get: function () { return add_interactive_1.createNonInteractiveAddError; } });
-Object.defineProperty(exports, "parseTags", { enumerable: true, get: function () { return add_interactive_1.parseTags; } });
 Object.defineProperty(exports, "promptTags", { enumerable: true, get: function () { return add_interactive_1.promptTags; } });

package/dist/cli/args.js

@@ -1,6 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.parseArgs = exports.hasFlag = exports.getSingleOption = void 0;
+/**
+ * Compatibility facade that re-exports shared CLI argument parsing helpers.
+ */
 var args_1 = require("../commands/args");
 Object.defineProperty(exports, "getSingleOption", { enumerable: true, get: function () { return args_1.getSingleOption; } });
 Object.defineProperty(exports, "hasFlag", { enumerable: true, get: function () { return args_1.hasFlag; } });

package/dist/cli/help.js

@@ -1,6 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.isKnownCommandName = exports.getKnownCommandNames = exports.buildHelpText = void 0;
+/**
+ * Compatibility facade that re-exports CLI help helpers from the commands layer.
+ */
 var help_1 = require("../commands/help");
 Object.defineProperty(exports, "buildHelpText", { enumerable: true, get: function () { return help_1.buildHelpText; } });
 Object.defineProperty(exports, "getKnownCommandNames", { enumerable: true, get: function () { return help_1.getKnownCommandNames; } });

package/dist/cli/interactive.js

@@ -1,6 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.promptForProviderSelection = exports.getRollbackSummaryById = exports.getRollbackSummary = exports.exportTargetExists = exports.confirmRollback = exports.confirmProviderRemoval = exports.confirmImport = exports.confirmExportOverwrite = exports.collectSetupProviderDetails = exports.collectEditInput = exports.chooseSetupStrategy = exports.chooseSetupProfiles = exports.chooseCodexDir = exports.canPrompt = void 0;
+/**
+ * Compatibility facade that re-exports interactive command helpers.
+ */
 var interactive_1 = require("../interaction/interactive");
 Object.defineProperty(exports, "canPrompt", { enumerable: true, get: function () { return interactive_1.canPrompt; } });
 Object.defineProperty(exports, "chooseCodexDir", { enumerable: true, get: function () { return interactive_1.chooseCodexDir; } });

package/dist/cli/output.js

@@ -90,7 +90,8 @@ function renderHumanSuccess(command, data, warnings) {
                         ? ` tags=${provider.tags.join(",")}`
                         : "";
                     const note = provider.note ? ` note=${provider.note}` : "";
-                    lines.push(`${provider.name} -> ${provider.profile}${tags}${note}`);
+                    const envKey = provider.envKey ? ` envKey=${provider.envKey}` : "";
+                    lines.push(`${provider.name} -> ${provider.profile}${envKey}${tags}${note}`);
                 }
             }
             break;
@@ -100,6 +101,7 @@ function renderHumanSuccess(command, data, warnings) {
             lines.push(`Provider: ${String(data?.providerName ?? "")}`);
             lines.push(`profile: ${String(provider.profile ?? "")}`);
             lines.push(`apiKey: ${String(provider.apiKey ?? "")}`);
+            lines.push(`envKey: ${String(provider.envKey ?? "")}`);
             if (provider.baseUrl) {
                 lines.push(`baseUrl: ${String(provider.baseUrl)}`);
             }
@@ -120,13 +122,17 @@ function renderHumanSuccess(command, data, warnings) {
             lines.push(`providersExists: ${String(data?.providersExists ?? false)}`);
             lines.push(`currentProfile: ${String(data?.currentProfile ?? "")}`);
             lines.push(`mappedProvider: ${String(data?.provider ?? "")}`);
+            lines.push(`activeProviderResolvable: ${String(data?.activeProviderResolvable ?? false)}`);
+            const auth = data?.auth ?? {};
+            lines.push(`authExists: ${String(auth.exists ?? false)}`);
+            lines.push(`authManagedKeys: ${Array.isArray(auth.managedSecretKeys) ? auth.managedSecretKeys.join(",") : ""}`);
             lines.push(`issues: ${Array.isArray(data?.issues) ? (data?.issues).length : 0}`);
             break;
         case "config-show": {
             lines.push(`activeProfile: ${String(data?.activeProfile ?? "")}`);
             const profiles = data?.profiles ?? [];
             for (const profile of profiles) {
-                lines.push(`${String(profile.name)} managed=${String(profile.managed)} active=${String(profile.isActive)} source=${String(profile.source)} model=${String(profile.model ?? "")} modelProvider=${String(profile.modelProvider ?? "")} baseUrl=${String(profile.baseUrl ?? "")}`);
+                lines.push(`${String(profile.name)} managed=${String(profile.managed)} active=${String(profile.isActive)} source=${String(profile.source)} model=${String(profile.model ?? "")} modelProvider=${String(profile.modelProvider ?? "")} baseUrl=${String(profile.baseUrl ?? "")} envKey=${String(profile.envKey ?? "")}`);
             }
             break;
         }
@@ -139,8 +145,8 @@ function renderHumanSuccess(command, data, warnings) {
         }
         case "switch":
             lines.push(`Switched to provider ${String(data?.provider ?? "")} using profile ${String(data?.profile ?? "")}.`);
+            lines.push(`envKey: ${String(data?.envKey ?? "")}`);
             lines.push(`Backup: ${String(data?.backupPath ?? "")}`);
-            lines.push(`Login performed: ${String(data?.loginPerformed ?? false)}`);
             break;
         case "import":
             lines.push(`Imported providers from file using mode ${String(data?.mode ?? "replace")}. Backup: ${String(data?.backupPath ?? "")}`);
@@ -148,12 +154,21 @@ function renderHumanSuccess(command, data, warnings) {
         case "export":
             lines.push(`Exported providers to ${String(data?.exportedTo ?? "")}.`);
             break;
-        case "setup":
-            lines.push(`Initialized providers in ${String(data?.codexDir ?? "")} using ${String(data?.strategy ?? "")}.`);
+        case "init":
+            lines.push(`Initialized Codex directory ${String(data?.codexDir ?? "")}.`);
+            lines.push(`Created codexDir: ${String(data?.createdCodexDir ?? false)}`);
+            lines.push(`Created providers.json: ${String(data?.createdProvidersFile ?? false)}`);
+            lines.push(`providersAlreadyExisted: ${String(data?.providersAlreadyExisted ?? false)}`);
+            break;
+        case "migrate":
+            lines.push(`Migrated providers in ${String(data?.codexDir ?? "")} using ${String(data?.strategy ?? "")}.`);
             lines.push(`Providers initialized: ${String(data?.providersInitialized ?? 0)}`);
             lines.push(`Doctor healthy: ${String(data?.doctor?.healthy ?? false)}`);
             lines.push(`Backup: ${String(data?.backupPath ?? "")}`);
             break;
+        case "setup":
+            lines.push("setup is deprecated. Use `codexs init` or `codexs migrate`.");
+            break;
         case "edit":
             lines.push(`Updated provider ${String(data?.provider ?? "")}. Backup: ${String(data?.backupPath ?? "")}`);
             lines.push(`Updated fields: ${Array.isArray(data?.updatedFields) ? (data?.updatedFields).join(", ") : ""}`);

package/dist/cli/prompt.js

@@ -1,5 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createPromptRuntime = void 0;
+/**
+ * Compatibility facade that re-exports the CLI prompt runtime types and factory.
+ */
 var prompt_1 = require("../interaction/prompt");
 Object.defineProperty(exports, "createPromptRuntime", { enumerable: true, get: function () { return prompt_1.createPromptRuntime; } });

package/dist/cli.js

@@ -9,7 +9,7 @@ const args_1 = require("./commands/args");
 const help_1 = require("./commands/help");
 const errors_1 = require("./domain/errors");
 const output_1 = require("./cli/output");
-const VERSION = "0.0.6";
+const VERSION = "0.0.7";
 /**
  * Prints the command help text to stdout.
  */

package/dist/commands/handlers.js

@@ -40,6 +40,7 @@ const edit_provider_1 = require("../app/edit-provider");
 const export_providers_1 = require("../app/export-providers");
 const get_current_profile_1 = require("../app/get-current-profile");
 const get_status_1 = require("../app/get-status");
+const init_codex_1 = require("../app/init-codex");
 const import_providers_1 = require("../app/import-providers");
 const list_config_profiles_1 = require("../app/list-config-profiles");
 const list_backups_1 = require("../app/list-backups");
@@ -87,7 +88,54 @@ async function handleRegisteredCommand(ctx, parsed, runtime = (0, prompt_1.creat
         case "current":
             return (0, get_current_profile_1.getCurrentProfile)(paths.configPath);
         case "status":
-            return (0, get_status_1.getStatus)(paths.codexDir, paths.configPath, paths.providersPath);
+            return (0, get_status_1.getStatus)(paths.codexDir, paths.configPath, paths.providersPath, paths.authPath);
+        case "init": {
+            let codexDir = ctx.options.codexDir;
+            const candidates = (0, config_repo_1.findCodexDirCandidates)(ctx.options.codexDirExplicit ? ctx.options.codexDir : null);
+            if (!ctx.options.codexDirExplicit) {
+                if (candidates.length > 1) {
+                    if (!(0, interactive_1.canPrompt)(runtime, ctx.options.json)) {
+                        throw (0, errors_1.cliError)("CODEX_DIR_AMBIGUOUS", "Multiple Codex directories were found.", {
+                            candidates,
+                        });
+                    }
+                    codexDir = await (0, interactive_1.chooseCodexDir)(runtime, candidates);
+                }
+                else if (candidates.length === 0) {
+                    if (!(0, interactive_1.canPrompt)(runtime, ctx.options.json)) {
+                        throw (0, errors_1.cliError)("CODEX_DIR_NOT_FOUND", "No Codex directory could be found.", {
+                            codexDir: ctx.options.codexDir,
+                        });
+                    }
+                    codexDir = await (0, interactive_1.chooseCodexDir)(runtime, candidates);
+                }
+                else {
+                    codexDir = candidates[0];
+                }
+            }
+            setupPaths = (0, codex_paths_1.createCodexPaths)(codexDir);
+            let createCodexDir = false;
+            if (!fs.existsSync(setupPaths.codexDir)) {
+                if (!(0, interactive_1.canPrompt)(runtime, ctx.options.json)) {
+                    throw (0, errors_1.cliError)("CODEX_DIR_NOT_FOUND", "The requested Codex directory does not exist.", {
+                        codexDir: setupPaths.codexDir,
+                    });
+                }
+                createCodexDir = await (0, interactive_1.confirmCreateCodexDir)(runtime, setupPaths.codexDir);
+                if (!createCodexDir) {
+                    throw (0, errors_1.cliError)("CODEX_DIR_NOT_FOUND", "The requested Codex directory does not exist.", {
+                        codexDir: setupPaths.codexDir,
+                    });
+                }
+            }
+            return (0, init_codex_1.initCodex)({
+                codexDir: setupPaths.codexDir,
+                providersPath: setupPaths.providersPath,
+                configPath: setupPaths.configPath,
+                authPath: setupPaths.authPath,
+                createCodexDir,
+            });
+        }
         case "config-show":
             return (0, show_config_1.showConfig)({
                 configPath: paths.configPath,
@@ -115,7 +163,6 @@ async function handleRegisteredCommand(ctx, parsed, runtime = (0, prompt_1.creat
                 providersPath: paths.providersPath,
                 authPath: paths.authPath,
                 providerName,
-                noLogin: (0, args_1.hasFlag)(parsed.commandOptions, "--no-login"),
             });
         }
         case "import": {
@@ -130,6 +177,7 @@ async function handleRegisteredCommand(ctx, parsed, runtime = (0, prompt_1.creat
                 const imported = (0, providers_1.validateProvidersShape)(JSON.parse(fs.readFileSync(sourceFile, "utf8")));
                 const current = (0, providers_repo_1.readProvidersFileIfExists)(paths.providersPath);
                 const next = merge ? (0, providers_repo_1.mergeProviders)(current, imported) : imported;
+                // Precompute orphaned references during confirmation so the interactive path fails before mutation.
                 (0, config_1.buildManagedProfileViews)(document, next)
                     .filter((view) => view.source === "orphaned-reference")
                     .map((view) => view.name)
@@ -172,7 +220,7 @@ async function handleRegisteredCommand(ctx, parsed, runtime = (0, prompt_1.creat
             let model = (0, args_1.getSingleOption)(parsed.commandOptions, "--model", false);
             let note = (0, args_1.getSingleOption)(parsed.commandOptions, "--note", false);
             let tags = parsed.commandOptions.get("--tag") ?? [];
-            const createProfile = (0, args_1.hasFlag)(parsed.commandOptions, "--create-profile");
+            let createProfile = (0, args_1.hasFlag)(parsed.commandOptions, "--create-profile");
             if (!providerName || !profile || !apiKey) {
                 if (ctx.options.json || !runtime.isInteractive()) {
                     throw (0, add_interactive_1.createNonInteractiveAddError)();
@@ -184,13 +232,15 @@ async function handleRegisteredCommand(ctx, parsed, runtime = (0, prompt_1.creat
                     baseUrl,
                     note,
                     tags,
-                }, (candidate) => Boolean((0, providers_repo_1.readProvidersFileIfExists)(paths.providersPath).providers[candidate]));
+                }, (candidate) => Boolean((0, providers_repo_1.readProvidersFileIfExists)(paths.providersPath).providers[candidate]), (candidate) => Boolean((0, config_repo_1.readStructuredConfig)(paths.configPath).profiles.find((profileView) => profileView.name === candidate)));
                 providerName = prompted.providerName;
                 profile = prompted.profile;
                 apiKey = prompted.apiKey;
+                model = prompted.model ?? null;
                 baseUrl = prompted.baseUrl ?? null;
                 note = prompted.note ?? null;
                 tags = prompted.tags;
+                createProfile = createProfile || prompted.createProfile;
             }
             return (0, add_provider_1.addProvider)({
                 codexDir: paths.codexDir,
@@ -198,6 +248,7 @@ async function handleRegisteredCommand(ctx, parsed, runtime = (0, prompt_1.creat
                 latestBackupPath: paths.latestBackupPath,
                 providersPath: paths.providersPath,
                 configPath: paths.configPath,
+                authPath: paths.authPath,
                 providerName,
                 profile,
                 apiKey,
@@ -235,6 +286,7 @@ async function handleRegisteredCommand(ctx, parsed, runtime = (0, prompt_1.creat
                 if (!provider) {
                     throw (0, errors_1.cliError)("PROVIDER_NOT_FOUND", `Provider "${providerName}" was not found.`);
                 }
+                // Prompted edit starts from the stored record so blank answers can safely preserve current values.
                 const prompted = await (0, interactive_1.collectEditInput)(runtime, provider);
                 profile = prompted.profile;
                 apiKey = prompted.apiKey;
@@ -251,6 +303,7 @@ async function handleRegisteredCommand(ctx, parsed, runtime = (0, prompt_1.creat
                 latestBackupPath: paths.latestBackupPath,
                 providersPath: paths.providersPath,
                 configPath: paths.configPath,
+                authPath: paths.authPath,
                 providerName,
                 profile,
                 apiKey,
@@ -293,8 +346,9 @@ async function handleRegisteredCommand(ctx, parsed, runtime = (0, prompt_1.creat
                 codexDir: paths.codexDir,
                 configPath: paths.configPath,
                 providersPath: paths.providersPath,
+                authPath: paths.authPath,
             });
-        case "setup": {
+        case "migrate": {
             let codexDir = ctx.options.codexDir;
             const candidates = (0, config_repo_1.findCodexDirCandidates)(ctx.options.codexDirExplicit ? ctx.options.codexDir : null);
             if (!ctx.options.codexDirExplicit) {
@@ -304,6 +358,7 @@ async function handleRegisteredCommand(ctx, parsed, runtime = (0, prompt_1.creat
                             candidates,
                         });
                     }
+                    // Ambiguous auto-discovery must be resolved before path-dependent flags are interpreted.
                     codexDir = await (0, interactive_1.chooseCodexDir)(runtime, candidates);
                 }
                 else if (candidates.length === 0) {
@@ -320,7 +375,7 @@ async function handleRegisteredCommand(ctx, parsed, runtime = (0, prompt_1.creat
             const overwrite = (0, args_1.hasFlag)(parsed.commandOptions, "--overwrite");
             const merge = (0, args_1.hasFlag)(parsed.commandOptions, "--merge");
             if (overwrite && merge) {
-                throw (0, errors_1.cliError)("INVALID_ARGUMENT", "setup does not allow both --merge and --overwrite.");
+                throw (0, errors_1.cliError)("INVALID_ARGUMENT", "migrate does not allow both --merge and --overwrite.");
             }
             let strategy = overwrite ? "overwrite" : merge ? "merge" : null;
             const providersExists = fs.existsSync(setupPaths.providersPath);
@@ -338,11 +393,12 @@ async function handleRegisteredCommand(ctx, parsed, runtime = (0, prompt_1.creat
             }
             const document = (0, config_repo_1.readStructuredConfig)(setupPaths.configPath);
             const adoptableProfiles = (0, config_1.buildManagedProfileViews)(document, null)
-                .filter((view) => view.source === "unmanaged" && view.model && view.modelProvider === view.name && view.baseUrl)
+                .filter((view) => view.source === "unmanaged" && view.model && view.modelProvider === view.name && view.baseUrl && view.envKey)
                 .map((view) => ({
                 name: view.name,
                 model: view.model,
                 baseUrl: view.baseUrl,
+                envKey: view.envKey,
             }))
                 .sort((left, right) => left.name.localeCompare(right.name));
             const selectedProfiles = Array.from((0, config_repo_1.listConfigProfiles)(setupPaths.configPath)).sort();
@@ -350,20 +406,29 @@ async function handleRegisteredCommand(ctx, parsed, runtime = (0, prompt_1.creat
             let providerDetailsByProfile = {};
             if ((0, interactive_1.canPrompt)(runtime, ctx.options.json)) {
                 adoptProfiles = await (0, interactive_1.chooseSetupProfiles)(runtime, adoptableProfiles);
-                providerDetailsByProfile = await (0, interactive_1.collectSetupProviderDetails)(runtime, adoptProfiles);
+                // Defaults are derived from config.toml so interactive setup only asks for missing provider metadata.
+                providerDetailsByProfile = await (0, interactive_1.collectSetupProviderDetails)(runtime, adoptProfiles, adoptableProfiles.reduce((accumulator, profile) => {
+                    accumulator[profile.name] = {
+                        providerName: profile.name,
+                        envKey: profile.envKey,
+                        baseUrl: profile.baseUrl,
+                    };
+                    return accumulator;
+                }, {}));
             }
             else {
-                throw (0, errors_1.cliError)("INVALID_ARGUMENT", "setup currently requires an interactive TTY to choose adoptable profiles and collect provider details.", {
+                throw (0, errors_1.cliError)("INVALID_ARGUMENT", "migrate currently requires an interactive TTY to choose adoptable profiles and collect provider details.", {
                     adoptableProfiles,
                     availableProfiles: selectedProfiles,
-                    suggestion: "Run `codexs setup` in an interactive terminal. Non-interactive setup input flags are not available in 0.0.6.",
+                    suggestion: "Run `codexs migrate` in an interactive terminal. Non-interactive migrate flags for profile selection and provider secrets are not available in this release.",
                 });
             }
-            return (0, setup_codex_1.setupCodex)({
+            return (0, setup_codex_1.migrateCodex)({
                 codexDirOption: ctx.options.codexDir,
                 codexDir: setupPaths.codexDir,
                 configPath: setupPaths.configPath,
                 providersPath: setupPaths.providersPath,
+                authPath: setupPaths.authPath,
                 backupsDir: setupPaths.backupsDir,
                 latestBackupPath: setupPaths.latestBackupPath,
                 strategy: strategy ?? "overwrite",
@@ -371,6 +436,10 @@ async function handleRegisteredCommand(ctx, parsed, runtime = (0, prompt_1.creat
                 providerDetailsByProfile,
             });
         }
+        case "setup":
+            throw (0, errors_1.cliError)("COMMAND_DEPRECATED", "setup has been split into init and migrate.", {
+                replacements: ["init", "migrate"],
+            });
         case "backups-list":
             return (0, list_backups_1.listBackupEntries)(paths.backupsDir);
         case "rollback":

package/dist/commands/help.js

@@ -59,7 +59,8 @@ function buildHelpText(commandName) {
             "  rollback restores files from a managed backup.",
             "",
             "Examples:",
-            "  codexs setup",
+            "  codexs init",
+            "  codexs migrate",
             "  codexs list",
             "  codexs switch",
             "  codexs add packycode --profile packycode --api-key sk-xxx",

package/dist/commands/registry.js

@@ -11,6 +11,9 @@ exports.isKnownHelpTopic = isKnownHelpTopic;
 exports.getPublicCommandNames = getPublicCommandNames;
 exports.getNestedCommandTokens = getNestedCommandTokens;
 const handlers_1 = require("./handlers");
+/**
+ * Canonical command registry used by parsing, help rendering, and dispatch.
+ */
 exports.COMMANDS = [
     {
         id: "config-show",
@@ -39,19 +42,48 @@ exports.COMMANDS = [
         examples: ["codexs config list-profiles", "codexs config list-profiles --json"],
     },
     {
-        id: "setup",
-        tokens: ["setup"],
+        id: "init",
+        tokens: ["init"],
+        handler: handlers_1.handleRegisteredCommand,
+        group: "write",
+        summary: "Initialize a Codex directory with an empty managed providers registry.",
+        usage: ["codexs init [--json] [--codex-dir <path>]"],
+        details: [
+            "Creates providers.json with an empty providers object when it does not exist yet.",
+            "Does not require codex CLI, config.toml, or auth.json, and does not run doctor.",
+            "TTY mode can resolve ambiguous Codex directories and confirm creating a missing directory.",
+            "Non-TTY and --json runs never prompt and fail when the target directory is missing.",
+        ],
+        examples: ["codexs init", "codexs init --json --codex-dir ~/.codex"],
+    },
+    {
+        id: "migrate",
+        tokens: ["migrate"],
         handler: handlers_1.handleRegisteredCommand,
         group: "write",
-        summary: "Initialize providers.json from an existing Codex directory.",
-        usage: ["codexs setup [--json] [--codex-dir <path>] [--merge|--overwrite]"],
+        summary: "Adopt unmanaged Codex config profiles into providers.json.",
+        usage: ["codexs migrate [--json] [--codex-dir <path>] [--merge|--overwrite]"],
         details: [
             "Reads config.toml profiles, collects complete provider records, then writes providers.json under managed backup flow.",
             "TTY mode can collect missing provider details and choose merge or overwrite when providers.json already exists.",
-            "In 0.0.6, setup adopt initialization requires a real TTY because profile selection and provider details are collected interactively.",
-            "Non-TTY and --json runs fail fast with a structured error instead of entering partial setup behavior.",
+            "Migrate adopts only runtime profiles that already expose model, model_provider, matching base_url, and env_key.",
+            "Non-TTY and --json runs still fail fast because migrate profile selection and provider details remain interactive in this release.",
+        ],
+        examples: ["codexs migrate", "codexs migrate --overwrite --json --codex-dir ~/.codex"],
+    },
+    {
+        id: "setup",
+        tokens: ["setup"],
+        handler: handlers_1.handleRegisteredCommand,
+        group: "write",
+        summary: "Deprecated. Use init or migrate instead.",
+        usage: ["codexs setup"],
+        details: [
+            "setup no longer performs initialization or migration work.",
+            "Use init for AI-friendly idempotent providers.json initialization.",
+            "Use migrate for interactive adoption from existing config.toml profiles.",
         ],
-        examples: ["codexs setup", "codexs setup --overwrite --json --codex-dir ~/.codex"],
+        examples: ["codexs help init", "codexs help migrate"],
     },
     {
         id: "list",
@@ -114,7 +146,7 @@ exports.COMMANDS = [
         details: [
             "Passed flags replace only the selected fields and keep the rest unchanged.",
             "TTY mode can first select a provider, then prompt for fields when no editable options were provided.",
-            "Interactive tags use preset multi-select plus optional custom comma-separated input.",
+            "Interactive tags use preset multi-select only.",
             "When rebinding to a missing profile, --create-profile requires both --model and --base-url.",
             "Backs up providers.json and config.toml before writing.",
         ],
@@ -135,7 +167,7 @@ exports.COMMANDS = [
             "Prompts only for missing required values when stdin/stdout are TTYs and --json is not set.",
             "Interactive add collects provider name, profile, and apiKey progressively as plain text inputs.",
             "Confirm API key when prompted interactively because the hidden prompt asks twice before writing.",
-            "Interactive tags use preset multi-select plus optional custom comma-separated input.",
+            "Interactive tags use preset multi-select only.",
             "Automation and non-TTY environments must pass all required values explicitly.",
             "Creating a missing profile section requires --create-profile together with --model and --base-url.",
         ],
@@ -146,15 +178,15 @@ exports.COMMANDS = [
         tokens: ["switch"],
         handler: handlers_1.handleRegisteredCommand,
         group: "write",
-        summary: "Switch to a provider and optionally refresh Codex login.",
-        usage: ["codexs switch <provider> [--no-login] [--json] [--codex-dir <path>]"],
+        summary: "Switch to a provider and rewrite the managed auth mirror.",
+        usage: ["codexs switch <provider> [--json] [--codex-dir <path>]"],
         details: [
             "When <provider> is omitted in a TTY, an interactive provider selector is shown.",
             "When <provider> is passed explicitly, switch proceeds directly without extra confirmation.",
-            "--no-login remains explicit and is never prompted interactively.",
+            "Switch updates the active config profile and rewrites auth.json from the provider envKey/apiKey pair.",
             "Backs up config.toml and auth.json, then rolls back on failure.",
         ],
-        examples: ["codexs switch freemodel", "codexs switch --no-login", "codexs switch freemodel --no-login --json"],
+        examples: ["codexs switch freemodel", "codexs switch packycode --json"],
     },
     {
         id: "remove",
@@ -243,22 +275,38 @@ const HELP_TOPIC_SET = new Set([
     ...exports.COMMANDS.map((command) => command.tokens.join(" ")),
     ...new Set(exports.COMMANDS.filter((command) => command.tokens.length > 1).map((command) => command.tokens[0])),
 ]);
+/**
+ * Returns a defensive copy of the public command registry.
+ */
 function getCommandDefinitions() {
     return exports.COMMANDS.slice();
 }
+/**
+ * Returns stable internal command ids in registry order.
+ */
 function getKnownCommandIds() {
     return exports.COMMANDS.map((command) => command.id);
 }
+/**
+ * Resolves one command definition by its canonical internal id.
+ */
 function findCommandDefinition(commandId) {
     if (commandId === "help" || commandId === "version") {
         return null;
     }
     return exports.COMMANDS.find((command) => command.id === commandId) ?? null;
 }
+/**
+ * Resolves a command definition from its tokenized CLI spelling.
+ */
 function findCommandDefinitionByTokens(tokens) {
     return exports.COMMANDS.find((command) => command.tokens.join(" ") === tokens.join(" ")) ?? null;
 }
+/**
+ * Matches argv against the longest registered token sequence first.
+ */
 function resolveCommandFromArgv(argv) {
+    // Nested commands such as "config show" must win over their shorter root tokens.
     for (const command of exports.COMMANDS
         .slice()
         .sort((left, right) => right.tokens.length - left.tokens.length)) {
@@ -275,15 +323,27 @@ function resolveCommandFromArgv(argv) {
         consumedTokens: 0,
     };
 }
+/**
+ * Reports whether a name is reserved by either a command id or its public token form.
+ */
 function isKnownCommandName(commandName) {
     return COMMAND_NAME_SET.has(commandName);
 }
+/**
+ * Reports whether a help topic is recognized by the help renderer.
+ */
 function isKnownHelpTopic(topic) {
     return HELP_TOPIC_SET.has(topic);
 }
+/**
+ * Returns public command names exactly as they appear in help and examples.
+ */
 function getPublicCommandNames() {
     return exports.COMMANDS.map((command) => command.tokens.join(" "));
 }
+/**
+ * Returns nested command spellings for one root token such as "config" or "backups".
+ */
 function getNestedCommandTokens(rootToken) {
     return exports.COMMANDS
         .filter((command) => command.tokens.length > 1 && command.tokens[0] === rootToken)