From 141d6d2a88f093fb4fb80fc15f104965d5f4eeba Mon Sep 17 00:00:00 2001
From: araharah-executor <executor@araharah.local>
Date: Sun, 25 Oct 2026 05:29:38 +0800
Subject: [PATCH] =?UTF-8?q?fix(07-06):=20root-cause=20the=20/cari=20menu?=
 =?UTF-8?q?=20defect=20=E2=80=94=20register-commands.mjs=20sent=20the=20wr?=
 =?UTF-8?q?ong=20Bot=20API=20field=20name?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- the Bot API parameter is 'scope' (verified against
  core.telegram.org/bots/api/methods/setmycommands); the script's
  'bot_command_scope' was an unknown field Telegram silently ignores,
  so every call hit the default scope and the two clear calls wiped the
  default set entirely — the ok:true lines proved nothing about scope
- registration re-run: default (agnostic/en/ms) + all_private_chats
  (agnostic/ms) read back help, privacy, cari via getMyCommands with
  the correct 'scope' param; group scopes verified cleared
- docs/KNOWN-LIMITATIONS.md: the 'Telegram-side defect' attribution
  corrected to the actual script bug; residual client menu-caching
  caveat + type-the-command workaround kept
- bot/README.md command row updated to the real scope set
---
 bot/README.md                     |  2 +-
 bot/scripts/register-commands.mjs | 22 +++++++++++++++-------
 docs/KNOWN-LIMITATIONS.md         | 21 ++++++++++++---------
 3 files changed, 28 insertions(+), 17 deletions(-)

diff --git a/bot/README.md b/bot/README.md
index 2193860..90ec3df 100644
--- a/bot/README.md
+++ b/bot/README.md
@@ -162,7 +162,7 @@ Run from the repo root (`npm run bot:<script>`) or inside `bot/`.
 | `npm run typecheck` | `tsc --noEmit` against `src/` with Workers types. |
 | `npm run dev` | `wrangler dev --port 8787 --local`. |
 | `npm run deploy` | `wrangler deploy` followed by `scripts/set-webhook.mjs`. |
-| `npm run commands` | `scripts/register-commands.mjs` — one-time `setMyCommands` in the default scope, plus a `language_code: "ms"` variant of that same default scope (both calls send `bot_command_scope: { type: "default" }`). |
+| `npm run commands` | `scripts/register-commands.mjs` — one-time `setMyCommands` arming every scope a stale set could shadow: default (en) · default+ms · all_private_chats (en) · all_private_chats+ms, plus clearing the group scopes (all calls send `scope: { type: … }` — the Bot API field name; a previous wrong name, `bot_command_scope`, was silently ignored by Telegram and caused the /cari-menu incident, fixed 2026-10-25). |
 
 `scripts/set-menu-button.mjs` is run directly (`node scripts/set-menu-button.mjs`) rather than through a package script; it points the bot's menu button at a `web_app` URL derived from `WEBHOOK_URL`'s origin.
 
diff --git a/bot/scripts/register-commands.mjs b/bot/scripts/register-commands.mjs
index 6793abd..f895b0d 100644
--- a/bot/scripts/register-commands.mjs
+++ b/bot/scripts/register-commands.mjs
@@ -75,18 +75,26 @@ function menuFor(locale) {
  * from-menu incident). The script therefore arms every scope it may shadow:
  *   default (en) · default+ms · all_private_chats (en) · all_private_chats+ms
  * and CLEARS the group scopes (leftover phase-2 experiments) so no junk set
