@acedatacloud/skills 2026.621.1 → 2026.621.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@acedatacloud/skills",
-  "version": "2026.621.1",
+  "version": "2026.621.3",
   "description": "Agent Skills for AceDataCloud AI services — music, image, video generation, LLM chat, web search. Compatible with Claude Code, GitHub Copilot, Gemini CLI, OpenAI Codex, and 30+ AI coding agents.",
   "keywords": [
     "agent-skills",

package/skills/discordbot/SKILL.md

@@ -0,0 +1,117 @@
+---
+name: discordbot
+description: List channels, read recent messages, and send messages on Discord using the user's own bot, via the Discord REST API. Use when the user wants their Discord BOT to post a message, read a channel, or list servers/channels — anything that acts in a server the bot was invited to.
+when_to_use: |
+  Trigger when the user wants to send, read, or list things on Discord
+  through their bot: list the servers/channels the bot can see, read recent
+  messages in a channel, or post / reply in a channel. Messages are sent as
+  the BOT, not the user's personal account, and only in servers the bot has
+  been invited to with the right permissions.
+connections: [discordbot]
+allowed_tools: [Bash]
+license: Apache-2.0
+metadata:
+  author: acedatacloud
+  version: "1.0"
+---
+
+We drive the [Discord API](https://discord.com/developers/docs/reference)
+with `curl + jq` using the user's **bot** token in `$DISCORDBOT_TOKEN`. The
+auth header is `Authorization: Bot $DISCORDBOT_TOKEN` — note the literal
+`Bot ` prefix (NOT `Bearer`). Base URL is `https://discord.com/api/v10`.
+
+This acts as the user's registered **bot**, so it can only see and act in
+servers (guilds) the bot has been **invited to** and only where it has the
+relevant permission (View Channels / Send Messages / Read Message History).
+A `403 Forbidden` (code 50001 "Missing Access" / 50013 "Missing
+Permissions") almost always means the bot isn't in that server or lacks the
+permission — tell the user to invite the bot or grant the permission rather
+than retrying.
+
+Errors are JSON `{"code": <n>, "message": "<reason>"}`. A `401` means the
+bot token is wrong/reset — ask the user to re-paste it at
+`auth.acedata.cloud/user/connections`. A `429` carries `retry_after`
+(seconds) — sleep that long, then retry; never parallelize.
+
+**Before sending a message, confirm the exact channel and content with the
+user.** Sending is irreversible and public to that channel.
+
+## Recipes
+
+### Verify the bot (always run first)
+
+```sh
+curl -sS -H "Authorization: Bot $DISCORDBOT_TOKEN" \
+  "https://discord.com/api/v10/users/@me" \
+  | jq '{id, username, bot}'
+```
+
+### List servers (guilds) the bot is in
+
+```sh
+curl -sS -H "Authorization: Bot $DISCORDBOT_TOKEN" \
+  "https://discord.com/api/v10/users/@me/guilds" \
+  | jq 'map({id, name})'
+```
+
+### List text channels in a server
+
+Channel `type` 0 = text, 5 = announcement; 2 = voice, 4 = category (skip
+those for messaging). You need a guild id from the call above.
+
+```sh
+GUILD_ID="123456789012345678"
+curl -sS -H "Authorization: Bot $DISCORDBOT_TOKEN" \
+  "https://discord.com/api/v10/guilds/$GUILD_ID/channels" \
+  | jq 'map(select(.type==0 or .type==5) | {id, name, type})'
+```
+
+### Read recent messages in a channel
+
+Reading message **content** requires the **Message Content Intent** to be
+enabled on the bot (Developer Portal → Bot → Privileged Gateway Intents).
+Without it, `content` comes back empty for messages that don't mention the
+bot. Needs the *Read Message History* permission in that channel.
+
+```sh
+CHANNEL_ID="123456789012345678"
+curl -sS -H "Authorization: Bot $DISCORDBOT_TOKEN" \
+  "https://discord.com/api/v10/channels/$CHANNEL_ID/messages?limit=20" \
+  | jq 'map({author: .author.username, ts: .timestamp, content})'
+```
+
+### Send a message to a channel
+
+```sh
+CHANNEL_ID="123456789012345678"
+curl -sS -X POST \
+  -H "Authorization: Bot $DISCORDBOT_TOKEN" \
+  -H "Content-Type: application/json" \
+  "https://discord.com/api/v10/channels/$CHANNEL_ID/messages" \
+  -d "$(jq -nc --arg c "Hello from the bot." '{content: $c}')"
+```
+
+### Reply to a specific message
+
+```sh
+CHANNEL_ID="123456789012345678"; MESSAGE_ID="987654321098765432"
+curl -sS -X POST \
+  -H "Authorization: Bot $DISCORDBOT_TOKEN" \
+  -H "Content-Type: application/json" \
+  "https://discord.com/api/v10/channels/$CHANNEL_ID/messages" \
+  -d "$(jq -nc --arg c "On it!" --arg m "$MESSAGE_ID" \
+        '{content: $c, message_reference: {message_id: $m}}')"
+```
+
+## Notes
+
+- A "server" in the UI is a "guild" in the API; messages live in channels
+  inside guilds. Always: list guilds → list that guild's channels → act on a
+  channel id. Don't invent ids.
+- The bot only sees servers it was invited to. To add it: Developer Portal →
+  OAuth2 → URL Generator → scope `bot` + the permissions you need → open the
+  URL → pick a server (the user needs *Manage Server* there).
+- This is a bot, not the user's account — it cannot read the user's DMs or
+  the user's full server list, only what the bot itself can access.
+- Mentions: `<@USER_ID>` pings a user, `<#CHANNEL_ID>` links a channel. Plain
+  text is fine for normal messages.

package/skills/telegram/SKILL.md

@@ -1,118 +1,242 @@
 ---
 name: telegram
-description: Read, search and send personal Telegram messages — list recent chats / contacts / groups, pull a conversation's history, search messages, and send a message — driven by the Telethon MTProto client with the user's own account. Use when the user mentions Telegram, a Telegram chat/group/contact, "我的 Telegram", reading or replying to Telegram messages, or summarizing Telegram conversations.
+description: Full personal Telegram control over MTProto (Telethon) with the user's own account — list/search chats, read & summarize history, see unread, look up contacts & chat info, download media, and send / reply / forward / edit / delete / react / send files / mark read. Use when the user mentions Telegram, a Telegram chat/group/contact, "我的 Telegram", reading/replying/forwarding/summarizing Telegram messages, their unread Telegram, or sending a file/message on Telegram.
 when_to_use: |
-  Trigger when the user wants to do anything with their personal Telegram
-  account: list recent conversations, read / summarize the history of a chat
-  or group, search their messages for a keyword, look up a contact, or send /
-  reply to a message. This drives the user's OWN account over MTProto (not a
-  bot), so it can see everything the user can see.
+  Trigger for anything on the user's personal Telegram account: list recent
+  conversations or just the unread ones, read / summarize a chat or group,
+  search one chat or across all chats, look up a contact or a chat's info,
+  download a photo/file from a message, or take an action — send, reply,
+  forward, edit, delete, react, send a file, or mark a chat read. This drives
+  the user's OWN account over MTProto (not a bot), so it sees everything they see.
 connections: [telegram]
 allowed_tools: [Bash]
 license: Apache-2.0
 metadata:
   author: acedatacloud
-  version: "1.0"
+  version: "1.1"
 ---
 
-We drive **personal** Telegram over the MTProto protocol with the
-[Telethon](https://docs.telethon.dev/) Python library — this acts as the user's own
-account (a "userbot"), so unlike the Bot API it can read full chat history, list every
-conversation, and message anyone the user can message.
+We drive **personal** Telegram over MTProto with [Telethon](https://docs.telethon.dev/) —
+this acts as the user's own account (a "userbot"), so unlike the Bot API it can read full
+history, list every conversation, and act on anyone the user can reach.
 
-The user's credentials are injected as environment variables by the connector:
+Credentials are injected as env vars by the connector:
 
-- `TELEGRAM_API_ID` — the app id (from my.telegram.org)
-- `TELEGRAM_API_HASH` — the app hash — **secret, never echo it**
-- `TELEGRAM_SESSION_STRING` — a Telethon `StringSession` = **full account access. Never log,
+- `TELEGRAM_API_ID` — app id
+- `TELEGRAM_API_HASH` — app hash — **secret, never echo**
+- `TELEGRAM_SESSION_STRING` — Telethon `StringSession` = **full account access. Never log,
   echo, or print it.** Treat it like the account password.
 
 ## Setup — write the helper once per session
 
-`telethon` is preinstalled in the sandbox image. The helper is written to `./tg.py` **in the
-current working directory** (the per-session workdir) — not a shared global path like `/tmp` —
-so concurrent sessions never race on or reuse each other's file.
+`telethon` is preinstalled in the sandbox. The helper is written to `./tg.py` **in the current
+working directory** (the per-session workdir) — not a shared global path — so concurrent
+sessions never race.
+
+Every state-changing command (`send`, `reply`, `send-file`, `forward`, `edit`, `delete`,
+`react`, `mark-read`) is **gated**: without a trailing `--confirm` it only DRY-RUNS (prints what
+it would do, changes nothing). Read commands run directly. `--confirm` is honored **only as the
+last argument** so a message/caption that merely contains "--confirm" can never silently confirm.
 
 ```sh
-# telethon is preinstalled; the `|| pip install` is a best-effort fallback only
-# (the sandbox is non-root, so a runtime install may not succeed — rely on the
-# preinstalled package).
 python3 -c "import telethon" 2>/dev/null || pip install --user --quiet telethon 2>/dev/null || true
 
 cat > ./tg.py <<'PY'
 import os, sys, json, asyncio
 from telethon import TelegramClient
 from telethon.sessions import StringSession
+from telethon.tl import functions
+from telethon.tl.types import ReactionEmoji
 
 API_ID = int(os.environ["TELEGRAM_API_ID"])
 API_HASH = os.environ["TELEGRAM_API_HASH"]
 SESSION = os.environ["TELEGRAM_SESSION_STRING"]
 
+_raw = sys.argv[1:]
+# --confirm is only honored as the LAST token, and only one is stripped, so a
+# message/caption that merely contains "--confirm" cannot silently confirm a write.
+CONFIRM = bool(_raw) and _raw[-1] == "--confirm"
+a = _raw[:-1] if CONFIRM else list(_raw)
+cmd = a[0] if a else "help"
+args = a[1:]
+GATED = {"send", "reply", "send-file", "forward", "edit", "delete", "react", "mark-read"}
+
+
+def out(o):
+    print(json.dumps(o, ensure_ascii=False, default=str))
+
 
 async def resolve(client, target):
-    # Accept a numeric id, @username, phone, or an exact chat display name.
+    # 1) try direct resolve; 2) fall back to scanning dialogs by id or exact name
+    #    (StringSession doesn't persist the entity cache, so a numeric id from a
+    #    previous invocation may need the dialog scan to recover its access hash).
+    for attempt in (lambda: client.get_entity(int(target)), lambda: client.get_entity(target)):
+        try:
+            return await attempt()
+        except Exception:
+            pass
+    ti = None
     try:
-        return await client.get_entity(int(target))
+        ti = int(target)
     except (ValueError, TypeError):
         pass
-    try:
-        return await client.get_entity(target)
-    except Exception:
-        async for d in client.iter_dialogs():
-            if d.name == target:
-                return d.entity
-        raise ValueError(f"could not resolve target: {target}")
+    async for d in client.iter_dialogs():
+        if (ti is not None and d.id == ti) or d.name == target:
+            return d.entity
+    raise ValueError(f"could not resolve target: {target}")
 
 
-async def main():
-    cmd = sys.argv[1]
-    async with TelegramClient(StringSession(SESSION), API_ID, API_HASH) as client:
+def msg_row(m):
+    return {"id": m.id, "date": str(m.date), "out": m.out, "sender_id": m.sender_id,
+            "text": m.message, "media": bool(m.media)}
+
+
+def need(n):
+    if len(args) < n:
+        raise ValueError(f"{cmd} needs {n} argument(s), got {len(args)}")
+
+
+async def run():
+    if cmd in GATED and not CONFIRM:
+        out({"dry_run": True, "command": cmd, "args": args,
+             "note": "re-run with --confirm as the LAST argument to actually perform this write"})
+        return
+    async with TelegramClient(StringSession(SESSION), API_ID, API_HASH) as cl:
         if cmd == "whoami":
-            me = await client.get_me()
-            print(json.dumps({"id": me.id, "username": me.username,
-                              "name": ((me.first_name or "") + " " + (me.last_name or "")).strip()},
-                             ensure_ascii=False))
+            me = await cl.get_me()
+            out({"id": me.id, "username": me.username,
+                 "name": ((me.first_name or "") + " " + (me.last_name or "")).strip(), "phone": me.phone})
+
         elif cmd == "list-chats":
-            limit = int(sys.argv[2]) if len(sys.argv) > 2 else 20
-            out = []
-            async for d in client.iter_dialogs(limit=limit):
-                out.append({"name": d.name, "id": d.id, "group": d.is_group,
+            limit = int(args[0]) if args and args[0].lstrip("-").isdigit() else 20
+            unread_only = "unread-only" in args
+            res = []
+            async for d in cl.iter_dialogs(limit=limit):
+                if unread_only and not d.unread_count:
+                    continue
+                res.append({"name": d.name, "id": d.id, "group": d.is_group,
                             "channel": d.is_channel, "user": d.is_user, "unread": d.unread_count})
-            print(json.dumps(out, ensure_ascii=False))
+            out(res)
+
+        elif cmd == "unread":
+            res = []
+            async for d in cl.iter_dialogs():
+                if d.unread_count:
+                    res.append({"name": d.name, "id": d.id, "unread": d.unread_count,
+                                "group": d.is_group, "channel": d.is_channel})
+            out(sorted(res, key=lambda x: -x["unread"]))
+
         elif cmd == "get-messages":
-            target = sys.argv[2]
-            n = int(sys.argv[3]) if len(sys.argv) > 3 else 50
-            ent = await resolve(client, target)
-            out = []
-            async for m in client.iter_messages(ent, limit=n):
-                out.append({"id": m.id, "date": str(m.date), "out": m.out,
-                            "sender_id": m.sender_id, "text": m.message})
-            out.reverse()
-            print(json.dumps(out, ensure_ascii=False))
+            need(1); ent = await resolve(cl, args[0])
+            n = int(args[1]) if len(args) > 1 else 50
+            rows = [msg_row(m) async for m in cl.iter_messages(ent, limit=n)]
+            rows.reverse()
+            out(rows)
+
         elif cmd == "search":
-            target, query = sys.argv[2], sys.argv[3]
-            n = int(sys.argv[4]) if len(sys.argv) > 4 else 30
-            ent = await resolve(client, target)
-            out = []
-            async for m in client.iter_messages(ent, search=query, limit=n):
-                out.append({"id": m.id, "date": str(m.date), "sender_id": m.sender_id, "text": m.message})
-            print(json.dumps(out, ensure_ascii=False))
+            need(2); ent = await resolve(cl, args[0])
+            q = args[1]; n = int(args[2]) if len(args) > 2 else 30
+            out([msg_row(m) async for m in cl.iter_messages(ent, search=q, limit=n)])
+
+        elif cmd == "search-global":
+            need(1); q = args[0]; n = int(args[1]) if len(args) > 1 else 30
+            rows = []
+            async for m in cl.iter_messages(None, search=q, limit=n):
+                r = msg_row(m); r["chat_id"] = m.chat_id
+                rows.append(r)
+            out(rows)
+
+        elif cmd == "contacts":
+            res = await cl(functions.contacts.GetContactsRequest(hash=0))
+            out([{"id": u.id, "username": u.username,
+                  "name": ((u.first_name or "") + " " + (u.last_name or "")).strip(), "phone": u.phone}
+                 for u in res.users])
+
+        elif cmd == "chat-info":
+            need(1); ent = await resolve(cl, args[0])
+            info = {"id": ent.id, "type": type(ent).__name__,
+                    "title": getattr(ent, "title", None),
+                    "name": ((getattr(ent, "first_name", "") or "") + " " + (getattr(ent, "last_name", "") or "")).strip() or None,
+                    "username": getattr(ent, "username", None)}
+            try:
+                info["participants"] = (await cl.get_participants(ent, limit=1)).total
+            except Exception:
+                pass
+            out(info)
+
+        elif cmd == "message-link":
+            need(2); ent = await resolve(cl, args[0]); mid = int(args[1])
+            try:
+                r = await cl(functions.channels.ExportMessageLinkRequest(channel=ent, id=mid))
+                out({"link": r.link})
+            except Exception as e:
+                out({"error": f"links only available for channels/supergroups: {e}"})
+
+        elif cmd == "download-media":
+            need(2); ent = await resolve(cl, args[0]); mid = int(args[1])
+            outdir = args[2] if len(args) > 2 else "./tg_downloads"
+            os.makedirs(outdir, exist_ok=True)
+            m = await cl.get_messages(ent, ids=mid)
+            if not m or not m.media:
+                out({"error": "no media on that message"}); return
+            path = await cl.download_media(m, file=outdir)
+            out({"downloaded": path})
+
+        # ---- gated writes (need trailing --confirm) ----
         elif cmd == "send":
-            # Gated: without --confirm this only DRY-RUNS (prints the intended
-            # target + text and sends nothing). Pass --confirm to actually send.
-            target, text = sys.argv[2], sys.argv[3]
-            confirm = "--confirm" in sys.argv[4:]
-            ent = await resolve(client, target)
-            if not confirm:
-                name = getattr(ent, "title", None) or getattr(ent, "first_name", None) or str(target)
-                print(json.dumps({"dry_run": True, "would_send_to": name, "text": text,
-                                  "note": "re-run with --confirm to actually send"}, ensure_ascii=False))
-                return
-            msg = await client.send_message(ent, text)
-            print(json.dumps({"sent": True, "id": msg.id}, ensure_ascii=False))
+            need(2); ent = await resolve(cl, args[0])
+            m = await cl.send_message(ent, args[1])
+            out({"sent": True, "id": m.id})
+
+        elif cmd == "reply":
+            need(3); ent = await resolve(cl, args[0])
+            m = await cl.send_message(ent, args[2], reply_to=int(args[1]))
+            out({"sent": True, "id": m.id, "reply_to": int(args[1])})
+
+        elif cmd == "send-file":
+            need(2); ent = await resolve(cl, args[0])
+            caption = args[2] if len(args) > 2 else None
+            m = await cl.send_file(ent, args[1], caption=caption)
+            out({"sent": True, "id": m.id})
+
+        elif cmd == "forward":
+            need(3); src = await resolve(cl, args[0]); mid = int(args[1]); dst = await resolve(cl, args[2])
+            fwd = await cl.forward_messages(dst, mid, src)
+            out({"forwarded": True, "id": getattr(fwd, "id", None) or [x.id for x in fwd]})
+
+        elif cmd == "edit":
+            need(3); ent = await resolve(cl, args[0])
+            m = await cl.edit_message(ent, int(args[1]), args[2])
+            out({"edited": True, "id": m.id})
+
+        elif cmd == "delete":
+            need(2); ent = await resolve(cl, args[0])
+            await cl.delete_messages(ent, int(args[1]))
+            out({"deleted": True, "id": int(args[1])})
+
+        elif cmd == "react":
+            need(3); ent = await resolve(cl, args[0]); mid = int(args[1]); emoji = args[2]
+            await cl(functions.messages.SendReactionRequest(
+                peer=ent, msg_id=mid, reaction=[ReactionEmoji(emoticon=emoji)]))
+            out({"reacted": True, "id": mid, "emoji": emoji})
+
+        elif cmd == "mark-read":
+            need(1); ent = await resolve(cl, args[0])
+            await cl.send_read_acknowledge(ent)
+            out({"marked_read": True})
+
         else:
-            print(json.dumps({"error": f"unknown command: {cmd}"}))
-            sys.exit(1)
+            out({"error": f"unknown command: {cmd}"}); sys.exit(1)
+
+
+async def main():
+    try:
+        await run()
+    except SystemExit:
+        raise
+    except Exception as e:
+        out({"error": f"{type(e).__name__}: {e}"})
+        sys.exit(1)
 
 
 asyncio.run(main())
@@ -120,76 +244,77 @@ PY
 echo "helper ready"
 ```
 
-## Verify the connection (run this first)
+## Verify the connection first
 
 ```sh
 python3 ./tg.py whoami
-# → {"id": 8367450178, "username": "GermeyAce", "name": "Germey"}
+# → {"id": 8367450178, "username": "GermeyAce", "name": "Germey", "phone": "..."}
 ```
 
-If this errors with an auth/session message, the stored session is dead (revoked or expired) —
-tell the user to reconnect the Telegram connector at https://auth.acedata.cloud/user/connections.
+On an auth/session error the stored session is dead — tell the user to reconnect at
+https://auth.acedata.cloud/user/connections.
 
-## Recipes
+## Read recipes
 
-### List recent conversations
+| Goal | Command |
+|---|---|
+| Recent conversations | `python3 ./tg.py list-chats 20` |
+| Only chats with unread (ranked) | `python3 ./tg.py unread` |
+| A chat's history (oldest→newest) | `python3 ./tg.py get-messages <target> 50` |
+| Search inside one chat | `python3 ./tg.py search <target> "kw" 30` |
+| Search across ALL chats | `python3 ./tg.py search-global "kw" 30` |
+| List contacts | `python3 ./tg.py contacts` |
+| Info about a chat/user | `python3 ./tg.py chat-info <target>` |
+| t.me link to a message | `python3 ./tg.py message-link <target> <msg_id>` |
 
-```sh
-python3 ./tg.py list-chats 20
-# → [{"name":"Ace <> ConduitOS","id":-5287630726,"group":true,...,"unread":0}, ...]
-```
+`<target>` = numeric id (most reliable — from `list-chats`), `@username`, phone, or exact chat
+name. In message rows, `out:true` = sent by the user; `media:true` = has an attachment.
 
-Use the returned `id` (or the exact `name`) as the target for the next calls.
+**Summarize-unread pattern**: `unread` → pick the chats that matter → `get-messages <id> N` on
+each → summarize. Don't dump 20k messages; sample the most-unread / most-relevant.
 
-### Read a conversation's history (oldest→newest)
+## Media
 
 ```sh
-# target = numeric id, @username, phone, or exact chat name; second arg = how many messages
-python3 ./tg.py get-messages -5287630726 50
-python3 ./tg.py get-messages @some_username 30
+# Download an attachment from a message → returns the saved path
+python3 ./tg.py download-media <target> <msg_id> ./tg_downloads
+# Send a local file or a URL (optional caption) — GATED
+python3 ./tg.py send-file <target> /path/or/https-url "caption" --confirm
 ```
 
-`out: true` means the message was sent BY the user; `sender_id` is the author. Summarize from
-the returned JSON.
+To hand a downloaded file back to the user as a link, upload it to the CDN (see the
+`cos-upload` skill) after `download-media`.
 
-### Search inside a conversation
+## Write recipes — all GATED (dry-run unless trailing `--confirm`)
 
-```sh
-python3 ./tg.py search -5287630726 "keyword" 30
-```
-
-(Server-side search is scoped to one chat. To search broadly, list chats first, then search the
-relevant ones.)
-
-### Send / reply to a message — TWO-STEP, confirm first
-
-Sending posts a **real message as the user**, so it is gated:
+Sending/editing/deleting acts as the **real user**. Always run the dry run first, show the user
+exactly what will happen, get an explicit "yes", then re-run with `--confirm` as the **last
+argument**. Never bulk-send.
 
 ```sh
-# Step 1 — DRY RUN (default, sends nothing). Show this preview to the user.
-python3 ./tg.py send -5287630726 "Hi, following up on this."
-# → {"dry_run": true, "would_send_to": "Ace <> ConduitOS", "text": "Hi, following up on this.", ...}
-
-# Step 2 — only after the user explicitly says yes in the conversation, add --confirm:
-python3 ./tg.py send -5287630726 "Hi, following up on this." --confirm
-# → {"sent": true, "id": 4502}
+python3 ./tg.py send    <target> "text"                          # → dry_run; add --confirm to send
+python3 ./tg.py reply   <target> <msg_id> "text" --confirm
+python3 ./tg.py forward <from_target> <msg_id> <to_target> --confirm
+python3 ./tg.py edit    <target> <msg_id> "new text" --confirm   # own messages
+python3 ./tg.py delete  <target> <msg_id> --confirm              # destructive
+python3 ./tg.py react   <target> <msg_id> "👍" --confirm
+python3 ./tg.py mark-read <target> --confirm                     # sends read receipts
 ```
 
-**Always run the dry run first, show the user exactly who + what, and require an explicit "yes"
-before re-running with `--confirm`** — even if the original instruction said "just send it".
-Never bulk-send.
-
-## Gotchas — surface these before the user is surprised
-
-- **This is the user's real account.** Sending posts as them; reading exposes all their private
-  chats. Be conservative.
-- **`FloodWaitError`**: Telegram rate-limits userbots. If a call fails with a flood-wait of N
-  seconds, tell the user to retry after N seconds — do not loop/retry aggressively (it escalates
-  toward an account ban).
-- **Dead session**: a `session_string` can be revoked by the user from Telegram → Settings →
-  Devices. On an `AuthKeyError` / unauthorized error, the fix is reconnecting the connector, not
-  retrying.
-- **Never print `TELEGRAM_SESSION_STRING` or `TELEGRAM_API_HASH`** — they are full-account
-  secrets. The helper never prints them; keep it that way.
-- **Resolving targets**: prefer the numeric `id` from `list-chats` (most reliable). Names work
-  only on an exact match; usernames need the leading `@`.
+The dry run returns `{"dry_run": true, "command": ..., "args": [...]}` — present that to the
+user verbatim as the confirmation prompt.
+
+## Gotchas — surface before the user is surprised
+
+- **This is the user's real account.** Confirm before any write; reading exposes private chats.
+- **`FloodWaitError`**: Telegram rate-limits userbots. On a flood-wait of N seconds, tell the
+  user to retry after N — never loop/retry aggressively (escalates toward a ban).
+- **Dead session**: revoked from Telegram → Settings → Devices, or ~6-month inactivity. On
+  `AuthKeyError`/unauthorized, reconnect the connector (don't retry).
+- **Never print `TELEGRAM_SESSION_STRING` / `TELEGRAM_API_HASH`** — full-account secrets.
+- **Targets**: prefer the numeric `id` from `list-chats` (the helper recovers its access hash by
+  scanning dialogs); names need an exact match, usernames need a leading `@`.
+- **`message-link`** only works for public channels/supergroups; private 1:1 / basic groups
+  return an error (no shareable link exists).
+- **`edit`/`delete`** generally only apply to the user's own messages (admins can delete others
+  in groups they manage).