metheus-governance-mcp-cli 0.2.63 → 0.2.65

package/README.md

@@ -213,8 +213,11 @@ Direct commands:
 metheus-governance-mcp-cli bot list
 metheus-governance-mcp-cli bot show --provider telegram --bot-key main
 metheus-governance-mcp-cli bot add --provider telegram
+metheus-governance-mcp-cli bot edit
 metheus-governance-mcp-cli bot edit --provider telegram
 metheus-governance-mcp-cli bot remove --provider telegram
+metheus-governance-mcp-cli bot set-default --provider telegram --bot-key main
+metheus-governance-mcp-cli bot migrate --provider telegram --bot-key main
 metheus-governance-mcp-cli bot global --provider telegram
 metheus-governance-mcp-cli bot verify --provider telegram --bot-key main
 ```
@@ -222,6 +225,8 @@ metheus-governance-mcp-cli bot verify --provider telegram --bot-key main
 Behavior:
 
 - `bot setup` asks for `Telegram / Slack / KakaoTalk` first, then prompts with numbered actions.
+- `bot add` without flags starts a guided question flow: provider -> server bot -> local bot key -> token -> verify -> role/AI binding -> default bot choice.
+- `bot edit` without flags starts a guided numbered flow: provider -> bot entry -> guided edit -> step-by-step field choices.
 - Telegram supports named local bot entries with:
   - `SERVER_BOT_ID`
   - `USERNAME`
@@ -235,13 +240,17 @@ Behavior:
 - `bot verify` checks the configured local token and prints the current AI binding summary.
 - `bot show` prints one local bot entry in detail.
 - `bot global` edits Telegram-wide local settings such as API base URL, allowed updates, and default bot key.
+- `bot set-default` updates `TELEGRAM_DEFAULT_BOT_KEY`.
+- `bot migrate` moves legacy `TELEGRAM_BOT_TOKEN` into a named Telegram bot entry.
 
 Non-interactive examples:
 
 ```bash
 metheus-governance-mcp-cli bot global --provider telegram --non-interactive true --api-base-url http://127.0.0.1:8999/telegram --auto-clear-webhook false --allowed-updates message,edited_message,channel_post
