@rubytech/create-maxy-code 0.1.581 → 0.1.583

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

@@ -17,10 +17,11 @@ 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 |
@@ -36,7 +37,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 +59,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 +215,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:
@@ -188,9 +252,40 @@ telegram-ask botId=<id> chatId=<chat> kind=editLiveLocation messageId=<id> latit
   longitude=-0.13
 ```
 
-`venue`, `contact` and `dice` are one call each. The two checklist kinds need
-`businessConnectionId`: Telegram sends a checklist only on behalf of a connected business account,
-and refuses without it.
+`venue`, `contact` and `dice` are one call each.
+
+**The two checklist kinds need a connected business account, and you do not have to find its
+identifier yourself.** `business_connection_id` is required on `sendChecklist` and
+`editMessageChecklist` and there is no variant without it, so a bot can never send a checklist as
+itself. Telegram announces the identifier once, on a `business_connection` update, when the operator
+connects the bot under Telegram, Settings, Business, Chatbots. This install captures it and stores it
+per bot, so `telegram-ask kind=checklist` with no `businessConnectionId` sends on the stored
+connection. Pass one explicitly only to override that. With nothing stored the tool refuses and names
+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)
@@ -199,8 +294,20 @@ business account" — that gate is the business connection, and it is the one `b
 carries. Bot API 9.4 (9 February 2026) allowed "custom emoji in messages directly sent by the bot to
 private, group and supergroup chats if the owner of the bot has a Telegram Premium subscription" —
 that gate is Premium, it is on the bot's OWNER rather than on a connection, and it governs custom
-emoji, not checklists. Whether Telegram Business itself requires Premium is not stated in Telegram's
-documentation, so do not tell an operator that it does or that it does not.
+emoji, not checklists.
+
+On Premium and Business, `core.telegram.org/api/business` says two things and you need both. "All
+Telegram Business features are available for free to Premium subscribers." And: "Additionally,
+connected bots are also available to non-Premium users." A checklist rides on a connected bot, so do
+not tell an operator that a checklist requires Premium. If Telegram nevertheless answers
+`PREMIUM_ACCOUNT_REQUIRED` on a `sendChecklist` that carried a valid `business_connection_id`, that is
+a finding worth reporting rather than a settled fact.
+
+**A Mini App button and a checklist cannot share one message.** Telegram's `InlineKeyboardButton`
+table says a `web_app` button is "Available only in private chats between a user and the bot. Not
+supported for messages sent on behalf of a business account." A checklist is sent on behalf of a
+business account, so send the Mini App button as its own ordinary message. This install's Mini App is
+`/field?bot=<botId>` on the install's own origin, not the public site.
 
 ### 9. Charging for something
 
@@ -221,10 +328,19 @@ keyboard to be a Pay button, and leaving the keyboard off gets that button for f
 `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.
 
-Set `isFlexible` and Telegram sends a shipping query mid-checkout; answer it with
-`action=answerShipping`, and answer the pre-checkout query that follows within ten seconds with
-`action=answerPreCheckout`. `ok=false` on either needs `errorMessage`, which Telegram shows the
-payer verbatim. `balance`, `transactions`, `refund` and `editSubscription` are the Stars controls.
+**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.
+
+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.
 
 ### Ephemeral messages
 
@@ -235,6 +351,96 @@ other send methods. The resulting message has `message_id: 0` and carries its id
 address. Send one through `telegram-api`; no named tool covers it, because nothing on this install
 sends group messages visible to a single user.
 
+## What arrives from Telegram
+
+Telegram defines twenty-six update classes. This install registers twenty-two and handles seventeen
+of them.
+
+| Class | Registered | What happens |
+|---|---|---|
+| `message`, `edited_message` | yes | a turn, with media, transcription, location and the quoted original when the sender replied |
+| `callback_query` | yes | answered, stored, and a turn unless it is a dispatch button |
+| `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` |
+| `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` | 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.
+
+### The `allowed_updates` trap
+
+Naming **any** class in `allowed_updates` replaces Telegram's default set. Telegram's default is
+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
+`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
+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,

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
 

package/payload/platform/plugins/whatsapp/references/channels-whatsapp.md

@@ -12,6 +12,18 @@ The agent has **no tool to initiate a WhatsApp message to an arbitrary number.**
 
 What the agent **can** still do: reply within an existing chat. **The `reply` and `reply-document` tools are retired**; the agent no longer chooses to deliver. Its answer is the text its turn ends with, read from the session record and sent by the gateway, split into separate messages on any line that is exactly `[[next]]`. A scheduled turn delivers the same way, so a scheduled turn with nothing to report must end with no text at all. Files go through `SendUserFile`, caught by a read-only JSONL follower on the session and funnelled through `sendWhatsAppDocument`, the one send core that owns path validation, the 100 MB ceiling, the canonical log, and per-file reconciliation. Delivery stays reply-only by construction: the follower runs only for an admin session and its recipient is fixed when the session spawns, so there is no recipient the agent can name. (The removed `whatsapp-send-document` route tool and the bridge path `SendUserFile` → `file-delivery-bridge.ts` → `POST /api/whatsapp/send-document` are the legacy webchat/email bridge surface, not the native WhatsApp channel.) Replying within your chats is what WhatsApp permits; starting new chats from a linked device is what it penalises.
 