- * shadows anything elsewhere. ————— */
+ * shadows anything elsewhere.
+ *
+ * GATE-BUG FIX (07-06 canary, 2026-10-25): the Bot API parameter is `scope`
+ * (https://core.telegram.org/bots/api/methods/setmycommands) — this script
+ * previously sent `bot_command_scope`, an unknown field Telegram SILENTLY
+ * ignores, so every call actually hit the default scope and the two "clear"
+ * calls wiped the default set entirely (the true root cause of the /cari
+ * menu defect; the setMyCommands ok:true lines proved nothing about scope).
+ * ————— */
 
 const API = `https://api.telegram.org/bot${token}/setMyCommands`;
 const JSON_HEADERS = { "content-type": "application/json" };
 
 const CALLS = [
-  { label: "default (en)", body: { commands: menuFor("en"), bot_command_scope: { type: "default" } } },
-  { label: "default (ms)", body: { commands: menuFor("ms"), bot_command_scope: { type: "default" }, language_code: "ms" } },
-  { label: "all_private_chats (en)", body: { commands: menuFor("en"), bot_command_scope: { type: "all_private_chats" } } },
-  { label: "all_private_chats (ms)", body: { commands: menuFor("ms"), bot_command_scope: { type: "all_private_chats" }, language_code: "ms" } },
-  { label: "clear all_group_chats", body: { commands: [], bot_command_scope: { type: "all_group_chats" } } },
-  { label: "clear all_chat_administrators", body: { commands: [], bot_command_scope: { type: "all_chat_administrators" } } },
+  { label: "default (en)", body: { commands: menuFor("en"), scope: { type: "default" } } },
+  { label: "default (ms)", body: { commands: menuFor("ms"), scope: { type: "default" }, language_code: "ms" } },
+  { label: "all_private_chats (en)", body: { commands: menuFor("en"), scope: { type: "all_private_chats" } } },
+  { label: "all_private_chats (ms)", body: { commands: menuFor("ms"), scope: { type: "all_private_chats" }, language_code: "ms" } },
+  { label: "clear all_group_chats", body: { commands: [], scope: { type: "all_group_chats" } } },
+  { label: "clear all_chat_administrators", body: { commands: [], scope: { type: "all_chat_administrators" } } },
 ];
 
 let failed = null;
diff --git a/docs/KNOWN-LIMITATIONS.md b/docs/KNOWN-LIMITATIONS.md
index 71dbdb2..4801b00 100644
--- a/docs/KNOWN-LIMITATIONS.md
+++ b/docs/KNOWN-LIMITATIONS.md
@@ -42,15 +42,18 @@ breaks the project's $0 mandate.
 
 ## The /cari command may be missing from the Telegram menu
 
-Some drivers see a command menu listing `/help` and `/privacy` but **not** `/cari`.
-This is a Telegram `setMyCommands` scope-resolution behaviour, not a bot bug:
-Telegram resolves a chat's menu from the narrowest scope that has ANY commands set,
-so a stale non-default scope (for example an old `all_private_chats` set recorded
-before `/cari` existed) shadows the default scope's fuller menu. The bot re-arms
-every such scope (`bot/scripts/register-commands.mjs`), but the Telegram client may
-keep showing the cached menu until the app restarts. **The workaround: type `/cari`
-in the chat** — the command itself has always worked; only its discoverability is
-affected.
+Some drivers saw a command menu listing `/help` and `/privacy` but **not** `/cari`.
+ROOT CAUSE (found and FIXED 2026-10-25, 07-06 launch-gate canary): it was a bot-side
+script bug, not a Telegram defect — `bot/scripts/register-commands.mjs` sent the scope
+under the wrong parameter name (`bot_command_scope`; the Bot API field is `scope`),
+which Telegram silently ignores, so every registration call actually hit the default
+scope and the group-scope "clear" calls wiped the default set entirely. The correct
+parameter was verified against https://core.telegram.org/bots/api/methods/setmycommands,
+the script was fixed, and all private-chat scopes now read back `help, privacy, cari`
+via `getMyCommands` (verified 2026-10-25). What REMAINS: the Telegram client caches the
+menu — a device that opened the bot before the fix may keep showing the stale menu
+until the app restarts. **The workaround: type `/cari` in the chat** — the command
+itself has always worked; only its discoverability was affected.
 
 ## Beta quality