-metheus-governance-mcp-cli bot add --provider telegram --non-interactive true --bot-key main --bot-id <server_bot_uuid> --token <telegram_bot_token> --role-profile monitor --client codex --permission-mode read_only --reasoning-effort low --default true
-metheus-governance-mcp-cli bot edit --provider telegram --bot-key main --non-interactive true --client claude --model claude-3.7-sonnet --permission-mode workspace_write --reasoning-effort medium
+metheus-governance-mcp-cli bot add --provider telegram --non-interactive true --bot-key main --server-bot-id <server_bot_uuid> --username <telegram_username> --token <telegram_bot_token> --role-profile monitor --ai-client codex --ai-model gpt-5-codex --ai-permission-mode read_only --ai-reasoning-effort low --default true
+metheus-governance-mcp-cli bot edit --provider telegram --bot-key main --non-interactive true --ai-client claude --ai-model claude-sonnet --ai-permission-mode workspace_write --ai-reasoning-effort medium
+metheus-governance-mcp-cli bot set-default --provider telegram --bot-key main --non-interactive true
+metheus-governance-mcp-cli bot migrate --provider telegram --bot-key main --server-bot-id <server_bot_uuid> --bot-name <telegram_username> --role-profile monitor --ai-client codex --ai-permission-mode read_only --ai-reasoning-effort low --non-interactive true
 metheus-governance-mcp-cli bot remove --provider telegram --bot-key main --non-interactive true
 metheus-governance-mcp-cli bot verify --provider telegram --bot-key main --json true
 ```
@@ -276,6 +285,9 @@ Checks:
 - role profile -> local CLI availability
 - route dry-run / trigger-policy safety warnings
 - local provider token presence for active project destinations
+- enabled runner route -> local bot env binding resolution
+- enabled runner route -> server bot UUID cross-check
+- legacy `TELEGRAM_BOT_TOKEN` fallback still in use
 - codex/claude/gemini/antigravity/cursor registration state
 - gateway `tools/list` reachability
 - `project.summary` access

package/cli.mjs

@@ -240,6 +240,8 @@ function printUsage() {
       `  ${cmd} bot add [--provider <telegram|slack|kakaotalk>] [--base-url <url>] [--timeout-seconds <n>]`,
       `  ${cmd} bot edit [--provider <telegram|slack|kakaotalk>] [--base-url <url>] [--timeout-seconds <n>]`,
       `  ${cmd} bot remove [--provider <telegram|slack|kakaotalk>]`,
+      `  ${cmd} bot set-default --provider telegram [--bot-key <key>]`,
+      `  ${cmd} bot migrate --provider telegram [--bot-key <key>] [--bot-id <uuid>] [--bot-name <name>]`,
       `  ${cmd} bot verify [--provider <telegram|slack|kakaotalk>] [--bot-key <key>] [--timeout-seconds <n>] [--json <true|false>]`,
       `  ${cmd} bot global --provider telegram [--api-base-url <url>] [--auto-clear-webhook <true|false>] [--allowed-updates <csv>] [--default-bot-key <key>]`,
       `  ${cmd} doctor [--project-id <uuid>] [--ctxpack-key <key>] [--base-url <url>] [--timeout-seconds <n>] [--strict <true|false>]`,
@@ -3527,6 +3529,8 @@ async function runDoctor(flags) {
     includeDrafts: true,
   }, { defaultBaseURL: DEFAULT_BASE_URL });
   const rows = [];
+  let runnerConfig = null;
+  let enabledRoutes = [];
   const providerTemplates = ensureAllProviderEnvTemplates();
   const runnerTemplate = ensureBotRunnerConfigTemplate();
   for (const provider of PROVIDER_ENV_ORDER) {
@@ -3541,9 +3545,9 @@ async function runDoctor(flags) {
   if (runnerTemplate.error) {
     addDoctorCheck(rows, "warn", "local bot runner config", `${runnerTemplate.error} (${runnerTemplate.filePath})`);
   } else {
-    const runnerConfig = loadBotRunnerConfig({ persistIfNeeded: true });
+    runnerConfig = loadBotRunnerConfig({ persistIfNeeded: true });
     const runnerState = loadBotRunnerState();
-    const enabledRoutes = ensureArray(runnerConfig.routes).filter((routeRaw) => safeObject(routeRaw).enabled);
+    enabledRoutes = ensureArray(runnerConfig.routes).filter((routeRaw) => safeObject(routeRaw).enabled);
     if (!enabledRoutes.length) {
       addDoctorCheck(rows, "warn", "local bot runner config", `template ready (${runnerTemplate.filePath}), no enabled routes`);
     } else {
@@ -3662,6 +3666,82 @@ async function runDoctor(flags) {
         deps: buildDoctorChecksDeps(),
       });
     }
+
+    if (runnerConfig && enabledRoutes.length > 0) {
+      let serverBots = null;
+      try {
+        serverBots = await listUserBotsForRunner({
+          siteBaseURL: normalizeSiteBaseURL(context.baseURL),
+          token,
+          timeoutSeconds,
+        }, buildRunnerDataDeps());
+      } catch {
+        serverBots = null;
+      }
+      for (const routeRaw of enabledRoutes) {
+        const route = normalizeRunnerRoute(routeRaw);
+        const routeLabel = route.name || route.projectID || route.provider;
+        const envConfig = loadProviderEnvConfig(route.provider, {
+          botID: route.botID,
+          botName: route.botName,
+          route,
+        });
+        if (!envConfig.ok) {
+          addDoctorCheck(
+            rows,
+            "fail",
+            `runner route ${routeLabel} binding`,
+            `${providerEnvConfig(route.provider).label} local bot env is unresolved (${envConfig.error})`,
+          );
+          continue;
+        }
+        const detailParts = [];
+        if (envConfig.botKey) detailParts.push(`bot=${envConfig.botKey}`);
+        if (envConfig.botUsername) detailParts.push(`@${envConfig.botUsername}`);
+        if (envConfig.serverBotID) detailParts.push(`server_bot_id=${envConfig.serverBotID}`);
+        if (envConfig.client) detailParts.push(`ai=${envConfig.client}`);
+        addDoctorCheck(
+          rows,
+          "ok",
+          `runner route ${routeLabel} binding`,
+          detailParts.join(", ") || "resolved",
+        );
+        if (route.botID && envConfig.serverBotID && route.botID !== envConfig.serverBotID) {
+          addDoctorCheck(
+            rows,
+            strictMode ? "fail" : "warn",
+            `runner route ${routeLabel} server_bot_id`,
+            `route bot_id ${route.botID} != local env ${envConfig.serverBotID}`,
+          );
+        }
+        if (route.botID && !envConfig.serverBotID) {
+          addDoctorCheck(
+            rows,
+            strictMode ? "fail" : "warn",
+            `runner route ${routeLabel} server_bot_id`,
+            `route bot_id ${route.botID} is set, but local env entry does not carry SERVER_BOT_ID`,
+          );
+        }
+        if (serverBots && route.botID) {
+          const match = ensureArray(serverBots).find((bot) => String(bot.id || "").trim() === String(route.botID || "").trim());
+          addDoctorCheck(
+            rows,
+            match ? "ok" : (strictMode ? "fail" : "warn"),
+            `runner route ${routeLabel} server bot`,
+            match ? `${match.name || "(unnamed)"} [${match.role || "-"}]` : `server bot ${route.botID} not found`,
+          );
+        }
+      }
+      const telegramDefaultConfig = loadProviderEnvConfig("telegram");
+      if (telegramDefaultConfig.ok && !telegramDefaultConfig.botKey && String(telegramDefaultConfig.token || "").trim()) {
+        addDoctorCheck(
+          rows,
+          "warn",
+          "telegram legacy token",
+          "TELEGRAM_BOT_TOKEN fallback is still active; run bot migrate --provider telegram to move to named entries",
+        );
+      }
+    }
   }
 
   for (const cliBin of MCP_CLIENTS) {

package/lib/bot-commands.mjs

@@ -43,6 +43,35 @@ function firstNonEmptyString(values) {
   return "";
 }
 
+function hasOwnFlag(flags, key) {
+  return Object.prototype.hasOwnProperty.call(safeObject(flags), key);
+}
+
+function getServerBotIDFlag(flags) {
+  const parsedFlags = safeObject(flags);
+  return firstNonEmptyString([parsedFlags["server-bot-id"], parsedFlags["bot-id"]]);
+}
+
+function getAIClientFlag(flags) {
+  const parsedFlags = safeObject(flags);
+  return firstNonEmptyString([parsedFlags["ai-client"], parsedFlags.client]);
+}
+
+function getAIModelFlag(flags) {
+  const parsedFlags = safeObject(flags);
+  return firstNonEmptyString([parsedFlags["ai-model"], parsedFlags.model]);
+}
+
+function getAIPermissionModeFlag(flags) {
+  const parsedFlags = safeObject(flags);
+  return firstNonEmptyString([parsedFlags["ai-permission-mode"], parsedFlags["permission-mode"]]);
+}
+
+function getAIReasoningEffortFlag(flags) {
+  const parsedFlags = safeObject(flags);
+  return firstNonEmptyString([parsedFlags["ai-reasoning-effort"], parsedFlags["reasoning-effort"]]);
+}
+
 function maskSecret(rawValue) {
   const text = String(rawValue || "").trim();
   if (!text) return "";
@@ -76,9 +105,11 @@ function printBotUsage(deps) {
       `  ${cliName} bot setup`,
       `  ${cliName} bot list [--provider <telegram|slack|kakaotalk>] [--json <true|false>]`,
       `  ${cliName} bot show [--provider <telegram|slack|kakaotalk>] [--bot-key <key>] [--bot-id <uuid>] [--bot-name <name>] [--json <true|false>]`,
-      `  ${cliName} bot add [--provider <telegram|slack|kakaotalk>] [--non-interactive <true|false>] [--yes <true|false>]`,
-      `  ${cliName} bot edit [--provider <telegram|slack|kakaotalk>] [--non-interactive <true|false>] [--bot-key <key>]`,
+      `  ${cliName} bot add [--provider <telegram|slack|kakaotalk>] [--base-url <url>] [--timeout-seconds <n>] [--non-interactive <true|false>] [--bot-key <key>] [--server-bot-id <uuid>] [--username <name>] [--token <token>] [--role-profile <name>] [--ai-client <name>] [--ai-model <name>] [--ai-permission-mode <mode>] [--ai-reasoning-effort <level>] [--default <true|false>] [--verify <true|false>]`,
+      `  ${cliName} bot edit [--provider <telegram|slack|kakaotalk>] [--base-url <url>] [--timeout-seconds <n>] [--non-interactive <true|false>] [--bot-key <key>] [--server-bot-id <uuid>] [--username <name>] [--token <token>] [--role-profile <name>] [--ai-client <name>] [--ai-model <name>] [--ai-permission-mode <mode>] [--ai-reasoning-effort <level>]`,
       `  ${cliName} bot remove [--provider <telegram|slack|kakaotalk>] [--non-interactive <true|false>] [--bot-key <key>]`,
+      `  ${cliName} bot set-default --provider telegram [--bot-key <key>] [--non-interactive <true|false>]`,
+      `  ${cliName} bot migrate --provider telegram [--bot-key <key>] [--bot-id <uuid>] [--bot-name <name>] [--keep-legacy-token <true|false>] [--non-interactive <true|false>]`,
       `  ${cliName} bot verify [--provider <telegram|slack|kakaotalk>] [--bot-key <key>] [--timeout-seconds <n>] [--json <true|false>]`,
       `  ${cliName} bot global --provider telegram [--non-interactive <true|false>] [--api-base-url <url>] [--auto-clear-webhook <true|false>] [--allowed-updates <csv>] [--default-bot-key <key>]`,
       "",
@@ -87,6 +118,27 @@ function printBotUsage(deps) {
 }
 
 function createPrompter() {
+  const scriptedPromptAnswersRaw = String(process.env.METHEUS_SCRIPTED_PROMPT_ANSWERS || "").trim();
+  if (scriptedPromptAnswersRaw) {
+    let scriptedAnswers = [];
+    try {
+      const parsed = JSON.parse(scriptedPromptAnswersRaw);
+      scriptedAnswers = ensureArray(parsed).map((value) => String(value ?? ""));
+    } catch {
+      scriptedAnswers = scriptedPromptAnswersRaw.split(/\r?\n/).map((value) => String(value ?? ""));
+    }
+    let answerIndex = 0;
+    return {
+      ask(promptText) {
+        process.stdout.write(promptText);
+        const answer = answerIndex < scriptedAnswers.length ? scriptedAnswers[answerIndex] : "";
+        answerIndex += 1;
+        process.stdout.write(`${answer}\n`);
+        return Promise.resolve(String(answer || ""));
+      },
+      close() {},
+    };
+  }
   return {
     ask(promptText) {
       return new Promise((resolve) => {
@@ -161,6 +213,19 @@ async function promptChoice(ui, title, options, { defaultIndex = 0, allowCancel
   }
 }
 
+async function promptKeepChangeClear(ui, title, { allowClear = true, defaultValue = "keep" } = {}) {
+  const options = [
+    { value: "keep", label: "Keep current value" },
+    { value: "change", label: "Change value" },
+  ];
+  if (allowClear) {
+    options.push({ value: "clear", label: "Clear value" });
+  }
+  const defaultIndex = Math.max(0, options.findIndex((option) => option.value === defaultValue));
+  const selected = await promptChoice(ui, title, options, { defaultIndex });
+  return selected?.value || "keep";
+}
+
 function loadProviderEnvState(provider, deps) {
   const ensureTemplate = requireDependency(deps, "ensureProviderEnvTemplate");
   const filePathResolver = requireDependency(deps, "providerEnvFilePath");
@@ -201,6 +266,10 @@ function removeTelegramEntry(parsedEnv, botKey) {
   return parsed;
 }
 
+function hasNamedTelegramEntry(parsedEnv, deps) {
+  return telegramEntriesForDisplay(parsedEnv, deps).length > 0;
+}
+
 function upsertTelegramEntry(parsedEnv, entry) {
   const parsed = removeTelegramEntry(parsedEnv, entry.key);
   const keys = telegramEntryEnvKeys(entry.key);
@@ -393,6 +462,175 @@ function findTelegramEntryByFlags(parsedEnv, flags, deps) {
   return null;
 }
 
+function saveTelegramBotEdit(parsed, selected, current, deps) {
+  let nextParsed = parsed;
+  if (current.key !== selected.key) {
+    nextParsed = removeTelegramEntry(nextParsed, selected.key);
+  }
+  nextParsed = upsertTelegramEntry(nextParsed, current);
+  if (String(parsed.TELEGRAM_DEFAULT_BOT_KEY || "").trim() === selected.key) {
+    nextParsed.TELEGRAM_DEFAULT_BOT_KEY = current.key;
+  }
+  const filePath = writeProviderEnvState("telegram", nextParsed, deps);
+  process.stdout.write(`Saved Telegram bot entry "${current.key}" to ${filePath}\n`);
+  return filePath;
+}
+
+async function editTelegramBotGuided(ui, parsed, selected, current, flags, deps) {
+  const bindingAction = await promptKeepChangeClear(ui, "Server bot binding", {
+    allowClear: true,
+    defaultValue: current.serverBotID ? "keep" : "change",
+  });
+  if (bindingAction === "change") {
+    const serverBot = await chooseServerBot(
+      ui,
+      "telegram",
+      flags["base-url"] || deps.defaultSiteURL,
+      intFromRaw(flags["timeout-seconds"], 15) || 15,
+      deps,
+    );
+    current.serverBotID = serverBot.botID;
+    if (!current.roleProfile && serverBot.role) {
+      current.roleProfile = serverBot.role;
+    }
+  } else if (bindingAction === "clear") {
+    current.serverBotID = "";
+  }
+
+  const usernameAction = await promptKeepChangeClear(ui, "Telegram username", {
+    allowClear: true,
+    defaultValue: current.username ? "keep" : "change",
+  });
+  if (usernameAction === "change") {
+    current.username = requireDependency(deps, "normalizeTelegramBotUsername")(
+      await promptRequiredLine(ui, "Telegram username (without @)", current.username),
+      "",
+    );
+  } else if (usernameAction === "clear") {
+    current.username = "";
+  }
+
+  const tokenAction = await promptKeepChangeClear(ui, "Telegram token", {
+    allowClear: false,
+    defaultValue: "keep",
+  });
+  if (tokenAction === "change") {
+    current.token = await promptRequiredLine(ui, "Telegram bot token", current.token);
+    if (await promptYesNo(ui, "Verify updated token now?", true)) {
+      const verifyResult = await verifyTelegramTokenCandidate(
+        "telegram",
+        current.token,
+        String(parsed.TELEGRAM_API_BASE_URL || "").trim(),
+        intFromRaw(flags["timeout-seconds"], 15) || 15,
+        deps,
+      );
+      process.stdout.write(`Verify: ${verifyResult.ok ? "OK" : "FAIL"}${verifyResult.detail ? ` - ${verifyResult.detail}` : ""}\n`);
+      const maybeUsername = extractVerifiedTelegramUsername(verifyResult.detail);
+      if (verifyResult.ok && maybeUsername && !current.username) {
+        current.username = maybeUsername;
+      }
+    }
+  }
+
+  const roleAction = await promptKeepChangeClear(ui, "Role profile", {
+    allowClear: true,
+    defaultValue: current.roleProfile ? "keep" : "change",
+  });
+  if (roleAction === "change") {
+    current.roleProfile = requireDependency(deps, "normalizeRunnerRoleProfileName")(
+      await promptTelegramRoleProfile(ui, deps, current.roleProfile),
+    );
+  } else if (roleAction === "clear") {
+    current.roleProfile = "";
+  }
+
+  const clientAction = await promptKeepChangeClear(ui, "AI client", {
+    allowClear: true,
+    defaultValue: current.client ? "keep" : "change",
+  });
+  if (clientAction === "change") {
+    current.client = requireDependency(deps, "normalizeLocalAIClientName")(
+      await promptAIClient(ui, deps, current.client),
+      "",
+    );
+  } else if (clientAction === "clear") {
+    current.client = "";
+  }
+
+  const modelAction = await promptKeepChangeClear(ui, "AI model", {
+    allowClear: true,
+    defaultValue: current.model ? "keep" : "change",
+  });
+  if (modelAction === "change") {
+    current.model = await promptLine(ui, "AI model", current.model);
+  } else if (modelAction === "clear") {
+    current.model = "";
+  }
+
+  const permissionAction = await promptKeepChangeClear(ui, "AI permission mode", {
+    allowClear: true,
+    defaultValue: current.permissionMode ? "keep" : "change",
+  });
+  if (permissionAction === "change") {
+    current.permissionMode = requireDependency(deps, "normalizeLocalAIPermissionMode")(
+      await promptPermissionMode(ui, current.permissionMode),
+      "",
+    );
+  } else if (permissionAction === "clear") {
+    current.permissionMode = "";
+  }
+
+  const reasoningAction = await promptKeepChangeClear(ui, "AI reasoning effort", {
+    allowClear: true,
+    defaultValue: current.reasoningEffort ? "keep" : "change",
+  });
+  if (reasoningAction === "change") {
+    current.reasoningEffort = requireDependency(deps, "normalizeLocalAIReasoningEffort")(
+      await promptReasoningEffort(ui, current.reasoningEffort),
+      "",
+    );
+  } else if (reasoningAction === "clear") {
+    current.reasoningEffort = "";
+  }
+
+  const botKeyAction = await promptKeepChangeClear(ui, "Local bot key", {
+    allowClear: false,
+    defaultValue: "keep",
+  });
+  if (botKeyAction === "change") {
+    const normalizeBotKey = requireDependency(deps, "normalizeTelegramBotEnvKey");
+    let nextKey = normalizeBotKey(await promptRequiredLine(ui, "Local bot key", current.key), current.key);
+    const existing = new Set(telegramEntriesForDisplay(parsed, deps).map((entry) => entry.key).filter((key) => key !== current.key));
+    while (existing.has(nextKey)) {
+      process.stdout.write(`Telegram bot key "${nextKey}" already exists.\n`);
+      nextKey = normalizeBotKey(await promptRequiredLine(ui, "Local bot key", `${nextKey}_2`), `${nextKey}_2`);
+    }
+    current.key = nextKey;
+  }
+
+  const defaultChoice = await promptChoice(
+    ui,
+    "Default Telegram bot setting",
+    [
+      { value: "keep", label: "Keep current default setting", description: String(parsed.TELEGRAM_DEFAULT_BOT_KEY || "").trim() === selected.key ? "currently default" : "not default" },
+      { value: "set", label: "Set this bot as default" },
+      { value: "unset", label: "Do not make this bot default" },
+    ],
+    { defaultIndex: 0 },
+  );
+  if (defaultChoice?.value === "set") {
+    parsed.TELEGRAM_DEFAULT_BOT_KEY = current.key;
+  } else if (defaultChoice?.value === "unset" && String(parsed.TELEGRAM_DEFAULT_BOT_KEY || "").trim() === selected.key) {
+    parsed.TELEGRAM_DEFAULT_BOT_KEY = "";
+  }
+
+  if (!await promptYesNo(ui, `Save changes for "${current.key}" now?`, true)) {
+    process.stdout.write("Cancelled.\n");
+    return;
+  }
+  saveTelegramBotEdit(parsed, selected, current, deps);
+}
+
 async function selectProvider(ui, initialProvider, deps) {
   const normalizeProvider = requireDependency(deps, "normalizeBotProvider");
   const provider = String(initialProvider || "").trim();
@@ -702,7 +940,7 @@ async function addTelegramBot(ui, flags, deps) {
   const nonInteractive = boolFromRaw(flags["non-interactive"] ?? flags.yes, false);
   const serverBot = nonInteractive
     ? {
-      botID: String(flags["server-bot-id"] || flags["bot-id"] || "").trim(),
+      botID: getServerBotIDFlag(flags),
       role: String(flags.role || "").trim(),
       name: "",
     }
@@ -777,27 +1015,27 @@ async function addTelegramBot(ui, flags, deps) {
   );
   const client = requireDependency(deps, "normalizeLocalAIClientName")(
     nonInteractive
-      ? String(flags.client || "").trim()
-      : await promptAIClient(ui, deps, flags.client || ""),
+      ? getAIClientFlag(flags)
+      : await promptAIClient(ui, deps, getAIClientFlag(flags)),
     "",
   );
-  const model = nonInteractive ? String(flags.model || "").trim() : await promptLine(ui, "AI model", String(flags.model || "").trim());
+  const model = nonInteractive ? getAIModelFlag(flags) : await promptLine(ui, "AI model", getAIModelFlag(flags));
   const permissionMode = requireDependency(deps, "normalizeLocalAIPermissionMode")(
     nonInteractive
-      ? String(flags["permission-mode"] || "").trim()
-      : await promptPermissionMode(ui, String(flags["permission-mode"] || "").trim()),
+      ? getAIPermissionModeFlag(flags)
+      : await promptPermissionMode(ui, getAIPermissionModeFlag(flags)),
     "",
   );
   const reasoningEffort = requireDependency(deps, "normalizeLocalAIReasoningEffort")(
     nonInteractive
-      ? String(flags["reasoning-effort"] || "").trim()
-      : await promptReasoningEffort(ui, String(flags["reasoning-effort"] || "").trim()),
+      ? getAIReasoningEffortFlag(flags)
+      : await promptReasoningEffort(ui, getAIReasoningEffortFlag(flags)),
     "",
   );
 
   const nextParsed = upsertTelegramEntry(parsed, {
     key: botKey,
-    serverBotID: String(flags["server-bot-id"] || serverBot.botID || "").trim(),
+    serverBotID: String(getServerBotIDFlag(flags) || serverBot.botID || "").trim(),
     username,
     token,
     roleProfile,
@@ -882,8 +1120,8 @@ async function editTelegramBot(ui, flags, deps) {
   }
   let current = { ...selected };
   if (nonInteractive) {
-    if (flags["server-bot-id"] || flags["bot-id"]) {
-      current.serverBotID = String(flags["server-bot-id"] || flags["bot-id"] || "").trim();
+    if (getServerBotIDFlag(flags)) {
+      current.serverBotID = getServerBotIDFlag(flags);
     }
     if (Object.prototype.hasOwnProperty.call(flags, "username")) {
       current.username = requireDependency(deps, "normalizeTelegramBotUsername")(flags.username || "");
@@ -894,25 +1132,35 @@ async function editTelegramBot(ui, flags, deps) {
     if (Object.prototype.hasOwnProperty.call(flags, "role-profile")) {
       current.roleProfile = requireDependency(deps, "normalizeRunnerRoleProfileName")(flags["role-profile"] || "");
     }
-    if (Object.prototype.hasOwnProperty.call(flags, "client")) {
-      current.client = requireDependency(deps, "normalizeLocalAIClientName")(flags.client || "", "");
+    if (hasOwnFlag(flags, "client") || hasOwnFlag(flags, "ai-client")) {
+      current.client = requireDependency(deps, "normalizeLocalAIClientName")(getAIClientFlag(flags), "");
     }
-    if (Object.prototype.hasOwnProperty.call(flags, "model")) {
-      current.model = String(flags.model || "").trim();
+    if (hasOwnFlag(flags, "model") || hasOwnFlag(flags, "ai-model")) {
+      current.model = getAIModelFlag(flags);
     }
-    if (Object.prototype.hasOwnProperty.call(flags, "permission-mode")) {
-      current.permissionMode = requireDependency(deps, "normalizeLocalAIPermissionMode")(flags["permission-mode"] || "", "");
+    if (hasOwnFlag(flags, "permission-mode") || hasOwnFlag(flags, "ai-permission-mode")) {
+      current.permissionMode = requireDependency(deps, "normalizeLocalAIPermissionMode")(getAIPermissionModeFlag(flags), "");
     }
-    if (Object.prototype.hasOwnProperty.call(flags, "reasoning-effort")) {
-      current.reasoningEffort = requireDependency(deps, "normalizeLocalAIReasoningEffort")(flags["reasoning-effort"] || "", "");
+    if (hasOwnFlag(flags, "reasoning-effort") || hasOwnFlag(flags, "ai-reasoning-effort")) {
+      current.reasoningEffort = requireDependency(deps, "normalizeLocalAIReasoningEffort")(getAIReasoningEffortFlag(flags), "");
     }
     if (boolFromRaw(flags.default, false)) {
       parsed.TELEGRAM_DEFAULT_BOT_KEY = current.key;
     }
-    let nextParsed = parsed;
-    nextParsed = upsertTelegramEntry(nextParsed, current);
-    const filePath = writeProviderEnvState("telegram", nextParsed, deps);
-    process.stdout.write(`Saved Telegram bot entry "${current.key}" to ${filePath}\n`);
+    saveTelegramBotEdit(parsed, selected, current, deps);
+    return;
+  }
+  const editMode = await promptChoice(
+    ui,
+    `How do you want to edit Telegram bot "${current.key}"?`,
+    [
+      { value: "guided", label: "Guided edit (Recommended)", description: "Step-by-step prompts with numbered choices" },
+      { value: "field_menu", label: "Field menu", description: "Choose one field at a time until save" },
+    ],
+    { defaultIndex: 0 },
+  );
+  if (editMode?.value === "guided") {
+    await editTelegramBotGuided(ui, parsed, selected, current, flags, deps);
     return;
   }
   while (true) {
@@ -936,16 +1184,7 @@ async function editTelegramBot(ui, flags, deps) {
     );
     if (!choice) return;
     if (choice.value === "save") {
-      let nextParsed = parsed;
-      if (current.key !== selected.key) {
-        nextParsed = removeTelegramEntry(nextParsed, selected.key);
-      }
-      nextParsed = upsertTelegramEntry(nextParsed, current);
-      if (String(parsed.TELEGRAM_DEFAULT_BOT_KEY || "").trim() === selected.key) {
-        nextParsed.TELEGRAM_DEFAULT_BOT_KEY = current.key;
-      }
-      const filePath = writeProviderEnvState("telegram", nextParsed, deps);
-      process.stdout.write(`Saved Telegram bot entry "${current.key}" to ${filePath}\n`);
+      saveTelegramBotEdit(parsed, selected, current, deps);
       return;
     }
     if (choice.value === "server_bot_id") {
@@ -1194,6 +1433,8 @@ async function runBotSetup(ui, flags, deps) {
     { value: "add", label: "Add bot" },
     { value: "edit", label: "Edit bot" },
     { value: "remove", label: "Remove bot" },
+    { value: "set_default", label: "Set default bot" },
+    { value: "migrate", label: "Migrate legacy token" },
     { value: "verify", label: "Verify bot" },
     { value: "global", label: "Telegram global settings" },
   ];
@@ -1244,6 +1485,14 @@ async function runBotSetup(ui, flags, deps) {
     }
     return;
   }
+  if (action.value === "set_default" && provider === "telegram") {
+    await runBotSetDefault(ui, flags, deps);
+    return;
+  }
+  if (action.value === "migrate" && provider === "telegram") {
+    await runBotMigrate(ui, flags, deps);
+    return;
+  }
   if (action.value === "verify") {
     await verifyProviderEntry(ui, provider, flags, deps);
     return;
@@ -1344,6 +1593,77 @@ async function runBotVerify(ui, flags, deps) {
   await verifyProviderEntry(ui, provider, flags, deps);
 }
 
+async function runBotSetDefault(ui, flags, deps) {
+  const provider = String(flags.provider || "").trim()
+    ? requireDependency(deps, "normalizeBotProvider")(flags.provider)
+    : "telegram";
+  if (provider !== "telegram") {
+    throw new Error("bot set-default currently supports only --provider telegram");
+  }
+  const state = loadProviderEnvState("telegram", deps);
+  const parsed = { ...state.parsed };
+  const nonInteractive = boolFromRaw(flags["non-interactive"] ?? flags.yes, false);
+  const selected = nonInteractive
+    ? findTelegramEntryByFlags(parsed, flags, deps)
+    : await chooseTelegramEntry(ui, parsed, deps, "Select default Telegram bot");
+  if (!selected) {
+    throw new Error("Telegram bot selector is required for set-default");
+  }
+  parsed.TELEGRAM_DEFAULT_BOT_KEY = selected.key;
+  const filePath = writeProviderEnvState("telegram", parsed, deps);
+  process.stdout.write(`Set TELEGRAM_DEFAULT_BOT_KEY=${selected.key} in ${filePath}\n`);
+}
+
+async function runBotMigrate(ui, flags, deps) {
+  const provider = String(flags.provider || "").trim()
+    ? requireDependency(deps, "normalizeBotProvider")(flags.provider)
+    : "telegram";
+  if (provider !== "telegram") {
+    throw new Error("bot migrate currently supports only --provider telegram");
+  }
+  const state = loadProviderEnvState("telegram", deps);
+  const parsed = { ...state.parsed };
+  const legacyToken = String(parsed.TELEGRAM_BOT_TOKEN || "").trim();
+  if (!legacyToken) {
+    process.stdout.write("No legacy TELEGRAM_BOT_TOKEN value is set.\n");
+    return;
+  }
+  const nonInteractive = boolFromRaw(flags["non-interactive"] ?? flags.yes, false);
+  const normalizeBotKey = requireDependency(deps, "normalizeTelegramBotEnvKey");
+  const existingKeys = new Set(telegramEntriesForDisplay(parsed, deps).map((entry) => entry.key));
+  const defaultKeyHint = normalizeBotKey(flags["bot-key"] || parsed.TELEGRAM_DEFAULT_BOT_KEY || "main", "main");
+  const botKey = normalizeBotKey(
+    nonInteractive
+      ? String(flags["bot-key"] || defaultKeyHint).trim()
+      : await promptRequiredLine(ui, "Local Telegram bot key for migrated entry", defaultKeyHint),
+    defaultKeyHint,
+  );
+  if (existingKeys.has(botKey)) {
+    throw new Error(`Telegram bot key "${botKey}" already exists`);
+  }
+  const nextParsed = upsertTelegramEntry(parsed, {
+    key: botKey,
+    serverBotID: getServerBotIDFlag(flags),
+    username: requireDependency(deps, "normalizeTelegramBotUsername")(flags["bot-name"] || flags.username || ""),
+    token: legacyToken,
+    roleProfile: requireDependency(deps, "normalizeRunnerRoleProfileName")(flags["role-profile"] || ""),
+    client: requireDependency(deps, "normalizeLocalAIClientName")(getAIClientFlag(flags), ""),
+    model: getAIModelFlag(flags),
+    permissionMode: requireDependency(deps, "normalizeLocalAIPermissionMode")(getAIPermissionModeFlag(flags), ""),
+    reasoningEffort: requireDependency(deps, "normalizeLocalAIReasoningEffort")(getAIReasoningEffortFlag(flags), ""),
+  });
+  if (!hasNamedTelegramEntry(parsed, deps) || !String(nextParsed.TELEGRAM_DEFAULT_BOT_KEY || "").trim()) {
+    nextParsed.TELEGRAM_DEFAULT_BOT_KEY = botKey;
+  }
+  if (!boolFromRaw(flags["keep-legacy-token"], false)) {
+    nextParsed.TELEGRAM_BOT_TOKEN = "";
+  }
+  const filePath = writeProviderEnvState("telegram", nextParsed, deps);
+  process.stdout.write(
+    `Migrated TELEGRAM_BOT_TOKEN to named entry "${botKey}" in ${filePath}${boolFromRaw(flags["keep-legacy-token"], false) ? " (legacy token preserved)" : ""}\n`,
+  );
+}
+
 async function runBotGlobal(ui, flags, deps) {
   const provider = String(flags.provider || "").trim()
     ? requireDependency(deps, "normalizeBotProvider")(flags.provider)
@@ -1389,6 +1709,14 @@ export async function runBotCommand(argv, deps) {
       await runBotRemove(ui, flags, deps);
       return;
     }
+    if (command === "set-default") {
+      await runBotSetDefault(ui, flags, deps);
+      return;
+    }
+    if (command === "migrate") {
+      await runBotMigrate(ui, flags, deps);
+      return;
+    }
     if (command === "verify") {
       await runBotVerify(ui, flags, deps);
       return;
@@ -1397,7 +1725,7 @@ export async function runBotCommand(argv, deps) {
       await runBotGlobal(ui, flags, deps);
       return;
     }
-    throw new Error("bot requires a subcommand: setup | list | show | add | edit | remove | verify | global");
+    throw new Error("bot requires a subcommand: setup | list | show | add | edit | remove | set-default | migrate | verify | global");
   } finally {
     ui.close();
   }

package/lib/selftest-bot-commands.mjs

@@ -225,29 +225,36 @@ export async function runSelftestBotCommands(push, deps) {
       cliPath,
       args: [
         "bot", "add",
-        "--provider", "telegram",
-        "--non-interactive", "true",
         "--base-url", baseURL,
         "--timeout-seconds", "5",
-        "--bot-key", "main_test",
-        "--bot-id", mock.bots[0].id,
-        "--token", "selftest-main-token",
-        "--role-profile", "monitor",
-        "--client", "codex",
-        "--permission-mode", "read_only",
-        "--reasoning-effort", "low",
-        "--default", "true",
-        "--verify", "true",
       ],
-      env,
+      env: {
+        ...env,
+        METHEUS_SCRIPTED_PROMPT_ANSWERS: JSON.stringify([
+          "1", // provider: telegram
+          "1", // server bot: first listed bot
+          "main_test",
+          "selftest-main-token",
+          "y", // verify now
+          "", // keep verified username
+          "3", // role profile: monitor
+          "2", // ai client: codex
+          "gpt-5-codex",
+          "2", // permission: read_only
+          "2", // reasoning: low
+          "y", // set as default
+        ]),
+      },
     });
     const addState = parseSimpleEnvText(fs.readFileSync(telegramEnvPath, "utf8"));
     push(
-      "bot_add_creates_named_telegram_entry",
+      "bot_add_guided_creates_named_telegram_entry",
       String(addState.TELEGRAM_BOT_MAIN_TEST_SERVER_BOT_ID || "") === mock.bots[0].id
+        && String(addState.TELEGRAM_BOT_MAIN_TEST_USERNAME || "").trim().toLowerCase() === "monitorselftestbot"
         && String(addState.TELEGRAM_BOT_MAIN_TEST_AI_CLIENT || "") === "codex"
+        && String(addState.TELEGRAM_BOT_MAIN_TEST_AI_MODEL || "") === "gpt-5-codex"
         && String(addState.TELEGRAM_DEFAULT_BOT_KEY || "") === "main_test",
-      `default=${String(addState.TELEGRAM_DEFAULT_BOT_KEY || "")} client=${String(addState.TELEGRAM_BOT_MAIN_TEST_AI_CLIENT || "")}`,
+      `default=${String(addState.TELEGRAM_DEFAULT_BOT_KEY || "")} client=${String(addState.TELEGRAM_BOT_MAIN_TEST_AI_CLIENT || "")} model=${String(addState.TELEGRAM_BOT_MAIN_TEST_AI_MODEL || "")}`,
     );
 
     const showResult = await runCLI({
@@ -268,6 +275,43 @@ export async function runSelftestBotCommands(push, deps) {
       `key=${String(safeObject(showPayload.entry).key || "")} client=${String(safeObject(showPayload.entry).client || "")}`,
     );
 
+    await runCLI({
+      cliPath,
+      args: ["bot", "edit"],
+      env: {
+        ...env,
+        METHEUS_SCRIPTED_PROMPT_ANSWERS: JSON.stringify([
+        "1", // provider: telegram
+        "1", // bot entry: main_test
+        "1", // edit mode: guided
+        "1", // keep server bot binding
+        "1", // keep username
+        "1", // keep token
+        "1", // keep role profile
+        "2", // change AI client
+        "4", // gemini
+        "2", // change AI model
+        "guided-gemini-pro",
+        "2", // change permission mode
+        "3", // workspace_write
+        "2", // change reasoning effort
+        "3", // medium
+        "1", // keep bot key
+        "1", // keep default setting
+        "y", // save
+        ]),
+      },
+    });
+    const guidedState = parseSimpleEnvText(fs.readFileSync(telegramEnvPath, "utf8"));
+    push(
+      "bot_edit_guided_prompts_update_ai_binding_fields",
+      String(guidedState.TELEGRAM_BOT_MAIN_TEST_AI_CLIENT || "") === "gemini"
+        && String(guidedState.TELEGRAM_BOT_MAIN_TEST_AI_MODEL || "") === "guided-gemini-pro"
+        && String(guidedState.TELEGRAM_BOT_MAIN_TEST_AI_PERMISSION_MODE || "") === "workspace_write"
+        && String(guidedState.TELEGRAM_BOT_MAIN_TEST_AI_REASONING_EFFORT || "") === "medium",
+      `client=${String(guidedState.TELEGRAM_BOT_MAIN_TEST_AI_CLIENT || "")} model=${String(guidedState.TELEGRAM_BOT_MAIN_TEST_AI_MODEL || "")}`,
+    );
+
     await runCLI({
       cliPath,
       args: [
@@ -294,6 +338,23 @@ export async function runSelftestBotCommands(push, deps) {
       `client=${String(editedState.TELEGRAM_BOT_MAIN_TEST_AI_CLIENT || "")} model=${String(editedState.TELEGRAM_BOT_MAIN_TEST_AI_MODEL || "")}`,
     );
 
+    await runCLI({
+      cliPath,
+      args: [
+        "bot", "set-default",
+        "--provider", "telegram",
+        "--bot-key", "main_test",
+        "--non-interactive", "true",
+      ],
+      env,
+    });
+    const defaultState = parseSimpleEnvText(fs.readFileSync(telegramEnvPath, "utf8"));
+    push(
+      "bot_set_default_updates_default_bot_key",
+      String(defaultState.TELEGRAM_DEFAULT_BOT_KEY || "") === "main_test",
+      `default=${String(defaultState.TELEGRAM_DEFAULT_BOT_KEY || "")}`,
+    );
+
     const verifyResult = await runCLI({
       cliPath,
       args: [
@@ -341,6 +402,80 @@ export async function runSelftestBotCommands(push, deps) {
       ensureArray(telegramEntry.entries).length === 0,
       `entries=${String(ensureArray(telegramEntry.entries).length)}`,
     );
+
+    await runCLI({
+      cliPath,
+      args: [
+        "bot", "add",
+        "--provider", "telegram",
+        "--non-interactive", "true",
+        "--base-url", baseURL,
+        "--timeout-seconds", "5",
+        "--bot-key", "explicit_test",
+        "--server-bot-id", mock.bots[0].id,
+        "--username", "MonitorSelftestBot",
+        "--token", "selftest-main-token",
+        "--role-profile", "monitor",
+        "--ai-client", "codex",
+        "--ai-model", "gpt-5-codex",
+        "--ai-permission-mode", "read_only",
+        "--ai-reasoning-effort", "low",
+        "--verify", "true",
+      ],
+      env,
+    });
+    const aliasAddState = parseSimpleEnvText(fs.readFileSync(telegramEnvPath, "utf8"));
+    push(
+      "bot_add_accepts_ai_prefixed_option_aliases",
+      String(aliasAddState.TELEGRAM_BOT_EXPLICIT_TEST_SERVER_BOT_ID || "") === mock.bots[0].id
+        && String(aliasAddState.TELEGRAM_BOT_EXPLICIT_TEST_AI_CLIENT || "") === "codex"
+        && String(aliasAddState.TELEGRAM_BOT_EXPLICIT_TEST_AI_MODEL || "") === "gpt-5-codex"
+        && String(aliasAddState.TELEGRAM_BOT_EXPLICIT_TEST_AI_PERMISSION_MODE || "") === "read_only"
+        && String(aliasAddState.TELEGRAM_BOT_EXPLICIT_TEST_AI_REASONING_EFFORT || "") === "low",
+      `client=${String(aliasAddState.TELEGRAM_BOT_EXPLICIT_TEST_AI_CLIENT || "")} model=${String(aliasAddState.TELEGRAM_BOT_EXPLICIT_TEST_AI_MODEL || "")}`,
+    );
+
+    await runCLI({
+      cliPath,
+      args: [
+        "bot", "remove",
+        "--provider", "telegram",
+        "--bot-key", "explicit_test",
+        "--non-interactive", "true",
+      ],
+      env,
+    });
+
+    const migratedEnv = parseSimpleEnvText(fs.readFileSync(telegramEnvPath, "utf8"));
+    migratedEnv.TELEGRAM_BOT_TOKEN = "legacy-selftest-token";
+    fs.writeFileSync(
+      telegramEnvPath,
+      Object.entries(migratedEnv).map(([key, value]) => `${key}=${String(value ?? "")}`).join("\n") + "\n",
+      "utf8",
+    );
+    await runCLI({
+      cliPath,
+      args: [
+        "bot", "migrate",
+        "--provider", "telegram",
+        "--bot-key", "legacy_main",
+        "--bot-id", mock.bots[0].id,
+        "--bot-name", "MonitorSelftestBot",
+        "--role-profile", "monitor",
+        "--client", "codex",
+        "--permission-mode", "read_only",
+        "--reasoning-effort", "low",
+        "--non-interactive", "true",
+      ],
+      env,
+    });
+    const migratedState = parseSimpleEnvText(fs.readFileSync(telegramEnvPath, "utf8"));
+    push(
+      "bot_migrate_converts_legacy_token_to_named_entry",
+      String(migratedState.TELEGRAM_BOT_LEGACY_MAIN_TOKEN || "") === "legacy-selftest-token"
+        && String(migratedState.TELEGRAM_BOT_TOKEN || "") === "",
+      `legacy_named=${String(migratedState.TELEGRAM_BOT_LEGACY_MAIN_TOKEN || "")} fallback=${String(migratedState.TELEGRAM_BOT_TOKEN || "")}`,
+    );
   } catch (err) {
     push("bot_commands_smoke", false, String(err?.message || err));
   } finally {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "metheus-governance-mcp-cli",
-  "version": "0.2.63",
+  "version": "0.2.65",
   "description": "Metheus Governance MCP CLI (setup + stdio proxy)",
   "type": "module",
   "files": [