+The operator-facing half of this rule now also lives in the admin identity, under its `## Channel reality` section. This page loads only with the WhatsApp skill, and on 2026-08-09 an admin turn that had not loaded it filled the gap from model priors and offered a cold send three times. The identity states which channels can start a conversation and with whom; this page stays the authority on why WhatsApp cannot. A change to either belongs in both.
+
+## The channel-suggestion clause
+
+The platform arm of this door's turn wrapper — `REFRAME_INSTRUCTION` in `platform/services/whatsapp-channel/src/notification.ts`, the body of a turn the operator authored from their own handset or the scheduler — ends with a clause telling the agent that when the turn wanted something this door cannot do (a button, an in-place card, a poll or checklist, a map pin, a photo or album, an invoice, a reply in a group, an edit to a message already sent, or a message to someone not already registered) it names the missing thing, says Telegram has it, and offers to set it up. It is conditioned on the turn: when this door served the request, the agent never raises another door, which is what stops it becoming a nag without needing a per-sender counter.
+
+It exists because Telegram's own wrapper gained a paragraph naming its surfaces and no counterpart was possible here, so on the weaker door the agent answered in prose and never said a better door existed.
+
+**WhatsApp-only, and it offers no counterweight.** A public visitor's turn takes the account arm and never reads this constant. The two twins' tests assert the clause's absence, so copying it across fails there. Three counterweights were drafted and each was struck on evidence: there is no outbound reach on this door at all and the paired number is a dedicated line no contact already holds; Telegram runs the same whisper wrapper, so the voice-note transcript is not this door's alone; and both doors gate inbound on the same `dmPolicy`. A clause that invents an advantage here is the defect it exists to close, and its test asserts all three are absent.
+
+**How to see it.** The `[reframe] op=applied` line carries `arm=<platform|account|webchat>` and `suggestClause=<bool>`, both read back off the composed body rather than off the branch the composer meant to take. `arm=platform suggestClause=false` means the constant shipped without the clause; `arm=account suggestClause=true`, or any `suggestClause=true` on a webchat line, is a leak. Whether it ever converts anyone has no event of its own, so the hourly `[channel-suggest-census]` counts the state instead: `accountsWaOnly` flat over weeks while `waOperatorTurns` climbs is the signal. It is a proxy and never proof of causation — an operator who reads the clause and decides against Telegram is a correct outcome that moves the number not at all.
+
 ## Per-account observe socket (account manager)
 
 Each sub-account can pair its own WhatsApp number as a linked device, separate from the house socket. This is intended for an account manager's phone: the agent reads that WhatsApp, but the phone's inbound is never treated as instructions to the agent.

package/payload/platform/services/claude-session-manager/dist/account-dir-schema-reconcile.d.ts

