From 93d9d0de06afa0788ef1f4436debcdef44e94b59 Mon Sep 17 00:00:00 2001
From: leon <leon@leondeMac-mini.local>
Date: Tue, 17 Feb 2026 07:53:11 -0500
Subject: [PATCH] docs(telegram): document bind flow and polling conflict
 guidance

---
 README.md                  | 17 +++++++++++++++++
 docs/network-deployment.md | 25 +++++++++++++++++++++++--
 2 files changed, 40 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index ec87d47..fb029f9 100644
--- a/README.md
+++ b/README.md
@@ -166,6 +166,9 @@ zeroclaw doctor
 # Check channel health
 zeroclaw channel doctor
 
+# Bind a Telegram identity into allowlist
+zeroclaw channel bind-telegram 123456789
+
 # Get integration setup details
 zeroclaw integrations info Telegram
 
@@ -277,6 +280,19 @@ Recommended low-friction setup (secure + fast):
 - **Slack:** allowlist your own Slack member ID (usually starts with `U`).
 - Use `"*"` only for temporary open testing.
 
+Telegram operator-approval flow:
+
+1. Keep `[channels_config.telegram].allowed_users = []` for deny-by-default startup.
+2. Unauthorized users receive a hint with a copyable operator command:
+   `zeroclaw channel bind-telegram <IDENTITY>`.
+3. Operator runs that command locally, then user retries sending a message.
+
+If you need a one-shot manual approval, run:
+
+```bash
+zeroclaw channel bind-telegram 123456789
+```
+
 If you're not sure which identity to use:
 
 1. Start channels and send one message to your bot.
@@ -563,6 +579,7 @@ See [aieos.org](https://aieos.org) for the full schema and live examples.
 | `doctor` | Diagnose daemon/scheduler/channel freshness |
 | `status` | Show full system status |
 | `channel doctor` | Run health checks for configured channels |
+| `channel bind-telegram <IDENTITY>` | Add one Telegram username/user ID to allowlist |
 | `integrations info <name>` | Show setup/status details for one integration |
 
 ## Development
diff --git a/docs/network-deployment.md b/docs/network-deployment.md
index 5fdc7fa..54a7694 100644
--- a/docs/network-deployment.md
+++ b/docs/network-deployment.md
@@ -55,7 +55,7 @@ baud = 115200
 
 [channels_config.telegram]
 bot_token = "YOUR_BOT_TOKEN"
-allowed_users = ["*"]
+allowed_users = []
 
 [gateway]
 host = "127.0.0.1"
@@ -127,11 +127,32 @@ Telegram uses **long-polling** by default:
 ```toml
 [channels_config.telegram]
 bot_token = "YOUR_BOT_TOKEN"
-allowed_users = ["*"]   # or specific @usernames / user IDs
+allowed_users = []      # deny-by-default, bind identities explicitly
 ```
 
 Run `zeroclaw daemon` — Telegram channel starts automatically.
 
+To approve one Telegram account at runtime:
+
+```bash
+zeroclaw channel bind-telegram <IDENTITY>
+```
+
+`<IDENTITY>` can be a numeric Telegram user ID or a username (without `@`).
+
+### 4.1 Single Poller Rule (Important)
+
+Telegram Bot API `getUpdates` supports only one active poller per bot token.
+
+- Keep one runtime instance for the same token (recommended: `zeroclaw daemon` service).
+- Do not run `cargo run -- channel start` or another bot process at the same time.
+
+If you hit this error:
+
+`Conflict: terminated by other getUpdates request`
+
+you have a polling conflict. Stop extra instances and restart only one daemon.
+
 ---
 
 ## 5. Webhook Channels (WhatsApp, Custom)