metheus-governance-mcp-cli 0.2.101 → 0.2.103

package/README.md

@@ -31,9 +31,9 @@ Install creates local provider settings templates here:
 These files are for local provider bot secrets, local transport options, and optional per-bot local AI binding.
 
 - Store locally:
-  - Telegram-wide settings in `~/.metheus/telegram-bots/_global.env`
-  - `TELEGRAM_BOT_TOKEN` as a legacy Telegram fallback in `_global.env`
-  - one Telegram bot file per entry in `~/.metheus/telegram-bots/<server-bot-name>.env`
+  - Telegram-wide settings in `~/.metheus/telegram-bots/global.env`
+  - `TELEGRAM_BOT_TOKEN` as a legacy Telegram fallback in `global.env`
+  - one Telegram bot file per entry in `~/.metheus/telegram-bots/<ServerBotName>.env`
   - `SLACK_BOT_TOKEN`
   - `KAKAOTALK_BOT_TOKEN`
 - Server-side Metheus stores project chat destination metadata separately:
@@ -41,12 +41,13 @@ These files are for local provider bot secrets, local transport options, and opt
   - `chat_id` / channel / room identifier
   - label / active state
 - Do not put project chat destination identifiers in local env files.
-- Telegram-wide settings now live in `telegram-bots/_global.env`; Telegram per-bot secrets and AI fields live in `telegram-bots/*.env`.
+- Telegram-wide settings now live in `telegram-bots/global.env`; Telegram per-bot secrets and server metadata live in `telegram-bots/*.env`.
+- Grouped server bots also persist `TELEGRAM_BOT_SERVER_ROLE_IDS`, so the local file keeps the exact role-to-server-bot-id mapping instead of pretending that one grouped bot has only one server UUID.
 
 Example templates:
 
 ```env
-# ~/.metheus/telegram-bots/_global.env
+# ~/.metheus/telegram-bots/global.env
 TELEGRAM_API_BASE_URL=
 TELEGRAM_AUTO_CLEAR_WEBHOOK=true
 TELEGRAM_ALLOWED_UPDATES=message,edited_message
@@ -57,9 +58,13 @@ TELEGRAM_BOT_TOKEN=
 ```
 
 ```env
-# ~/.metheus/telegram-bots/ryoai_bot.env
-TELEGRAM_BOT_NAME=ryoai_bot
-TELEGRAM_BOT_SERVER_BOT_ID=
+# ~/.metheus/telegram-bots/RyoAI_bot.env
+TELEGRAM_BOT_SERVER_BOT_ID=<server_bot_uuid>
+TELEGRAM_BOT_SERVER_NAME=RyoAI_bot
+TELEGRAM_BOT_SERVER_ROLES=monitor,review,worker,approval
+TELEGRAM_BOT_SERVER_ROLE_IDS=monitor:<uuid>,review:<uuid>,worker:<uuid>,approval:<uuid>
+# Optional fallback only when server bot binding is unavailable
+# TELEGRAM_BOT_USERNAME=ryoai_bot
 TELEGRAM_BOT_TOKEN=
 TELEGRAM_BOT_ROLE_PROFILE=
 TELEGRAM_BOT_AI_CLIENT=
@@ -169,10 +174,12 @@ metheus-governance-mcp-cli setup --project-id <project_uuid> --ctxpack-key "<ctx
 - `~/.metheus/kakaotalk.env`
 - `~/.metheus/bot-runner.json`
 
+Bootstrap or setup does not create one file per server bot automatically. Per-bot Telegram files are created later when you run `bot add`, `bot verify`, or `bot edit` against a real server bot identity.
+
 When Telegram local config already exists, bootstrap/setup keeps your secrets but auto-normalizes the layout to the latest split structure:
 
-- Telegram-wide settings stay in `~/.metheus/telegram-bots/_global.env`
-- per-bot secrets move to `~/.metheus/telegram-bots/<server-bot-name>.env`
+- Telegram-wide settings stay in `~/.metheus/telegram-bots/global.env`
+- per-bot secrets move to `~/.metheus/telegram-bots/<ServerBotName>.env`
 - stale inline keys such as `TELEGRAM_BOT_<NAME>_BOT_*` are rewritten into generic per-bot keys
 
 Fill provider bot secrets and provider-local transport options locally. Project chat destination identifiers should be managed on the Metheus server as project chat destinations, not as local env values and not inside legacy Chat Hooks/webhooks.
@@ -182,7 +189,7 @@ Fill provider bot secrets and provider-local transport options locally. Project
 - which provider/role bot profile to use
 - which `project_id -> workspace_dir` mapping to apply locally
 - which role profile maps to which local CLI/model/permission/reasoning policy
-- which server bot maps to which local LLM execution profile via `telegram-bots/_global.env`, `telegram-bots/*.env`, or fallback `bot_bindings`
+- which server bot maps to which local LLM execution profile via `telegram-bots/global.env`, `telegram-bots/*.env`, or fallback `bot_bindings`
 
 Built-in helper command for legacy fallback/testing:
 
@@ -223,15 +230,15 @@ Direct commands:
 
 ```bash
 metheus-governance-mcp-cli bot list
-metheus-governance-mcp-cli bot show --provider telegram --bot-key ryoai_bot
+metheus-governance-mcp-cli bot show --provider telegram --bot-name RyoAI_bot
 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 ryoai_bot
-metheus-governance-mcp-cli bot migrate --provider telegram --bot-key ryoai_bot
+metheus-governance-mcp-cli bot set-default --provider telegram --bot-name RyoAI_bot
+metheus-governance-mcp-cli bot migrate --provider telegram --bot-name RyoAI_bot
 metheus-governance-mcp-cli bot global --provider telegram
-metheus-governance-mcp-cli bot verify --provider telegram --bot-key ryoai_bot
+metheus-governance-mcp-cli bot verify --provider telegram --bot-name RyoAI_bot
 ```
 
 Behavior:
@@ -258,9 +265,12 @@ Behavior:
 - `bot set-default` without flags starts a guided numbered flow: provider -> bot entry -> confirm default change.
 - `bot verify` without flags starts a guided numbered flow: provider -> bot entry -> output format.
 - `bot remove` without flags starts a guided numbered flow: provider -> bot entry -> confirm removal.
-- Telegram stores one bot file per entry under `~/.metheus/telegram-bots/<server-bot-name>.env` with generic fields:
-  - `TELEGRAM_BOT_NAME`
+- Telegram stores one bot file per entry under `~/.metheus/telegram-bots/<ServerBotName>.env` with generic fields:
   - `TELEGRAM_BOT_SERVER_BOT_ID`
+  - `TELEGRAM_BOT_SERVER_NAME`
+  - `TELEGRAM_BOT_SERVER_ROLES`
+  - `TELEGRAM_BOT_SERVER_ROLE_IDS`
+  - `TELEGRAM_BOT_USERNAME` only as a fallback when server bot binding is unavailable
   - `TELEGRAM_BOT_TOKEN`
   - `TELEGRAM_BOT_ROLE_PROFILE`
   - `TELEGRAM_BOT_AI_CLIENT`
@@ -270,6 +280,7 @@ Behavior:
 - Slack and KakaoTalk currently use a single local token entry per provider in this command flow.
 - `bot verify` checks the configured local token, cross-checks the server bot binding, prints the effective runtime role profile summary that the runner will use, and shows which local runner routes currently point at this bot entry.
 - `bot show` prints one local bot entry in detail, including grouped role summaries when one server bot name expands to multiple roles and any linked local runner routes.
+- In `bot show` and `bot verify`, `stored_*` fields come from the local env file and `live_server_*` fields come from the current server `me/bots` response.
 - `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.
@@ -280,16 +291,16 @@ Non-interactive examples:
 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 --server-bot-id <server_bot_uuid> --token <telegram_bot_token> --default true
 metheus-governance-mcp-cli bot add --provider telegram --non-interactive true --server-bot-id <server_bot_uuid> --token <telegram_bot_token> --ai-client gpt --ai-model "gpt-5.4" --ai-permission-mode read_only --ai-reasoning-effort low
-metheus-governance-mcp-cli bot edit --provider telegram --bot-key ryoai_bot --non-interactive true --ai-client claude --ai-model "Sonnet 4.6r" --ai-permission-mode danger_full_access --ai-reasoning-effort high
-metheus-governance-mcp-cli bot set-default --provider telegram --bot-key ryoai_bot --non-interactive true
-metheus-governance-mcp-cli bot migrate --provider telegram --bot-key ryoai_bot --server-bot-id <server_bot_uuid> --bot-name <telegram_username> --role-profile monitor --ai-client gpt --ai-permission-mode read_only --ai-reasoning-effort low --non-interactive true
-metheus-governance-mcp-cli bot remove --provider telegram --bot-key ryoai_bot --non-interactive true
-metheus-governance-mcp-cli bot verify --provider telegram --bot-key ryoai_bot --json true
+metheus-governance-mcp-cli bot edit --provider telegram --bot-name RyoAI_bot --non-interactive true --ai-client claude --ai-model "Sonnet 4.6r" --ai-permission-mode danger_full_access --ai-reasoning-effort high
+metheus-governance-mcp-cli bot set-default --provider telegram --bot-name RyoAI_bot --non-interactive true
+metheus-governance-mcp-cli bot migrate --provider telegram --bot-name RyoAI_bot --server-bot-id <server_bot_uuid> --role-profile monitor --ai-client gpt --ai-permission-mode read_only --ai-reasoning-effort low --non-interactive true
+metheus-governance-mcp-cli bot remove --provider telegram --bot-name RyoAI_bot --non-interactive true
+metheus-governance-mcp-cli bot verify --provider telegram --bot-name RyoAI_bot --json true
 ```
 
-For direct Telegram adds, the CLI can derive the local entry key from the matched server bot name. You no longer need `--bot-key` or `--username` in the normal server-bound path. Treat `--bot-key` as an advanced override only when you intentionally want a different local suffix.
+For direct Telegram adds, the CLI derives the local file name from the matched server bot name. You normally do not need `--bot-key` or `--username`. Treat `--bot-key` as an advanced compatibility selector only when you intentionally need to target an older local selector directly.
 
-For direct Telegram edits, `--bot-key` still identifies which saved local entry to update. If one server bot name expands to multiple roles such as `approval / worker / review / monitor`, prefer the guided `bot edit` flow so you can keep the current grouped settings, edit one role only, or walk every role in sequence instead of forcing one entry-level AI override.
+For direct Telegram edits, prefer `--bot-name` or `--bot-id` because server bot identity is the source of truth. Use `--bot-key` only when you intentionally need the advanced local selector. If one server bot name expands to multiple roles such as `approval / worker / review / monitor`, prefer the guided `bot edit` flow so you can keep the current grouped settings, edit one role only, or walk every role in sequence instead of forcing one entry-level AI override.
 
 Current support status:
 
@@ -371,6 +382,7 @@ Execution model:
 Commands:
 
 ```bash
+metheus-governance-mcp-cli runner list
 metheus-governance-mcp-cli runner once --route-name telegram-monitor
 metheus-governance-mcp-cli runner start --route-name telegram-monitor
 ```
@@ -397,7 +409,7 @@ Recommended production path:
 - keep `project_mappings.<project_id>.workspace_dir` aligned to that teammate's actual local project folder
 - let `ctxpack pull` or project connection refresh the mapping automatically
 - keep per-role execution policy under `role_profiles`
-- keep Telegram-wide binding defaults in `~/.metheus/telegram-bots/_global.env`
+- keep Telegram-wide binding defaults in `~/.metheus/telegram-bots/global.env`
 - use `bot_bindings` in `bot-runner.json` only as local fallback/override
 - runner resolution order is: explicit `route.role_profile` -> provider env bot binding -> `bot_bindings` -> server bot role -> `route.role`
 
@@ -470,7 +482,7 @@ Notes:
 - `local-bot-bridge` reads stdin JSON from the runner and can call Codex/Claude/Gemini for you
 - `route.command` fallback is disabled by default; enable it only temporarily with `METHEUS_ALLOW_LEGACY_RUNNER_COMMAND=1`
 - today this automation path is implemented for Telegram end-to-end
-- prefer `TELEGRAM_API_BASE_URL=` inside `~/.metheus/telegram-bots/_global.env` for local Telegram API overrides; `METHEUS_TELEGRAM_API_BASE_URL` remains a process-level fallback mainly for mock/regression testing
+- prefer `TELEGRAM_API_BASE_URL=` inside `~/.metheus/telegram-bots/global.env` for local Telegram API overrides; `METHEUS_TELEGRAM_API_BASE_URL` remains a process-level fallback mainly for mock/regression testing
 - Slack can use direct local send, but automatic inbound runner flow is not completed yet
 - KakaoTalk config can be stored now, but direct send/runner flow is not implemented yet
 - `doctor` now reports provider support for both enabled runner routes and active project chat destinations