@@ -43,15 +43,46 @@ export interface ReconcileDeps {
  * account has settings reports hooks-missing=0 and reads as fenced.
  *
  * The matcher is compared for equality, which is the shape
- * provision-account-dir.sh writes for all five. A settings file that reaches the
- * same effect another way — a matcher-less catch-all entry, or a regex
- * alternation — reads as missing here. That is intended: what this audits is
- * whether the account carries the provisioned fence, and drift from the template
- * is worth a line even when it happens to be equivalent.
+ * provision-account-dir.sh writes for the five tool rows. A settings file that
+ * reaches the same effect another way — a matcher-less catch-all entry, or a
+ * regex alternation — reads as missing here. That is intended: what this audits
+ * is whether the account carries the provisioned fence, and drift from the
+ * template is worth a line even when it happens to be equivalent.
+ *
+ * A row with a null matcher inverts that test to "no matcher key at all", which
+ * is the shape account-settings.json writes for every UserPromptSubmit hook. The
+ * rule is the same in both directions: match the template exactly.
  */
 export declare function hookRegistration(accountDir: string): {
     missing: string[];
 } | null;
+/**
+ * Per-account count of the entity folders and their child folders.
+ *
+ * The archive exception widened the guard's depth rule, and a rule that is too
+ * wide produces NO event: a successful write emits nothing, so an entity folder
+ * quietly growing a second subtree on some route is invisible. `stray` above zero
+ * is that signature.
+ *
+ * `entities` rides the same line because `stray=0` alone cannot tell a clean
+ * account from a walker that read nothing: `entities=0` on an account that holds
+ * entity folders is the not-measuring reading, and the two are indistinguishable
+ * without the denominator.
+ *
+ * Directories only; files are not counted. Dot-prefixed entries are skipped at
+ * both levels, because SCHEMA.md's name rule exempts them at every level and the
+ * write guard skips them too: counting one as a stray would raise a standing
+ * alarm about an entry the rules permit.
+ *
+ * A bucket that does not exist, or a child that cannot be stat'd, contributes
+ * nothing rather than throwing: the caller already swallows per-account errors,
+ * and a partial count is worth more than a dropped line.
+ */
+export declare function entitySubdirs(accountDir: string): {
+    entities: number;
+    archive: number;
+    stray: number;
+};
 /** One reconcile pass over every account under the accounts root: one op=strays
  *  line naming the unaccounted-for entries of each account that has any, then the
  *  single summary line. An account is any child dir with an account.json (the

package/payload/platform/services/claude-session-manager/dist/account-dir-schema-reconcile.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"account-dir-schema-reconcile.d.ts","sourceRoot":"","sources":["../src/account-dir-schema-reconcile.ts"],"names":[],"mappings":"AA8EA,MAAM,WAAW,eAAe;IAC9B,aAAa,EAAE,MAAM,CAAA;IACrB,QAAQ,EAAE,MAAM,CAAA;IAChB,OAAO,EAAE,MAAM,CAAA;CAChB;AAED,MAAM,WAAW,eAAgB,SAAQ,eAAe;IACtD;;;;;0CAKsC;IACtC,UAAU,EAAE,MAAM,EAAE,CAAA;CACrB;AAED;;+DAE+D;AAC/D,wBAAgB,mBAAmB,CACjC,CAAC,EAAE,eAAe,EAClB,WAAW,SAAI,EACf,aAAa,SAAI,EACjB,UAAU,SAAI,EACd,YAAY,SAAI,EAChB,cAAc,SAAI,GACjB,MAAM,CAIR;AAED;;8EAE8E;AAC9E,wBAAgB,oBAAoB,CAAC,UAAU,EAAE,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC,CAcpE;AA+ED;;;8EAG8E;AAC9E,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,MAAM,GAAG,eAAe,CAoCpE;AAED,MAAM,WAAW,aAAa;IAC5B,YAAY,EAAE,MAAM,CAAA;IACpB,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAA;CAC/B;AAqED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,MAAM,GAAG;IAAE,OAAO,EAAE,MAAM,EAAE,CAAA;CAAE,GAAG,IAAI,CA6BjF;AAED;;;;;;;;;;;;;iCAaiC;AACjC,wBAAgB,YAAY,CAAC,IAAI,EAAE,aAAa,GAAG,IAAI,CA6EtD;AAED,MAAM,WAAW,yBAAyB;IACxC,KAAK,IAAI,IAAI,CAAA;IACb,IAAI,IAAI,IAAI,CAAA;CACb;AAED;oDACoD;AACpD,wBAAgB,+BAA+B,CAC7C,IAAI,EAAE,aAAa,GAAG;IAAE,UAAU,EAAE,MAAM,CAAA;CAAE,GAC3C,yBAAyB,CAiB3B"}
+{"version":3,"file":"account-dir-schema-reconcile.d.ts","sourceRoot":"","sources":["../src/account-dir-schema-reconcile.ts"],"names":[],"mappings":"AA8EA,MAAM,WAAW,eAAe;IAC9B,aAAa,EAAE,MAAM,CAAA;IACrB,QAAQ,EAAE,MAAM,CAAA;IAChB,OAAO,EAAE,MAAM,CAAA;CAChB;AAED,MAAM,WAAW,eAAgB,SAAQ,eAAe;IACtD;;;;;0CAKsC;IACtC,UAAU,EAAE,MAAM,EAAE,CAAA;CACrB;AAED;;+DAE+D;AAC/D,wBAAgB,mBAAmB,CACjC,CAAC,EAAE,eAAe,EAClB,WAAW,SAAI,EACf,aAAa,SAAI,EACjB,UAAU,SAAI,EACd,YAAY,SAAI,EAChB,cAAc,SAAI,GACjB,MAAM,CAIR;AAED;;8EAE8E;AAC9E,wBAAgB,oBAAoB,CAAC,UAAU,EAAE,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC,CAcpE;AA+ED;;;8EAG8E;AAC9E,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,MAAM,GAAG,eAAe,CAoCpE;AAED,MAAM,WAAW,aAAa;IAC5B,YAAY,EAAE,MAAM,CAAA;IACpB,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAA;CAC/B;AA8ED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,MAAM,GAAG;IAAE,OAAO,EAAE,MAAM,EAAE,CAAA;CAAE,GAAG,IAAI,CAgCjF;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,aAAa,CAAC,UAAU,EAAE,MAAM,GAAG;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAuCtG;AAED;;;;;;;;;;;;;iCAaiC;AACjC,wBAAgB,YAAY,CAAC,IAAI,EAAE,aAAa,GAAG,IAAI,CAsFtD;AAED,MAAM,WAAW,yBAAyB;IACxC,KAAK,IAAI,IAAI,CAAA;IACb,IAAI,IAAI,IAAI,CAAA;CACb;AAED;oDACoD;AACpD,wBAAgB,+BAA+B,CAC7C,IAAI,EAAE,aAAa,GAAG;IAAE,UAAU,EAAE,MAAM,CAAA;CAAE,GAC3C,yBAAyB,CAiB3B"}