@rubytech/create-maxy-code 0.1.582 → 0.1.584

package/payload/platform/plugins/telegram/mcp/dist/tools/webhook-register.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"webhook-register.d.ts","sourceRoot":"","sources":["../../src/tools/webhook-register.ts"],"names":[],"mappings":"AAgBA,MAAM,WAAW,qBAAqB;IACpC,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,OAAO,GAAG,QAAQ,CAAC;IACzB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB,QAAQ,CAAC,EAAE,MAAM,GAAG,WAAW,GAAG,UAAU,CAAC;IAC7C,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;CACtB;AAED,MAAM,WAAW,mBAAmB;IAClC,YAAY,EAAE,MAAM,GAAG,SAAS,CAAC;IACjC,SAAS,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9B,GAAG,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC5B,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;IACzB,0EAA0E;IAC1E,MAAM,CAAC,EAAE,MAAM,MAAM,CAAC;IACtB,+EAA+E;IAC/E,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,CAAC;CAC3C;AAED,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,OAAO,CAAC;CAClB;AAID;;;;;;;uBAOuB;AACvB,wBAAsB,eAAe,CACnC,MAAM,EAAE,qBAAqB,EAC7B,IAAI,EAAE,mBAAmB,GACxB,OAAO,CAAC,qBAAqB,CAAC,CAsKhC"}
+{"version":3,"file":"webhook-register.d.ts","sourceRoot":"","sources":["../../src/tools/webhook-register.ts"],"names":[],"mappings":"AAgBA,MAAM,WAAW,qBAAqB;IACpC,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,OAAO,GAAG,QAAQ,GAAG,YAAY,CAAC;IACxC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;8DAC0D;IAC1D,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB,QAAQ,CAAC,EAAE,MAAM,GAAG,WAAW,GAAG,UAAU,CAAC;IAC7C,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;CACtB;AAED,MAAM,WAAW,mBAAmB;IAClC,YAAY,EAAE,MAAM,GAAG,SAAS,CAAC;IACjC,SAAS,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9B,GAAG,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC5B,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;IACzB,0EAA0E;IAC1E,MAAM,CAAC,EAAE,MAAM,MAAM,CAAC;IACtB,+EAA+E;IAC/E,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,CAAC;CAC3C;AAED,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,OAAO,CAAC;CAClB;AAID;;;;;;;uBAOuB;AACvB,wBAAsB,eAAe,CACnC,MAAM,EAAE,qBAAqB,EAC7B,IAAI,EAAE,mBAAmB,GACxB,OAAO,CAAC,qBAAqB,CAAC,CAmPhC"}

package/payload/platform/plugins/telegram/mcp/dist/tools/webhook-register.js

@@ -3,7 +3,7 @@ import { dirname } from "node:path";
 import { admitsWebhookPath, botIdFromToken, persistTelegramBot, CANONICAL_TELEGRAM_PREFIX, } from "../lib/account-write.js";
 import { setWebhook, getWebhookInfo, webhookVerdict, TELEGRAM_ALLOWED_UPDATES } from "../lib/telegram.js";
 import { configDirName, resolveSecretFilePath } from "../lib/secret-path.js";
-import { accountDirFor, isActiveAgentSlug } from "../lib/agent-active.js";
+import { accountDirFor, isActiveAgentSlug, listSpecialistCardNames } from "../lib/agent-active.js";
 import { buildWebhookUrl } from "../lib/webhook-url.js";
 const TAG = "[telegram-setup]";
 const fail = (text) => ({ text, isError: true });
@@ -16,7 +16,7 @@ const fail = (text) => ({ text, isError: true });
  *  The persist runs LAST: a registration that cannot be proved reachable leaves
  *  nothing on disk. */
 export async function webhookRegister(params, deps) {
-    const { botToken, webhookUrl, role, agent, adminUsers, dmPolicy, allowFrom } = params;
+    const { botToken, webhookUrl, role, agent, specialist, adminUsers, dmPolicy, allowFrom } = params;
     const { platformRoot, accountId, log } = deps;
     const fetchImpl = deps.fetchImpl ?? fetch;
     const nowSec = deps.nowSec ?? (() => Math.floor(Date.now() / 1000));
@@ -50,6 +50,26 @@ export async function webhookRegister(params, deps) {
             return fail(`Agent "${agent}" is not an active agent on this account, so a bot cannot answer as it.`);
         }
     }
+    // Task 2619 — a specialist bot names the card it runs as and the ids allowed
+    // to message it. Both are required. There is no `open` policy for this role,
+    // so an empty allowlist would register a bot nobody can reach; and an
+    // unresolvable card would register a bot that refuses every message it ever
+    // receives, silently, because nothing announces a card being renamed.
+    if (role === "specialist") {
+        if (!specialist || specialist.length === 0) {
+            log(`${TAG} op=token-write-rejected reason=no-specialist botId=${botId}`);
+            return fail(`A specialist bot must name the specialist it runs as. Pass \`specialist\` with one of this account's specialist card names.`);
+        }
+        const cards = listSpecialistCardNames(accountDirFor(platformRoot, accountId));
+        if (!cards.includes(specialist)) {
+            log(`${TAG} op=token-write-rejected reason=specialist-unknown botId=${botId} specialist=${specialist}`);
+            return fail(`"${specialist}" is not a specialist on this account, so a bot cannot run as it. This account has: ${cards.join(", ") || "none"}.`);
+        }
+        if (!allowFrom || allowFrom.length === 0) {
+            log(`${TAG} op=token-write-rejected reason=no-allowlist botId=${botId}`);
+            return fail(`A specialist bot needs a list of who may message it. Pass \`allowFrom\` with the numeric Telegram user IDs allowed to reach it; there is no open policy for this role.`);
+        }
+    }
     // Task 2560 — exactly one path reaches the handler. Asserted before Telegram
     // is touched, so a refused path leaves no registration behind.
     const webhookPath = (() => {
@@ -80,6 +100,36 @@ export async function webhookRegister(params, deps) {
             return fail(`Invalid bot token: ${meData.description ?? "getMe failed"}`);
         }
         const botUsername = meData.result?.username ?? "unknown";
+        // Task 2616 — the group pre-flight, BEFORE the freshness stamp, so a refused
+        // bot leaves no registration behind and nothing on disk. That order is Task
+        // 2560's.
+        //
+        // Privacy mode is what keeps a bot in a room to commands, @mentions and
+        // replies. With it off the bot receives every message anyone types in every
+        // group it is in, and nothing else on this install would say so: no update
+        // names the setting and the flood reads as ordinary traffic.
+        //
+        // A flag Telegram did not send refuses nothing and prints `absent`, never
+        // `false`: `false` would claim Telegram had told us privacy was on when it
+        // had told us nothing, and this line is the only standing record of what it
+        // said at registration time.
+        const rawReadAll = meData.result?.can_read_all_group_messages;
+        const rawJoin = meData.result?.can_join_groups;
+        const say = (v) => (v === undefined ? "absent" : String(v));
+        const privacyOff = rawReadAll === true;
+        const cannotJoin = rawJoin === false;
+        const groupVerdict = privacyOff || cannotJoin ? "refused" : "ok";
+        log(`[telegram-webhook] op=group-preflight botId=${botId} canJoinGroups=${say(rawJoin)} ` +
+            `canReadAllGroupMessages=${say(rawReadAll)} verdict=${groupVerdict}`);
+        if (privacyOff) {
+            return fail(`@${botUsername} has group privacy mode OFF, so in any group it joins it would receive every ` +
+                `message anyone types. In BotFather: /mybots, pick this bot, Bot Settings, Group Privacy, ` +
+                `Turn on. Then register again. Nothing was registered or written.`);
+        }
+        if (cannotJoin) {
+            return fail(`@${botUsername} cannot be added to groups. In BotFather: /mybots, pick this bot, Bot Settings, ` +
+                `Allow Groups?, Turn on. Then register again. Nothing was registered or written.`);
+        }
         // Stamped immediately before registering: the probe below only treats an
         // error Telegram saw AT OR AFTER this moment as this registration's.
         const registeredAtSec = nowSec();
@@ -130,7 +180,9 @@ export async function webhookRegister(params, deps) {
         // failure here means nothing was persisted.
         const entry = role === "admin"
             ? { id: botId, token: botToken, role: "admin", ...(adminUsers ? { adminUsers } : {}) }
-            : { id: botId, token: botToken, role: "public", agent: agent, ...(dmPolicy ? { dmPolicy } : {}), ...(allowFrom ? { allowFrom } : {}) };
+            : role === "specialist"
+                ? { id: botId, token: botToken, role: "specialist", specialist: specialist, allowFrom: allowFrom }
+                : { id: botId, token: botToken, role: "public", agent: agent, ...(dmPolicy ? { dmPolicy } : {}), ...(allowFrom ? { allowFrom } : {}) };
         const persisted = persistTelegramBot(platformRoot, accountId, entry);
         if (!persisted.ok) {
             log(`${TAG} op=token-write-rejected reason=${persisted.error}${persisted.dir ? ` dir=${persisted.dir}` : ""}`);
@@ -144,7 +196,10 @@ export async function webhookRegister(params, deps) {
         // shape. This tool no longer deletes anything of its own.
         return {
             isError: false,
-            text: `Webhook registered for @${botUsername} (bot ${botId}, role ${role}${role === "public" ? `, answering as ${agent}` : ""})` +
+            text: `Webhook registered for @${botUsername} (bot ${botId}, role ${role}` +
+                (role === "public" ? `, answering as ${agent}` : "") +
+                (role === "specialist" ? `, running ${specialist} for ${allowFrom.length} allowed user(s)` : "") +
+                `)` +
                 `\nURL: ${registeredUrl}` +
                 `\nSecret: generated and saved to ${secretFilePath}` +
                 verifyInfo,

package/payload/platform/plugins/telegram/mcp/dist/tools/webhook-register.js.map

@@ -1 +1 @@
-{"version":3,"file":"webhook-register.js","sourceRoot":"","sources":["../../src/tools/webhook-register.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"webhook-register.js","sourceRoot":"","sources":["../../src/tools/webhook-register.ts"],"names":[],"mappings":"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"}

package/payload/platform/plugins/telegram/skills/build/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: build
-description: Build your own Telegram functionality on this install — cards with buttons, editing a card in place, answering a button press, opening a Mini App inside the chat, sending and fetching files, polls and locations, invoices and Telegram Stars, threading a chat per job, and reaching any of the 185 Bot API methods through telegram-api. Use when the operator wants Telegram to do something the named tools do not already do.
+description: Build your own Telegram functionality on this install — cards with buttons, editing a card in place, answering a button press, opening a Mini App inside the chat, sending and fetching files, polls and locations, threading a chat per job, and reaching any of the 185 Bot API methods through telegram-api. Use when the operator wants Telegram to do something the named tools do not already do.
 ---
 
 # Build a Telegram surface
@@ -17,15 +17,15 @@ and this skill says how to call it.
 
 ## What you have
 
-Ten named tools for the common paths, and one passthrough for everything else.
+Eleven named tools for the common paths, and one passthrough for everything else.
 
 | Tool | Use it for |
 |---|---|
+| `mcp__telegram__telegram-reach` | Which chats each registered bot can message now, and which allowlisted admins have never messaged it |
 | `mcp__telegram__telegram-card` | Posting a card, or editing the one your key already names |
 | `mcp__telegram__telegram-ask` | Polls, checklists, locations, venues, contacts, dice |
 | `mcp__telegram__telegram-media-send` | Sending a photo, file, video, audio or album, and editing media or captions |
 | `mcp__telegram__telegram-media-fetch` | Fetching a file by `file_id` |
-| `mcp__telegram__telegram-invoice` | Invoices, invoice links, checkout answers, Telegram Stars |
 | `mcp__telegram__telegram-thread` | Forum topics, one thread per job |
 | `mcp__telegram__message-history` | Reading what arrived |
 | `mcp__telegram__telegram-webhook-register` | Registering a bot's webhook. The only sanctioned path |
@@ -36,7 +36,20 @@ Ten named tools for the common paths, and one passthrough for everything else.
 `telegram-api` takes `botId` (never a token), `method`, `params`, and optionally `files` and
 `timeoutMs`. Field names inside `params` are Telegram's own snake_case.
 
-## The five methods it will not call
+## Who you can send to
+
+Telegram does not let a bot open a conversation. Somebody who has messaged one of this account's
+bots can be messaged back at any time with `telegram-card` and their chat id; somebody who never has
+must write to the bot first, and no tool here can shortcut that.
+
+`telegram-reach` is what tells the two apart. It takes no parameters and lists, per registered bot,
+every private chat that has messaged it — chat id, name, and when they last wrote — plus any admin
+user allowlisted on that bot who has never messaged. Being on the allowlist is not the same fact as
+having opened the chat, and only the second one makes a send possible.
+
+Read it before telling anybody a Telegram send is impossible.
+
+## The seven methods it will not call
 
 Each refusal names the tool that owns the capability instead.
 
@@ -45,6 +58,41 @@ Each refusal names the tool that owns the capability instead.
 | `setWebhook`, `deleteWebhook` | Webhook state is registered on the one path the maxy edge admits, stamped with the bot id. A raw call silently repoints or stops every inbound message | `telegram-webhook-register` |
 | `getUpdates` | Telegram's two ways of receiving updates are mutually exclusive, and this one does not work while a webhook is set | The webhook already delivers inbound |
 | `logOut`, `close` | Both move the bot off the cloud Bot API server | Nothing. Do not do this |
+| `getManagedBotToken`, `replaceManagedBotToken` | The result IS a live bot token. Relaying it puts a credential in a tool result, and therefore in the transcript | `telegram-bot-provision`, which persists tokens and returns only bot ids |
+
+`getManagedBotAccessSettings` and `setManagedBotAccessSettings` are NOT refused: they return no
+credential, so refusing them would remove a capability while protecting nothing. Prefer
+`telegram-bot-provision action=access` anyway, which logs the change.
+
+## Creating a bot without BotFather
+
+`telegram-bot-provision` has four actions.
+
+| Action | What it does |
+|---|---|
+| `offer` | Sends a one-tap button into a private chat. The person taps it, names the bot, and this install receives it, stores its token, restricts it to its owner and registers its webhook |
+| `rotate` | Revokes a managed bot's token, saves the replacement, and re-registers the webhook at the URL it was already on |
+| `access` | Reads the access settings when `isAccessRestricted` is omitted; writes them when it is given. Up to ten `addedUserIds` besides the owner |
+| `list` | This account's bots by id and role. Never a token |
+
+```
+telegram-bot-provision botId=<managing-bot> action=offer chatId=<private-chat>
+  suggestedName="Front Desk" suggestedUsername="frontdesk_bot"
+```
+
+Three things to know before using it:
+
+- The managing bot must have management of other bots enabled **once**, in the @BotFather Mini App.
+  No API call turns it on. `offer` checks `getMe().can_manage_bots` and refuses with the Mini App
+  named, so a button that would do nothing is never sent.
+- The button is a REPLY keyboard and Telegram makes it **private chats only**. A group or channel
+  id will not work.
+- A provisioned bot lands as `role:'unbound'` and answers nobody until an agent is bound to it. It
+  is restricted to its owner on Telegram's side at the same time.
+
+Telegram sends no `request_id` back and no event discriminator, so a creation and a token change
+are told apart only by whether the account already holds the bot id, and the log correlates on
+`newBotId` rather than on the request id.
 
 ## Five things people actually build
 
@@ -166,6 +214,21 @@ form needs forum topic mode enabled on the bot: `sendMessage`'s `message_thread_
 working "for forum supergroups and private chats of bots with forum topic mode enabled only", so
 without it the topic exists and nothing can be sent into it.
 
+**A message from a topic is answered in that topic, and you do not arrange it.** The route reads the
+topic off the inbound and threads it through the reply, so your turn's final text lands where the
+question was asked. You only pass `messageThreadId` yourself when you are sending into a topic
+nobody just wrote in.
+
+**A checklist cannot go into a topic.** `sendChecklist` is the one send method with no
+`message_thread_id` in its table. `telegram-ask` refuses that pair before the network call rather
+than dropping the field and letting the checklist land in the group's General thread, which used to
+read as the call having worked. Send it without `messageThreadId`, or use a poll or a plain message
+for the topic itself.
+
+**Only a real topic counts.** Telegram also stamps `message_thread_id` on an ordinary reply in a
+supergroup, so the route keys on `is_topic_message` instead. A plain reply is answered in the
+conversation, not pulled into a thread.
+
 ### 8. Asking a question, or sending a place
 
 `telegram-ask` covers the structured sends. A poll takes its answers as plain strings:
@@ -200,6 +263,29 @@ connection. Pass one explicitly only to override that. With nothing stored the t
 the operator step, which means the answer is to ask the operator to connect the bot, not to hunt for
 a parameter.
 
+**A customer messaging the connected business account reaches you in their own conversation, not the
+operator's.** Once the operator connects the bot under Telegram, Settings, Business, Chatbots, every
+message in that account's private chats arrives here as a turn of its own. Four things follow.
+
+The turn is a **stranger's**, so it runs as the entry's public agent and carries none of the
+operator's standing rules, whatever role the bot itself holds. The two conversations never share a
+session even when the same person is in both.
+
+Every reply **quotes the connection**, and you do not supply it: `telegram-card` and the turn's own
+reply fill it in from the stored connection. Telegram routes the message as the business account
+rather than as the bot, and there is no variant without it.
+
+The **24-hour window is a hard limit**. `BusinessBotRights.can_reply` grants the right to answer only
+"in the private chats that had incoming messages in the last 24 hours". A send past that is refused
+here before it is attempted, and the refusal names the window. Nothing is emitted when a window
+closes, so a customer you leave unanswered simply becomes unreachable with no error anywhere. Answer
+while you can.
+
+An edit from the customer **changes the message you already have** rather than arriving as a new one.
+It still raises a turn, because a customer who rewrites their question has asked something new; what
+it does not do is leave you two messages to reconcile. A deletion marks the message deleted rather
+than removing it, so what was withdrawn stays readable, and it raises no turn at all.
+
 **A business connection and Telegram Premium are two separate gates, and they govern different
 things.** Telegram states them apart, so do not treat one as the other. Bot API 9.1 (3 July 2025)
 added `sendChecklist` and `editMessageChecklist` "allowing bots to send a checklist on behalf of a
@@ -224,36 +310,13 @@ business account, so send the Mini App button as its own ordinary message. This
 
 ### 9. Charging for something
 
-`telegram-invoice` takes Telegram Stars with `currency=XTR` and no provider token, or a real
-currency through a token from BotFather. Amounts are whole numbers in the currency's smallest unit,
-so £4.50 is 450 and a 500-star price is 500.
-
-```
-telegram-invoice botId=<id> action=send chatId=<chat> title="Emergency callout"
-  description="Same-day attendance, first hour" payload="job-4102" currency="XTR"
-  prices=[{label:"Callout", amount:500}]
-```
-
-`action=link` returns a payable URL instead of posting into a chat, which is what you want for a
-link you paste somewhere else. Don't pass buttons: Telegram requires the first button of an invoice
-keyboard to be a Pay button, and leaving the keyboard off gets that button for free.
-
-`payload` is your own reference. It is never shown to the payer and it comes back on the
-successful-payment update, which is how a payment is matched to a job.
-
-**You do not answer the pre-checkout query.** Telegram cancels the transaction if no answer lands
-within ten seconds, and a turn cannot start and finish in ten seconds, so the inbound route answers
-it itself: `ok=true` for a sender with access, `ok=false` for one without. You then get a turn saying
-`[pre-checkout approved: …]`, and once the payer confirms, a second one saying
-`[payment received: …]` with your own `payload` on it. `action=answerPreCheckout` stays on the tool
-for a surface that answers out of band; calling it for a query the route has already answered gets a
-Telegram error about a stale id.
+You cannot, inside Telegram. The payment surface was removed: there is no `telegram-invoice`
+tool, and `telegram-api` refuses all eight Bot API payment methods.
 
-Set `isFlexible` and Telegram sends a shipping query mid-checkout. That one **is** yours: the route
-raises a turn saying `[shipping query: …]` with the `queryId`, because only you know the options.
-Answer it with `action=answerShipping`. `ok=false` needs `errorMessage`, which Telegram shows the
-payer verbatim. `balance`, `transactions`, `refund` and `editSubscription` are the Stars controls; a
-subscription that is cancelled, re-enabled or fails to charge arrives as its own turn.
+The reason is redemption, not capability. Telegram Stars cannot be withdrawn by a bot — that
+route is a client API method returning a Fragment page that takes a TON wallet address — and the
+fiat path needs a BotFather provider this install does not hold. Charge outside Telegram and send
+the payer a link; `telegram-card` takes a `url` button for exactly that.
 
 ### Ephemeral messages
 
@@ -266,7 +329,8 @@ sends group messages visible to a single user.
 
 ## What arrives from Telegram
 
-Telegram defines twenty-six update classes. This install registers fourteen and handles ten of them.
+Telegram defines twenty-six update classes. This install registers twenty-two and handles seventeen
+of them.
 
 | Class | Registered | What happens |
 |---|---|---|
@@ -275,14 +339,29 @@ Telegram defines twenty-six update classes. This install registers fourteen and
 | `poll_answer` | yes | a turn per voter |
 | `poll` | yes | a turn on close only, naming the question and the counts |
 | `message_reaction` | yes | a turn naming the emoji and the message reacted to |
-| `pre_checkout_query` | yes | answered by the route inside ten seconds, then a turn |
-| `shipping_query` | yes | a turn; you answer it with `telegram-invoice action=answerShipping` |
+| `pre_checkout_query` | no | logged and left to cancel: no answer, no turn |
+| `shipping_query` | no | logged only, no turn |
 | `subscription` | yes | a turn naming the state (`canceled`, `active`, `failed`) |
 | `my_chat_member` | yes | logged only, no turn: in a DM this is a block or an unblock |
 | `business_connection` | yes | recorded so `business_connection_id` can be supplied |
-| `business_message`, `edited_business_message`, `deleted_business_messages` | yes | registered and stored; no turn is raised from them yet |
+| `business_message` | yes | a turn, in the customer's own session |
+| `edited_business_message` | yes | a turn, and it patches the message rather than adding one |
+| `deleted_business_messages` | yes | marks the stored rows deleted, no turn |
+| `chat_member` | yes | logged only, no turn: another member joined, left or was removed |
+| `chat_join_request` | yes | logged only, no turn |
+| `message_reaction_count` | yes | logged against the message, no turn: the anonymous tally, as against `message_reaction` which names the reactor |
+| `chat_boost`, `removed_chat_boost` | yes | logged only, no turn |
+| `channel_post`, `edited_channel_post` | yes | a turn, attributed to the channel, when the channel is allowlisted |
 | everything else | no | does not arrive |
 
+None of `chat_member`, `chat_join_request`, `message_reaction_count` or the two boost classes raises
+a turn, and none takes an access decision: they are things that happened, with nobody addressing the
+bot, so there is nobody to admit or refuse.
+
+**A channel post has no author.** Telegram documents `Message.from` as "may be empty for messages
+sent to channels", so the turn names the channel by its title and there is no person in it. Do not
+address a channel post as if somebody wrote it.
+
 **A reaction may never arrive in a DM.** Telegram documents `message_reaction` as requiring the bot
 to be an administrator in the chat, and a private chat has no administrator. The class is registered
 and the handler exists; if nothing ever arrives from a DM, reactions are group-only here.
@@ -293,8 +372,13 @@ Naming **any** class in `allowed_updates` replaces Telegram's default set. Teleg
 every class except `chat_member`, `message_reaction` and `message_reaction_count` — so a class that
 works today and is missing from the list stops arriving, with no error in any log.
 
+Those same three are the ones outside the default, so a bot registered before they were added
+receives none of them until it re-registers. That is not a failure anything reports: the bot simply
+never sees a reaction or a membership change.
+
 The list lives in exactly one place, `TELEGRAM_ALLOWED_UPDATES` in
-`plugins/telegram/mcp/src/lib/telegram.ts`. Add a class there and nowhere else, and re-register the
+`platform/lib/telegram-managed-bot/` (re-exported from
+`plugins/telegram/mcp/src/lib/telegram.ts`). Add a class there and nowhere else, and re-register the
 webhook: `allowed_updates` is set at registration, so an existing bot keeps the list it was
 registered with. `telegram-webhook-register` prints
 `op=webhook-allowed … match=yes|no` against what `getWebhookInfo` reports back; `match=no` means
@@ -303,6 +387,36 @@ Telegram registered something narrower than was asked for.
 The registration test asserts the whole array, not that a particular name is in it, because the
 failure it guards against is a name silently dropped.
 
+## Sending to a channel or a group
+
+Every send whose chat id you choose is checked before it reaches Telegram. A chat id beginning
+`-100` is a channel or a supergroup — Telegram gives the two the same id shape and nothing local can
+tell them apart — and it is refused unless the operator listed it in that bot's `allowChannels` or
+`allowGroups`. The refusal names the id and both fields, and nothing is sent.
+
+This is a refusal, not a retry. A channel post reaches every subscriber and cannot be unsent, so the
+check happens before the network call rather than after Telegram's answer. If you are refused, say
+so plainly and name the id; do not try another tool, and do not reach for `telegram-api` to route
+around it, because the same check applies there on `params.chat_id`.
+
+Both lists live on public bot entries only. An admin, specialist or unbound bot reaches no channel
+and no group, in either direction.
+
+A private chat id (positive) and a basic group id (negative, no `-100`) are unaffected.
+
+## Answering a comment on a channel post
+
+Telegram builds a comment thread by auto-forwarding each channel post into the channel's linked
+discussion group. That forwarded copy is the thread root, and it is not a message anybody sent you:
+it raises no turn, because the post itself already reached you through the channel.
+
+A comment arrives as an ordinary group message whose turn carries the root's message id. Answer by
+replying beneath that root, not at the bottom of the group, or the answer reads to everyone in the
+thread as no answer at all.
+
+A commenter who posted anonymously has no personal identity. The turn names the group they commented
+as, which is the only identity Telegram supplies.
+
 ## Reading the method list
 
 `references/methods.md` carries all 185 names grouped as Telegram documents them: Getting updates,
@@ -315,8 +429,9 @@ works without waiting for a release here. `telegram-api-census` is what reports
 
 ### What stays in the passthrough, and why
 
-Named tools own the conversation, structured-input, media-in, media-out, payments and threading
-buckets: 39 methods in all. These stay on `telegram-api` deliberately, because they are config-time
+Named tools own the conversation, structured-input, media-in, media-out and threading buckets: 31
+methods in all. The payments bucket has no owner: the surface was removed and `telegram-api`
+refuses all eight. These stay on `telegram-api` deliberately, because they are config-time
 rather than per-turn: membership (23 methods), business-account (12), bot-self-config (19, including
 the four managed-bot token methods), org-verification (4) and chat-cosmetic (6).
 

package/payload/platform/plugins/telegram/skills/build/references/methods.md

@@ -1,8 +1,9 @@
 # Bot API 10.2 methods
 
 Every method `telegram-api` can call, as documented at `core.telegram.org/bots/api`
-on 14 July 2026. Five of them are refused, and each refusal names the tool that owns
-the capability instead. Pass the name to `telegram-api` exactly as written here:
+on 14 July 2026. Seven of them are refused, and each refusal names the tool that owns
+the capability instead. The eight Bot API payment methods are not listed at all: this
+install takes no payment inside Telegram and `telegram-api` refuses them by name. Pass the name to `telegram-api` exactly as written here:
 Telegram's own documentation is case-insensitive but this list is not, because the
 census matches it literally.
 
@@ -197,17 +198,6 @@ census matches it literally.
 
 - `answerInlineQuery`
 
-## Payments
-
-- `sendInvoice`
-- `createInvoiceLink`
-- `answerShippingQuery`
-- `answerPreCheckoutQuery`
-- `getMyStarBalance`
-- `getStarTransactions`
-- `refundStarPayment`
-- `editUserStarSubscription`
-
 ## Telegram Passport
 
 - `setPassportDataErrors`

package/payload/platform/plugins/telegram/skills/configure/SKILL.md

@@ -18,12 +18,30 @@ A finished Telegram setup has all of these, and the skill is not done until each
 - The bot is stored as one entry in `account.json`'s `telegram.bots` array (under the brand install, never `~/.claude/`). The `telegram-webhook-register` tool writes it there and logs `[telegram-setup] op=token-write dir=… brand=…`.
 - The webhook is registered against a URL whose path is `/api/telegram/` (the only path the maxy edge admits). The register tool refuses any other path and logs `op=webhook-register path=… botId=… account=… admitted=false` when it does.
 - The registered URL carries `bot=<botId>`, the bot's own Telegram id. The register tool derives it from the token and appends it, so you never type it. The receiver requires it and rejects `reason=unknown-bot`; the bot id is what determines the account, so no `account=` is carried.
-- The bot's `role` is stated, not inferred: `admin` or `public`. It selects the spawn path, so it is a privilege decision.
-- Access policy is set **on that entry**: an admin bot carries the operator's numeric Telegram user IDs (`adminUsers`); a public bot carries a DM policy (and an allowlist when the policy is `allowlist`). Nothing is shared with the account's other bots.
-- A public bot names the `agent` it answers as, and that agent is active. An admin bot names none: it reads `agents/admin` by construction.
+- The bot's `role` is stated, not inferred: `admin`, `public` or `specialist`. It selects the spawn path, so it is a privilege decision. (A bot that arrived through the one-tap path lands as `unbound`, which answers nobody; giving it a role is what finishes it.)
+- Access policy is set **on that entry**: an admin bot carries the operator's numeric Telegram user IDs (`adminUsers`); a public bot carries a DM policy (and an allowlist when the policy is `allowlist`); a specialist bot carries `allowFrom` and nothing else, because there is no open policy for that role. Nothing is shared with the account's other bots.
+- A public bot names the `agent` it answers as, and that agent is active. A specialist bot names the `specialist` card it runs as, and the account has that card. An admin bot names neither: it reads `agents/admin` by construction.
+- If the bot is to work in a **group**, it is a public bot (never an admin or specialist bot), its group privacy mode is on in BotFather before registration, and every group it answers in is listed by chat id on that entry (`groupPolicy: 'allowlist'`, `allowGroups`). An admin bot cannot be used in a group at all.
+- If the bot is to work in a **channel**, it is a public bot for the same reason, it is a channel administrator with post rights, and every channel it reads or posts to is listed by chat id on that entry (`channelPolicy: 'allowlist'`, `allowChannels`). The list gates both directions: a channel not on it is neither read nor posted to. An admin bot cannot be used in a channel at all, and it can no longer post to any group or channel either, in either direction.
 
 An account may hold any number of bots. Registering, re-pointing or removing one never disturbs another, in any account.
 
+## Two ways in, and the first one is preferred
+
+**The one-tap path.** If this account already has a working admin bot, a new bot needs no BotFather
+visit and no token typed anywhere. Call `telegram-bot-provision action=offer` with that admin bot's
+id and the operator's private chat id. They tap the button, name the bot, and this install receives
+it, stores its token, restricts it to its owner and registers its webhook by itself. What arrives is
+a `role:'unbound'` entry that answers nobody; binding it to an agent is the only step left.
+
+That path needs the managing bot to have management of other bots enabled **once**, in the
+@BotFather Mini App. No API call turns it on. `offer` checks first and refuses with the Mini App
+named rather than sending a button that would do nothing.
+
+**The BotFather path**, below, is still the way in for the first bot on an install, and for a bot
+the operator already owns. Everything after Step 1 applies to it alone: a provisioned bot has
+already had Steps 1, 3, 4 and 5 done for it.
+
 ## Flow
 
 Read `references/setup-guide.md` (cited throughout this flow) with the `plugin-read` tool (`file="references/setup-guide.md"`), which resolves it at the plugin root. A plain `Read` against this skill's base directory misses, because the file lives one level up at the plugin root, not under the skill.
@@ -32,12 +50,17 @@ Read `references/setup-guide.md` (cited throughout this flow) with the `plugin-r
 
 Follow `references/setup-guide.md` "Creating a Bot": the operator creates the bot via @BotFather and gives you the token (e.g. `123456:ABC-DEF…`). Confirm you have it before continuing.
 
+Skip this step entirely when the account already has a working admin bot: use `telegram-bot-provision action=offer` instead, and no token is ever handled by anyone.
+
 ### Step 2 — Decide the role, and for a public bot its agent
 
 Ask which role this bot serves (see `references/setup-guide.md` "Admin Bot vs Public Bot"). The role is stated by the operator, never worked out from anything else: it decides which spawn path the bot's messages take.
 
 - **Admin bot** — only the numeric Telegram user IDs the operator names for THIS bot may message it; everything else is denied. Collect those IDs (`references/setup-guide.md` "Finding Your Telegram User ID"). It answers as the admin agent.
 - **Public bot** — customer-facing; choose a DM policy (`open`, `allowlist`, or `disabled`), for `allowlist` the allowed numeric IDs, and **which of this account's agents answers on it**. Call `account-manage` to list the account's agents and let the operator pick one. The agent must be active; the register tool refuses an inactive or unknown slug.
+- **Specialist bot** — a bot bound to one of the account's own specialist cards, so messaging it runs that specialist with its own prompt and its own tools instead of the admin seat. Collect two things: **which card** (the file name under the account's `specialists/agents/`, without `.md` — that is the name the spawn resolves, not the card's title) and **who may message it** (numeric IDs). Both are required: there is no open policy for this role, because the session carries the card's own tool surface rather than the public zero-tool ringfence.
+
+If the operator wants this bot in a **group**, say plainly that groups are a public-bot feature. An admin bot added to a group answers nobody: it would otherwise put the operator's own agent, with the operator's own standing rules and tools, into a room other people read, and every member's messages into its context. There is no setting that changes this.
 
 The account may already hold other bots. This one is added alongside them and shares nothing with them.
 
@@ -54,15 +77,62 @@ The register tool aborts on any other path, so do not invent `/channels/telegram
 Call `telegram-webhook-register` with:
 - `botToken` — the BotFather token
 - `webhookUrl` — the URL from Step 3
-- `role` — `admin` or `public`
+- `role` — `admin`, `public` or `specialist`
 - admin bot: `adminUsers` — the numeric IDs from Step 2
 - public bot: `agent` — the slug from Step 2, plus `dmPolicy` and, for `allowlist`, `allowFrom`
+- specialist bot: `specialist` — the card file name from Step 2, plus `allowFrom` (both required)
+
+On success the tool has, in this order: verified the token, derived the bot id, set the webhook with a generated secret (written to `~/.<brand>/telegram-secrets/<botId>`), probed Telegram and confirmed no delivery error since the registration, and only then persisted the entry into `account.json`'s `telegram.bots` array. It logs `op=webhook-register admitted=true` + `op=webhook-verify reachable=true` + `op=token-write`. It replaces only the entry with this bot's id, so the account's other bots are untouched. If it returns an error, read it back to the operator verbatim — the common ones are a wrong path (`admitted=false`), a webhook Telegram cannot reach (`op=webhook-verify reachable=false`), a public bot with no or an inactive `agent` (`op=token-write-rejected reason=no-agent|agent-inactive`), a specialist bot with no card, an unknown card or an empty allowlist (`op=token-write-rejected reason=no-specialist|specialist-unknown|no-allowlist`), or a token write blocked outside the brand install.
+
+### Step 4a — Groups, when the bot is to work in one
+
+Only for a public bot, and only if the operator asked for it. Skip this step entirely otherwise.
+
+The outcome is that an allowlisted group can address the bot and gets an answer in that group, and that the bot reads nothing else said in the room.
+
+Three things have to be true, and the register tool has already checked the first:
+
+- **Group privacy mode is ON in BotFather.** With it off the bot receives every message anyone types in every group it joins. `telegram-webhook-register` refuses such a bot outright and logs `[telegram-webhook] op=group-preflight … canReadAllGroupMessages=true verdict=refused`, naming the BotFather step. With it on, Telegram delivers only commands, @mentions and replies to the bot's own messages, which is why no further "was I being addressed" rule exists anywhere in the code.
+- **The bot is in the group.** A group admin adds it. The install cannot do this and does not try.
+- **The group's chat id is on the entry.** Set `groupPolicy: 'allowlist'` and put the numeric chat id in `allowGroups`. A supergroup id is negative and long, e.g. `-1001234567890`. Until the id is listed, the bot answers nobody in that room and logs `op=group-refused … reason=not-in-allowGroups`.
+
+The chat is what is admitted, not its members: once a group is allowlisted, anyone in it can address the bot, including people on no `allowFrom` list. Say that to the operator in those words before they allowlist a room. `dmPolicy` and `allowFrom` govern one-to-one chats only and are never consulted for a group.
+
+A group is one conversation, not one per member: everyone in the room shares a single thread and a single session, and each turn names who spoke.
+
+## Setting a bot up in a channel
+
+The outcome is that a post in an allowlisted channel reaches the agent, that the agent can post to
+that channel and no other, and that comments on a post can be attributed and answered.
+
+Three things have to be true:
+
+- **The bot is a channel administrator, with post rights.** A channel admin adds it and grants
+  "Post Messages". The install cannot do this and does not try. Without the post right the bot still
+  reads posts but every send fails, which from the agent's side is indistinguishable from a channel
+  nobody reads.
+- **The channel's chat id is on the entry.** Set `channelPolicy: 'allowlist'` and put the numeric
+  chat id in `allowChannels`. A channel id is negative and long, e.g. `-1001234567890`. Until the id
+  is listed, no post from that channel reaches the agent (`op=channel-refused …
+  reason=not-in-allowChannels`) and no send to it leaves the install.
+- **For comments, the channel has a linked discussion group,** and that group is allowlisted too
+  (`groupPolicy`, `allowGroups`). Telegram builds comment threads by auto-forwarding each post into
+  the linked group; without the link there is nothing to comment on and nothing to answer in.
+
+The list gates **both directions**. That is the difference from a group, and it is deliberate: a
+channel post reaches every subscriber and cannot be unsent, so a send to a channel outside
+`allowChannels` is refused before it reaches Telegram, and the refusal names both list fields.
+
+Say this to the operator in these words before they allowlist a channel: the agent will be able to
+post to it, and a post cannot be taken back.
 
-On success the tool has, in this order: verified the token, derived the bot id, set the webhook with a generated secret (written to `~/.<brand>/telegram-secrets/<botId>`), probed Telegram and confirmed no delivery error since the registration, and only then persisted the entry into `account.json`'s `telegram.bots` array. It logs `op=webhook-register admitted=true` + `op=webhook-verify reachable=true` + `op=token-write`. It replaces only the entry with this bot's id, so the account's other bots are untouched. If it returns an error, read it back to the operator verbatim — the common ones are a wrong path (`admitted=false`), a webhook Telegram cannot reach (`op=webhook-verify reachable=false`), a public bot with no or an inactive `agent` (`op=token-write-rejected reason=no-agent|agent-inactive`), or a token write blocked outside the brand install.
+A channel post has no author. Telegram sends no sender for it, so the turn names the channel by its
+title. A comment does have an author, unless the person commented anonymously, in which case the
+turn names the group they commented as.
 
 ### Step 5 — Confirm
 
-Tell the operator the bot is connected, which role it has, and that messaging the bot now reaches the agent and a reply returns. For a public bot, name the agent that will respond. If the account holds other bots, say that this one is separate from them: its own people, its own agent, its own conversations.
+Tell the operator the bot is connected, which role it has, and that messaging the bot now reaches the agent and a reply returns. For a public bot, name the agent that will respond; for a specialist bot, name the card and say the conversation stays the same one across days. If the account holds other bots, say that this one is separate from them: its own people, its own agent, its own conversations.
 
 ## Failure modes (state these loudly, do not paper over)
 
@@ -76,6 +146,17 @@ Tell the operator the bot is connected, which role it has, and that messaging th
 - **One bot id claimed by two accounts** — inbound is refused `[telegram-inbound] op=reject reason=duplicate-bot-id`, and the standing `[telegram-audit] op=duplicate-bot-id` names it every tick. Two accounts hold the same token. Remove it from the one that should not have it; nothing picks between them.
 - **Chat id claimed by two bots** — a scheduled dispatch logs `[schedule-inject] op=telegram-destination-ambiguous … dispatched=no`. Two bots, in one account or two, list the same numeric ID in their `adminUsers`. Remove it from the one that should not have it; the dispatch refuses rather than guessing which bot the person should hear from.
 - **A secret file with no bot, or a bot with no secret file** — `[telegram-audit] op=secret-orphan botId=… side=file|entry`. Neither shows up any other way. `side=entry` means that bot cannot receive anything until it re-registers; `side=file` is left-over state from a bot that has been removed.
+- **Group privacy mode off at registration** — register returns an error naming BotFather's Group Privacy setting and logs `op=group-preflight … verdict=refused`. Nothing was registered and nothing written. Turn privacy on, then register again.
+- **The bot cannot be added to groups** — the same refusal, naming BotFather's "Allow Groups?" setting instead.
+- **Admin bot in a group** — `[telegram-inbound] op=group-refused … reason=admin-entry-no-groups`, and no turn runs. This is not a misconfiguration to fix; the admin persona never enters a group. Use a public bot for the room.
+- **Group not allowlisted** — `op=group-refused … reason=not-in-allowGroups` (the id is missing from `allowGroups`) or `reason=group-policy-disabled` (the entry has no `groupPolicy: 'allowlist'` at all). Both are silent to everyone in the room, so check the log rather than assuming the bot is broken.
+- **Privacy mode turned off AFTER registration** — nothing fails and no update says so; the bot simply starts reading every message in the room. The hourly `[telegram-audit] op=group-census … privacyOff=<n>` is the only thing that reports it. `privacyOff>0` needs the BotFather setting turned back on.
+- **Bot removed from a group** — every later send fails and no inbound arrives again. `op=chat-member-group … status=kicked` catches it live; if the install was down when it happened, the hourly `op=group-census … absent=<n>` is what surfaces it. Read `bots=` and `groups=` on that line before trusting `absent=0`: zero absent out of zero groups is an install with no groups, not a healthy one.
+- **Admin or specialist bot in a channel** — `[telegram-inbound] op=channel-refused … reason=admin-entry-no-channels` (or `specialist-entry-no-channels`, or `unbound-entry-no-channels`), and no turn runs. Not a misconfiguration to fix; those personas never enter a channel. Use a public bot.
+- **Channel not allowlisted** — `op=channel-refused … reason=not-in-allowChannels` (the id is missing from `allowChannels`) or `reason=channel-policy-disabled` (the entry has no `channelPolicy: 'allowlist'` at all). Both are silent to every subscriber, so read the log rather than assuming the bot is broken. The same two states also refuse every send, logged as `[telegram-outbound] op=channel-send … allowed=no reason=not-in-allowChannels`.
+- **Agent says it cannot post to a channel or group** — the id is on neither `allowChannels` nor `allowGroups`. Both lists exist on public entries only, so an admin, specialist or unbound bot can never post to any channel or group. The refusal names the id and both fields.
+- **Bot loses its post rights, or is demoted in a channel** — every later send fails one at a time and nothing announces it. The hourly `[telegram-audit] op=channel-census … admin=<n> notAdmin=<n> noPostRight=<n>` is the only thing that reports it. `noPostRight>0` means the bot is still an administrator but cannot post; `notAdmin>0` means it is no longer an administrator at all. Read `bots=` and `channels=` before trusting either zero: zero out of zero channels is an install with no channels, not a healthy one.
+- **Comments arrive but answers land in the wrong place** — the reply must sit beneath the auto-forwarded root post, whose id the turn carries. `op=channel-comment-root … rootMessageId=<id>` is the record of that id; a thread with no root line is a thread whose comments point nowhere, which means the discussion group is not linked or not allowlisted.
 
 ## Language