diff --git a/README.md b/README.md
index d47154a..1e88d44 100644
--- a/README.md
+++ b/README.md
@@ -16,7 +16,7 @@
     <a href="#-quick-start">Quick Start</a> &bull;
     <a href="#-features">Features</a> &bull;
     <a href="#-comparison">Comparison</a> &bull;
-    <a href="#-telegram-bot-21-commands">Telegram Bot</a> &bull;
+    <a href="#-telegram-bot-27-commands">Telegram Bot</a> &bull;
     <a href="#-cli-reference">CLI Reference</a> &bull;
     <a href="#-changelog">Changelog</a> &bull;
     <a href="https://www.samnet.dev/learn/networking/mtproto-proxy-telegram/">Full Guide ↗</a>
@@ -413,7 +413,7 @@ mtproxymax secret remove bob     # Permanent removal
 
 ---
 
-### 🤖 Telegram Bot (21 Commands)
+### 🤖 Telegram Bot (27 Commands)
 
 Full proxy management from your phone. Setup takes 60 seconds:
 
@@ -421,27 +421,124 @@ Full proxy management from your phone. Setup takes 60 seconds:
 mtproxymax telegram setup
 ```
 
+The bot registers its commands with Telegram, so tapping the **`/` menu button** in
+the chat lists everything you are allowed to run — no need to memorise them. The
+menu is scoped to your role: everyone sees the public self-service commands, admins
+see the Admin Control Plane, and superadmins additionally see `/mp_remove`,
+`/mp_restart`, `/mp_update` and `/mp_lockdown`. The list is re-synced whenever the
+bot service starts; to refresh it by hand use:
+
+```bash
+mtproxymax telegram sync-commands
+```
+
+**Public self-service** — every user, including ones with no admin role:
+
+| Command | Description |
+|---------|-------------|
+| `/start` | Self-service onboarding |
+| `/my_status <label>` | Your data quota and expiry |
+| `/redeem <code> [label]` | Redeem a voucher |
+| `/voucher <code> [label]` | Alias for `/redeem` |
+| `/support <message>` | Send a ticket to the admins |
+
+**Admin Control Plane** (`admin` and above):
+
 | Command | Description |
 |---------|-------------|
 | `/mp_status` | Proxy status, uptime, connections |
 | `/mp_secrets` | List all users with active connections |
 | `/mp_link` | Get proxy details + QR code image |
 | `/mp_add <label>` | Add new user |
-| `/mp_remove <label>` | Delete user |
-| `/mp_revoke <label>` | Revoke and purge a user secret immediately |
 | `/mp_rotate <label>` | Generate new key for user |
 | `/mp_enable <label>` | Re-enable disabled user |
 | `/mp_disable <label>` | Temporarily disable user |
-| `/mp_lockdown [on\|off]` | Toggle emergency panic lockdown defensive posture |
-| `/mp_digest` | View live executive health, posture, and traffic digest box |
 | `/mp_limits` | Show all user limits |
 | `/mp_setlimit` | Set user limits |
 | `/mp_traffic` | Per-user traffic breakdown |
 | `/mp_upstreams` | List proxy chains |
 | `/mp_health` | Run diagnostics |
+| `/mp_digest` | View live executive health, posture, and traffic digest box |
+| `/mp_broadcast <msg>` | Message every known bot user |
+| `/mp_fleet` | Global federation fleet dashboard |
+| `/mp_voucher create\|list` | Generate or list vouchers |
+| `/reply <chat_id> <msg>` | Answer a support ticket |
+| `/mp_help` | Show all commands |
+
+**Superadmin only:**
+
+| Command | Description |
+|---------|-------------|
+| `/mp_remove <label>` | Delete user (`/mp_revoke` is an alias, handled but not listed in the `/` menu) |
 | `/mp_restart` | Restart proxy |
 | `/mp_update` | Check for updates |
-| `/mp_help` | Show all commands |
+| `/mp_lockdown [on\|off]` | Toggle emergency panic lockdown defensive posture |
+
+#### Inline menu buttons
+
+Replies carry buttons, so most of the above is reachable by tapping rather than
+typing. Tapping **👥 Users** opens a paginated list; tapping a user opens a card
+showing its live connections, unique IPs, quota bar and expiry, with actions
+attached. Tapping **📈 Traffic** opens the analytics view with 24h / 7d / 30d
+windows.
+
+Anything that destroys state is behind a confirmation step — the ⏸ Disable,
+♻️ Rotate and 🗑 Remove buttons only *ask*; a second tap on **✅ Yes** performs
+it. Nothing destructive is ever one mis-tap away.
+
+The buttons you see are filtered by your role: a `reseller` gets the public
+views only, and a button never grants more than typing the equivalent command
+would.
+
+#### Traffic history
+
+The bot records rolling traffic samples under
+`/opt/mtproxymax/relay_stats/history/` (5-minute samples, 7-day retention) and
+uses them for the analytics view and the periodic report. Samples are stored as
+**deltas**, so an engine restart or a traffic reset cannot corrupt a window.
+
+```bash
+mtproxymax telegram history status   # sample counts, date range, retention
+mtproxymax telegram history prune    # apply retention now
+mtproxymax telegram history reset    # delete all recorded history
+```
+
+#### Report settings
+
+| Setting | Default | Meaning |
+|---------|---------|---------|
+| `TELEGRAM_INTERVAL` | `6` | Hours between periodic reports |
+| `TELEGRAM_REPORT_DETAIL` | `auto` | `auto` sends a full report only when there was traffic, otherwise a one-line heartbeat. `full` and `summary` force the two behaviours. |
+| `TELEGRAM_HISTORY_ENABLED` | `true` | Record traffic samples |
+| `TELEGRAM_HISTORY_INTERVAL_MIN` | `5` | Minutes between samples |
+| `TELEGRAM_HISTORY_RETENTION_DAYS` | `7` | Days of history to keep |
+
+#### 🎛 Running the proxy from buttons
+
+Every command above also exists as a button, so day-to-day management needs no
+typing. Send any command — or tap **🏠 Menu** on any reply — to open the hub:
+
+| Section | What it covers |
+|---------|----------------|
+| 👥 **Users** | Paginated list → per-user card with live connections, traffic, quota bar, expiry, note and quota-reset day, plus link/QR, enable, disable, rotate and remove |
+| 📊 **Per-user traffic** | What that user moved over the last 24h / 7d / 30d, with a 24-hour sparkline, beside their quota and expiry |
+| ⚙️ **Manage** (per user) | Quota, connection cap, IP cap, expiry, monthly quota-reset day, note, ad-tag, and applying a saved limit template to that user |
+| 🧩 **Templates** | Create, edit every field of, apply and delete limit templates |
+| 📈 **Traffic** | Windowed totals (24h / 7d / 30d) with a sparkline, peak and average rate, and top talkers |
+| 🖥 **Server** | Engine health, posture digest, upstreams, fleet, vouchers, updates |
+| 🛠 **Tools** | Add user, broadcast, rotate-all, lockdown, restart, apply update |
+| ⚙️ **Settings** | Port, domain, metrics port, report interval |
+
+Limits are edited with preset buttons for the common values, plus a **✏️ Custom…**
+prompt for anything else. Anything that affects live users — removing, rotating,
+disabling, restarting, locking down — asks for confirmation first, and the
+confirmation is the only path that performs the write.
+
+**Typed input.** Adding a user, setting a custom limit, saving a template name,
+broadcasting and writing a note all need text, which buttons cannot supply. Tapping
+one of those sends a prompt; your next message is taken as the answer. The prompt is
+always escapable: sending any `/command` cancels it, and so does the **❌ Cancel**
+button. An unanswered prompt expires after five minutes.
 
 **Automatic alerts & announcements:**
 - 🚨 Emergency Lockdown activated → immediate posture alert
@@ -628,6 +725,16 @@ mtproxymax status        # Overview with connections count
 - Active connections per user
 - Cumulative tracking across restarts
 
+Cumulative counters only ever grow, so they cannot answer *"how much moved
+today, and is that more or less than yesterday?"*. For that the Telegram bot
+records a rolling history of 5-minute samples (see
+[Traffic history](#traffic-history)) and reports **windowed** figures — 24h/7d/30d
+totals, period-over-period change, peak and average rate, top talkers, and an
+hourly sparkline — both in the periodic report and in the 📈 Traffic view.
+
+The periodic report is activity-aware: with no traffic in the window it
+collapses to a one-line heartbeat rather than repeating a dashboard of zeroes.
+
 ---
 
 ### 🌍 Geo-Blocking
@@ -1503,6 +1610,7 @@ mtproxymax update                       # Check for script + engine updates
 - **Automated SSL Shield (`ssl-shield`):** Zero-touch Let's Encrypt / `openssl` certificate issuance and ACME domain management.
 - **Automated Cloud Backups (`backup-cloud`):** Automatic tarball offloading to Telegram admin chat (`sendDocument`) or multi-cloud storage (`rclone`/S3/R2).
 - **Dual-Tier Telegram Bot (`telegram`):** Public self-service tier (`/start`, `/my_status <label>`, `/voucher`) combined with an authenticated Admin Control Plane (`/mp_fleet`, `/mp_secrets`, `/mp_lockdown`).
+- **Telegram Command Menu:** The bot registers its commands via `setMyCommands`, so the in-app `/` menu button lists every command you can run. Scopes mirror the role model — public commands for everyone, the Admin Control Plane for admins, and the superadmin-only commands (`/mp_remove`, `/mp_restart`, `/mp_update`, `/mp_lockdown`) only for superadmins. Re-synced on every bot service start and on `mtproxymax telegram sync-commands`.
 - **Comprehensive Hardening & Audit:** Fixed race conditions (`flock`), prevented configuration code injection (`grep | cut`), added comma/pipe CSV import normalization (`secret_import`), and ensured strict-mode container fallbacks across 18,369 lines (`100% clean`).
 
 ### v1.3.1 — Performance & Anti-DPI Upgrade Suite
diff --git a/mtproxymax.sh b/mtproxymax.sh
index b0ac44b..34bef34 100644
--- a/mtproxymax.sh
+++ b/mtproxymax.sh
@@ -147,6 +147,12 @@ TELEGRAM_CHAT_ID=""
 TELEGRAM_INTERVAL=6
 TELEGRAM_ALERTS_ENABLED="true"
 TELEGRAM_SERVER_LABEL="MTProxyMax"
+# Rolling traffic history. Disabling it stops new samples; existing ones stay.
+TELEGRAM_HISTORY_ENABLED="true"
+TELEGRAM_HISTORY_INTERVAL_MIN="5"
+TELEGRAM_HISTORY_RETENTION_DAYS="7"
+# auto = send a full report only when there was traffic, else a heartbeat.
+TELEGRAM_REPORT_DETAIL="auto"
 AUTO_UPDATE_ENABLED="true"
 
 # Anti-DPI & Stealth Defenses
@@ -718,6 +724,10 @@ TELEGRAM_CHAT_ID='${TELEGRAM_CHAT_ID}'
 TELEGRAM_INTERVAL='${TELEGRAM_INTERVAL}'
 TELEGRAM_ALERTS_ENABLED='${TELEGRAM_ALERTS_ENABLED}'
 TELEGRAM_SERVER_LABEL='${TELEGRAM_SERVER_LABEL}'
+TELEGRAM_HISTORY_ENABLED='${TELEGRAM_HISTORY_ENABLED}'
+TELEGRAM_HISTORY_INTERVAL_MIN='${TELEGRAM_HISTORY_INTERVAL_MIN}'
+TELEGRAM_HISTORY_RETENTION_DAYS='${TELEGRAM_HISTORY_RETENTION_DAYS}'
+TELEGRAM_REPORT_DETAIL='${TELEGRAM_REPORT_DETAIL}'
 
 # Auto-Update
 AUTO_UPDATE_ENABLED='${AUTO_UPDATE_ENABLED}'
@@ -803,6 +813,7 @@ load_settings() {
             PROXY_SECRET_URL|PROXY_CONFIG_V4_URL|PROXY_CONFIG_V6_URL|\
             TELEGRAM_ENABLED|TELEGRAM_BOT_TOKEN|TELEGRAM_CHAT_ID|\
             TELEGRAM_INTERVAL|TELEGRAM_ALERTS_ENABLED|TELEGRAM_SERVER_LABEL|\
+            TELEGRAM_HISTORY_ENABLED|TELEGRAM_HISTORY_INTERVAL_MIN|TELEGRAM_HISTORY_RETENTION_DAYS|TELEGRAM_REPORT_DETAIL|\
             AUTO_UPDATE_ENABLED|SECRET_AUTO_ROTATE_DAYS|BACKUP_RETENTION_DAYS|QUOTA_ENFORCEMENT_MODE|\
             STEALTH_SHIELD|STEALTH_PRESET|STEALTH_MSS_CLAMP|LOCKDOWN_MODE|PORT_POOL_PORTS|QOS_LIMIT_MBPS|HAPPY_HOURS_WINDOW|\
             REPLICATION_ENABLED|REPLICATION_ROLE|REPLICATION_SYNC_INTERVAL|\
@@ -3471,8 +3482,13 @@ secret_generate_links() {
                 local label="${SECRETS_LABELS[$i]}"
                 local fs; fs=$(build_faketls_secret "${SECRETS_KEYS[$i]}")
                 local link="https://t.me/proxy?server=${server_ip}&port=${PROXY_PORT}&secret=${fs}"
-                local qr_url="https://api.qrserver.com/v1/create-qr-code/?size=200x200&data=$(printf '%s' "$link" | sed 's/:/%3A/g;s|/|%2F|g;s/?/%3F/g;s/=/%3D/g;s/&/%26/g')"
-                echo "<div class='user'><h2>${label}</h2><a href='${link}'>${link}</a><br><img src='${qr_url}' alt='QR'></div>"
+                # Rendered here and inlined: pointing <img> at a remote
+                # renderer would post this user's key to it every time the sheet
+                # is opened. Empty means no renderer — the link above still works.
+                local qr_url; qr_url=$(_qr_data_uri "$link")
+                local qr_tag=""
+                [ -n "$qr_url" ] && qr_tag="<br><img src='${qr_url}' alt='QR'>"
+                echo "<div class='user'><h2>${label}</h2><a href='${link}'>${link}</a>${qr_tag}</div>"
             done
             echo "</body></html>"
         } > "$outfile"
@@ -6579,12 +6595,17 @@ EOF
         local label="${SECRETS_LABELS[$i]}"
         local sec="${SECRETS_KEYS[$i]}"
         local tg_url="tg://proxy?server=${ip}&port=${port}&secret=${sec}"
-        local qr_api="https://api.qrserver.com/v1/create-qr-code/?size=150x150&data=${tg_url}"
-        
+        # Inlined rather than fetched: see _qr_data_uri.
+        local qr_api; qr_api=$(_qr_data_uri "$tg_url")
+
         echo "<div class='card'>" >> "$outfile"
         echo "  <h3>${label}</h3>" >> "$outfile"
         echo "  <p>High-Speed MTProto Proxy</p>" >> "$outfile"
-        echo "  <div class='qr-box'><img src='${qr_api}' alt='QR Code' width='150' height='150'></div>" >> "$outfile"
+        if [ -n "$qr_api" ]; then
+            echo "  <div class='qr-box'><img src='${qr_api}' alt='QR Code' width='150' height='150'></div>" >> "$outfile"
+        else
+            echo "  <p><small>No QR renderer on the server — install <code>qrencode</code> to include codes.</small></p>" >> "$outfile"
+        fi
         echo "  <p>Scan with Telegram Camera</p>" >> "$outfile"
         echo "</div>" >> "$outfile"
     done
@@ -9693,12 +9714,49 @@ secret_qr() {
 }
 
 
-# Generate QR code URL (for Telegram photo messages)
-generate_qr_url() {
-    local link="$1"
-    local encoded
-    encoded=$(printf '%s' "$link" | sed 's/&/%26/g; s/?/%3F/g; s/=/%3D/g; s/:/%3A/g; s|/|%2F|g')
-    echo "https://api.qrserver.com/v1/create-qr-code/?size=300x300&data=${encoded}"
+# Render a QR to a PNG on this host. Non-zero when no renderer is available.
+#
+# Duplicated from the bot daemon on purpose: the daemon is generated as a
+# self-contained script and never sources this one, which is the same reason
+# format_bytes and friends appear in both.
+_qr_png() {
+    local data="$1" out="$2"
+    [ -n "$data" ] && [ -n "$out" ] || return 1
+    if command -v qrencode &>/dev/null; then
+        qrencode -o "$out" -s 6 -m 2 "$data" 2>/dev/null && [ -s "$out" ] && return 0
+    fi
+    if command -v python3 &>/dev/null && python3 -c '' &>/dev/null 2>&1 && \
+       python3 -c 'import qrcode' &>/dev/null; then
+        python3 - "$data" "$out" <<'PYQ' 2>/dev/null && [ -s "$out" ] && return 0
+import sys
+import qrcode
+qrcode.make(sys.argv[1]).save(sys.argv[2])
+PYQ
+    fi
+    rm -f "$out" 2>/dev/null
+    return 1
+}
+
+# A self-contained <img> source for a QR, or "" when nothing can render one.
+#
+# The exported HTML sheets used to point <img> straight at api.qrserver.com, so
+# opening the sheet in a browser handed every user's proxy key — the link IS the
+# credential — to a third party. A data: URI keeps the image inside the file and
+# the key on this machine. Callers must render the link without an image when
+# this returns empty rather than reaching for a remote renderer.
+_qr_data_uri() {
+    local data="$1" png b64
+    command -v base64 &>/dev/null || return 0
+    png=$(mktemp "${TMPDIR:-/tmp}/mtpx-qr.XXXXXX") || return 0
+    if _qr_png "$data" "$png"; then
+        # busybox base64 has no -w, GNU's wraps at 76 columns by default.
+        b64=$(base64 -w0 < "$png" 2>/dev/null) || b64=$(base64 < "$png" 2>/dev/null | tr -d '\n')
+        rm -f "$png" 2>/dev/null
+        [ -n "$b64" ] && printf 'data:image/png;base64,%s' "$b64"
+        return 0
+    fi
+    rm -f "$png" 2>/dev/null
+    return 0
 }
 
 # ── Section 11: Geo-Blocking ────────────────────────────────
@@ -10327,6 +10385,8 @@ admin_add() {
         echo "${tg_id}|${role}|${label}|$(date -u '+%Y-%m-%d')" >> "$ADMINS_FILE"
     fi
     log_success "Admin ${tg_id} registered as '${role}' (${label})"
+    # Keep the new admin's Telegram command menu in step with their role.
+    telegram_sync_commands &>/dev/null || true
 }
 
 admin_remove() {
@@ -10335,6 +10395,8 @@ admin_remove() {
     load_admins
     grep -v "^${tg_id}|" "$ADMINS_FILE" > "${ADMINS_FILE}.tmp" 2>/dev/null && mv "${ADMINS_FILE}.tmp" "$ADMINS_FILE"
     log_success "Admin ${tg_id} removed"
+    # Drop the revoked admin's menu so it stops offering admin commands.
+    telegram_clear_commands "$tg_id" &>/dev/null || true
 }
 
 admin_list() {
@@ -11017,11 +11079,238 @@ telegram_send_message() {
     return 1
 }
 
-telegram_send_photo() {
-    local photo_url="$1" caption="${2:-}"
+# ── Telegram command menu (setMyCommands) ────────────────────────────────────
+# Without this the client-side "/" menu button has nothing to show and the bot's
+# commands are only discoverable by reading /mp_help. The lists below are the
+# single source of truth: the bot daemon re-runs `mtproxymax telegram
+# sync-commands` on boot rather than duplicating them into its own heredoc.
+# Format is one "command|description" per line, without the leading slash.
+TG_CMDS_PUBLIC="start|Self-service onboarding and help
+my_status|Check your data quota and expiry (usage: /my_status <label>)
+redeem|Redeem a voucher code (usage: /redeem <code> [label])
+voucher|Alias for /redeem
+support|Send a support request to the server admins"
+
+TG_CMDS_ADMIN="mp_help|Show all commands
+mp_status|Proxy status, uptime and traffic
+mp_secrets|List all secrets with per-user stats
+mp_link|Get proxy links and QR codes
+mp_add|Add a new secret (usage: /mp_add <label>)
+mp_rotate|Rotate a secret key (usage: /mp_rotate <label>)
+mp_enable|Enable a secret (usage: /mp_enable <label>)
+mp_disable|Disable a secret (usage: /mp_disable <label>)
+mp_limits|Show per-user limits
+mp_setlimit|Set user limits (connections, IPs, quota, expiry)
+mp_traffic|Detailed per-user traffic breakdown
+mp_upstreams|List upstream routes
+mp_health|Run health diagnostics
+mp_digest|System health and security digest
+mp_broadcast|Broadcast a message to all known bot users
+mp_fleet|Global federation fleet dashboard
+mp_voucher|Generate or list vouchers
+reply|Reply to a support ticket (usage: /reply <chat_id> <message>)"
+
+# Superadmins additionally get the four commands _process_cmd gates on role.
+TG_CMDS_SUPERADMIN="${TG_CMDS_ADMIN}
+mp_remove|Remove or revoke a secret (usage: /mp_remove <label>)
+mp_restart|Restart the proxy
+mp_update|Check for and apply updates
+mp_lockdown|Emergency lockdown toggle (usage: /mp_lockdown on/off)"
+
+# Render a "command|description" table as the JSON array the Bot API expects.
+_tg_commands_json() {
+    local table="$1" name desc json="" first=1 line
+    while IFS= read -r line || [ -n "$line" ]; do
+        [ -z "$line" ] && continue
+        name="${line%%|*}"
+        desc="${line#*|}"
+        # Entries are static, but sanitise defensively: Telegram rejects the
+        # entire list if any single entry is malformed, so a stray control
+        # character or quote in a future description must not break the menu.
+        desc=$(printf '%s' "$desc" | tr '\t' ' ' | tr -d '[:cntrl:]')
+        desc="${desc//\\/\\\\}"
+        desc="${desc//\"/\\\"}"
+        [ "$first" -eq 1 ] || json="${json},"
+        first=0
+        json="${json}{\"command\":\"${name}\",\"description\":\"${desc}\"}"
+    done <<< "$table"
+    printf '[%s]' "$json"
+}
+
+# POST to a Bot API method, keeping the token out of the process list. Returns 0
+# only when Telegram acknowledges the call.
+_tg_api_post() {
+    local method="$1" body="$2"
+    local token="${TELEGRAM_BOT_TOKEN:-}"
+    [ -n "$token" ] || return 0
+    local _cfg
+    _cfg=$(_mktemp) || return 0
+    printf 'url = "https://api.telegram.org/bot%s/%s"\n' "$token" "$method" > "$_cfg"
+    local response
+    response=$(curl -s --max-time 10 -K "$_cfg" \
+        -H 'Content-Type: application/json' \
+        -d "$body" 2>/dev/null) || true
+    rm -f "$_cfg"
+    echo "$response" | grep -q '"ok":true'
+}
+
+# Register a command list for one scope. An empty scope means the default scope,
+# which applies to every user who has no more specific scope.
+_tg_set_commands() {
+    local scope="$1" commands="$2"
+    local body
+    if [ -n "$scope" ]; then
+        body="{\"commands\":${commands},\"scope\":${scope}}"
+    else
+        body="{\"commands\":${commands}}"
+    fi
+    _tg_api_post setMyCommands "$body"
+}
+
+# Push the whole menu: public commands for everyone, the admin control plane for
+# admins, and the privileged commands for superadmins. Entirely best-effort — a
+# network failure must never abort setup or the bot daemon.
+# Print the registered command list for a role, as "command|description" lines.
+#
+# The bot daemon cannot read TG_CMDS_* itself — they live here, outside the
+# heredoc it is generated from, and it deliberately re-runs `telegram
+# sync-commands` on boot rather than keeping a copy that could drift. Its /help
+# view calls this instead, so the list a user is shown and the list Telegram is
+# told about are the same bytes.
+telegram_print_commands() {
+    case "${1:-admin}" in
+        public) printf '%s\n' "$TG_CMDS_PUBLIC" ;;
+        # A reseller reaches the public surface plus the voucher engine, which
+        # is exactly the allowlist _process_cmd applies to that role.
+        reseller)
+            printf '%s\n' "$TG_CMDS_PUBLIC"
+            printf 'mp_voucher|Generate or list vouchers\n'
+            ;;
+        superadmin) printf '%s\n' "$TG_CMDS_SUPERADMIN" ;;
+        *) printf '%s\n' "$TG_CMDS_ADMIN" ;;
+    esac
+}
+
+telegram_sync_commands() {
+    local cid role _rest
+    [ "${TELEGRAM_ENABLED:-false}" = "true" ] || return 0
+    [ -n "${TELEGRAM_BOT_TOKEN:-}" ] || return 0
+
+    local pub admin super
+    pub=$(_tg_commands_json "$TG_CMDS_PUBLIC")
+    admin=$(_tg_commands_json "$TG_CMDS_ADMIN")
+    super=$(_tg_commands_json "$TG_CMDS_SUPERADMIN")
+
+    _tg_set_commands "" "$pub" || log_warn "Could not register the public command menu"
+
+    if [ -n "${TELEGRAM_CHAT_ID:-}" ]; then
+        _tg_set_commands "{\"type\":\"chat\",\"chat_id\":${TELEGRAM_CHAT_ID}}" "$super" || true
+    fi
+
+    # RBAC admins, mirroring the role gates in _process_cmd.
+    if [ -f "${ADMINS_FILE:-}" ]; then
+        while IFS='|' read -r cid role _rest || [ -n "$cid" ]; do
+            [[ "$cid" =~ ^-?[0-9]+$ ]] || continue
+            [ "$cid" = "${TELEGRAM_CHAT_ID:-}" ] && continue
+            if [ "$role" = "superadmin" ]; then
+                _tg_set_commands "{\"type\":\"chat\",\"chat_id\":${cid}}" "$super" || true
+            else
+                _tg_set_commands "{\"type\":\"chat\",\"chat_id\":${cid}}" "$admin" || true
+            fi
+        done < "${ADMINS_FILE}"
+    fi
+    return 0
+}
+
+# Drop a chat's custom menu so a revoked admin stops seeing the admin commands.
+telegram_clear_commands() {
+    local cid="${1:-}"
+    [[ "$cid" =~ ^-?[0-9]+$ ]] || return 0
+    _tg_api_post deleteMyCommands "{\"scope\":{\"type\":\"chat\",\"chat_id\":${cid}}}" || true
+    return 0
+}
+
+# Inspect and maintain the rolling traffic history written by the bot daemon.
+#
+# The daemon owns the format; the manager only counts rows and prunes, so the
+# analytics live in exactly one place. The field order is duplicated here for
+# readability, which matches how format_bytes is already duplicated between the
+# two — keep this comment and the daemon's in step:
+#
+#   global.tsv   epoch|in_delta|out_delta|conns|marker
+#   users.tsv    epoch|label|in_delta|out_delta
+telegram_history_cmd() {
+    local sub="${1:-status}"
+    local dir="${STATS_DIR}/history"
+    case "$sub" in
+        status)
+            echo -e "  ${BOLD}Traffic history:${NC} ${dir}"
+            if [ ! -d "$dir" ]; then
+                echo -e "  ${DIM}No history recorded yet.${NC}"
+                return 0
+            fi
+            local gn=0 un=0
+            [ -f "$dir/global.tsv" ] && gn=$(wc -l < "$dir/global.tsv" 2>/dev/null || echo 0)
+            [ -f "$dir/users.tsv" ]  && un=$(wc -l < "$dir/users.tsv" 2>/dev/null || echo 0)
+            echo -e "  ${DIM}Global samples: ${gn} | Per-user rows: ${un}${NC}"
+            if [ -f "$dir/global.tsv" ] && [ "$gn" -gt 0 ]; then
+                local first last
+                first=$(head -1 "$dir/global.tsv" | cut -d'|' -f1)
+                last=$(tail -1 "$dir/global.tsv" | cut -d'|' -f1)
+                echo -e "  ${DIM}Oldest: $(date -d "@${first}" '+%Y-%m-%d %H:%M' 2>/dev/null || echo "$first")${NC}"
+                echo -e "  ${DIM}Newest: $(date -d "@${last}" '+%Y-%m-%d %H:%M' 2>/dev/null || echo "$last")${NC}"
+            fi
+            echo -e "  ${DIM}Retention: ${TELEGRAM_HISTORY_RETENTION_DAYS:-7} day(s) | Sample interval: ${TELEGRAM_HISTORY_INTERVAL_MIN:-5} min${NC}"
+            ;;
+        prune)
+            check_root
+            if [ ! -d "$dir" ]; then
+                echo -e "  ${DIM}No history to prune.${NC}"
+                return 0
+            fi
+            local cutoff=$(( $(date +%s) - ${TELEGRAM_HISTORY_RETENTION_DAYS:-7} * 86400 ))
+            local f tmp
+            for f in "$dir/global.tsv" "$dir/users.tsv"; do
+                [ -f "$f" ] || continue
+                tmp=$(mktemp "$dir/.prune.XXXXXX") || continue
+                chmod 600 "$tmp"
+                if awk -F'|' -v c="$cutoff" '$1 + 0 >= c' "$f" > "$tmp"; then
+                    mv "$tmp" "$f" 2>/dev/null || rm -f "$tmp"
+                else
+                    rm -f "$tmp"
+                fi
+            done
+            echo -e "  ${GREEN}✓${NC} Pruned history to the last ${TELEGRAM_HISTORY_RETENTION_DAYS:-7} day(s)."
+            ;;
+        reset)
+            check_root
+            [ -d "$dir" ] || return 0
+            echo -e "  ${YELLOW}This deletes all recorded traffic history. Reports and the${NC}"
+            echo -e "  ${YELLOW}traffic view will start from empty; secret quotas are unaffected.${NC}"
+            local _c=""
+            read -r -p "  Type 'yes' to confirm: " _c
+            if [ "$_c" != "yes" ]; then
+                echo -e "  ${DIM}Cancelled.${NC}"
+                return 0
+            fi
+            rm -f "$dir/global.tsv" "$dir/users.tsv"
+            echo -e "  ${GREEN}✓${NC} History cleared."
+            ;;
+        *)
+            echo -e "  Usage: mtproxymax telegram history [status|prune|reset]"
+            ;;
+    esac
+}
+
+# Upload a photo from a file on this host. The Bot API only fetches a URL
+# itself, so a locally rendered image has to be sent as multipart — and it is
+# the reason the QR no longer has to be posted to a third party first.
+telegram_send_photo_file() {
+    local file="$1" caption="${2:-}"
     local token="${TELEGRAM_BOT_TOKEN}"
     local chat_id="${TELEGRAM_CHAT_ID}"
     { [ -z "$token" ] || [ -z "$chat_id" ]; } && return 1
+    [ -s "$file" ] || return 1
 
     local label="${TELEGRAM_SERVER_LABEL:-MTProxyMax}"
     [ -n "$caption" ] && caption="[${label}] ${caption}"
@@ -11030,18 +11319,19 @@ telegram_send_photo() {
     _cfg=$(_mktemp) || return 1
     printf 'url = "https://api.telegram.org/bot%s/sendPhoto"\n' "$token" > "$_cfg"
 
-    curl -s --max-time 15 --max-filesize 10485760 -X POST \
+    curl -s --max-time 30 -X POST \
         -K "$_cfg" \
-        --data-urlencode "chat_id=${chat_id}" \
-        --data-urlencode "photo=${photo_url}" \
-        --data-urlencode "caption=${caption}" \
-        --data-urlencode "parse_mode=Markdown" \
+        -F "chat_id=${chat_id}" \
+        -F "photo=@${file}" \
+        --form-string "caption=${caption}" \
+        --form-string "parse_mode=Markdown" \
         >/dev/null 2>&1 || true
     local rc=$?
     rm -f "$_cfg"
     return $rc
 }
 
+
 telegram_get_chat_id() {
     local token="${TELEGRAM_BOT_TOKEN}"
     [ -z "$token" ] && return 1
@@ -11117,11 +11407,19 @@ telegram_notify_proxy_started() {
 
     telegram_send_message "$msg"
 
-    # Send QR for first enabled secret
+    # Send QR for first enabled secret. Rendered here and uploaded as a file;
+    # a remote renderer would be handed the key.
     if [ -n "$_first_secret" ]; then
-        local qr_url
-        qr_url=$(generate_qr_url "https://t.me/proxy?server=${server_ip}&port=${PROXY_PORT}&secret=${_first_secret}")
-        telegram_send_photo "$qr_url" "📱 *MTProxy QR Code* — Scan in Telegram to connect"
+        local _qr_link _qr_file
+        _qr_link="https://t.me/proxy?server=${server_ip}&port=${PROXY_PORT}&secret=${_first_secret}"
+        _qr_file=$(mktemp "${TMPDIR:-/tmp}/mtpx-qr.XXXXXX") || _qr_file=""
+        if [ -n "$_qr_file" ] && _qr_png "$_qr_link" "$_qr_file"; then
+            telegram_send_photo_file "$_qr_file" "📱 *MTProxy QR Code* — Scan in Telegram to connect"
+            rm -f "$_qr_file"
+        else
+            rm -f "$_qr_file" 2>/dev/null
+            telegram_send_message "🔗 [Connect](${_qr_link})\n\n_Install \`qrencode\` for a scannable QR._"
+        fi
     fi
 }
 
@@ -11216,6 +11514,9 @@ telegram_setup_wizard() {
     echo ""
     log_success "Telegram bot configured!"
 
+    # Populate the client-side "/" command menu straight away.
+    telegram_sync_commands &>/dev/null &
+
     # Send test message
     telegram_test_message
 
@@ -11315,6 +11616,7 @@ load_tg_settings() {
                 AD_TAG|GEOBLOCK_MODE|BLOCKLIST_COUNTRIES|AUTO_UPDATE_ENABLED|\
                 TELEGRAM_ENABLED|TELEGRAM_BOT_TOKEN|TELEGRAM_CHAT_ID|\
                 TELEGRAM_INTERVAL|TELEGRAM_SERVER_LABEL|TELEGRAM_ALERTS_ENABLED|\
+                TELEGRAM_HISTORY_ENABLED|TELEGRAM_HISTORY_INTERVAL_MIN|TELEGRAM_HISTORY_RETENTION_DAYS|TELEGRAM_REPORT_DETAIL|\
                 LOCKDOWN_MODE|QOS_LIMIT_MBPS|HAPPY_HOURS_WINDOW|PORT_POOL_PORTS|STEALTH_PRESET|COVER_WATCHDOG_ENABLED|DDNS_ENABLED|DDNS_RECORD_NAME)
                     printf -v "$key" '%s' "$val" ;;
             esac
@@ -11369,44 +11671,296 @@ tg_send_to() {
         --data-urlencode "parse_mode=Markdown" >/dev/null 2>&1
 }
 
-tg_send_photo() {
-    local photo="$1" caption="${2:-}"
-    curl -s --max-time 15 -X POST \
+
+# ── QR codes ────────────────────────────────────────────────────────────────
+#
+# The QR used to be drawn by handing the proxy link to api.qrserver.com and
+# letting Telegram fetch the image from there. The link IS the credential —
+# server, port and secret are the whole key — so that handed a working proxy key
+# to a third party on every /mp_link, every /start and every voucher redemption,
+# including in the customer's own chat. It is rendered on this host now, and the
+# image is uploaded from here; nothing but Telegram sees it.
+#
+# The same reasoning applies to the QR image embedded in the exported HTML
+# sheets, which were built from the same kind of URL.
+
+# Render a QR to a PNG on this host. Non-zero when no renderer is available, in
+# which case the caller must NOT fall back to a remote one.
+_qr_png() {
+    local data="$1" out="$2"
+    [ -n "$data" ] && [ -n "$out" ] || return 1
+    if command -v qrencode &>/dev/null; then
+        qrencode -o "$out" -s 6 -m 2 "$data" 2>/dev/null && [ -s "$out" ] && return 0
+    fi
+    if _tg_have_python && python3 -c 'import qrcode' &>/dev/null; then
+        python3 - "$data" "$out" <<'PYQ' 2>/dev/null && [ -s "$out" ] && return 0
+import sys
+import qrcode
+qrcode.make(sys.argv[1]).save(sys.argv[2])
+PYQ
+    fi
+    rm -f "$out" 2>/dev/null
+    return 1
+}
+
+# Upload a local file as a photo. The token travels in a curl config rather than
+# argv so it never appears in `ps`; -F is required because the image is a file,
+# not a URL the API can fetch itself.
+_tg_send_photo_file() {
+    local chat="$1" file="$2" caption="${3:-}"
+    [ -s "$file" ] || return 1
+    curl -s --max-time 30 -X POST \
         -K <(printf 'url = "https://api.telegram.org/bot%s/sendPhoto"\n' "$TELEGRAM_BOT_TOKEN") \
-        --data-urlencode "chat_id=${TELEGRAM_CHAT_ID}" \
-        --data-urlencode "photo=${photo}" \
-        --data-urlencode "caption=[$(_esc "${TELEGRAM_SERVER_LABEL:-MTProxyMax}")] ${caption}" \
-        --data-urlencode "parse_mode=Markdown" >/dev/null 2>&1
+        -F "chat_id=${chat}" \
+        -F "photo=@${file}" \
+        --form-string "caption=[$(_esc "${TELEGRAM_SERVER_LABEL:-MTProxyMax}")] ${caption}" \
+        --form-string "parse_mode=Markdown" >/dev/null 2>&1
+}
+
+# "https://t.me/proxy?...", the one form of the link that is also a credential.
+_proxy_link() {
+    printf 'https://t.me/proxy?server=%s&port=%s&secret=%s' "$1" "$2" "$3"
+}
+
+_send_qr() {
+    local chat="$1" ip="$2" port="$3" secret="$4" caption="$5"
+    local link png
+    link=$(_proxy_link "$ip" "$port" "$secret")
+    png=$(mktemp "${TMPDIR:-/tmp}/mtpx-qr.XXXXXX") || png=""
+    if [ -n "$png" ] && _qr_png "$link" "$png"; then
+        _tg_send_photo_file "$chat" "$png" "$caption"
+        rm -f "$png" 2>/dev/null
+        return 0
+    fi
+    rm -f "$png" 2>/dev/null
+    # No renderer here. Send the tappable link rather than reaching for a remote
+    # one: the operator gets something usable, and the key stays on this host.
+    tg_send_to "$chat" "🔗 [Connect](${link})\n\n_Install \`qrencode\` (or \`python3-qrcode\`) for a scannable QR._"
+    return 1
 }
 
 # Send QR code image for a proxy secret (no text URL — avoids Telegram bot bans)
 send_proxy_qr() {
     local ip="$1" port="$2" secret="$3" caption="${4:-Scan in Telegram to connect}"
-    local hl="https://t.me/proxy?server=${ip}&port=${port}&secret=${secret}"
-    local el=$(printf '%s' "$hl" | sed 's/&/%26/g;s/?/%3F/g;s/=/%3D/g;s/:/%3A/g;s|/|%2F|g')
-    tg_send_photo "https://api.qrserver.com/v1/create-qr-code/?size=300x300&data=${el}" "$caption"
+    _send_qr "$TELEGRAM_CHAT_ID" "$ip" "$port" "$secret" "$caption"
 }
 
-tg_send_photo_to() {
-    local target_cid="$1" photo="$2" caption="${3:-}"
-    curl -s --max-time 15 -X POST \
-        -K <(printf 'url = "https://api.telegram.org/bot%s/sendPhoto"\n' "$TELEGRAM_BOT_TOKEN") \
-        --data-urlencode "chat_id=${target_cid}" \
-        --data-urlencode "photo=${photo}" \
-        --data-urlencode "caption=[$(_esc "${TELEGRAM_SERVER_LABEL:-MTProxyMax}")] ${caption}" \
-        --data-urlencode "parse_mode=Markdown" >/dev/null 2>&1
-}
 
 send_proxy_qr_to() {
     local target_cid="$1" ip="$2" port="$3" secret="$4" caption="${5:-Scan in Telegram to connect}"
-    local hl="https://t.me/proxy?server=${ip}&port=${port}&secret=${secret}"
-    local el=$(printf '%s' "$hl" | sed 's/&/%26/g;s/?/%3F/g;s/=/%3D/g;s/:/%3A/g;s|/|%2F|g')
-    tg_send_photo_to "$target_cid" "https://api.qrserver.com/v1/create-qr-code/?size=300x300&data=${el}" "$caption"
+    _send_qr "$target_cid" "$ip" "$port" "$secret" "$caption"
 }
 
 # Escape Markdown special chars in labels for Telegram
 _esc() { local t="$1"; t="${t//_/\\_}"; t="${t//\*/\\*}"; t="${t//\`/\\\`}"; echo "$t"; }
 
+# ── Bot API primitives ──────────────────────────────────────────────────────
+# The daemon is emitted from a QUOTED heredoc, so it inherits nothing from the
+# manager — no _mktemp, no log_*. Everything here is self-contained.
+#
+# tg_send()/tg_send_to() are deliberately left untouched: they have ~40 call
+# sites and tg_send also fires webhook_send, so the reply_markup-capable
+# variants below are additive rather than a signature change.
+
+# Single curl chokepoint for Bot API methods. Fields travel as urlencoded form
+# values — reply_markup is just a JSON string in one of them — which needs no
+# Content-Type header and no temp file, and keeps the token out of the process
+# list via -K process substitution.
+_tg_post_method() {
+    local _m="$1"; shift
+    local _f=()
+    while [ $# -gt 0 ]; do _f+=(--data-urlencode "$1"); shift; done
+    curl -s --max-time 15 -X POST \
+        -K <(printf 'url = "https://api.telegram.org/bot%s/%s"\n' "$TELEGRAM_BOT_TOKEN" "$_m") \
+        "${_f[@]}" 2>/dev/null
+}
+
+# The "[label | ip]" prefix every outgoing message carries. Exposed because the
+# chunker has to budget for it — Telegram counts UTF-16 units, and an emoji in
+# the label costs two.
+_tg_header() {
+    local label="${TELEGRAM_SERVER_LABEL:-MTProxyMax}"
+    local _ip; _ip=$(get_cached_ip)
+    if [ -n "$_ip" ]; then printf '[%s | %s] ' "$(_esc "$label")" "$_ip"
+    else printf '[%s] ' "$(_esc "$label")"; fi
+}
+
+# Split a body into pieces that each fit Telegram's 4096-unit cap, emitted with
+# a trailing \x1f after every piece so they can be read back with `read -d`.
+# A fenced block that straddles a split is closed in the outgoing piece and
+# reopened in the next, otherwise the monospace alignment breaks.
+_tg_chunk_text() {
+    local budget="$1" body="$2"
+    local _sep=$'\x1f'
+    local chunk="" line fence=0 out=""
+    while IFS= read -r line || [ -n "$line" ]; do
+        if [ -n "$chunk" ] && [ $(( ${#chunk} + ${#line} + 1 )) -gt "$budget" ]; then
+            if [ "$fence" -eq 1 ]; then
+                out="${out}${chunk}"$'\n''```'"${_sep}"
+                chunk='```'
+            else
+                out="${out}${chunk}${_sep}"
+                chunk=""
+            fi
+        fi
+        if [ -z "$chunk" ]; then chunk="$line"; else chunk="${chunk}"$'\n'"${line}"; fi
+        case "$line" in
+            '```'*) if [ "$fence" -eq 0 ]; then fence=1; else fence=0; fi ;;
+        esac
+    done <<< "$body"
+    printf '%s%s' "${out}${chunk}" "$_sep"
+}
+
+# Send a text to a chat, chunked if needed, with an optional keyboard on the
+# final piece. A 400 from Telegram is retried once without parse_mode: a
+# malformed Markdown entity should cost the formatting, not the whole message.
+_tg_send_pieces() {
+    local _chat="$1" _hdr="$2" _body="$3" _markup="${4:-}"
+    local _budget=$(( 4096 - ${#_hdr} - 32 ))
+    [ "$_budget" -lt 256 ] && _budget=256
+    local -a _parts=()
+    local _piece=""
+    while IFS= read -r -d $'\x1f' _piece || [ -n "$_piece" ]; do
+        [ -z "$_piece" ] && continue
+        _parts+=("$_piece")
+    done < <(_tg_chunk_text "$_budget" "$_body")
+    local _n=${#_parts[@]} _i=0 _resp
+    local _last_out=""
+    for _piece in "${_parts[@]}"; do
+        _i=$(( _i + 1 ))
+        local _args=( "chat_id=${_chat}" "text=${_hdr}${_piece}" "parse_mode=Markdown" )
+        if [ "$_i" -eq "$_n" ] && [ -n "$_markup" ]; then
+            _args+=( "reply_markup=${_markup}" )
+        fi
+        _resp=$(_tg_post_method sendMessage "${_args[@]}")
+        _last_out="$_resp"
+        case "$_resp" in
+            *'"ok":true'*) : ;;
+            *'"error_code":400'*)
+                local _plain=( "chat_id=${_chat}" "text=${_hdr}${_piece}" )
+                if [ "$_i" -eq "$_n" ] && [ -n "$_markup" ]; then
+                    _plain+=( "reply_markup=${_markup}" )
+                fi
+                _last_out=$(_tg_post_method sendMessage "${_plain[@]}")
+                ;;
+        esac
+    done
+    printf '%s' "$_last_out"
+}
+
+# message_id of the last send, or empty.
+_tg_msg_id() { printf '%s' "$1" | grep -o '"message_id":[0-9]*' | head -1 | grep -o '[0-9]*'; }
+
+tg_send_kb() {
+    local _text="$1" _markup="${2:-}"
+    local _hdr; _hdr=$(_tg_header)
+    local _body; _body=$(printf '%b' "$_text")
+    _tg_send_pieces "${TELEGRAM_CHAT_ID}" "$_hdr" "$_body" "$_markup" >/dev/null
+    webhook_send "$_text" 2>/dev/null || true
+}
+
+tg_send_to_kb() {
+    local _chat="$1" _text="$2" _markup="${3:-}"
+    local _body; _body=$(printf '%b' "$_text")
+    _tg_send_pieces "$_chat" "" "$_body" "$_markup" >/dev/null
+}
+
+# Replace a message's text and keyboard in place. Telegram answers 400
+# "message is not modified" when the text AND markup are unchanged, which
+# happens on every tap of the page the user is already on — treat it as success.
+tg_edit() {
+    local _chat="$1" _mid="$2" _text="$3" _markup="${4:-}"
+    [ -n "$_mid" ] || return 0
+    local _args=( "chat_id=${_chat}" "message_id=${_mid}" "text=${_text}" "parse_mode=Markdown" )
+    [ -n "$_markup" ] && _args+=( "reply_markup=${_markup}" )
+    _tg_post_method editMessageText "${_args[@]}" >/dev/null
+}
+
+# Swap only the keyboard, leaving the body alone. Cheaper than a full edit and
+# it sidesteps "message is not modified" for a pure page flip.
+tg_edit_markup() {
+    local _chat="$1" _mid="$2" _markup="$3"
+    [ -n "$_mid" ] || return 0
+    _tg_post_method editMessageReplyMarkup \
+        "chat_id=${_chat}" "message_id=${_mid}" "reply_markup=${_markup}" >/dev/null
+}
+
+# Acknowledge a callback. The client spins until this arrives, so it must be
+# called on EVERY path including denial and error.
+tg_answer_cb() {
+    local _id="$1" _toast="${2:-}" _alert="${3:-false}"
+    [ -n "$_id" ] || return 0
+    local _args=( "callback_query_id=${_id}" )
+    [ -n "$_toast" ] && _args+=( "text=${_toast}" )
+    [ "$_alert" = "true" ] && _args+=( "show_alert=true" )
+    _tg_post_method answerCallbackQuery "${_args[@]}" >/dev/null
+}
+
+# ── Inline-keyboard callback_data codec ─────────────────────────────────────
+# Grammar: <ns>[:<action>[:<target>[:<page>]]], trailing empty fields trimmed.
+# All ASCII, so byte length equals character length. Fields 3 and 4 are purely
+# positional — their meaning depends on the namespace (for "u:l" field 3 is a
+# page; for "u:s" it is a label and field 4 the page). The dispatcher assigns
+# meaning; the codec only guarantees shape.
+#
+# The Bot API caps callback_data at 64 bytes, and a single over-long payload
+# makes Telegram reject the ENTIRE reply_markup with a 400 — the whole message
+# is lost, not just that one button. So _cb_enc refuses rather than truncating:
+# a truncated payload would decode into a different, still-valid target.
+_CB_MAX=64
+
+# Labels are the only caller-supplied field in a payload, and a ':' inside one
+# would shift the positional fields — turning "u:s:ali:ce" into a 4-field
+# payload that decodes to a different target. Refusing anything outside the
+# secrets.conf charset makes field injection structurally impossible.
+_cb_label_ok() {
+    [[ "$1" =~ ^[a-zA-Z0-9_-]{1,32}$ ]]
+}
+
+# _cb_enc <ns> <action> <target> <page> -> payload on stdout, non-zero if the
+# result would be malformed or over-long.
+_cb_enc() {
+    local ns="$1" act="$2" tgt="$3" page="$4" out
+    [[ "$ns" =~ ^[a-z]{1,2}$ ]] || return 1
+    if [ -n "$act" ]  && ! _cb_label_ok "$act";  then return 1; fi
+    if [ -n "$tgt" ]  && ! _cb_label_ok "$tgt";  then return 1; fi
+    if [ -n "$page" ] && ! _cb_label_ok "$page"; then return 1; fi
+    # An action namespace is meaningless without a target, so require one here
+    # and the dispatcher can then trust that any a:/c: payload it sees names a
+    # label. (It still re-validates that the label exists.)
+    case "$ns" in
+        a|c) [ -n "$tgt" ] || return 1 ;;
+    esac
+    out="$ns"
+    [ -n "$act" ]  && out="${out}:${act}"
+    [ -n "$tgt" ]  && out="${out}:${tgt}"
+    [ -n "$page" ] && out="${out}:${page}"
+    [ "${#out}" -le "${_CB_MAX:-64}" ] || return 1
+    printf '%s' "$out"
+}
+
+# _cb_dec <payload> -> sets _CB_NS _CB_ACT _CB_TGT _CB_PAGE; non-zero if the
+# payload is malformed or over-long.
+#
+# Sets globals rather than printing to stdout on purpose: rendering a menu with
+# 30 buttons would otherwise fork 30 subshells. Callers must therefore never
+# write `x=$(_cb_dec ...)` — the assignments would be lost.
+_cb_dec() {
+    local p="$1"
+    _CB_NS=""; _CB_ACT=""; _CB_TGT=""; _CB_PAGE=""
+    [ -n "$p" ] || return 1
+    [ "${#p}" -le "${_CB_MAX:-64}" ] || return 1
+    [[ "$p" =~ ^[a-z]{1,2}(:[A-Za-z0-9_-]{1,32}){0,3}$ ]] || return 1
+    local IFS=':' _f
+    local -a _fields
+    read -r -a _fields <<< "$p"
+    _CB_NS="${_fields[0]}"
+    [ "${#_fields[@]}" -gt 1 ] && _CB_ACT="${_fields[1]}"
+    [ "${#_fields[@]}" -gt 2 ] && _CB_TGT="${_fields[2]}"
+    [ "${#_fields[@]}" -gt 3 ] && _CB_PAGE="${_fields[3]}"
+    return 0
+}
+
 is_running() {
     is_proxy_running
 }
@@ -11594,9 +12148,30 @@ update_traffic() {
     [ "$delta_out" -lt 0 ] 2>/dev/null && delta_out=$cur_out
     _cum_in=$((_cum_in + delta_in))
     _cum_out=$((_cum_out + delta_out))
+    # Accumulate the same corrected delta into the history bucket. Doing it
+    # here rather than re-deriving it later means the restart handling above is
+    # inherited by construction instead of duplicated.
+    _bucket_in=$(( ${_bucket_in:-0} + delta_in ))
+    _bucket_out=$(( ${_bucket_out:-0} + delta_out ))
     _prev_total_in=$cur_in
     _prev_total_out=$cur_out
 
+    # Connections and engine uptime for the sample row. A DECREASE in uptime
+    # means the engine restarted, which is recorded as a marker so a later
+    # window spanning the gap can explain itself.
+    local _extra _conns _up
+    _extra=$(printf '%s' "$_metrics" | awk '
+        /^telemt_user_connections_current\{/ { c+=$NF }
+        /^telemt_uptime_seconds /             { u=$NF }
+        END { printf "%.0f %.0f", c+0, u+0 }')
+    read -r _conns _up <<< "$_extra"
+    _bucket_conns="${_conns:-0}"
+    if [ "${_prev_uptime:-0}" -gt 0 ] 2>/dev/null && [ "${_up:-0}" -gt 0 ] 2>/dev/null && \
+       [ "${_up:-0}" -lt "${_prev_uptime:-0}" ] 2>/dev/null; then
+        _bucket_marker="R"
+    fi
+    _prev_uptime="${_up:-0}"
+
     # Per-user delta tracking — single awk pass for all users into associative array
     declare -A _parsed_ui=() _parsed_uo=()
     if [ -n "$_metrics" ]; then
@@ -11621,6 +12196,8 @@ update_traffic() {
         [ "$dou" -lt 0 ] 2>/dev/null && dou=$uo
         _cum_user_in["$label"]=$(( ${_cum_user_in["$label"]:-0} + du ))
         _cum_user_out["$label"]=$(( ${_cum_user_out["$label"]:-0} + dou ))
+        _bucket_user_in["$label"]=$(( ${_bucket_user_in["$label"]:-0} + du ))
+        _bucket_user_out["$label"]=$(( ${_bucket_user_out["$label"]:-0} + dou ))
         _prev_user_in["$label"]=$ui
         _prev_user_out["$label"]=$uo
     done < "$SECRETS_FILE"
@@ -11631,6 +12208,206 @@ update_traffic() {
 
 get_cum_user_traffic() { echo "${_cum_user_in[$1]:-0} ${_cum_user_out[$1]:-0}"; }
 
+# `command -v python3` is not sufficient: the Windows Store ships a python3.exe
+# alias that sits on PATH but fails the moment it runs, and some distros ship a
+# stub. Probe by actually executing it.
+_tg_have_python() {
+    command -v python3 &>/dev/null || return 1
+    python3 -c '' &>/dev/null 2>&1
+}
+
+# Both extractors emit the same tab-separated 6-field records:
+#
+#   <update_id>\t<kind>\t<chat_id>\t<message_id>\t<callback_id>\t<payload>
+#
+# kind is "msg" or "cb"; for "msg" the callback id is "-". A record is emitted
+# for EVERY element of `result`, even one carrying no message at all, because
+# the consumer advances the offset per record — skipping one would make
+# Telegram redeliver it forever.
+_tg_parse_updates_py() {
+    printf '%s' "$1" | python3 -c '
+import json,sys
+
+# Pin LF. Python in text mode translates "\n" to os.linesep, so on Windows the
+# records would come out CRLF and the trailing "\r" would end up inside the
+# command payload. The awk extractor always emits LF; this keeps them identical
+# on every platform.
+try:
+    sys.stdout.reconfigure(newline="\n")
+except Exception:
+    pass
+
+def clean(v):
+    if not isinstance(v, str):
+        v = "" if v is None else str(v)
+    # only the first line is the command
+    v = v.split("\n")[0].replace("\t", " ").replace("\r", "")
+    return v[:512]
+
+try:
+    data = json.load(sys.stdin)
+except Exception:
+    sys.exit(0)
+if not isinstance(data, dict):
+    sys.exit(0)
+for r in data.get("result", []) or []:
+    if not isinstance(r, dict):
+        continue
+    uid = r.get("update_id")
+    if uid is None:
+        continue
+    cq = r.get("callback_query")
+    if isinstance(cq, dict):
+        m = cq.get("message")
+        m = m if isinstance(m, dict) else {}
+        ch = m.get("chat")
+        ch = ch if isinstance(ch, dict) else {}
+        print("%s\tcb\t%s\t%s\t%s\t%s" % (uid, ch.get("id", ""), m.get("message_id", ""),
+                                          cq.get("id", ""), clean(cq.get("data", ""))))
+    else:
+        m = r.get("message")
+        m = m if isinstance(m, dict) else {}
+        ch = m.get("chat")
+        ch = ch if isinstance(ch, dict) else {}
+        print("%s\tmsg\t%s\t%s\t-\t%s" % (uid, ch.get("id", ""), m.get("message_id", ""),
+                                          clean(m.get("text", ""))))
+' 2>/dev/null
+}
+
+# Dependency-free fallback, used on hosts without a working python3 — notably
+# Alpine, which this project supports via OpenRC.
+#
+# This MUST be a character scanner rather than a regex pass: a regex cannot tell
+# whether a `}` or `"` sits inside a string literal, and a command's text can
+# contain both ("tricky \"chat\":{\"id\":999}"). The scanner tracks string and
+# escape state and object/array depth, so embedded JSON in a text field is inert.
+#
+# One documented divergence from the python path: \uXXXX escapes are left as
+# literal text rather than decoded. Command text is ASCII in practice, and a
+# mis-decoded command simply matches nothing.
+_tg_parse_updates_awk() {
+    awk '
+    function reset() {
+        e_upd=""; e_chat=""; e_msgid=""; e_text=""; e_cbid=""; e_cbdata=""; e_cb=0
+    }
+    function scalar(k, parent, v) {
+        if (!inel) return
+        if      (k == "update_id"  && parent == "")               e_upd    = v
+        else if (k == "message_id" && parent == "message")        e_msgid  = v
+        else if (k == "id"         && parent == "chat")           e_chat   = v
+        else if (k == "text"       && parent == "message")        e_text   = v
+        else if (k == "id"         && parent == "callback_query") e_cbid   = v
+        else if (k == "data"       && parent == "callback_query") e_cbdata = v
+    }
+    function flush(   kind, cbid, pay, p) {
+        if (e_upd == "") return
+        if (e_cb) { kind = "cb";  cbid = e_cbid; pay = e_cbdata }
+        else      { kind = "msg"; cbid = "-";    pay = e_text }
+        p = index(pay, "\n"); if (p > 0) pay = substr(pay, 1, p - 1)
+        gsub(/\r/, "", pay)
+        if (length(pay) > 512) pay = substr(pay, 1, 512)
+        printf "%s\t%s\t%s\t%s\t%s\t%s\n", e_upd, kind, e_chat, e_msgid, cbid, pay
+    }
+    { if (NR == 1) s = $0; else s = s "\n" $0; next }
+    END {
+        n = length(s)
+        depth = 0; instr = 0; esc = 0; intok = 0
+        arrdepth = -1; inel = 0; want_result = 0
+        curkey = ""; buf = ""; kstk[0] = ""
+        reset()
+        for (i = 1; i <= n; i++) {
+            c = substr(s, i, 1)
+            if (instr) {
+                if (esc) {
+                    esc = 0
+                    if      (c == "n") buf = buf "\n"
+                    else if (c == "t") buf = buf "\t"
+                    else if (c == "r") buf = buf "\r"
+                    else if (c == "b") buf = buf "\b"
+                    else if (c == "f") buf = buf "\f"
+                    else if (c == "u") buf = buf "\\u"
+                    else buf = buf c
+                    continue
+                }
+                if (c == "\\") { esc = 1; continue }
+                if (c == "\"") {
+                    instr = 0
+                    j = i + 1
+                    while (j <= n) {
+                        d = substr(s, j, 1)
+                        if (d == " " || d == "\t" || d == "\n" || d == "\r") { j++; continue }
+                        break
+                    }
+                    if (j <= n && substr(s, j, 1) == ":") {
+                        curkey = buf
+                        if (curkey == "result" && depth == 1) want_result = 1
+                    } else {
+                        scalar(curkey, kstk[depth], buf)
+                    }
+                    continue
+                }
+                buf = buf c
+                continue
+            }
+            if (intok) {
+                if (c == "," || c == "}" || c == "]" || c == " " || c == "\t" || c == "\n" || c == "\r") {
+                    intok = 0
+                    scalar(curkey, kstk[depth], buf)
+                    buf = ""
+                    i--
+                    continue
+                }
+                buf = buf c
+                continue
+            }
+            if (c == "\"") { instr = 1; buf = ""; continue }
+            if (c == "{" || c == "[") {
+                if (c == "[" && want_result) { arrdepth = depth + 1; want_result = 0 }
+                depth++
+                if (c == "{" && inel && curkey == "callback_query") e_cb = 1
+                if (c == "{" && arrdepth >= 0 && depth == arrdepth + 1) {
+                    kstk[depth] = ""
+                    inel = 1
+                    reset()
+                } else {
+                    kstk[depth] = curkey
+                }
+                continue
+            }
+            if (c == "}" || c == "]") {
+                if (c == "}" && inel && depth == arrdepth + 1) { flush(); inel = 0 }
+                depth--
+                continue
+            }
+            if (c == ":" || c == "," || c == " " || c == "\t" || c == "\n" || c == "\r") continue
+            intok = 1; buf = c
+        }
+    }
+    ' <<< "$1"
+}
+
+# Read one batch of records and dispatch. Process substitution, deliberately not
+# a pipe: a pipeline would run the dispatchers in a subshell and silently
+# discard every global they set.
+_consume_updates() {
+    local _uid _kind _cid _mid _cbid _pay
+    while IFS=$'\t' read -r _uid _kind _cid _mid _cbid _pay || [ -n "$_uid" ]; do
+        [ -z "$_uid" ] && continue
+        [[ "$_uid" =~ ^[0-9]+$ ]] || continue
+        # Belt and braces: the extractors already strip CR from the payload and
+        # pin LF terminators, but a stray one here would silently corrupt every
+        # command by appending a character to it.
+        _pay="${_pay%$'\r'}"
+        # Advance per consumed record, not per batch: a parser failure midway
+        # then redelivers the unconsumed tail instead of losing it.
+        printf '%s\n' "$(( _uid + 1 ))" > "$OFFSET_FILE"
+        case "$_kind" in
+            msg) _process_cmd "$_uid" "$_cid" "$_pay" ;;
+            cb)  _process_callback "$_cid" "$_mid" "$_cbid" "$_pay" ;;
+        esac
+    done < <(if _tg_have_python; then _tg_parse_updates_py "$1"; else _tg_parse_updates_awk "$1"; fi)
+}
+
 process_commands() {
     local offset=$(cat "$OFFSET_FILE" 2>/dev/null || echo "0")
     [[ "$offset" =~ ^[0-9]+$ ]] || offset="0"
@@ -11639,38 +12416,7 @@ process_commands() {
         -K <(printf 'url = "https://api.telegram.org/bot%s/getUpdates?offset=%s&timeout=25"\n' "$TELEGRAM_BOT_TOKEN" "$offset") \
         2>/dev/null) || true
     [ -z "$updates" ] && return
-
-    if command -v python3 &>/dev/null; then
-        echo "$updates" | python3 -c "
-import json,sys
-try:
-    data=json.load(sys.stdin)
-    for r in data.get('result',[]):
-        uid=r['update_id']
-        txt=r.get('message',{}).get('text','').split('\n')[0][:200]
-        cid=r.get('message',{}).get('chat',{}).get('id','')
-        print(f'{uid}\t{cid}\t{txt}')
-except Exception:
-    pass
-" 2>/dev/null | while IFS=$'\t' read -r _uid _cid _txt || [ -n "$_uid" ]; do
-            [ -z "$_uid" ] && continue
-            _process_cmd "$_uid" "$_cid" "$_txt"
-        done
-    else
-        # Fallback: grep-based parsing (no python)
-        local _new_offset
-        _new_offset=$(echo "$updates" | grep -oE '"update_id"\s*:\s*[0-9]+' | tail -1 | grep -oE '[0-9]+')
-        if [ -n "$_new_offset" ]; then
-            echo "$((_new_offset + 1))" > "$OFFSET_FILE"
-        fi
-        local _text _cid
-        _text=$(echo "$updates" | grep -oE '"text"\s*:\s*"[^"]*"' | tail -1 | sed 's/.*"text"\s*:\s*"//;s/"$//')
-        _cid=$(echo "$updates" | grep -oE '"chat"\s*:\s*\{[^}]*"id"\s*:\s*-?[0-9]+' | tail -1 | grep -oE -- '-?[0-9]+$')
-        [ -n "$_text" ] && [ -n "$_cid" ] && {
-            _new_offset=${_new_offset:-0}
-            _process_cmd "$_new_offset" "$_cid" "$_text"
-        }
-    fi
+    _consume_updates "$updates"
 }
 
 _check_tg_role() {
@@ -11697,8 +12443,12 @@ _tg_security_log() {
 }
 
 _process_cmd() {
+    # update_id is accepted but no longer used for the offset: _consume_updates
+    # owns that, so it advances once per consumed record rather than once per
+    # dispatched command. Kept in the signature because callers and tests pass
+    # it positionally.
     local update_id="$1" chat_id="$2" text="$3"
-    echo "$((update_id + 1))" > "$OFFSET_FILE"
+    : "${update_id:=0}"
 
     local role
     role=$(_check_tg_role "$chat_id")
@@ -11708,10 +12458,17 @@ _process_cmd() {
         grep -q "^${chat_id}$" "${INSTALL_DIR}/bot_users.txt" 2>/dev/null || echo "$chat_id" >> "${INSTALL_DIR}/bot_users.txt" 2>/dev/null || true
     fi
 
+    # An armed prompt owns the next plain message from this chat. It runs before
+    # the command table so a value can never be mistaken for a command, and it
+    # deliberately sits AFTER the role lookup — the answer still executes as the
+    # sender, never as whoever armed the prompt.
+    _tg_pending_try "$chat_id" "$text" && return
+
     # Public user or unauthenticated commands
     case "$text" in
         /start|/start@*)
-            tg_send_to "$chat_id" "🛡️ *Welcome to MTProxyMax Self-Service Portal (${VERSION})*\n\n👋 Hello! You can use this bot to check your proxy status, data limits, and connection links without admin assistance.\n\n📱 *Public Commands Available:*\n  /my_status <label> — Check your data quota & expiration\n  /redeem <code> [label] — Redeem a gift code / voucher\n  /voucher <code> [label] — Alias for /redeem\n  /support <message> — Send a support request to server admins"
+            tg_send_to_kb "$chat_id" "🛡️ *Welcome to MTProxyMax Self-Service Portal (${VERSION})*\n\n👋 Hello! You can use this bot to check your proxy status, data limits, and connection links without admin assistance.\n\n📱 *Public Commands Available:*\n  /my_status <label> — Check your data quota & expiration\n  /redeem <code> [label] — Redeem a gift code / voucher\n  /voucher <code> [label] — Alias for /redeem\n  /support <message> — Send a support request to server admins" \
+                "$(_tg_button_bar "$chat_id")"
             return
             ;;
         /my_status\ *|/my_status@*\ *)
@@ -11815,16 +12572,30 @@ _process_cmd() {
                     local cnt=$(echo "$text" | awk '{print $3}')
                     local qta=$(echo "$text" | awk '{print $4}')
                     local dys=$(echo "$text" | awk '{print $5}')
-                    "${INSTALL_DIR}/mtproxymax" voucher create "${cnt:-1}" "${qta:-10G}" "${dys:-30}" &>/dev/null
-                    local vout=$("${INSTALL_DIR}/mtproxymax" voucher list active | tail -n +3 | head -n "${cnt:-1}")
-                    tg_send "🎟 *Generated Vouchers*\n\`\`\`\n${vout}\n\`\`\`"
+                    [[ "$cnt" =~ ^[0-9]+$ ]] && [ "$cnt" -ge 1 ] && [ "$cnt" -le 100 ] || cnt=1
+                    # Snapshot the active count first: the vault is append-only,
+                    # so the rows past that index are exactly the new ones. The
+                    # previous version read the list back and did `tail -n +3`,
+                    # which silently showed the wrong rows.
+                    local _before; _before=$(_tg_voucher_count)
+                    "${INSTALL_DIR}/mtproxymax" voucher create "$cnt" "${qta:-10G}" "${dys:-30}" &>/dev/null
+                    local vbody; vbody=$(_tg_voucher_lines "$_before")
+                    if [ -n "$vbody" ]; then
+                        tg_send "🎟 *Generated ${cnt} voucher(s)*${vbody}"
+                    else
+                        tg_send "❌ No vouchers were created — check the server log."
+                    fi
                     ;;
                 list)
-                    local vout=$("${INSTALL_DIR}/mtproxymax" voucher list active | head -n 25)
-                    tg_send "📋 *Active Vouchers*\n\`\`\`\n${vout}\n\`\`\`"
+                    local vbody; vbody=$(_tg_voucher_lines)
+                    if [ -n "$vbody" ]; then
+                        tg_send "📋 *Active Vouchers*${vbody}"
+                    else
+                        tg_send "📋 *Active Vouchers*\n\n_None yet._"
+                    fi
                     ;;
                 *)
-                    tg_send "🎟 *Voucher Engine*\n\nUsage:\n\`/mp_voucher create <count> <quota> <days>\`\n\`/mp_voucher list\`"
+                    tg_send "🎟 *Voucher Engine*\n\n• /mp\\_voucher create <count> <quota> <days>\n• /mp\\_voucher list"
                     ;;
             esac
             ;;
@@ -11836,7 +12607,8 @@ _process_cmd() {
             fi
             local _si _so _sc; read -r _si _so _sc <<< "$(get_stats)"
             local up=$(get_uptime)
-            tg_send "📱 *MTProxy Status*\n\n🟢 Status: Running\n⏱ Uptime: $(format_duration $up)\n👥 Connections: ${_sc}\n📊 Traffic: ↓ $(format_bytes ${_cum_out:-0}) ↑ $(format_bytes ${_cum_in:-0})\n🔗 Port: ${PROXY_PORT} | Domain: ${PROXY_DOMAIN}"
+            tg_send_kb "📱 *MTProxy Status*\n\n🟢 Status: Running\n⏱ Uptime: $(format_duration $up)\n👥 Connections: ${_sc}\n📊 Traffic: ↓ $(format_bytes ${_cum_out:-0}) ↑ $(format_bytes ${_cum_in:-0})\n🔗 Port: ${PROXY_PORT} | Domain: ${PROXY_DOMAIN}" \
+                "$(_tg_button_bar "$chat_id")"
             ;;
         /mp_secrets|/mp_secrets@*)
             load_tg_settings
@@ -11863,7 +12635,7 @@ _process_cmd() {
                 local cui=${_cum_user_in["$label"]:-0} cuo=${_cum_user_out["$label"]:-0}
                 msg+="${icon} *$(_esc "$label")* — ${uc} conn | ↓$(format_bytes $cuo) ↑$(format_bytes $cui)\n"
             done < "$SECRETS_FILE"
-            tg_send "$msg"
+            tg_send_kb "$msg" "$(_tg_button_bar "$chat_id")"
             ;;
         /mp_link|/mp_link@*)
             load_tg_settings
@@ -11977,10 +12749,20 @@ _process_cmd() {
             ;;
         /mp_health|/mp_health@*)
             local health_out
-            health_out=$("${INSTALL_DIR}/mtproxymax" health 2>&1 | sed 's/\x1b\[[0-9;]*m//g' | head -20) || true
-            local status_icon="🟢"
-            echo "$health_out" | grep -qi "fail\|error\|down" && status_icon="🔴"
-            tg_send "${status_icon} *Health Check*\n\n\`\`\`\n${health_out}\n\`\`\`"
+            health_out=$("${INSTALL_DIR}/mtproxymax" health 2>&1 | sed 's/\x1b\[[0-9;]*m//g' | head -40) || true
+            local hbody
+            hbody=$(_tg_kv_lines <<< "$health_out")
+            if [ -z "$hbody" ]; then
+                # The check output is key/value today. If that ever changes, fall
+                # back to the raw lines rather than an empty reply — a failed
+                # parse must not read as "everything is fine".
+                hbody=$(while IFS= read -r _l; do
+                            [ -z "$_l" ] && continue
+                            printf '\n• %s' "$(_esc "$_l")"
+                        done <<< "$(printf '%s' "$health_out" | head -15)")
+                [ -z "$hbody" ] && hbody=$'\n⚠️ No output from the health check.'
+            fi
+            tg_send_kb "🩺 *Health Check*${hbody}" "$(_tg_button_bar "$chat_id")"
             ;;
         /mp_traffic|/mp_traffic@*)
             load_tg_settings
@@ -11996,7 +12778,7 @@ _process_cmd() {
                 local cuo; cuo=$(echo "$cum_u" | awk '{print $2}')
                 msg+="👤 *$(_esc "$label")*: ↓ $(format_bytes $cuo) ↑ $(format_bytes $cui)\n"
             done < "$SECRETS_FILE"
-            tg_send "$msg"
+            tg_send_kb "$msg" "$(_tg_button_bar "$chat_id")"
             ;;
         /mp_update|/mp_update@*)
             [ "$role" != "superadmin" ] && { tg_send "⛔ Permission denied: superadmin required."; return; }
@@ -12004,7 +12786,12 @@ _process_cmd() {
             local update_out
             update_out=$("${INSTALL_DIR}/mtproxymax" update </dev/null 2>&1 | sed 's/\x1b\[[0-9;]*m//g' | tail -5)
             if [ -n "$update_out" ]; then
-                tg_send "📋 Update check:\n\`\`\`\n${update_out}\n\`\`\`"
+                local ubody=""
+                while IFS= read -r _l; do
+                    [ -z "$_l" ] && continue
+                    ubody+="\n• $(_esc "$_l")"
+                done <<< "$update_out"
+                tg_send "📋 *Update check*${ubody}"
             else
                 tg_send "✅ Script is up to date"
             fi
@@ -12032,18 +12819,63 @@ _process_cmd() {
             local sl_ips=$(echo "$args" | awk '{print $3}')
             local sl_quota=$(echo "$args" | awk '{print $4}')
             local sl_exp=$(echo "$args" | awk '{print $5}')
-            [ -z "$sl_label" ] && tg_send "❌ Usage: /mp\\_setlimit <label> <conns> <ips> <quota> [expires]\nExample: /mp\\_setlimit alice 100 5 5G 2026-12-31" && return
+            [ -z "$sl_label" ] && tg_send "❌ Usage: /mp\\_setlimit <label> <conns> <ips> <quota> [expires]\nExample: /mp\\_setlimit alice 100 5 5G 2026-12-31\n_Leave a field out to keep it as it is._" && return
             [[ "$sl_label" =~ ^[a-zA-Z0-9_-]+$ ]] || { tg_send "❌ Invalid label"; return; }
-            if "${INSTALL_DIR}/mtproxymax" secret setlimits "$sl_label" "${sl_conns:-0}" "${sl_ips:-0}" "${sl_quota:-0}" "${sl_exp:-}" &>/dev/null; then
-                tg_send "✅ Limits updated for *$(_esc "$sl_label")*\nConns: ${sl_conns:-0} | IPs: ${sl_ips:-0} | Quota: ${sl_quota:-0}"
+
+            # Only the fields actually given are written. `secret setlimits`
+            # cannot express that: it reads an empty argument as 0, and
+            # secret_set_limits reads 0 as UNLIMITED — so `/mp_setlimit alice
+            # 100` used to clear alice's IP cap and quota as a side effect. The
+            # per-field `secret setlimit` verb touches one field and no other.
+            local -a _sl_changes=() _sl_flags
+            [ -n "$sl_conns" ] && _sl_changes+=("conns:$sl_conns")
+            [ -n "$sl_ips" ]   && _sl_changes+=("ips:$sl_ips")
+            [ -n "$sl_quota" ] && _sl_changes+=("quota:$sl_quota")
+            [ -n "$sl_exp" ]   && _sl_changes+=("expires:$sl_exp")
+            if [ "${#_sl_changes[@]}" -eq 0 ]; then
+                tg_send "❌ Nothing to change — give at least one of conns, ips, quota or expires."
+                return
+            fi
+
+            local _ok=1 _i _n=${#_sl_changes[@]}
+            for (( _i = 0; _i < _n; _i++ )); do
+                # Every field but the last is applied without a reload, so a
+                # multi-field change costs one engine sync rather than four.
+                _sl_flags=()
+                [ $(( _i + 1 )) -lt "$_n" ] && _sl_flags=(--no-restart)
+                "${INSTALL_DIR}/mtproxymax" secret setlimit "$sl_label" \
+                    "${_sl_changes[$_i]%%:*}" "${_sl_changes[$_i]#*:}" "${_sl_flags[@]}" &>/dev/null || _ok=0
+            done
+            if [ "$_ok" -eq 1 ]; then
+                local _shown="" _c
+                for _c in "${_sl_changes[@]}"; do _shown+="${_shown:+ · }${_c/:/ = }"; done
+                tg_send "✅ Limits updated for *$(_esc "$sl_label")*\n${_shown}"
             else
-                tg_send "❌ Failed to set limits for *$(_esc "$sl_label")* — check label exists"
+                tg_send "❌ Failed to set limits for *$(_esc "$sl_label")* — check the value and that the label exists"
             fi
             ;;
         /mp_fleet|/mp_fleet@*)
             local fleet_out; fleet_out=$("${INSTALL_DIR}/mtproxymax" fleet status 2>/dev/null | sed 's/\x1b\[[0-9;]*m//g')
-            [ -z "$fleet_out" ] && fleet_out="No multi-server fleet telemetry collected yet."
-            tg_send "🌐 *Global Federation Fleet Summary*\n\`\`\`\n${fleet_out}\n\`\`\`"
+            if [ -z "$fleet_out" ]; then
+                tg_send "🌐 *Fleet*\n\n_No multi-server fleet telemetry collected yet._"
+                return
+            fi
+            # One block per node. The CLI aligns this with printf padding, which
+            # only reads as columns inside a fence; per-node lines carry the same
+            # data and survive a proportional font.
+            local _f _msg="🌐 *Fleet*" _n=0 _h _ip _users _traffic _load
+            while IFS= read -r _f; do
+                case "$_f" in ""|HOSTNAME*|*"---"*) continue ;; esac
+                read -r _h _ip _users _traffic _load _ <<< "$_f"
+                [ -z "$_h" ] && continue
+                _msg+="\n🟢 *$(_esc "$_h")*"
+                [ -n "$_ip" ] && _msg+=" — \`$(_esc "$_ip")\`"
+                [ -n "$_users" ] && _msg+=" · 👥 ${_users}"
+                [ -n "$_traffic" ] && _msg+=" · 📊 ${_traffic}"
+                _n=$(( _n + 1 ))
+            done <<< "$fleet_out"
+            [ "$_n" -eq 0 ] && _msg+="\n\n_No nodes reported._"
+            tg_send "$_msg"
             ;;
         /mp_upstreams|/mp_upstreams@*)
             load_tg_settings
@@ -12083,7 +12915,7 @@ _process_cmd() {
                 *)
                     load_tg_settings
                     local st="🟢 NORMAL"; [ "${LOCKDOWN_MODE:-false}" = "true" ] && st="🔴 LOCKDOWN ACTIVE"
-                    tg_send "🔒 *Emergency Lockdown Mode*: ${st}\n\nUsage:\n\`/mp_lockdown on\` — Activate Emergency Shield\n\`/mp_lockdown off\` — Return to Normal"
+                    tg_send "🔒 *Emergency Lockdown Mode*: ${st}\n\n• /mp\\_lockdown on — Activate Emergency Shield\n• /mp\\_lockdown off — Return to Normal"
                     ;;
             esac
             ;;
@@ -12133,36 +12965,2097 @@ _process_cmd() {
             tg_send "📢 Broadcast dispatched to all users."
             ;;
         /mp_help|/mp_help@*)
-            tg_send "📋 *MTProxyMax Commands (${VERSION})*\n\n*Public Self-Service:*\n/start — Self-service onboarding\n/my\_status <label> — Check data quota & expiry\n/voucher <code> — Redeem voucher code\n/support <msg> — Send ticket to helpdesk\n\n*Admin Control Plane:*\n/mp\_fleet — Global Federation Fleet Dashboard\n/mp\_voucher create <cnt> <qta> <dys> — Generate vouchers\n/mp\_voucher list — List vouchers\n/mp\_status — Proxy status\n/mp\_secrets — List secrets\n/mp\_link — Get proxy links + QR\n/mp\_add <label> — Add secret\n/mp\_remove / /mp\_revoke <label> — Remove secret\n/mp\_rotate <label> — Rotate secret\n/mp\_enable <label> — Enable secret\n/mp\_disable <label> — Disable secret\n/mp\_limits — Show user limits\n/mp\_setlimit — Set user limits\n/mp\_upstreams — List upstreams\n/mp\_traffic — Traffic report\n/mp\_health — Health check\n/mp\_lockdown [on|off] — Emergency shield\n/mp\_digest — System digest report\n/mp\_broadcast <msg> — Broadcast to all users\n/reply <chat\_id> <msg> — Reply to support ticket\n/mp\_restart — Restart proxy\n/mp\_update — Check for updates\n/mp\_help — This help"
+            tg_send_kb "📋 *MTProxyMax Commands (${VERSION})*\n\n*Public Self-Service:*\n/start — Self-service onboarding\n/my\_status <label> — Check data quota & expiry\n/voucher <code> — Redeem voucher code\n/support <msg> — Send ticket to helpdesk\n\n*Admin Control Plane:*\n/mp\_fleet — Global Federation Fleet Dashboard\n/mp\_voucher create <cnt> <qta> <dys> — Generate vouchers\n/mp\_voucher list — List vouchers\n/mp\_status — Proxy status\n/mp\_secrets — List secrets\n/mp\_link — Get proxy links + QR\n/mp\_add <label> — Add secret\n/mp\_remove / /mp\_revoke <label> — Remove secret\n/mp\_rotate <label> — Rotate secret\n/mp\_enable <label> — Enable secret\n/mp\_disable <label> — Disable secret\n/mp\_limits — Show user limits\n/mp\_setlimit — Set user limits\n/mp\_upstreams — List upstreams\n/mp\_traffic — Traffic report\n/mp\_health — Health check\n/mp\_lockdown [on|off] — Emergency shield\n/mp\_digest — System digest report\n/mp\_broadcast <msg> — Broadcast to all users\n/reply <chat\_id> <msg> — Reply to support ticket\n/mp\_restart — Restart proxy\n/mp\_update — Check for updates\n/mp\_help — This help" "$(_tg_button_bar "$chat_id")"
             ;;
     esac
 }
 
-# Cleanup trap for temp files
-trap _cleanup EXIT
+# >>> TG_MENU_BEGIN
 
-# Main loop
-echo "$$" > "$PID_FILE"
-mkdir -p "$(dirname "$OFFSET_FILE")"
-load_tg_settings
-load_traffic
 
-_last_report=0
-_report_interval=$(( ${TELEGRAM_INTERVAL:-6} * 3600 ))
-_last_health=0
-_last_traffic_update=0
-_last_enforcement=0
-declare -A _prev_log_in=()
-declare -A _prev_log_out=()
+# >>> TG_PENDING_BEGIN
+# ── Pending input ───────────────────────────────────────────────────────────
+#
+# Inline buttons cannot collect typed text, so a flow that needs a value arms a
+# prompt for that chat and the next plain message from it is taken as the
+# answer. State is one line per chat:
+#
+#   <chat_id>|<verb>|<target>|<expires_epoch>
+#
+# This daemon is the only reader AND the only writer (one shell, one loop), so
+# the rewrite needs no lock — the same reasoning the history appenders use.
+#
+# The answer is consumed by _tg_pending_try before the command dispatcher ever
+# sees it, and a slash command always escapes: being trapped in a prompt with no
+# way back to the command surface is a worse failure than losing an answer.
+_TG_PENDING_TTL=300
+_tg_pending_file() { printf '%s' "${INSTALL_DIR}/relay_stats/.tg_pending"; }
+
+_tg_pending_set() {
+    local chat="$1" verb="$2" target="${3:--}"
+    local f now exp tmp
+    f=$(_tg_pending_file)
+    # An empty path would make the temp file below land in the CURRENT
+    # DIRECTORY as "./.tmp.<pid>" — which is how a stray dotfile gets committed.
+    # INSTALL_DIR is always set in the shipped daemon, so this only ever fires
+    # in a caller that sourced the block without it.
+    [ -n "$f" ] || return 1
+    now=$(date +%s)
+    exp=$(( now + ${_TG_PENDING_TTL:-300} ))
+    mkdir -p "${INSTALL_DIR}/relay_stats" 2>/dev/null || true
+    tmp="${f}.tmp.$$"
+    # Re-arm REPLACES rather than appends: leaving an older line in place would
+    # answer with the stale verb, and the file is read top-down.
+    {
+        [ -f "$f" ] && grep -v "^${chat}|" "$f" 2>/dev/null
+        printf '%s|%s|%s|%s\n' "$chat" "$verb" "$target" "$exp"
+    } > "$tmp" 2>/dev/null && mv "$tmp" "$f" 2>/dev/null
+    chmod 600 "$f" 2>/dev/null || true
+    return 0
+}
+
+# Read-and-clear. Prints "<verb>|<target>"; non-zero when nothing was armed.
+_tg_pending_take() {
+    local chat="$1" f now tmp out="" matched=1
+    f=$(_tg_pending_file)
+    [ -n "$f" ] || return 1
+    [ -f "$f" ] || return 1
+    now=$(date +%s)
+    tmp="${f}.tmp.$$"
+    # Expired rows are dropped here rather than by a sweeper: this is the only
+    # place they matter, and a prompt nobody answers leaves no garbage behind.
+    while IFS='|' read -r _c _v _t _e; do
+        [ -z "$_c" ] && continue
+        if [ "$_c" = "$chat" ]; then
+            if [ "${_e:-0}" -gt "$now" ] 2>/dev/null; then
+                out="${_v}|${_t}"; matched=0
+            fi
+            continue
+        fi
+        printf '%s|%s|%s|%s\n' "$_c" "$_v" "$_t" "$_e"
+    done < "$f" > "$tmp" 2>/dev/null
+    mv "$tmp" "$f" 2>/dev/null || : > "$f"
+    [ "$matched" -eq 0 ] || return 1
+    printf '%s' "$out"
+    return 0
+}
+
+_tg_pending_clear() {
+    local chat="$1" f tmp
+    f=$(_tg_pending_file)
+    [ -n "$f" ] || return 0
+    [ -f "$f" ] || return 0
+    tmp="${f}.tmp.$$"
+    grep -v "^${chat}|" "$f" > "$tmp" 2>/dev/null
+    mv "$tmp" "$f" 2>/dev/null || rm -f "$tmp" 2>/dev/null
+    return 0
+}
+
+# Arm a prompt and tell the chat about it. The prompt is SENT rather than used to
+# edit the card that spawned it, because that card is what the operator wants to
+# come back to when they cancel.
+_tg_pending_prompt() {
+    local chat="$1" verb="$2" target="$3" text="$4"
+    _tg_pending_set "$chat" "$verb" "$target" || return 1
+    _UI_ROLE="$(_check_tg_role "$chat")"
+    _kb_reset
+    _kb_row "❌ Cancel|p:x"
+    tg_send_to_kb "$chat" "${text}\n\n_Send it as a normal message. Any /command cancels._" "$(_kb_json)"
+    return 0
+}
+
+# Give an armed prompt first refusal on an incoming message. Returns 0 when the
+# message was consumed as an answer, 1 when the caller must dispatch it.
+_tg_pending_try() {
+    local chat="$1" text="$2" v
+    case "$text" in
+        /*) _tg_pending_clear "$chat"; return 1 ;;
+    esac
+    v=$(_tg_pending_take "$chat") || return 1
+    _tg_pending_run "$chat" "${v%%|*}" "${v#*|}" "$text"
+    return 0
+}
+
+# Dispatch a consumed answer to the flow that armed the prompt.
+_tg_pending_run() {
+    local chat="$1" verb="$2" target="$3" value="$4"
+    case "$verb" in
+        add)
+            if ! _cb_label_ok "$value"; then
+                tg_send_to "$chat" "❌ Invalid label — letters, digits, '_' and '-' only, max 32 characters."
+                return 1
+            fi
+            if ! "${INSTALL_DIR}/mtproxymax" secret add "$value" &>/dev/null; then
+                tg_send_to "$chat" "❌ Could not add *$(_esc "$value")* — it may already exist."
+                return 1
+            fi
+            tg_send_to "$chat" "✅ Secret *$(_esc "$value")* created.$(_tg_new_secret_link "$value")"
+            ;;
+        note|adtag)
+            # target is the label, read back out of a file on disk, so it is
+            # re-validated here exactly as it was on the way in.
+            if ! _cb_label_ok "$target" || ! _cb_secret_exists "$target"; then
+                tg_send_to "$chat" "❌ That secret no longer exists."
+                return 1
+            fi
+            if [ "$verb" = "adtag" ]; then
+                # 32 hex is what the engine accepts; "clear" reverts to the
+                # global tag. Anything else would be written and then ignored.
+                if [ "$value" != "clear" ] && ! [[ "$value" =~ ^[0-9a-fA-F]{32}$ ]]; then
+                    tg_send_to "$chat" "❌ An ad-tag must be 32 hex characters, or 'clear'."
+                    return 1
+                fi
+            fi
+            if "${INSTALL_DIR}/mtproxymax" secret "$verb" "$target" "$value" &>/dev/null; then
+                tg_send_to "$chat" "✅ ${verb} updated for *$(_esc "$target")*."
+            else
+                tg_send_to "$chat" "❌ Could not update the ${verb}."
+                return 1
+            fi
+            ;;
+        tplnew)
+            # "name" or "name conns ips quota expires". read rather than word
+            # splitting: an unquoted expansion would let a "*" in the text glob
+            # against the working directory.
+            local _nm _c _i _q _e
+            read -r _nm _c _i _q _e <<< "$value"
+            if ! _cb_label_ok "$_nm"; then
+                tg_send_to "$chat" "❌ Use letters, digits, '_' and '-' only, max 32 characters."
+                return 1
+            fi
+            if "${INSTALL_DIR}/mtproxymax" template save "$_nm" "${_c:-0}" "${_i:-0}" "${_q:-0}" "${_e:-0}" "" &>/dev/null; then
+                tg_send_to "$chat" "✅ Template *$(_esc "$_nm")* saved. Open *Templates* to tune each field."
+            else
+                tg_send_to "$chat" "❌ Could not save the template."
+                return 1
+            fi
+            ;;
+        tplnotes|tplexpires)
+            if ! _cb_label_ok "$target" || ! _cb_tpl_exists "$target"; then
+                tg_send_to "$chat" "❌ That template no longer exists."
+                return 1
+            fi
+            [ "$verb" = "tplnotes" ] && _cb_tpl_set "$target" notes "$value" || _cb_tpl_set "$target" expires "$value"
+            tg_send_to "$chat" "✅ Template *$(_esc "$target")* updated."
+            ;;
+        broadcast)
+            if [ -z "$value" ]; then
+                tg_send_to "$chat" "❌ Nothing to broadcast."
+                return 1
+            fi
+            if "${INSTALL_DIR}/mtproxymax" broadcast "$value" &>/dev/null; then
+                tg_send_to "$chat" "📢 Broadcast dispatched."
+            else
+                tg_send_to "$chat" "❌ Broadcast failed."
+                return 1
+            fi
+            ;;
+        setq|setc|seti|setx|setr)
+            # target is the label. It came out of a file on disk, so it is
+            # re-validated here exactly as it was on the way in.
+            if ! _cb_label_ok "$target" || ! _cb_secret_exists "$target"; then
+                tg_send_to "$chat" "❌ That secret no longer exists."
+                return 1
+            fi
+            _CB_TOAST=""
+            if _cb_apply_limit "$verb" "$target" "$value"; then
+                tg_send_to "$chat" "✅ *$(_esc "$target")*: ${_CB_TOAST}"
+            else
+                tg_send_to "$chat" "❌ ${_CB_TOAST}"
+                return 1
+            fi
+            ;;
+        *)
+            tg_send_to "$chat" "❌ That prompt is no longer valid."
+            return 1
+            ;;
+    esac
+    return 0
+}
+
+# The connect block for a just-created secret, or "" if it cannot be built.
+# Shared by every flow that provisions a secret so the wording and the
+# FakeTLS/plain branch stay in one place.
+_tg_new_secret_link() {
+    local label="$1" ip secret dh fs
+    ip=$(get_cached_ip)
+    [ -z "$ip" ] && return 0
+    secret=$(grep -E "^${label}\|" "$SECRETS_FILE" 2>/dev/null | head -1 | cut -d'|' -f2)
+    [ -z "$secret" ] && return 0
+    if [ "${MASKING_ENABLED:-true}" != "false" ]; then
+        dh=$(domain_to_hex "${PROXY_DOMAIN:-cloudflare.com}")
+        fs="ee${secret}${dh}"
+    else
+        fs="dd${secret}"
+    fi
+    printf '\n\n🔗 [Connect](https://t.me/proxy?server=%s&port=%s&secret=%s)\n📡 `%s:%s`' \
+        "$ip" "${PROXY_PORT}" "$fs" "$ip" "${PROXY_PORT}"
+}
+# <<< TG_PENDING_END
+# ── Interactive inline-keyboard menus ───────────────────────────────────────
+#
+# The security model: callback_data is entirely attacker-controlled — a user
+# can send any payload they like — so every tap is re-authorised here against
+# the same rules _process_cmd applies. A button must never grant more than
+# typing the equivalent command would.
+#
+# TG_CB_CAPS is the single source of truth for "what capability does this
+# action need". BOTH the renderer (to decide which buttons to show) and the
+# enforcer (to decide whether to act) read it, so the two cannot drift apart.
+# The same property is pinned by tests/test_telegram_callback_dispatch.sh,
+# which fails if this table stops matching _process_cmd's gates.
+#
+# Capabilities, weakest first: public < reseller < admin < superadmin.
+TG_CB_CAPS="n=public
+m=public
+m:h=public
+u:l=admin
+u:s=admin
+t=admin
+t:w=admin
+t:u=admin
+y=admin
+y:e=admin
+s=admin
+a:enable=admin
+a:disable=admin
+a:rotate=admin
+c:enable=admin
+c:disable=admin
+c:rotate=admin
+a:remove=superadmin
+c:remove=superadmin
+u:m=admin
+u:t=admin
+e=admin
+e:q=admin
+e:c=admin
+e:i=admin
+e:x=admin
+e:r=admin
+e:n=admin
+e:a=admin
+e:t=admin
+c:setq=admin
+c:setc=admin
+c:seti=admin
+c:setx=admin
+c:setr=admin
+c:tpl=admin
+p=public
+p:x=public
+k=admin
+k:e=admin
+k:p=admin
+k:a=admin
+k:s=admin
+k:d=admin
+k:n=admin
+g=admin
+g:a=admin
+g:b=admin
+y:d=admin
+y:p=admin
+y:f=admin
+y:v=admin
+y:u=admin
+a:rotall=superadmin
+c:rotall=superadmin
+a:restart=superadmin
+c:restart=superadmin
+a:update=superadmin
+c:update=superadmin
+a:lockdown=superadmin
+c:lockdown=superadmin"
+
+_tg_cap_rank() {
+    case "$1" in
+        public)     echo 0 ;;
+        reseller)   echo 1 ;;
+        admin)      echo 2 ;;
+        superadmin) echo 3 ;;
+        *)          echo -1 ;;
+    esac
+}
+
+# An unrecognised role string ranks as public-only and is refused LOUDLY,
+# whereas the literal role "none" is refused silently — mirroring _process_cmd,
+# where an unknown auth level is denied and audited but an unauthenticated
+# chatter is simply ignored. admins.conf is hand-editable, so anything that is
+# not exactly superadmin or reseller must never exceed public.
+_tg_role_rank() {
+    case "$1" in
+        superadmin) echo 3 ;;
+        reseller)   echo 1 ;;
+        *)          echo 0 ;;
+    esac
+}
+
+# Capability for a namespace, preferring the ns:action entry over the bare ns.
+_tg_cap_for() {
+    local ns="$1" act="${2:-}"
+    local k v found=""
+    while IFS='=' read -r k v; do
+        [ -z "$k" ] && continue
+        if [ -n "$act" ] && [ "$k" = "${ns}:${act}" ]; then printf '%s' "$v"; return 0; fi
+        [ "$k" = "$ns" ] && found="$v"
+    done <<< "$TG_CB_CAPS"
+    printf '%s' "$found"
+}
+
+# 0 if the role currently rendering (_UI_ROLE) may use this action.
+_cb_can() {
+    local cap need have
+    cap=$(_tg_cap_for "$1" "${2:-}")
+    [ -n "$cap" ] || return 1
+    need=$(_tg_cap_rank "$cap")
+    have=$(_tg_role_rank "${_UI_ROLE:-none}")
+    [ "$need" -ge 0 ] || return 1
+    [ "$have" -ge "$need" ]
+}
+
+# ── Rendering helpers ───────────────────────────────────────────────────────
+_tg_json_esc() {
+    local t="$1"
+    t="${t//\\/\\\\}"
+    t="${t//\"/\\\"}"
+    printf '%s' "$t"
+}
+
+_TG_KB=""
+_kb_reset() { _TG_KB=""; }
+# _kb_row "Label|payload" "Label|payload" ... — rows with no usable button are
+# dropped, which keeps a viewer without permission from seeing an empty row.
+_kb_row() {
+    local spec lbl data out="" first=1
+    for spec in "$@"; do
+        lbl="${spec%%|*}"; data="${spec#*|}"
+        [ -z "$data" ] && continue
+        [ "$first" -eq 1 ] || out="${out},"
+        first=0
+        out="${out}{\"text\":\"$(_tg_json_esc "$lbl")\",\"callback_data\":\"$(_tg_json_esc "$data")\"}"
+    done
+    [ -z "$out" ] && return 0
+    [ -n "$_TG_KB" ] && _TG_KB="${_TG_KB},"
+    _TG_KB="${_TG_KB}[${out}]"
+}
+_kb_json() { [ -n "$_TG_KB" ] && printf '{"inline_keyboard":[%s]}' "$_TG_KB"; }
+
+# Replace the message the button lived on. Both _CB_CHAT and _CB_MID come from
+# the callback itself, which Telegram authenticates, so no chat id ever has to
+# travel inside callback_data where a user could forge it.
+_cb_edit() {
+    local text="$1" kb="${2:-}"
+    tg_edit "$_CB_CHAT" "$_CB_MID" "$(printf '%b' "$text")" "$kb"
+}
+_cb_edit_markup() {
+    local kb="$1"
+    tg_edit_markup "$_CB_CHAT" "$_CB_MID" "$kb"
+}
+
+_tg_metrics_raw() {
+    curl -s --max-time 2 "http://127.0.0.1:${PROXY_METRICS_PORT:-9090}/metrics" 2>/dev/null
+}
+
+# Per-user live metrics in ONE awk pass: "label|conns|ips" per line. Forking
+# per user would make a 50-user menu unusably slow.
+_cb_user_metrics() {
+    local _m; _m=$(_tg_metrics_raw)
+    [ -z "$_m" ] && return 0
+    printf '%s' "$_m" | awk '
+        function lbl(s, k,   p, q) { p=index(s,k"=\""); if(!p) return ""; s=substr(s,p+length(k)+2); q=index(s,"\""); return q ? substr(s,1,q-1) : "" }
+        /^telemt_user_connections_current\{/ { u=lbl($0,"user"); if(u) c[u]+=$NF }
+        /^telemt_user_unique_ips_current\{/  { u=lbl($0,"user"); if(u) i[u]+=$NF }
+        END { for(u in c) printf "%s|%.0f|%.0f\n", u, c[u]+0, i[u]+0 }
+    '
+}
+
+_cb_secret_exists() {
+    [ -n "$1" ] && _cb_label_ok "$1" && [ -f "$SECRETS_FILE" ] && \
+        grep -qE "^$1\|" "$SECRETS_FILE" 2>/dev/null
+}
+
+# ── Views ───────────────────────────────────────────────────────────────────
+_cb_render_hub() {
+    local _up _msg
+    _up=$(get_uptime)
+    _msg="🛡️ *MTProxyMax* — $(_esc "${TELEGRAM_SERVER_LABEL:-MTProxyMax}")"
+    _msg+="\n\n🟢 Running · ⏱ $(format_duration "${_up:-0}")"
+    _msg+="\n👥 $(get_active_connections) live connections"
+    _msg+="\n\nChoose a view:"
+    _kb_reset
+    _kb_row "$(_cb_can u l && printf '👥 Users|u:l:0')" "$(_cb_can t && printf '📈 Traffic|t')"
+    _kb_row "$(_cb_can y && printf '🖥 Server|y')"     "$(_cb_can k && printf '🧩 Templates|k')"
+    _kb_row "$(_cb_can g && printf '🛠 Tools|g')"      "$(_cb_can s && printf '⚙️ Settings|s')"
+    _kb_row "❓ Help|m:h"
+    _cb_edit "$_msg" "$(_kb_json)"
+}
+
+# The list is rendered from the same source Telegram is told about, fetched
+# over the CLI. The old version was a hand-maintained string that had already
+# drifted from TG_CMDS_* — it advertised commands that no longer existed and
+# missed ones that did.
+_cb_render_help() {
+    local _case="admin"
+    case "${_UI_ROLE:-none}" in
+        superadmin) _case="superadmin" ;;
+        reseller)   _case="reseller" ;;
+        *)          _case="public" ;;
+    esac
+
+    local out
+    out=$("${INSTALL_DIR}/mtproxymax" telegram commands "$_case" 2>/dev/null)
+    # An underscore in a command name is Markdown emphasis, so the leading slash
+    # has to be escaped or "/mp_status" renders as "/mp" + italic "status".
+    out=$(printf '%s' "$out" | sed 's|^|/|; s|_|\\_|g')
+
+    local _msg="📋 *Commands*"
+    if [ -n "$out" ]; then
+        _msg+="\n\n${out}"
+    else
+        _msg+="\n\n_Command list unavailable — try_ \`mtproxymax telegram sync-commands\`_._"
+    fi
+    _msg+="\n\n_Every one of these is also a button. Send any command to get the menu._"
+
+    _kb_reset
+    _kb_row "🏠 Menu|m"
+    _cb_edit "$_msg" "$(_kb_json)"
+}
+
+_cb_render_user_list() {
+    local page="${1:-0}" note="${2:-}"
+    [[ "$page" =~ ^[0-9]+$ ]] || page=0
+    [ -f "$SECRETS_FILE" ] || { _cb_edit "📋 No secrets configured." ""; return 0; }
+
+    local -a _labels=() _enabled=()
+    local label secret created enabled rest
+    while IFS='|' read -r label secret created enabled rest || [ -n "$label" ]; do
+        [[ "$label" =~ ^# ]] && continue
+        _cb_label_ok "$label" || continue
+        _labels+=("$label"); _enabled+=("$enabled")
+    done < "$SECRETS_FILE"
+
+    local _total=${#_labels[@]}
+    local per=6
+    local _pages=$(( (_total + per - 1) / per ))
+    [ "$_pages" -lt 1 ] && _pages=1
+    [ "$page" -ge "$_pages" ] && page=$(( _pages - 1 ))
+
+    declare -A _conns=()
+    while IFS='|' read -r _l _c _i; do
+        [ -n "$_l" ] && _conns["$_l"]="${_c:-0}"
+    done < <(_cb_user_metrics)
+
+    local _msg="${note:+${note}\n\n}"
+    _msg+="👥 *Users* — ${_total} total"
+    # Declared separately on purpose: inside a single `local a=6 b=$((a+6))`
+    # bash expands $a against the OUTER scope, so _end silently came out as
+    # per rather than start+per and every page after the first rendered empty.
+    local _i _start _end
+    _start=$(( page * per ))
+    _end=$(( _start + per ))
+    [ "$_end" -gt "$_total" ] && _end=$_total
+    _kb_reset
+    for (( _i = _start; _i < _end; _i++ )); do
+        local _lbl="${_labels[$_i]}" _icon="🟢"
+        [ "${_enabled[$_i]}" != "true" ] && _icon="🔴"
+        local _btn="${_icon} ${_lbl}"
+        [ "${#_btn}" -gt 34 ] && _btn="${_btn:0:34}"
+        _kb_row "${_btn}|u:s:${_lbl}:${page}"
+    done
+    local _prev="" _next=""
+    [ "$page" -gt 0 ] && _prev="◀ Prev|u:l:$(( page - 1 ))"
+    [ "$_end" -lt "$_total" ] && _next="Next ▶|u:l:$(( page + 1 ))"
+    _kb_row "$_prev" "$(( page + 1 ))/${_pages}|n" "$_next"
+    _kb_row "🏠 Menu|m"
+    _cb_edit "$_msg" "$(_kb_json)"
+}
+
+_cb_bar() {
+    local pct="${1:-0}"
+    [[ "$pct" =~ ^-?[0-9]+$ ]] || pct=0
+    [ "$pct" -lt 0 ] && pct=0
+    [ "$pct" -gt 100 ] && pct=100
+    local _f=$(( pct / 10 )) _e=$(( 10 - pct / 10 ))
+    local _s="" _i
+    for (( _i = 0; _i < _f; _i++ )); do _s+="▓"; done
+    for (( _i = 0; _i < _e; _i++ )); do _s+="░"; done
+    printf '%s' "$_s"
+}
+
+_cb_render_user_detail() {
+    local label="$1" page="${2:-0}" note="${3:-}"
+    ! _cb_secret_exists "$label" && { _CB_TOAST="Secret '$label' not found"; return 1; }
+    [[ "$page" =~ ^[0-9]+$ ]] || page=0
+
+    local _line _l _s _created _en _mc _mi _q _ex _notes _adtag
+    _line=$(grep -E "^${label}\|" "$SECRETS_FILE" 2>/dev/null | head -1)
+    IFS='|' read -r _l _s _created _en _mc _mi _q _ex _notes _adtag <<< "$_line"
+
+    local _conns=0 _ips=0
+    while IFS='|' read -r _ml _mc2 _mi2; do
+        [ "$_ml" = "$label" ] && { _conns="${_mc2:-0}"; _ips="${_mi2:-0}"; }
+    done < <(_cb_user_metrics)
+
+    local _in="${_cum_user_in[$label]:-0}" _out="${_cum_user_out[$label]:-0}"
+    local _total=$(( _in + _out ))
+    local _icon="🟢 active" ; [ "$_en" != "true" ] && _icon="🔴 disabled"
+
+    local _msg="${note:+${note}\n\n}"
+    _msg+="👤 *$(_esc "$label")*\n"
+    _msg+="🔌 ${_icon} · 📡 ${_conns} conn / ${_ips} IP\n"
+    _msg+="📊 since reset: ↓ $(format_bytes "$_out") ↑ $(format_bytes "$_in")\n"
+    if [ -n "$_q" ] && [ "$_q" -gt 0 ] 2>/dev/null; then
+        local _pct=$(( (_total * 100) / _q ))
+        [ "$_pct" -gt 100 ] && _pct=100
+        _msg+="🧮 quota $(_cb_bar "$_pct") ${_pct}% of $(format_bytes "$_q")\n"
+    else
+        _msg+="🧮 quota unlimited\n"
+    fi
+    if [ -n "$_ex" ] && [ "$_ex" != "0" ] && [ "$_ex" != "" ]; then
+        local _exp_e _days
+        _exp_e=$(_iso_to_epoch "$_ex")
+        if [ "${_exp_e:-0}" -gt 0 ] 2>/dev/null; then
+            _days=$(( (_exp_e - $(date +%s)) / 86400 ))
+            if [ "$_days" -lt 0 ]; then _msg+="⏳ expired on ${_ex}\n"
+            else _msg+="⏳ expires in ${_days}d (${_ex})\n"; fi
+        fi
+    else
+        _msg+="⏳ no expiry\n"
+    fi
+
+    local _reset; _reset=$(_cb_quota_reset_day "$label")
+    [ -n "$_notes" ] && _msg+="📝 $(_esc "$_notes")\n"
+    [ -n "$_reset" ] && _msg+="🔁 Quota resets on day ${_reset}\n"
+
+    _kb_reset
+    _kb_row "🔄 Refresh|u:s:${label}:${page}" "🔗 Link|u:k:${label}"
+    _kb_row "$(_kb_spec "⚙️ Manage" "u" "m" "$label" "$page")" "$(_kb_spec "📊 Traffic" "u" "t" "$label" "$page")"
+    if [ "$_en" = "true" ]; then
+        _cb_can a disable && _kb_row "⏸ Disable|a:disable:${label}" "$(_cb_can a rotate && printf '♻️ Rotate|a:rotate:%s' "$label")"
+    else
+        _cb_can a enable && _kb_row "▶️ Enable|a:enable:${label}"
+    fi
+    _cb_can a remove && _kb_row "🗑 Remove|a:remove:${label}"
+    _kb_row "◀ Back|u:l:${page}"
+    _cb_edit "$_msg" "$(_kb_json)"
+}
+
+# "Label|payload", or "" when the payload cannot be encoded. One payload over
+# 64 bytes makes Telegram reject the WHOLE keyboard with a 400, so a button that
+# silently disappears is strictly better than a card that fails to render — but
+# only where the caller says so in the body. See _cb_render_tpl_picker.
+_kb_spec() {
+    local lbl="$1" p
+    p=$(_cb_enc "$2" "$3" "$4" "$5") || return 0
+    printf '%s|%s' "$lbl" "$p"
+}
+
+# Human text for a preset value. Values travel the wire in their raw form (the
+# callback charset has no room for "+", "∞" or a space), so the pretty form is
+# always computed here rather than stored.
+_cb_preset_label() {
+    case "$1" in
+        q|c|i) [ "$2" = "0" ] && printf '∞' || printf '%s' "$2" ;;
+        x)     [ "$2" = "0" ] && printf 'never' || printf '+%sd' "$2" ;;
+        *)     printf '%s' "$2" ;;
+    esac
+}
+
+_cb_render_user_manage() {
+    local label="$1" page="${2:-0}"
+    ! _cb_secret_exists "$label" && { _CB_TOAST="Secret '$label' not found"; return 1; }
+    [[ "$page" =~ ^[0-9]+$ ]] || page=0
+
+    local _line _l _s _created _en _mc _mi _q _ex _notes _adtag
+    _line=$(grep -E "^${label}\|" "$SECRETS_FILE" 2>/dev/null | head -1)
+    IFS='|' read -r _l _s _created _en _mc _mi _q _ex _notes _adtag <<< "$_line"
+
+    local _reset; _reset=$(_cb_quota_reset_day "$label")
+
+    local _msg="⚙️ *Manage $(_esc "$label")*\n\n"
+    if [ -n "$_q" ] && [ "$_q" -gt 0 ] 2>/dev/null; then
+        _msg+="🧮 Quota: $(format_bytes "$_q")\n"
+    else
+        _msg+="🧮 Quota: unlimited\n"
+    fi
+    _msg+="🔌 Max connections: $([ -n "$_mc" ] && [ "$_mc" != "0" ] && printf '%s' "$_mc" || printf 'unlimited')\n"
+    _msg+="🌐 Max IPs: $([ -n "$_mi" ] && [ "$_mi" != "0" ] && printf '%s' "$_mi" || printf 'unlimited')\n"
+    _msg+="⏳ Expires: $(_cb_expiry_text "$_ex")\n"
+    _msg+="🔁 Quota reset: $([ -n "$_reset" ] && printf 'day %s' "$_reset" || printf 'off')\n"
+    _msg+="📝 Note: $([ -n "$_notes" ] && printf '%s' "$(_esc "$_notes")" || printf '_none_')\n"
+    _msg+="🏷 Ad-tag: $([ -n "$_adtag" ] && printf '`%s`' "$(_esc "$_adtag")" || printf '_global default_')"
+    # The expiry picker's relative presets and its "never" option mean different
+    # CLI verbs, so say which is which rather than making the operator guess.
+
+    _kb_reset
+    _kb_row "$(_kb_spec "🧮 Quota" "e" "q" "$label" "$page")" \
+            "$(_kb_spec "🔌 Conns" "e" "c" "$label" "$page")"
+    _kb_row "$(_kb_spec "🌐 IPs" "e" "i" "$label" "$page")" \
+            "$(_kb_spec "⏳ Expiry" "e" "x" "$label" "$page")"
+    _kb_row "$(_kb_spec "🔁 Reset day" "e" "r" "$label" "$page")" \
+            "$(_kb_spec "🧩 Template" "e" "t" "$label" "$page")"
+    _kb_row "$(_kb_spec "📝 Note" "e" "n" "$label" "$page")" \
+            "$(_kb_spec "🏷 Ad-tag" "e" "a" "$label" "$page")"
+    _kb_row "◀ Back|u:s:${label}:${page}"
+    _cb_edit "$_msg" "$(_kb_json)"
+}
+
+# The picker for one limit field. Every button commits through the per-field
+# CLI verb — never `secret setlimits`, whose zeroes mean "unlimited" and would
+# silently clear the fields the operator did not touch.
+_cb_render_limits() {
+    local field="$1" label="$2" page="${3:-0}" act title presets
+    ! _cb_secret_exists "$label" && { _CB_TOAST="Secret '$label' not found"; return 1; }
+    [[ "$page" =~ ^[0-9]+$ ]] || page=0
+
+    case "$field" in
+        q) act="setq"; title="Quota";               presets="5G 10G 50G 100G 0" ;;
+        c) act="setc"; title="Max connections";     presets="5 10 20 50 0" ;;
+        i) act="seti"; title="Max IPs";             presets="1 3 5 10 0" ;;
+        x) act="setx"; title="Expiry";              presets="7 30 90 365 0" ;;
+        r) act="setr"; title="Quota reset day";     presets="1 15 28 off" ;;
+        *) _CB_TOAST="Unknown field"; return 1 ;;
+    esac
+
+    local _msg="🧮 *${title} — $(_esc "$label")*\n\n"
+    case "$field" in
+        q) _msg+="_Pick a cap, or ∞ for no limit._" ;;
+        c) _msg+="_Telegram opens ~3 connections per device, so a cap under 5 will break a single client._" ;;
+        i) _msg+="_An IP cap is a weak anti-sharing measure: mobile clients roam between cells._" ;;
+        x) _msg+="_Relative presets extend from today. 'never' clears the date._" ;;
+        r) _msg+="_Resets the traffic counter on that day of each month._" ;;
+    esac
+
+    _kb_reset
+    # Two per row. Built as an array rather than a space-joined string: a spec
+    # containing a space would otherwise split into two bogus buttons.
+    local -a _specs=()
+    local _v _spec
+    for _v in $presets; do
+        _spec=$(_kb_spec "$(_cb_preset_label "$field" "$_v")" "c" "$act" "$label" "$_v")
+        [ -n "$_spec" ] && _specs+=("$_spec")
+        if [ "${#_specs[@]}" -eq 2 ]; then _kb_row "${_specs[@]}"; _specs=(); fi
+    done
+    [ "${#_specs[@]}" -gt 0 ] && _kb_row "${_specs[@]}"
+    # A value the presets do not cover. It arms a pending prompt rather than
+    # committing, because the grammar has no room for free text.
+    _kb_row "$(_kb_enc_custom "$label" "$field")"
+    _kb_row "◀ Back|u:m:${label}:${page}"
+    _cb_edit "$_msg" "$(_kb_json)"
+}
+
+# "✏️ Custom…" — arms a pending prompt for a value the presets do not cover. The
+# field rides in the page slot so the flow keeps the label as its target, which
+# is what every other payload in this file does.
+_kb_enc_custom() {
+    local label="$1" field="$2" p
+    p=$(_cb_enc "e" "z" "$label" "$field") || return 0
+    printf '✏️ Custom…|%s' "$p"
+}
+
+# ── Limit templates ─────────────────────────────────────────────────────────
+#
+# templates.conf holds "name|conns|ips|quota|expires|notes", and the CLI's
+# `template save` already overwrites by name — so editing a template is a
+# read-modify-write that rebuilds the row with one field replaced. No new CLI
+# verb is needed, but the rebuild has to carry the fields it did not touch:
+# template_save replaces the whole row, so a stale or mis-split read would
+# quietly reset notes and expiry, the two easiest columns to lose.
+
+_cb_tpl_get() {   # <name> <field 1..6> -> value, "" if absent
+    local f="${INSTALL_DIR}/templates.conf" _n _c _i _q _e _notes
+    [ -f "$f" ] || return 0
+    while IFS='|' read -r _n _c _i _q _e _notes; do
+        [ "$_n" = "$1" ] || continue
+        case "$2" in
+            1) printf '%s' "$_n" ;; 2) printf '%s' "$_c" ;; 3) printf '%s' "$_i" ;;
+            4) printf '%s' "$_q" ;; 5) printf '%s' "$_e" ;; 6) printf '%s' "$_notes" ;;
+        esac
+        return 0
+    done < "$f"
+}
+
+_cb_tpl_exists() {
+    [ -n "$1" ] && [ -f "${INSTALL_DIR}/templates.conf" ] && \
+        grep -qE "^$1\|" "${INSTALL_DIR}/templates.conf" 2>/dev/null
+}
+
+# Write the row back with one field replaced. Reads inside the same call that
+# writes it, so the fields the operator did not touch are the ones on disk now.
+_cb_tpl_set() {   # <name> <slot> <value>; slot = conns|ips|quota|expires|notes
+    local name="$1" slot="$2" value="$3"
+    local _c _i _q _e _notes
+    _c=$(_cb_tpl_get "$name" 2); _i=$(_cb_tpl_get "$name" 3)
+    _q=$(_cb_tpl_get "$name" 4); _e=$(_cb_tpl_get "$name" 5)
+    _notes=$(_cb_tpl_get "$name" 6)
+    case "$slot" in
+        conns)   _c="$value" ;;
+        ips)     _i="$value" ;;
+        quota)   _q="$value" ;;
+        expires) _e="$value" ;;
+        notes)   _notes="$value" ;;
+        *) return 1 ;;
+    esac
+    "${INSTALL_DIR}/mtproxymax" template save "$name" "${_c:-0}" "${_i:-0}" "${_q:-0}" "${_e:-0}" "${_notes:-}" &>/dev/null
+}
+
+_cb_render_tpl_list() {
+    local f="${INSTALL_DIR}/templates.conf" _msg="🧩 *Limit templates*\n" _n=0 _t _rest _skipped=""
+    _kb_reset
+    if [ -f "$f" ]; then
+        while IFS='|' read -r _t _rest; do
+            [ -z "$_t" ] && continue
+            # A name outside the callback charset cannot be a button. Say so in
+            # the body rather than letting _kb_spec drop it without a trace.
+            if ! _cb_label_ok "$_t"; then _skipped+="${_t} "; continue; fi
+            _kb_row "$(_kb_spec "📋 $_t" "k" "e" "$_t" "0")"
+            _n=$(( _n + 1 ))
+        done < "$f"
+    fi
+    if [ -n "$_skipped" ]; then
+        _msg+="\n_Not shown (name has characters a button cannot carry): ${_skipped}_"
+    fi
+    if [ "$_n" -eq 0 ]; then
+        _msg+="\n_Nothing saved yet._"
+    fi
+    _msg+="\n\n_A template is a named bundle of limits you can apply to any secret._"
+    _kb_row "$(_cb_can k n && printf '➕ New template|k:n')"
+    _kb_row "🏠 Menu|m"
+    _cb_edit "$_msg" "$(_kb_json)"
+}
+
+_cb_render_tpl_edit() {
+    local name="$1" page="${2:-0}" _c _i _q _e _notes
+    ! _cb_tpl_exists "$name" && { _CB_TOAST="Template '$name' not found"; return 1; }
+    _c=$(_cb_tpl_get "$name" 2); _i=$(_cb_tpl_get "$name" 3)
+    _q=$(_cb_tpl_get "$name" 4); _e=$(_cb_tpl_get "$name" 5)
+    _notes=$(_cb_tpl_get "$name" 6)
+
+    local _msg="🧩 *$(_esc "$name")*\n\n"
+    _msg+="🔌 Max connections: $([ -n "$_c" ] && [ "$_c" != "0" ] && printf '%s' "$_c" || printf 'unlimited')\n"
+    _msg+="🌐 Max IPs: $([ -n "$_i" ] && [ "$_i" != "0" ] && printf '%s' "$_i" || printf 'unlimited')\n"
+    _msg+="🧮 Quota: $([ -n "$_q" ] && [ "$_q" != "0" ] && printf '%s' "$(format_bytes "$_q")" || printf 'unlimited')\n"
+    _msg+="⏳ Expires: $(_cb_expiry_text "$_e")\n"
+    _msg+="📝 Notes: $([ -n "$_notes" ] && printf '%s' "$(_esc "$_notes")" || printf '_none_')"
+
+    _kb_reset
+    _kb_row "$(_kb_spec "🔌 Conns" "k" "p" "$name" "c")" "$(_kb_spec "🌐 IPs" "k" "p" "$name" "i")"
+    _kb_row "$(_kb_spec "🧮 Quota" "k" "p" "$name" "q")" "$(_kb_spec "⏳ Expires" "k" "p" "$name" "x")"
+    _kb_row "$(_kb_spec "📝 Notes" "k" "p" "$name" "n")"
+    _kb_row "$(_cb_can k s && printf '✨ Apply to a user…|k:s:%s:0' "$name")"
+    _kb_row "$(_cb_can k d && printf '🗑 Delete|k:d:%s:0' "$name")"
+    _kb_row "◀ Back|k"
+    _cb_edit "$_msg" "$(_kb_json)"
+}
+
+# The preset picker for one template field. Commits straight to c:tplset rather
+# than through a confirmation: this edits a stored template, which changes
+# nothing for a connected user and is one tap from being undone. The confirm
+# rule is for actions that touch live secrets.
+_cb_render_tpl_field() {
+    local name="$1" field="$2"
+    ! _cb_tpl_exists "$name" && { _CB_TOAST="Template '$name' not found"; return 1; }
+
+    local slot presets title hint
+    case "$field" in
+        c) slot="conns";   presets="5 10 20 50 0";   title="Max connections"; hint="Telegram opens ~3 connections per device." ;;
+        i) slot="ips";     presets="1 3 5 10 0";     title="Max IPs";          hint="A secondary anti-sharing measure." ;;
+        q) slot="quota";   presets="5G 10G 50G 100G 0"; title="Quota";         hint="0 means unlimited." ;;
+        x) slot="expires"; presets="0";              title="Expires";          hint="A date is set per user when the template is applied; type one to change it." ;;
+        n) slot="notes";   presets="";               title="Notes";            hint="Free text." ;;
+        *) _CB_TOAST="Unknown field"; return 1 ;;
+    esac
+
+    if [ "$field" = "n" ]; then
+        # Notes has no useful presets, so it goes straight to a typed prompt.
+        _tg_pending_prompt "$_CB_CHAT" "tplnotes" "$name" \
+            "📝 *Notes for template $(_esc "$name")*\n\nSend the text to store."
+        _CB_TOAST="Send the note"
+        return 0
+    fi
+    if [ "$field" = "x" ]; then
+        _tg_pending_prompt "$_CB_CHAT" "tplexpires" "$name" \
+            "⏳ *Expiry for template $(_esc "$name")*\n\nSend a date as YYYY-MM-DD, or 0 for none."
+        _CB_TOAST="Send the date"
+        return 0
+    fi
+
+    local _msg="🧩 *${title} — $(_esc "$name")*\n\n_${hint}_"
+    _kb_reset
+    local -a _specs=()
+    local _v _spec
+    for _v in $presets; do
+        _spec=$(_kb_spec "$(_cb_preset_label "$field" "$_v")" "c" "tplset" "$name" "${field}${_v}")
+        [ -n "$_spec" ] && _specs+=("$_spec")
+        if [ "${#_specs[@]}" -eq 2 ]; then _kb_row "${_specs[@]}"; _specs=(); fi
+    done
+    [ "${#_specs[@]}" -gt 0 ] && _kb_row "${_specs[@]}"
+    _kb_row "◀ Back|k:e:${name}:0"
+    _cb_edit "$_msg" "$(_kb_json)"
+}
+
+_cb_render_tpl_apply_picker() {
+    local name="$1" page="${2:-0}" _t
+    ! _cb_tpl_exists "$name" && { _CB_TOAST="Template '$name' not found"; return 1; }
+
+    local _msg="✨ *Apply $(_esc "$name") to…*\n" _n=0
+    _kb_reset
+    while IFS='|' read -r _l _rest; do
+        [[ "$_l" =~ ^# ]] && continue
+        [ -z "$_l" ] && continue
+        _cb_label_ok "$_l" || continue
+        _kb_row "$(_kb_spec "👤 $_l" "c" "tpl" "$_l" "$name")"
+        _n=$(( _n + 1 ))
+    done < "$SECRETS_FILE"
+    [ "$_n" -eq 0 ] && _msg+="\n_No secrets to apply it to._"
+    _kb_row "◀ Back|k:e:${name}:0"
+    _cb_edit "$_msg" "$(_kb_json)"
+}
+
+# Templates that can be applied to this secret. A name that cannot survive the
+# callback charset is listed as text rather than as a button: _kb_spec drops
+# what it cannot encode, and a template the operator can see is unavailable
+# beats one that silently is not there.
+_cb_render_tpl_picker() {
+    local label="$1" page="${2:-0}" f="${INSTALL_DIR}/templates.conf" _t _rest
+    ! _cb_secret_exists "$label" && { _CB_TOAST="Secret '$label' not found"; return 1; }
+    [[ "$page" =~ ^[0-9]+$ ]] || page=0
+
+    local _msg="🧩 *Apply a template to $(_esc "$label")*\n\n"
+    _kb_reset
+    local _n=0 _skipped=""
+    if [ -f "$f" ]; then
+        while IFS='|' read -r _t _rest; do
+            [ -z "$_t" ] && continue
+            if ! _cb_label_ok "$_t"; then _skipped+="${_t} "; continue; fi
+            _kb_row "$(_kb_spec "📋 $_t" "c" "tpl" "$label" "$_t")"
+            _n=$(( _n + 1 ))
+        done < "$f"
+    fi
+    if [ -n "$_skipped" ]; then
+        _msg+="_Not shown (name has characters a button cannot carry): ${_skipped}_\n\n"
+    fi
+    if [ "$_n" -eq 0 ]; then
+        _msg+="_Nothing to apply. Save one with_ \`mtproxymax template save <name> <conns> <ips> <quota> <expires>\`_._\n"
+    fi
+    _kb_row "◀ Back|u:m:${label}:${page}"
+    _cb_edit "$_msg" "$(_kb_json)"
+}
+
+# What one user actually moved, windowed. users.tsv has been written since the
+# history subsystem landed but nothing read it back per user — the user card
+# could only show the cumulative total since the last reset, which cannot
+# answer "how much today, and is that up or down?".
+#
+# All three windows are on one card rather than behind a window selector: three
+# totals fit comfortably, and a selector would need a fifth field the callback
+# grammar does not have, costing the origin page on the way back.
+_cb_render_user_traffic() {
+    local label="$1" page="${2:-0}"
+    ! _cb_label_ok "$label" && { _CB_TOAST="Invalid label"; return 1; }
+    ! _cb_secret_exists "$label" && { _CB_TOAST="Secret '$label' not found"; return 1; }
+    [[ "$page" =~ ^[0-9]+$ ]] || page=0
+
+    local _now _w
+    _now=$(date +%s)
+    local _msg="📊 *Traffic — $(_esc "$label")*\n"
+    local _in _out
+    for _w in 86400 604800 2592000; do
+        # history_users already does the windowed sum in one pass; reuse it
+        # rather than adding a second reader that could drift from it.
+        IFS='|' read -r _ _in _out <<< "$(history_users "$_w" "$_now" "$label")"
+        case "$_w" in
+            86400)   _msg+="\n*Last 24h*  ↓ $(format_bytes "${_out:-0}")  ↑ $(format_bytes "${_in:-0}")" ;;
+            604800)  _msg+="\n*Last 7d*   ↓ $(format_bytes "${_out:-0}")  ↑ $(format_bytes "${_in:-0}")" ;;
+            2592000) _msg+="\n*Last 30d*  ↓ $(format_bytes "${_out:-0}")  ↑ $(format_bytes "${_in:-0}")" ;;
+        esac
+    done
+
+    local _spark
+    _spark=$(_tg_spark "$(history_user_series "$label" 86400 "$_now" 24)")
+    [ -n "$_spark" ] && _msg+="\n\n📉 ${_spark}"
+
+    # The card carries the same quota/expiry context as the user card, so an
+    # operator reading the traffic does not have to navigate back to judge it.
+    local _line _q _ex
+    _line=$(grep -E "^${label}\|" "$SECRETS_FILE" 2>/dev/null | head -1)
+    IFS='|' read -r _ _ _ _ _ _ _q _ex _ <<< "$_line"
+    if [ -n "$_q" ] && [ "$_q" -gt 0 ] 2>/dev/null; then
+        local _cum=$(( ${_cum_user_in[$label]:-0} + ${_cum_user_out[$label]:-0} ))
+        local _pct=$(( (_cum * 100) / _q ))
+        [ "$_pct" -gt 100 ] && _pct=100
+        _msg+="\n\n🧮 quota $(_cb_bar "$_pct") ${_pct}% of $(format_bytes "$_q")"
+    fi
+    [ -n "$_ex" ] && [ "$_ex" != "0" ] && _msg+="\n⏳ expires $(_cb_expiry_text "$_ex")"
+
+    _kb_reset
+    _kb_row "🔄 Refresh|u:t:${label}:${page}" "⚙️ Manage|u:m:${label}:${page}"
+    _kb_row "◀ Back|u:s:${label}:${page}"
+    _cb_edit "$_msg" "$(_kb_json)"
+}
+
+_cb_quota_reset_day() {
+    local f="${INSTALL_DIR}/secrets_quota_reset.conf" _l _d
+    [ -f "$f" ] || return 0
+    while IFS='|' read -r _l _d; do
+        [ "$_l" = "$1" ] && { printf '%s' "$_d"; return 0; }
+    done < "$f"
+}
+
+_cb_expiry_text() {
+    local ex="$1" e days
+    if [ -z "$ex" ] || [ "$ex" = "0" ]; then printf 'never'; return 0; fi
+    e=$(_iso_to_epoch "$ex")
+    if [ "${e:-0}" -gt 0 ] 2>/dev/null; then
+        days=$(( (e - $(date +%s)) / 86400 ))
+        if [ "$days" -lt 0 ]; then printf 'expired (%s)' "$ex"
+        else printf 'in %sd (%s)' "$days" "$ex"; fi
+    else
+        printf '%s' "$ex"
+    fi
+}
+
+_cb_render_confirm() {
+    local verb="$1" label="$2" page="${3:-0}" pretty=""
+    case "$verb" in
+        enable)  pretty="Enable" ;;
+        disable) pretty="Disable" ;;
+        rotate)  pretty="Rotate" ;;
+        remove)  pretty="Remove" ;;
+        rotall)  pretty="Rotate all secrets" ;;
+        restart) pretty="Restart the proxy" ;;
+        update)  pretty="Apply the update" ;;
+        lockdown)
+            case "$label" in
+                on)  pretty="Activate lockdown" ;;
+                off) pretty="Lift lockdown" ;;
+                *) _CB_TOAST="Unknown mode"; return 1 ;;
+            esac ;;
+        *) _CB_TOAST="Unknown action"; return 1 ;;
+    esac
+
+    # The global verbs are targetless. "_" is their placeholder, and it is
+    # matched here rather than treated as a label so that a secret genuinely
+    # named "_" is still a secret for enable/disable/rotate/remove.
+    case "$verb" in
+        rotall|restart|update|lockdown) label="" ;;
+    esac
+    [ -n "$label" ] && ! _cb_secret_exists "$label" && { _CB_TOAST="Secret '$label' not found"; return 1; }
+
+    local _extra=""
+    case "$verb" in
+        rotall)  _extra="\n\nEvery client on every secret will have to reconnect." ;;
+        restart) _extra="\n\nThe proxy is briefly unreachable to all users." ;;
+        update)  _extra="\n\nThe installed script is replaced and the proxy may restart." ;;
+        lockdown) _extra="\n\nThis hardens the kernel posture and tightens the proxy immediately." ;;
+        disable)
+            local _c=0
+            while IFS='|' read -r _ml _mc2 _mi2; do
+                [ "$_ml" = "$label" ] && _c="${_mc2:-0}"
+            done < <(_cb_user_metrics)
+            [ "${_c:-0}" -gt 0 ] && _extra="\n\nThis immediately disconnects *${_c}* active session(s)."
+            ;;
+        remove) _extra="\n\nThe key stops working immediately and cannot be restored." ;;
+        rotate) _extra="\n\nEvery client using this key must reconnect." ;;
+    esac
+    local _msg="⚠️ *${pretty} $(_esc "$label")?*${_extra}"
+    _kb_reset
+    _kb_row "✅ Yes, ${pretty,,}|c:${verb}:${label}" "❌ Cancel|u:s:${label}:${page}"
+    _cb_edit "$_msg" "$(_kb_json)"
+}
+
+# Arm a pending prompt for a limit value outside the preset set. The verb in the
+# store is the same one the preset commits through, so the typed value lands on
+# exactly the same validated path — the prompt is not a second, laxer way in.
+_cb_prompt_custom_limit() {
+    local label="$1" field="$2" act="" title=""
+    ! _cb_secret_exists "$label" && { _CB_TOAST="Secret '$label' not found"; return 1; }
+    case "$field" in
+        q) act="setq"; title="quota (e.g. 250M, 2G, or 0 for unlimited)" ;;
+        c) act="setc"; title="maximum connections (a whole number, 0 for unlimited)" ;;
+        i) act="seti"; title="maximum unique IPs (a whole number, 0 for unlimited)" ;;
+        x) act="setx"; title="expiry as days from today (0 for never) or YYYY-MM-DD" ;;
+        r) act="setr"; title="quota reset day (1-28, or 'off')" ;;
+        *) _CB_TOAST="Unknown field"; return 1 ;;
+    esac
+    _tg_pending_prompt "$_CB_CHAT" "$act" "$label" \
+        "✏️ *Custom ${act#set} for $(_esc "$label")*\n\nSend the value as a normal message — ${title}."
+    _CB_TOAST="Send the value"
+}
+
+# Validate and apply one limit change. Sets _CB_TOAST on failure; returns 0 when
+# the CLI accepted it.
+#
+# The value arrives through callback_data (attacker-controlled) or through the
+# pending store (a file on disk), so it is validated here rather than trusted.
+# Every field goes through the per-field `secret setlimit` verb and never
+# `secret setlimits`, whose zeroes read as "unlimited" and would silently clear
+# the fields the operator did not touch.
+_cb_apply_limit() {
+    local verb="$1" label="$2" value="$3"
+    case "$verb" in
+        setq)
+            [[ "$value" =~ ^[0-9]+[KMGTkmgt]?$ ]] || { _CB_TOAST="Enter a size like 250M or 2G"; return 1; }
+            "${INSTALL_DIR}/mtproxymax" secret setlimit "$label" quota "$value" &>/dev/null \
+                && { _CB_TOAST="Quota updated"; return 0; }
+            ;;
+        setc)
+            { [[ "$value" =~ ^[0-9]+$ ]] && [ "$value" -le 1000000 ]; } || { _CB_TOAST="Enter a number up to 1000000"; return 1; }
+            "${INSTALL_DIR}/mtproxymax" secret setlimit "$label" conns "$value" &>/dev/null \
+                && { _CB_TOAST="Connection limit updated"; return 0; }
+            ;;
+        seti)
+            { [[ "$value" =~ ^[0-9]+$ ]] && [ "$value" -le 100000 ]; } || { _CB_TOAST="Enter a number up to 100000"; return 1; }
+            "${INSTALL_DIR}/mtproxymax" secret setlimit "$label" ips "$value" &>/dev/null \
+                && { _CB_TOAST="IP limit updated"; return 0; }
+            ;;
+        setx)
+            if [ "$value" = "0" ]; then
+                "${INSTALL_DIR}/mtproxymax" secret setlimit "$label" expires 0 &>/dev/null \
+                    && { _CB_TOAST="Expiry cleared"; return 0; }
+            elif [[ "$value" =~ ^[0-9]{4}-[0-9]{2}-[0-9]{2}$ ]]; then
+                "${INSTALL_DIR}/mtproxymax" secret setlimit "$label" expires "$value" &>/dev/null \
+                    && { _CB_TOAST="Expiry set to ${value}"; return 0; }
+            elif [[ "$value" =~ ^[0-9]+$ ]] && [ "$value" -le 3650 ]; then
+                # Relative dates are the CLI's job: it already does the calendar
+                # arithmetic, including the short-month and timezone handling.
+                "${INSTALL_DIR}/mtproxymax" secret extend "$label" "$value" &>/dev/null \
+                    && { _CB_TOAST="Extended by ${value}d"; return 0; }
+            else
+                _CB_TOAST="Enter days (1-3650), YYYY-MM-DD, or 0 for never"
+                return 1
+            fi
+            ;;
+        setr)
+            case "$value" in
+                off) ;;
+                [0-9]|[12][0-9]) ;;
+                *) _CB_TOAST="Enter a day between 1 and 28, or 'off'"; return 1 ;;
+            esac
+            "${INSTALL_DIR}/mtproxymax" secret quota-reset "$label" "$value" &>/dev/null \
+                && { _CB_TOAST="Reset day updated"; return 0; }
+            ;;
+        *) _CB_TOAST="Unknown action"; return 1 ;;
+    esac
+    _CB_TOAST="Failed — check the server log"
+    return 1
+}
+
+# One field of a stored template, encoded as "<field-letter><value>" so a field
+# name and its value fit in the single slot the grammar has left.
+_cb_exec_tplset() {
+    local name="$1" spec="$2" field="${2:0:1}" value="${2:1}"
+    case "$field" in
+        c) { [[ "$value" =~ ^[0-9]+$ ]] && [ "$value" -le 1000000 ]; } || { _CB_TOAST="Enter a number up to 1000000"; return 1; }
+           _cb_tpl_set "$name" conns "$value" ;;
+        i) { [[ "$value" =~ ^[0-9]+$ ]] && [ "$value" -le 100000 ]; } || { _CB_TOAST="Enter a number up to 100000"; return 1; }
+           _cb_tpl_set "$name" ips "$value" ;;
+        q) [[ "$value" =~ ^[0-9]+[KMGTkmgt]?$ ]] || { _CB_TOAST="Enter a size like 250M or 2G"; return 1; }
+           _cb_tpl_set "$name" quota "$value" ;;
+        *) _CB_TOAST="Unknown field"; return 1 ;;
+    esac
+    _CB_TOAST="Saved"
+    return 0
+}
+
+# The verbs that act on the server rather than on one secret. They have no
+# label, and for lockdown the second field is a mode rather than a page number.
+_cb_exec_global() {
+    local verb="$1" arg="$2" out=""
+    case "$verb" in
+        rotall)
+            if out=$("${INSTALL_DIR}/mtproxymax" secret rotate --all 2>&1); then
+                _CB_TOAST="All secrets rotated"
+            else
+                _CB_TOAST="Rotate-all failed"
+            fi
+            _cb_render_tools
+            ;;
+        restart)
+            if "${INSTALL_DIR}/mtproxymax" restart &>/dev/null; then
+                _CB_TOAST="Restarting"
+            else
+                _CB_TOAST="Restart failed"
+            fi
+            _cb_render_tools
+            ;;
+        update)
+            out=$("${INSTALL_DIR}/mtproxymax" update </dev/null 2>&1 | sed 's/\x1b\[[0-9;]*m//g' | tail -5)
+            _CB_TOAST="Update finished"
+            _cb_render_update "$out"
+            ;;
+        lockdown)
+            case "$arg" in
+                on|off) ;;
+                *) _CB_TOAST="Unknown lockdown mode"; return 1 ;;
+            esac
+            if "${INSTALL_DIR}/mtproxymax" lockdown "$arg" &>/dev/null; then
+                _CB_TOAST="Lockdown ${arg}"
+                # LOCKDOWN_MODE is read by the renderers; reload it so the tools
+                # card reflects the change on the very next draw.
+                load_tg_settings
+            else
+                _CB_TOAST="Lockdown failed"
+            fi
+            _cb_render_tools
+            ;;
+        *) _CB_TOAST="Unknown action"; return 1 ;;
+    esac
+    return 0
+}
+
+# Only the c: namespace mutates anything. a: just renders a confirmation, so a
+# destructive action is never one mis-tap away.
+#
+# $3 is the origin list page for the secret verbs and the VALUE for the set-*
+# verbs: the grammar allows four fields and a commit needs both, so they share
+# the slot. The cost is that a limit change forgets which list page the operator
+# came from. Putting the value in the action instead would cost more — the
+# capability table matches exact keys and is what decides whether a tap is
+# allowed at all, so a dynamic action name could not be authorised.
+_cb_exec_action() {
+    local verb="$1" label="$2" page="${3:-0}" out=""
+    case "$verb" in
+        rotall|restart|update|lockdown)
+            # Targetless global verbs run before the label checks below: they
+            # have no secret to validate, and for lockdown the second field is
+            # the mode ("on"/"off") rather than a page.
+            _cb_exec_global "$verb" "$label"
+            return $?
+            ;;
+        tpl)
+            # Apply a stored template to a secret. The template name rides in
+            # the page slot, so both names have to survive the callback budget;
+            # _kb_spec drops the button when they cannot.
+            ! _cb_label_ok "$label" && { _CB_TOAST="Invalid label"; return 1; }
+            ! _cb_secret_exists "$label" && { _CB_TOAST="Secret '$label' not found"; return 1; }
+            ! _cb_tpl_exists "$page" && { _CB_TOAST="Template '$page' not found"; return 1; }
+            if "${INSTALL_DIR}/mtproxymax" template apply "$page" "$label" &>/dev/null; then
+                _CB_TOAST="Applied"
+                _cb_render_user_manage "$label" 0
+            else
+                _CB_TOAST="Failed"
+                _cb_render_user_manage "$label" 0
+            fi
+            return 0
+            ;;
+        tplset)
+            # One field of a stored template. page is "<field-letter><value>".
+            ! _cb_tpl_exists "$label" && { _CB_TOAST="Template '$label' not found"; return 1; }
+            _cb_exec_tplset "$label" "$page" || return 1
+            _cb_render_tpl_edit "$label" 0
+            return 0
+            ;;
+        tplnew)
+            # Named only; the values come from the editor afterwards. A name is
+            # typed, so this is reached through the pending prompt rather than a
+            # button — the branch stays for completeness and tests.
+            ! _cb_label_ok "$page" && { _CB_TOAST="Invalid template name"; return 1; }
+            "${INSTALL_DIR}/mtproxymax" template save "$page" 0 0 0 0 "" &>/dev/null \
+                && _CB_TOAST="Created" || _CB_TOAST="Failed"
+            _cb_render_tpl_edit "$page" 0
+            return 0
+            ;;
+        tpldel)
+            ! _cb_tpl_exists "$label" && { _CB_TOAST="Template '$label' not found"; return 1; }
+            "${INSTALL_DIR}/mtproxymax" template delete "$label" &>/dev/null \
+                && _CB_TOAST="Deleted" || _CB_TOAST="Failed"
+            _cb_render_tpl_list
+            return 0
+            ;;
+        enable|disable|rotate|remove) ;;
+        setq|setc|seti|setx|setr) ;;
+        *) _CB_TOAST="Unknown action"; return 1 ;;
+    esac
+    ! _cb_label_ok "$label" && { _CB_TOAST="Invalid label"; return 1; }
+    ! _cb_secret_exists "$label" && { _CB_TOAST="Secret '$label' not found"; return 1; }
+    # Only the secret verbs carry a page number. Coercing unconditionally here
+    # would flatten a limit value like "10G" or "off" to 0 before it was read.
+    case "$verb" in
+        enable|disable|rotate|remove) [[ "$page" =~ ^[0-9]+$ ]] || page=0 ;;
+    esac
+
+    case "$verb" in
+        setq|setc|seti|setx|setr)
+            # Applied, then the card is redrawn. A button tap is the only caller
+            # that wants a redraw — the pending-input path shares this validation
+            # and reports back in the chat instead, which is why the write lives
+            # in _cb_apply_limit rather than here.
+            _cb_apply_limit "$verb" "$label" "$page" || return 1
+            _cb_render_user_manage "$label" 0
+            return 0
+            ;;
+    esac
+
+    if [ "$verb" = "remove" ]; then
+        if out=$("${INSTALL_DIR}/mtproxymax" secret remove "$label" 2>&1); then
+            _CB_TOAST="Removed"
+            _cb_render_user_list "$page" "🗑 Removed *$(_esc "$label")*"
+        else
+            _CB_TOAST="Failed"
+            _cb_render_user_detail "$label" "$page" "❌ Could not remove *$(_esc "$label")*"
+        fi
+        return 0
+    fi
+
+    if out=$("${INSTALL_DIR}/mtproxymax" secret "$verb" "$label" 2>&1); then
+        _CB_TOAST="Done"
+    else
+        _CB_TOAST="Failed"
+    fi
+    _cb_render_user_detail "$label" "$page"
+}
+
+_cb_render_traffic() {
+    local win="${1:-24h}"
+    case "$win" in
+        7d)  _win_s=604800 ;;
+        30d) _win_s=2592000 ;;
+        *)   win="24h"; _win_s=86400 ;;
+    esac
+    local _now; _now=$(date +%s)
+    local _ci _co _pi _po _pct _peak _avg _n _span
+    IFS='|' read -r _ci _co _pi _po _pct _peak _avg _n _span <<< "$(history_summary "$_win_s" "$_now")"
+
+    local _msg="📈 *Traffic — last ${win}*\n\n"
+    _msg+="↓ $(format_bytes "${_co:-0}")  ↑ $(format_bytes "${_ci:-0}")$(_tg_pct_str "$_pct")\n"
+    _msg+="⚡ Peak $(format_bytes "${_peak:-0}")/s · Avg $(format_bytes "${_avg:-0}")/s\n"
+    _msg+="👥 $(get_active_connections) live now\n"
+    if [ "${_n:-0}" -gt 0 ]; then
+        _msg+="\n_from ${_n} sample(s) over $(format_duration "${_span:-0}")_\n"
+    else
+        _msg+="\n_No history recorded yet._\n"
+    fi
+
+    local _spark
+    _spark=$(_tg_spark "$(history_hourly "$_win_s" "$_now")")
+    # Inline, not fenced. The glyphs are block elements, which are drawn as a
+    # tiling set and share an advance width in a proportional font, so the
+    # sparkline stays aligned without a fence — and a fence would wrap it in a
+    # monospace box with a copy button, which is the wrong shape for a chart.
+    # Not passed through _esc either: the glyphs contain no Markdown
+    # metacharacter, and escaping would render literal backslashes.
+    [ -n "$_spark" ] && _msg+="\n📉 ${_spark}\n"
+
+    local _top _l _b
+    _top=$(history_top "$_win_s" "$_now" 5)
+    if [ -n "$_top" ]; then
+        _msg+="\n🏆 *Top talkers*\n"
+        while IFS='|' read -r _l _b; do
+            [ -z "$_l" ] && continue
+            _msg+="👤 $(_esc "$_l"): $(format_bytes "${_b:-0}")\n"
+        done <<< "$_top"
+    fi
+
+    _kb_reset
+    _kb_row "$([ "$win" = "24h" ] && printf '24h ✓|t:w:24h' || printf '24h|t:w:24h')" \
+            "$([ "$win" = "7d" ] && printf '7d ✓|t:w:7d' || printf '7d|t:w:7d')" \
+            "$([ "$win" = "30d" ] && printf '30d ✓|t:w:30d' || printf '30d|t:w:30d')"
+    _kb_row "🔄 Refresh|t:w:${win}" "🏠 Menu|m"
+    _cb_edit "$_msg" "$(_kb_json)"
+}
+
+_cb_render_engine() {
+    local _m _msg
+    _m=$(_tg_metrics_raw)
+    _msg="🩺 *Engine*\n\n"
+    if [ -z "$_m" ]; then
+        _msg+="Metrics unavailable.\n"
+    else
+        _msg+=$(printf '%s' "$_m" | awk '
+            function v(n,   i) { return (n in m) ? m[n] : 0 }
+            /^telemt_uptime_seconds /        { m["up"]=$NF }
+            /^telemt_connections_total /     { m["tot"]=$NF }
+            /^telemt_connections_bad_total / { m["bad"]=$NF }
+            /^telemt_connections_current /   { m["cur"]=$NF }
+            /^telemt_upstream_connect_success_total / { m["oks"]=$NF }
+            /^telemt_upstream_connect_fail_total /    { m["fai"]=$NF }
+            END {
+                bad = (v("tot") > 0) ? (v("bad") * 100.0 / v("tot")) : 0
+                att = v("oks") + v("fai")
+                ok  = (att > 0) ? (v("oks") * 100.0 / att) : 100
+                printf "👥 live %d · total %d\n", v("cur"), v("tot")
+                printf "⚠️ bad handshakes %.1f%%\n", bad
+                printf "🔗 upstream success %.1f%%\n", ok
+            }')
+        _msg+=$'\n'
+    fi
+    _kb_reset
+    _kb_row "🔄 Refresh|y"        "$(_cb_can y d && printf '📊 Digest|y:d')"
+    _kb_row "$(_cb_can y p && printf '🌐 Upstreams|y:p')" "$(_cb_can y f && printf '🛰 Fleet|y:f')"
+    _kb_row "$(_cb_can y v && printf '🎟 Vouchers|y:v')"  "$(_cb_can y u && printf '⬆️ Updates|y:u')"
+    _kb_row "🏠 Menu|m"
+    _cb_edit "$_msg" "$(_kb_json)"
+}
+
+# The posture half of what /mp_digest used to render. The three load_*() calls
+# the old handler made are manager-only and were silent no-ops inside the daemon
+# — so it advertised an SSL Shield and a Cloud Backup status it could never
+# actually read. Only the settings the daemon genuinely loads are shown.
+_cb_render_digest() {
+    local _ip _up=0 _rc=0 _st _qos _hh _msg
+    _ip=$(get_cached_ip)
+    is_proxy_running && { _up=$(get_container_uptime); _rc=$(get_active_connections); }
+    _st="🟢 NORMAL"; [ "${LOCKDOWN_MODE:-false}" = "true" ] && _st="🔴 LOCKDOWN ACTIVE"
+    _qos="off"; [ "${QOS_LIMIT_MBPS:-0}" -gt 0 ] 2>/dev/null && _qos="${QOS_LIMIT_MBPS} Mbps/IP"
+    _hh="off"; [ -n "${HAPPY_HOURS_WINDOW:-}" ] && _hh="${HAPPY_HOURS_WINDOW}"
+
+    local _total=0 _active=0 _l _en _rest
+    while IFS='|' read -r _l _s _c _en _rest; do
+        [[ "$_l" =~ ^# ]] && continue
+        [ -z "$_l" ] && continue
+        _total=$(( _total + 1 ))
+        [ "$_en" = "true" ] && _active=$(( _active + 1 ))
+    done < "$SECRETS_FILE"
+
+    _msg="📊 *Digest*\n\n"
+    _msg+="🖥 Server: \`$(_esc "${_ip:-unknown}")\` (port ${PROXY_PORT:-?})\n"
+    _msg+="⚡️ Posture: ${_st}\n"
+    _msg+="⏱ Uptime: $(format_duration "${_up:-0}")\n"
+    _msg+="🔌 Connections: ${_rc} live\n"
+    _msg+="🏎 QoS shaping: ${_qos}\n"
+    _msg+="🕒 Happy hours: ${_hh}\n"
+    _msg+="🎫 Secrets: ${_active} active of ${_total}\n"
+    _msg+="📈 Total traffic: ↓ $(format_bytes "${_cum_out:-0}") ↑ $(format_bytes "${_cum_in:-0}")"
+    _kb_reset
+    _kb_row "◀ Back|y" "🏠 Menu|m"
+    _cb_edit "$_msg" "$(_kb_json)"
+}
+
+_cb_render_upstreams() {
+    local uf="${INSTALL_DIR}/upstreams.conf" _msg="🌐 *Upstreams*\n"
+    if [ ! -f "$uf" ]; then
+        _msg+="\n🟢 direct — all traffic leaves from this server."
+    else
+        local name type addr user pass weight iface enabled icon
+        while IFS='|' read -r name type addr user pass weight iface enabled; do
+            [[ "$name" =~ ^# ]] && continue
+            [ -z "$name" ] && continue
+            # Backward compat: the old 7-column layout kept `enabled` in field 7.
+            if [ "$iface" = "true" ] || [ "$iface" = "false" ]; then enabled="$iface"; iface=""; fi
+            icon="🟢"; [ "$enabled" != "true" ] && icon="🔴"
+            _msg+="\n${icon} *$(_esc "$name")* — ${type}"
+            [ -n "$addr" ] && _msg+=" \`$(_esc "$addr")\`"
+            [ -n "$iface" ] && _msg+=" [${iface}]"
+            _msg+=" · weight ${weight:-?}"
+        done < "$uf"
+    fi
+    _kb_reset
+    _kb_row "◀ Back|y" "🏠 Menu|m"
+    _cb_edit "$_msg" "$(_kb_json)"
+}
+
+_cb_render_fleet() {
+    local out
+    out=$("${INSTALL_DIR}/mtproxymax" fleet status 2>/dev/null | sed 's/\x1b\[[0-9;]*m//g')
+    local _msg="🛰 *Fleet*" _n=0 _f _h _ip _users _traffic _load
+    if [ -n "$out" ]; then
+        while IFS= read -r _f; do
+            case "$_f" in ""|HOSTNAME*|*"---"*) continue ;; esac
+            read -r _h _ip _users _traffic _load _ <<< "$_f"
+            [ -z "$_h" ] && continue
+            _msg+="\n🟢 *$(_esc "$_h")*"
+            [ -n "$_ip" ] && _msg+=" — \`$(_esc "$_ip")\`"
+            [ -n "$_users" ] && _msg+=" · 👥 ${_users}"
+            [ -n "$_traffic" ] && _msg+=" · 📊 ${_traffic}"
+            _n=$(( _n + 1 ))
+        done <<< "$out"
+    fi
+    [ "$_n" -eq 0 ] && _msg+="\n\n_No multi-server telemetry collected yet._"
+    _kb_reset
+    _kb_row "◀ Back|y" "🏠 Menu|m"
+    _cb_edit "$_msg" "$(_kb_json)"
+}
+
+_cb_render_vouchers() {
+    local body _msg
+    body=$(_tg_voucher_lines)
+    if [ -n "$body" ]; then
+        _msg="🎟 *Active vouchers*${body}"
+    else
+        _msg="🎟 *Active vouchers*\n\n_None yet. Create them from the CLI with_ \`mtproxymax voucher create\`_._"
+    fi
+    _kb_reset
+    _kb_row "◀ Back|y" "🏠 Menu|m"
+    _cb_edit "$_msg" "$(_kb_json)"
+}
+
+# The update check is read-only; applying it is a separate, confirmed action.
+_cb_render_update() {
+    local out="$1" _msg="⬆️ *Updates*" _l
+    if [ -n "$out" ]; then
+        while IFS= read -r _l; do
+            [ -z "$_l" ] && continue
+            _msg+="\n• $(_esc "$_l")"
+        done <<< "$out"
+    else
+        _msg+="\n\n_No output from the update check._"
+    fi
+    _kb_reset
+    _kb_row "$(_cb_can a update && printf '⬆️ Apply update|a:update:_')"
+    _kb_row "◀ Back|y" "🏠 Menu|m"
+    _cb_edit "$_msg" "$(_kb_json)"
+}
+
+# Everything that needs typed input, plus the three global verbs. The global
+# verbs are targetless, so they carry "_" where a secret label would go; the
+# dispatcher special-cases that placeholder for these verbs ONLY, so a secret
+# genuinely called "_" keeps working.
+_cb_render_tools() {
+    local _msg="🛠 *Tools*\n\n_Each of these needs something typed, or affects the whole server._"
+    _kb_reset
+    _kb_row "$(_cb_can g a && printf '➕ Add user|g:a')"   "$(_cb_can g b && printf '📢 Broadcast|g:b')"
+    _kb_row "$(_cb_can a rotall && printf '♻️ Rotate all|a:rotall:_')"
+    if [ "${LOCKDOWN_MODE:-false}" = "true" ]; then
+        _cb_can a lockdown && _kb_row "🔓 Lift lockdown|a:lockdown:off"
+    else
+        _cb_can a lockdown && _kb_row "🔒 Lockdown|a:lockdown:on"
+    fi
+    _kb_row "$(_cb_can a restart && printf '🔄 Restart proxy|a:restart:_')" \
+            "$(_cb_can a update  && printf '⬆️ Apply update|a:update:_')"
+    _kb_row "🏠 Menu|m"
+    _cb_edit "$_msg" "$(_kb_json)"
+}
+
+_cb_render_settings() {
+    local _msg="⚙️ *Settings*\n\n"
+    _msg+="🔌 Port: \`${PROXY_PORT:-?}\`\n"
+    _msg+="🌐 Domain: \`$(_esc "${PROXY_DOMAIN:-?}")\`\n"
+    _msg+="📊 Metrics port: \`${PROXY_METRICS_PORT:-?}\`\n"
+    _msg+="⏱ Report interval: ${TELEGRAM_INTERVAL:-6}h\n"
+    _kb_reset
+    _kb_row "🏠 Menu|m"
+    _cb_edit "$_msg" "$(_kb_json)"
+}
+
+# Send the connect link and QR as a NEW message rather than editing: an inline
+# keyboard cannot carry a photo, so the QR has to go out separately.
+_cb_send_link() {
+    local label="$1"
+    ! _cb_secret_exists "$label" && { _CB_TOAST="Secret '$label' not found"; return 1; }
+    local _secret _ip _dh _fs
+    _secret=$(grep -E "^${label}\|" "$SECRETS_FILE" 2>/dev/null | head -1 | cut -d'|' -f2)
+    _ip=$(get_cached_ip)
+    [ -z "$_ip" ] && { _CB_TOAST="Cannot detect the server IP"; return 1; }
+    if [ "${MASKING_ENABLED:-true}" != "false" ]; then
+        _dh=$(domain_to_hex "${PROXY_DOMAIN:-cloudflare.com}")
+        _fs="ee${_secret}${_dh}"
+    else
+        _fs="dd${_secret}"
+    fi
+    _CB_TOAST="Link sent"
+    send_proxy_qr_to "$_CB_CHAT" "$_ip" "${PROXY_PORT}" "$_fs"
+}
+
+# The standard button bar attached to ordinary command replies. Inline buttons
+# carry their message implicitly via callback_query.message.message_id, so a
+# reply becomes a live dashboard with no stored message id and no session
+# state. Filtered by the requesting chat's role, so a reply never advertises a
+# button its reader cannot use.
+_tg_button_bar() {
+    local chat="$1"
+    _UI_ROLE="$(_check_tg_role "$chat")"
+    _kb_reset
+    _kb_row "$(_cb_can u l && printf '👥 Users|u:l:0')" "$(_cb_can t && printf '📈 Traffic|t')"
+    _kb_row "$(_cb_can y && printf '🩺 Health|y')" "🏠 Menu|m"
+    _kb_json
+}
+
+# ── Dispatch ────────────────────────────────────────────────────────────────
+_cb_dispatch() {
+    local role cap need have
+    if ! _cb_dec "$_CB_DATA"; then
+        _CB_TOAST="This menu is out of date — send /menu"
+        return 1
+    fi
+    load_tg_settings
+    role=$(_check_tg_role "$_CB_CHAT")
+    _UI_ROLE="$role"
+
+    # Track the chatter so /mp_broadcast reaches button-only users too.
+    if [ -n "$_CB_CHAT" ]; then
+        mkdir -p "$INSTALL_DIR" 2>/dev/null || true
+        grep -q "^${_CB_CHAT}$" "${INSTALL_DIR}/bot_users.txt" 2>/dev/null || \
+            echo "$_CB_CHAT" >> "${INSTALL_DIR}/bot_users.txt" 2>/dev/null || true
+    fi
+
+    cap=$(_tg_cap_for "$_CB_NS" "$_CB_ACT")
+    if [ -z "$cap" ]; then
+        _CB_TOAST="This menu is out of date — send /menu"
+        return 1
+    fi
+    need=$(_tg_cap_rank "$cap")
+    have=$(_tg_role_rank "$role")
+    if [ "$have" -lt "$need" ]; then
+        if [ "$role" = "none" ]; then
+            # Unauthenticated: answer, change nothing, log nothing — the same
+            # silent refusal _process_cmd gives.
+            _CB_TOAST=""
+            return 1
+        fi
+        _tg_security_log "$_CB_CHAT" "callback ${_CB_NS}:${_CB_ACT}${_CB_TGT:+:}${_CB_TGT}"
+        _CB_TOAST="Permission denied"
+        _CB_ALERT="true"
+        return 1
+    fi
+
+    case "$_CB_NS" in
+        n) : ;;   # page indicator: acknowledge, leave the message alone
+        m)
+            if [ "$_CB_ACT" = "h" ]; then _cb_render_help; else _cb_render_hub; fi
+            ;;
+        u)
+            case "$_CB_ACT" in
+                l) _cb_render_user_list "${_CB_TGT:-0}" ;;
+                s) _cb_render_user_detail "$_CB_TGT" "${_CB_PAGE:-0}" ;;
+                k) _cb_send_link "$_CB_TGT" ;;
+                m) _cb_render_user_manage "$_CB_TGT" "${_CB_PAGE:-0}" ;;
+                t) _cb_render_user_traffic "$_CB_TGT" "${_CB_PAGE:-0}" ;;
+                *) _CB_TOAST="Unknown action" ;;
+            esac
+            ;;
+        e)
+            # One namespace for "edit a property of this secret". The page slot
+            # is the origin card for the pickers and the field code for the
+            # custom-value prompt, so it is read per action rather than once.
+            case "$_CB_ACT" in
+                q|c|i|x|r) _cb_render_limits "$_CB_ACT" "$_CB_TGT" "${_CB_PAGE:-0}" ;;
+                z) _cb_prompt_custom_limit "$_CB_TGT" "${_CB_PAGE:-}" ;;
+                t) _cb_render_tpl_picker "$_CB_TGT" "${_CB_PAGE:-0}" ;;
+                n) ! _cb_secret_exists "$_CB_TGT" && { _CB_TOAST="Secret not found"; } || \
+                   _tg_pending_prompt "$_CB_CHAT" "note" "$_CB_TGT" \
+                       "📝 *Note for $(_esc "$_CB_TGT")*\n\nSend the text to store. Send \`-\` to clear it." ;;
+                a) ! _cb_secret_exists "$_CB_TGT" && { _CB_TOAST="Secret not found"; } || \
+                   _tg_pending_prompt "$_CB_CHAT" "adtag" "$_CB_TGT" \
+                       "🏷 *Ad-tag for $(_esc "$_CB_TGT")*\n\nSend the 32-hex tag from \@MTProxybot, or \`clear\` to fall back to the global tag." ;;
+                *) _CB_TOAST="Unknown action" ;;
+            esac
+            ;;
+        a) _cb_render_confirm "$_CB_ACT" "$_CB_TGT" "${_CB_PAGE:-0}" ;;
+        c) _cb_exec_action "$_CB_ACT" "$_CB_TGT" "${_CB_PAGE:-0}" ;;
+        p)
+            # The prompt's own Cancel button. It clears whatever is armed for
+            # THIS chat and nothing else — _CB_CHAT comes from the callback,
+            # which Telegram authenticates, never from callback_data.
+            _tg_pending_clear "$_CB_CHAT"
+            _CB_TOAST="Cancelled"
+            ;;
+        g)
+            case "$_CB_ACT" in
+                a) _tg_pending_prompt "$_CB_CHAT" "add" "-" "➕ *Add a user*\n\nSend the new secret's label." ;;
+                b) _tg_pending_prompt "$_CB_CHAT" "broadcast" "-" "📢 *Broadcast*\n\nSend the message to deliver to every known bot user." ;;
+                "") _cb_render_tools ;;
+                *) _CB_TOAST="Unknown action" ;;
+            esac
+            ;;
+        k)
+            case "$_CB_ACT" in
+                "")  _cb_render_tpl_list ;;
+                e)   _cb_render_tpl_edit "$_CB_TGT" "${_CB_PAGE:-0}" ;;
+                p)   _cb_render_tpl_field "$_CB_TGT" "${_CB_PAGE:-}" ;;
+                s)   _cb_render_tpl_apply_picker "$_CB_TGT" "${_CB_PAGE:-0}" ;;
+                a)   _cb_render_tpl_apply_picker "$_CB_TGT" "${_CB_PAGE:-0}" ;;
+                d)   _cb_render_confirm "tpldel" "$_CB_TGT" "${_CB_PAGE:-0}" ;;
+                n)   _tg_pending_prompt "$_CB_CHAT" "tplnew" "-" "🧩 *New template*\n\nSend a name (letters, digits, '_', '-'), and optionally the values on the same line: \`name conns ips quota expires\`." ;;
+                *)   _CB_TOAST="Unknown action" ;;
+            esac
+            ;;
+        t) _cb_render_traffic "${_CB_TGT:-24h}" ;;
+        y)
+            case "$_CB_ACT" in
+                "")  _cb_render_engine ;;
+                d)   _cb_render_digest ;;
+                p)   _cb_render_upstreams ;;
+                f)   _cb_render_fleet ;;
+                v)   _cb_render_vouchers ;;
+                # Read-only: the CLI's `update` APPLIES the update, so the check
+                # only reports what is installed and offers the apply button.
+                u)   _cb_render_update "Installed version: ${VERSION}" ;;
+                *)   _CB_TOAST="Unknown action" ;;
+            esac
+            ;;
+        s) _cb_render_settings ;;
+        *) _CB_TOAST="This menu is out of date — send /menu" ;;
+    esac
+    return 0
+}
+
+# Callback-query entry point. Bash has no `finally`, so answering is made
+# structural rather than a discipline: _cb_dispatch never answers, and the
+# exactly-one answer below runs on every path — including denial, a stale
+# menu, and an unknown namespace. Without it the client spins forever.
+_process_callback() {
+    _CB_CHAT="$1"; _CB_MID="$2"; _CB_ID="$3"; _CB_DATA="$4"
+    _CB_TOAST=""; _CB_ALERT="false"
+    _cb_dispatch || true
+    tg_answer_cb "$_CB_ID" "$_CB_TOAST" "$_CB_ALERT"
+}
+# >>> TG_FMT_BEGIN
+# ── Reply formatting ────────────────────────────────────────────────────────
+#
+# Command replies used to dump CLI output into a Markdown code fence, which
+# Telegram draws as a monospace box with a copy button. That is the wrong shape
+# for a status reply: it reads as pasted console output, it cannot wrap, and it
+# puts a tap target on every line.
+#
+# The replacement is one line per fact. Alignment by padding is not available —
+# `printf "%-14s"` pads with letters, and letters do not have a uniform advance
+# width in a proportional font, so padded columns collapse outside a fence. The
+# block-element glyphs used for bars and sparklines are a different case: they
+# are drawn as a tiling set and DO share an advance width, which is why the
+# charts can stay inline.
+
+# "  Key:            value" -> "✅ *Key*: value", one line each. The padding is
+# decorative, so dropping it costs nothing; the key/value pairs are the data.
+_tg_kv_lines() {
+    local _line _k _v _icon _n=0
+    while IFS= read -r _line; do
+        [ -z "$_line" ] && continue
+        [[ "$_line" =~ ^[[:space:]]*([^:]+):[[:space:]]*(.*)$ ]] || continue
+        _k="${BASH_REMATCH[1]}"
+        _v="${BASH_REMATCH[2]}"
+        # Trim the padding printf added between the key and the colon.
+        _k="${_k%"${_k##*[![:space:]]}"}"
+        [ -z "$_k" ] && continue
+        case "$_v" in
+            *fail*|*Fail*|*FAIL*|*error*|*Error*|*down*|*Down*|*stopped*|*not\ running*)
+                _icon="❌" ;;
+            *warn*|*Warn*|*WARN*|*degraded*|*slow*)
+                _icon="⚠️" ;;
+            *) _icon="✅" ;;
+        esac
+        printf '\n%s *%s*: %s' "$_icon" "$(_esc "$_k")" "$(_esc "$_v")"
+        _n=$(( _n + 1 ))
+    done
+    [ "$_n" -gt 0 ]
+}
+
+# Active vouchers as one line each, read from vouchers.conf rather than parsed
+# out of the CLI's padded table — the source of truth for both the list reply
+# and the create reply, and it needs no column alignment to be re-derived.
+#
+# skip_first drops the rows that already existed before a create, so the reply
+# shows the codes that were just generated instead of the whole inventory.
+_tg_voucher_lines() {
+    local skip_first="${1:-0}" f="${INSTALL_DIR}/vouchers.conf" _n=0
+    local _code _quota _days _conns _ips _tier _status _created _by _at
+    [ -f "$f" ] || return 0
+    while IFS='|' read -r _code _quota _days _conns _ips _tier _status _created _by _at; do
+        [ -z "$_code" ] && continue
+        [ "$_status" != "ACTIVE" ] && continue
+        _n=$(( _n + 1 ))
+        [ "$_n" -le "$skip_first" ] && continue
+        # The code goes inside a Markdown span, so anything outside the code
+        # alphabet would either break the span or inject formatting.
+        _code=$(printf '%s' "$_code" | tr -cd 'A-Za-z0-9-')
+        [ -z "$_code" ] && continue
+        printf '\n🎟 `%s`' "$_code"
+        [ -n "$_quota" ] && [ "$_quota" != "0" ] && printf ' · %s' "$(format_bytes "$_quota")"
+        [ -n "$_days" ] && [ "$_days" != "0" ] && printf ' · %sd' "$_days"
+        [ -n "$_tier" ] && [ "$_tier" != "standard" ] && printf ' · %s' "$_tier"
+    done < "$f"
+}
+
+# How many ACTIVE rows vouchers.conf holds, so a create can report only the new
+# ones. Counted before the create runs.
+_tg_voucher_count() {
+    local f="${INSTALL_DIR}/vouchers.conf" _status
+    [ -f "$f" ] || { printf '0'; return 0; }
+    local _c=0
+    while IFS='|' read -r _code _q _d _cn _i _t _status _cr _by _at; do
+        [ -z "$_code" ] && continue
+        [ "$_status" = "ACTIVE" ] && _c=$(( _c + 1 ))
+    done < "$f"
+    printf '%s' "$_c"
+}
+# <<< TG_FMT_END
+
+# <<< TG_MENU_END
+
+# >>> TG_HISTORY_BEGIN
+# ── Rolling traffic history ─────────────────────────────────────────────────
+#
+# Two append-only files under relay_stats/history/:
+#
+#   global.tsv   epoch|in_delta|out_delta|conns|marker
+#   users.tsv    epoch|label|in_delta|out_delta   (sparse: only non-zero rows)
+#
+# DELTAS, not cumulative counters. A cumulative record goes stale the moment
+# the engine restarts or a traffic reset rewinds the counters, forcing every
+# reader to re-implement restart detection. With deltas a reset just yields a
+# smaller bucket, and a windowed sum is `t >= start { s += $2 }`.
+#
+# Only ONE writer (this daemon) appends, so appends need no lock; only the
+# read-modify-write in _history_prune does.
+#
+# Marker column: "-" normal, "R" engine restart, "X" traffic reset.
+HISTORY_DIR="${INSTALL_DIR}/relay_stats/history"
+
+_bucket_in=0
+_bucket_out=0
+_bucket_conns=0
+_bucket_marker="-"
+_prev_uptime=0
+declare -A _bucket_user_in _bucket_user_out
+
+_history_init() {
+    mkdir -p "$HISTORY_DIR" 2>/dev/null || true
+    [ -f "$HISTORY_DIR/global.tsv" ] || : > "$HISTORY_DIR/global.tsv" 2>/dev/null || true
+    [ -f "$HISTORY_DIR/users.tsv" ] || : > "$HISTORY_DIR/users.tsv" 2>/dev/null || true
+}
+
+_history_zero_buckets() {
+    _bucket_in=0; _bucket_out=0; _bucket_conns=0; _bucket_marker="-"
+    local _k
+    for _k in "${!_bucket_user_in[@]}";  do _bucket_user_in["$_k"]=0; done
+    for _k in "${!_bucket_user_out[@]}"; do _bucket_user_out["$_k"]=0; done
+}
+
+# Flush the accumulated buckets as one sample and reset them. Called on its own
+# timer, so the bucket window matches the sample interval rather than the 60s
+# traffic tick.
+history_sample() {
+    local epoch="${1:-$(date +%s)}"
+    _history_init
+    printf '%s|%s|%s|%s|%s\n' "$epoch" "${_bucket_in:-0}" "${_bucket_out:-0}" \
+        "${_bucket_conns:-0}" "${_bucket_marker:--}" >> "$HISTORY_DIR/global.tsv" 2>/dev/null
+    local _l _di _do
+    for _l in "${!_bucket_user_in[@]}"; do
+        _di="${_bucket_user_in[$_l]:-0}"; _do="${_bucket_user_out[$_l]:-0}"
+        [ "${_di:-0}" -eq 0 ] 2>/dev/null && [ "${_do:-0}" -eq 0 ] 2>/dev/null && continue
+        printf '%s|%s|%s|%s\n' "$epoch" "$_l" "$_di" "$_do" >> "$HISTORY_DIR/users.tsv" 2>/dev/null
+    done
+    _history_zero_buckets
+}
+
+# "cur_in|cur_out|prev_in|prev_out|pct|peak_bps|avg_bps|samples|span_s"
+#
+# pct is -1 when the previous window holds nothing, never inf/nan — a formatter
+# downstream would choke on those. peak uses the ACTUAL gap between samples,
+# not the nominal interval, so a daemon outage shows as a real gap rather than
+# a phantom spike; avg divides by the span actually covered, so a 7-day query
+# against 3 hours of history reports honestly instead of inflating.
+history_summary() {
+    local win="$1" now="$2"
+    local f="$HISTORY_DIR/global.tsv"
+    [ -f "$f" ] || { printf '0|0|0|0|n/a|0|0|0|0'; return 0; }
+    awk -F'|' -v win="$win" -v now="$now" '
+        {
+            t = $1 + 0
+            if (t > now) next
+            if (t >= now - win) {
+                ci += $2; co += $3; cn++
+                if (fs == "" || t < fs) fs = t
+                if (t > ls) ls = t
+            } else if (t >= now - 2 * win) { pi += $2; po += $3 }
+            if (pt != "" && t > pt) {
+                d = ($2 + $3) / (t - pt)
+                if (t >= now - win && d > peak) peak = d
+            }
+            pt = t
+        }
+        END {
+            # "n/a" rather than a numeric sentinel: -1 would be indistinguishable
+            # from a genuine 1%% decrease, and inf/nan would break the formatter.
+            pct = "n/a"
+            if (pi + po > 0) pct = int(((ci + co) - (pi + po)) * 100 / (pi + po)) ""
+            span = (ls > fs) ? (ls - fs) : 0
+            avg = (span > 0) ? int((ci + co) / span) : 0
+            printf "%d|%d|%d|%d|%s|%d|%d|%d|%d\n", ci, co, pi, po, pct, peak, avg, cn, span
+        }
+    ' "$f" 2>/dev/null || printf '0|0|0|0|n/a|0|0|0|0'
+}
+
+# A single-line sparkline for the hourly series. The bar glyphs are passed as a
+# SPACE-separated string and split on that, never on "" — splitting a multibyte
+# string into characters is locale-dependent, and under a C locale `substr`
+# would slice a 3-byte bar glyph in half and emit mojibake.
+_tg_spark() {
+    local vals="$1"
+    [ -n "$vals" ] || return 0
+    awk -v v="$vals" -v b="▁ ▂ ▃ ▄ ▅ ▆ ▇ █" '
+        BEGIN {
+            n = split(v, a, " "); nb = split(b, BAR, " ")
+            max = 0
+            for (i = 1; i <= n; i++) if (a[i] + 0 > max) max = a[i] + 0
+            out = ""
+            for (i = 1; i <= n; i++) {
+                if (max <= 0) { out = out BAR[1]; continue }
+                idx = int(a[i] * (nb - 1) / max) + 1
+                if (idx < 1) idx = 1
+                if (idx > nb) idx = nb
+                out = out BAR[idx]
+            }
+            printf "%s", out
+        }'
+}
+
+# Format a period-over-period figure. "n/a" means the previous window was empty
+# and prints nothing at all, rather than a misleading ▲0%.
+_tg_pct_str() {
+    local p="$1"
+    [[ "$p" =~ ^-?[0-9]+$ ]] || return 0
+    if   [ "$p" -gt 0 ]; then printf '  ▲%d%%' "$p"
+    elif [ "$p" -lt 0 ]; then printf '  ▼%d%%' "$(( -p ))"
+    else printf '  ▬0%%'
+    fi
+}
+
+# "label|in|out" for every requested label, in the order requested, in ONE awk
+# pass — a page of six users must not cost six scans. A label with no history
+# reports 0|0 rather than going missing.
+history_users() {
+    local win="$1" now="$2"; shift 2
+    [ "$#" -gt 0 ] || return 0
+    local f="$HISTORY_DIR/users.tsv" _l want=""
+    for _l in "$@"; do want="${want}${_l} "; done
+    if [ ! -f "$f" ]; then
+        for _l in "$@"; do printf '%s|0|0\n' "$_l"; done
+        return 0
+    fi
+    # NOTE: the accumulators must not be named i/o — awk forbids one name being
+    # both a scalar and an array, and the BEGIN loop already uses i as a counter.
+    awk -F'|' -v win="$win" -v now="$now" -v want="$want" '
+        BEGIN { n = split(want, a, " "); for (i = 1; i <= n; i++) if (a[i] != "") { W[a[i]] = 1; ord[++m] = a[i] } }
+        { t = $1 + 0; if (t < now - win || t > now) next
+          if ($2 in W) { accI[$2] += $3; accO[$2] += $4 } }
+        END { for (k = 1; k <= m; k++) printf "%s|%d|%d\n", ord[k], accI[ord[k]] + 0, accO[ord[k]] + 0 }
+    ' "$f" 2>/dev/null
+}
+
+# 24 space-separated bucket totals across the window, oldest first.
+history_hourly() {
+    local win="$1" now="$2"
+    local f="$HISTORY_DIR/global.tsv"
+    [ -f "$f" ] || { local _o="0" _i; for (( _i = 1; _i < 24; _i++ )); do _o="${_o} 0"; done; printf '%s' "$_o"; return 0; }
+    awk -F'|' -v win="$win" -v now="$now" '
+        BEGIN { n = 24; w = win / n; for (i = 0; i < n; i++) b[i] = 0 }
+        { s = now - win; t = $1 + 0
+          if (t < s || t > now) next
+          idx = int((t - s) / w)
+          if (idx < 0) idx = 0
+          if (idx > n - 1) idx = n - 1
+          b[idx] += $2 + $3 }
+        END { out = ""; for (i = 0; i < n; i++) out = out (i ? " " : "") b[i] + 0; print out }
+    ' "$f" 2>/dev/null
+}
+
+# One user's series across the window, bucketed the same way history_hourly
+# buckets the global one, so _tg_spark consumes either unchanged.
+#
+# A label with no rows yields ZEROS rather than an empty string: the card draws
+# a flat line for a quiet account, and an empty string would silently drop the
+# sparkline row instead. The filter is on the label column, so one user's rows
+# can never be counted for another.
+history_user_series() {
+    local label="$1" win="$2" now="$3" n="${4:-24}"
+    local f="$HISTORY_DIR/users.tsv"
+    [ -f "$f" ] || { local _o="0" _i; for (( _i = 1; _i < n; _i++ )); do _o="${_o} 0"; done; printf '%s' "$_o"; return 0; }
+    awk -F'|' -v win="$win" -v now="$now" -v n="$n" -v who="$label" '
+        BEGIN { w = win / n; for (i = 0; i < n; i++) b[i] = 0 }
+        { if ($2 != who) next
+          s = now - win; t = $1 + 0
+          if (t < s || t > now) next
+          idx = int((t - s) / w)
+          if (idx < 0) idx = 0
+          if (idx > n - 1) idx = n - 1
+          b[idx] += $3 + $4 }
+        END { out = ""; for (i = 0; i < n; i++) out = out (i ? " " : "") b[i] + 0; print out }
+    ' "$f" 2>/dev/null || printf '0'
+}
+
+# "label|bytes", heaviest first. One awk plus one sort, whatever the user count.
+history_top() {
+    local win="$1" now="$2" n="${3:-3}"
+    local f="$HISTORY_DIR/users.tsv"
+    [ -f "$f" ] || return 0
+    awk -F'|' -v win="$win" -v now="$now" '
+        { t = $1 + 0; if (t < now - win || t > now) next; s[$2] += $3 + $4 }
+        END { for (k in s) printf "%s|%d\n", k, s[k] }
+    ' "$f" 2>/dev/null | sort -t'|' -k2 -rn | head -n "$n"
+}
+
+# Drop samples older than the retention window. This is the only read-modify-
+# write against the store, so it takes a lock — on fd 8, NOT the fd 9 that
+# save_traffic holds, because bash file descriptors are process-global and
+# reusing 9 here would close the traffic lock mid-critical-section.
+#
+# A `command -v flock` guard is not sufficient on its own: busybox ships a flock
+# applet, so the guard passes, and it is specifically `-w` that busybox lacks.
+# The lock call then failed, this loop `continue`d, and the prune did nothing at
+# all on Alpine — silently, so global.tsv grew without bound and the retention
+# setting was quietly not honoured. Fall back to `-n`, which busybox does
+# support, rather than trusting that the binary's presence implies the flags.
+#
+# `exec` here is redirection-only, so it applies to the whole shell: a trailing
+# 2>/dev/null would silence stderr for the rest of the process, not just for
+# this line, which is why none of these carry one.
+history_prune() {
+    local days="$1" now="${2:-$(date +%s)}"
+    local cutoff=$(( now - days * 86400 ))
+    _history_init
+    local f tmp
+    for f in "$HISTORY_DIR/global.tsv" "$HISTORY_DIR/users.tsv"; do
+        [ -f "$f" ] || continue
+        exec 8>"$HISTORY_DIR/.history.lock" || continue
+        if command -v flock &>/dev/null; then
+            flock -w 5 8 2>/dev/null ||
+                flock -n 8 2>/dev/null ||
+                { exec 8>&-; continue; }
+        fi
+        tmp=$(mktemp "$HISTORY_DIR/.prune.XXXXXX" 2>/dev/null)
+        if [ -n "$tmp" ]; then
+            chmod 600 "$tmp" 2>/dev/null
+            awk -F'|' -v c="$cutoff" '$1 + 0 >= c' "$f" > "$tmp" 2>/dev/null
+            mv "$tmp" "$f" 2>/dev/null || rm -f "$tmp"
+        fi
+        exec 8>&-
+    done
+}
+# <<< TG_HISTORY_END
+
+# >>> TG_REPORT_BEGIN
+# The periodic report.
+#
+# The previous version sent the same three facts every interval — uptime, live
+# connections, and two LIFETIME cumulative totals — whether or not anything had
+# happened. That is monotonically less informative as uptime grows: the numbers
+# only ever get bigger, and it can never answer "how much moved today, and is
+# that more or less than yesterday?".
+#
+# This reports a WINDOW instead, and adapts: with no traffic at all in the
+# window it collapses to a one-line heartbeat, because a full dashboard of
+# zeroes every six hours is noise. TELEGRAM_REPORT_DETAIL forces either
+# behaviour ('full' or 'summary'); 'auto' decides from the data.
+_tg_periodic_report() {
+    local now="$1" win="${2:-86400}"
+    local _ci _co _pi _po _pct _peak _avg _n _span
+    IFS='|' read -r _ci _co _pi _po _pct _peak _avg _n _span <<< "$(history_summary "$win" "$now")"
+    _ci=${_ci:-0}; _co=${_co:-0}
+
+    local _label="${TELEGRAM_SERVER_LABEL:-MTProxyMax}"
+    local _up _live
+    _up=$(get_uptime)
+    _live=$(get_active_connections)
+    local _detail="${TELEGRAM_REPORT_DETAIL:-auto}"
+    local _idle=0
+    [ "$_ci" -eq 0 ] && [ "$_co" -eq 0 ] && _idle=1
+
+    if [ "$_detail" = "summary" ] || { [ "$_detail" = "auto" ] && [ "$_idle" -eq 1 ]; }; then
+        if [ "$_idle" -eq 1 ]; then
+            tg_send_kb "🟢 *${_label}* — alive, idle ${_n:-0} sample(s)\n⏱ $(format_duration "${_up:-0}") · 👥 ${_live} live" \
+                "$(_tg_button_bar "${TELEGRAM_CHAT_ID}")"
+        else
+            tg_send_kb "📊 *${_label}*\n\n🟢 Running · ⏱ $(format_duration "${_up:-0}")\n👥 ${_live} live · 📈 24h ↓ $(format_bytes "$_co") ↑ $(format_bytes "$_ci")" \
+                "$(_tg_button_bar "${TELEGRAM_CHAT_ID}")"
+        fi
+        return 0
+    fi
+
+    local _msg="📊 *Report — $(_esc "$_label")*\n\n"
+    _msg+="🟢 Running · ⏱ $(format_duration "${_up:-0}") · 👥 ${_live} live\n"
+    _msg+="📈 24h ↓ $(format_bytes "$_co") ↑ $(format_bytes "$_ci")$(_tg_pct_str "$_pct")\n"
+    _msg+="⚡ Peak $(format_bytes "$_peak")/s · Avg $(format_bytes "$_avg")/s\n"
+
+    local _spark
+    _spark=$(_tg_spark "$(history_hourly "$win" "$now")")
+    # Inline, not fenced — see _cb_render_traffic for why the fence bought
+    # nothing. Deliberately NOT passed through _esc: the block glyphs contain no
+    # Markdown metacharacter, and escaping would render literal backslashes.
+    [ -n "$_spark" ] && _msg+="\n📉 ${_spark}\n"
+
+    local _top _l _b _first=1
+    _top=$(history_top "$win" "$now" 3)
+    if [ -n "$_top" ]; then
+        _msg+="🏆 "
+        while IFS='|' read -r _l _b; do
+            [ -z "$_l" ] && continue
+            [ "$_first" -eq 1 ] || _msg+=" · "
+            _first=0
+            _msg+="$(_esc "$_l") $(format_bytes "${_b:-0}")"
+        done <<< "$_top"
+        _msg+="\n"
+    fi
+
+    # Quota pressure and expiry reuse the same 80/100 thresholds and the same
+    # ISO parser as the enforcement loop, so the two cannot disagree.
+    local _q80=0 _exp3=0 _seclabel _secret _created _en _mc _mi _q _ex _notes _adtag
+    if [ -f "$SECRETS_FILE" ]; then
+        while IFS='|' read -r _seclabel _secret _created _en _mc _mi _q _ex _notes _adtag || [ -n "$_seclabel" ]; do
+            [[ "$_seclabel" =~ ^# ]] && continue
+            [ -z "$_seclabel" ] && continue
+            if [ -n "$_q" ] && [ "${_q:-0}" -gt 0 ] 2>/dev/null; then
+                local _used=$(( ${_cum_user_in[$_seclabel]:-0} + ${_cum_user_out[$_seclabel]:-0} ))
+                [ $(( (_used * 100) / _q )) -ge 80 ] && _q80=$(( _q80 + 1 ))
+            fi
+            if [ -n "$_ex" ] && [ "$_ex" != "0" ]; then
+                local _ee
+                _ee=$(_iso_to_epoch "$_ex")
+                if [ "${_ee:-0}" -gt 0 ] 2>/dev/null; then
+                    local _dl=$(( (_ee - now) / 86400 ))
+                    [ "$_dl" -ge 0 ] && [ "$_dl" -le 3 ] && _exp3=$(( _exp3 + 1 ))
+                fi
+            fi
+        done < "$SECRETS_FILE"
+    fi
+    [ "$_q80" -gt 0 ] && _msg+="⚠️ ${_q80} user(s) at ≥80% quota\n"
+    [ "$_exp3" -gt 0 ] && _msg+="⏳ ${_exp3} expiring within 3 days\n"
+
+    tg_send_kb "$_msg" "$(_tg_button_bar "${TELEGRAM_CHAT_ID}")"
+}
+# <<< TG_REPORT_END
+
+# Cleanup trap for temp files
+trap _cleanup EXIT
+
+# Main loop
+echo "$$" > "$PID_FILE"
+mkdir -p "$(dirname "$OFFSET_FILE")"
+load_tg_settings
+load_traffic
+
+# Register the client-side "/" command menu via the manager, which owns the
+# command tables. Best-effort and backgrounded so a Telegram outage can never
+# delay or break the poll loop.
+"${INSTALL_DIR}/mtproxymax" telegram sync-commands &>/dev/null &
+
+_last_report=0
+_report_interval=$(( ${TELEGRAM_INTERVAL:-6} * 3600 ))
+_last_health=0
+_last_traffic_update=0
+_last_enforcement=0
+# Seeded to now so the first tick after a restart does not immediately write a
+# near-empty bucket for the seconds since the process started.
+_last_hist_sample=$(date +%s)
+_last_hist_prune=$(date +%s)
+declare -A _prev_log_in=()
+declare -A _prev_log_out=()
+
+while true; do
+    load_tg_settings
+    _report_interval=$(( ${TELEGRAM_INTERVAL:-6} * 3600 ))
+    # Update traffic counters every 60 seconds (always, even if bot is disabled)
+    _now=$(date +%s)
+    if [ $((_now - _last_traffic_update)) -ge 60 ] && is_running; then
+        _last_traffic_update=$_now
+        update_traffic 2>/dev/null
+
+        # Flush a history sample on its own coarser timer, so a bucket spans the
+        # sample interval rather than the 60s tick. This sits before the
+        # TELEGRAM_ENABLED guard below, so history keeps recording even while
+        # the bot is switched off.
+        if [ "${TELEGRAM_HISTORY_ENABLED:-true}" = "true" ] && \
+           [ $(( _now - _last_hist_sample )) -ge $(( ${TELEGRAM_HISTORY_INTERVAL_MIN:-5} * 60 )) ]; then
+            _last_hist_sample=$_now
+            history_sample "$_now"
+        fi
+        if [ "${TELEGRAM_HISTORY_ENABLED:-true}" = "true" ] && \
+           [ $(( _now - _last_hist_prune )) -ge 86400 ]; then
+            _last_hist_prune=$_now
+            history_prune "${TELEGRAM_HISTORY_RETENTION_DAYS:-7}" "$_now" &
+        fi
 
-while true; do
-    load_tg_settings
-    _report_interval=$(( ${TELEGRAM_INTERVAL:-6} * 3600 ))
-    # Update traffic counters every 60 seconds (always, even if bot is disabled)
-    _now=$(date +%s)
-    if [ $((_now - _last_traffic_update)) -ge 60 ] && is_running; then
-        _last_traffic_update=$_now
-        update_traffic 2>/dev/null
         [ "${PORTAL_ENABLED:-false}" = "true" ] && "${INSTALL_DIR}/mtproxymax" portal generate &>/dev/null
 
         # Connection log: append per-user activity (delta = current cumulative - previous cumulative)
@@ -12272,10 +15165,7 @@ while true; do
     if [ $((_now - _last_report)) -ge $_report_interval ]; then
         _last_report=$_now
         if is_running; then
-            _ri=0 _ro=0 _rc=0
-            read -r _ri _ro _rc <<< "$(get_stats)" || true
-            _up=$(get_uptime)
-            tg_send "📊 *Periodic Report*\n\n🟢 Running | ⏱ $(format_duration ${_up:-0})\n👥 Connections: ${_rc}\n📊 ↓ $(format_bytes ${_cum_out:-0}) ↑ $(format_bytes ${_cum_in:-0})"
+            _tg_periodic_report "$_now" 86400
         fi
     fi
 
@@ -14177,6 +17067,8 @@ show_cli_help() {
     echo -e "    ${GREEN}telegram setup${NC}          Run Telegram bot wizard"
     echo -e "    ${GREEN}telegram status${NC}         Show Telegram bot status"
     echo -e "    ${GREEN}telegram test${NC}           Send test message"
+    echo -e "    ${GREEN}telegram sync-commands${NC}  Refresh the in-app command menu"
+    echo -e "    ${GREEN}telegram history${NC}        Traffic history: status | prune | reset"
     echo -e "    ${GREEN}broadcast <msg>${NC}         Broadcast announcement via Telegram bot"
     echo -e "    ${GREEN}telegram disable${NC}        Disable Telegram"
     echo -e "    ${GREEN}telegram remove${NC}         Remove Telegram bot"
@@ -15860,6 +18752,9 @@ cli_main() {
             load_secrets
             case "${1:-status}" in
                 setup)   check_root; telegram_setup_wizard ;;
+                sync-commands) check_root; telegram_sync_commands ;;
+                commands) telegram_print_commands "${2:-admin}" ;;
+                history) telegram_history_cmd "${2:-status}";;
                 test)    telegram_test_message ;;
                 status|"")
                     if [ "$TELEGRAM_ENABLED" != "true" ]; then
@@ -18497,8 +21392,11 @@ show_info_qrcode() {
     echo -e "  ${BOLD}QR generation methods (auto-detected):${NC}"
     echo -e "  ${GREEN}1.${NC} ${BOLD}qrencode${NC} (native) — fastest, renders in terminal"
     echo -e "     Install: ${DIM}apt install qrencode${NC}"
-    echo -e "  ${GREEN}2.${NC} ${BOLD}Docker${NC} — uses alpine + qrencode container"
-    echo -e "  ${GREEN}3.${NC} ${BOLD}Web API${NC} — qrserver.com (for Telegram photo messages)"
+    echo -e "  ${GREEN}2.${NC} ${BOLD}python3-qrcode${NC} — renders a PNG for the bot and the HTML sheets"
+    echo -e "     Install: ${DIM}pip install qrcode${NC}"
+    echo -e "  ${DIM}Without one of these the bot sends the tappable link instead of a QR"
+    echo -e "  image. It is never rendered by a remote service: the link contains the"
+    echo -e "  secret, so posting it anywhere would hand over the key.${NC}"
     echo ""
     echo -e "  ${BOLD}Commands:${NC}"
     echo -e "  ${GREEN}mtproxymax secret qr <label>${NC}   Show QR in terminal"
diff --git a/tests/test_telegram_callback_data.sh b/tests/test_telegram_callback_data.sh
new file mode 100644
index 0000000..358bb94
--- /dev/null
+++ b/tests/test_telegram_callback_data.sh
@@ -0,0 +1,165 @@
+#!/bin/bash
+# Tests for the inline-keyboard callback_data codec.
+#
+# callback_data is capped at 64 bytes by the Bot API, and a single over-long
+# payload makes Telegram reject the ENTIRE reply_markup with a 400 — the whole
+# message is lost, not just the one button. Equally, a target containing ':'
+# would shift the positional fields and silently decode to a different target.
+# These tests pin both properties.
+set -o pipefail
+
+if [ "${BASH_VERSINFO[0]:-0}" -lt 4 ]; then
+    echo "SKIP: bash 4+ required (got ${BASH_VERSION:-unknown})" >&2
+    exit 0
+fi
+
+TEST_TMPDIR=$(mktemp -d)
+INSTALL_DIR="$TEST_TMPDIR/install"
+mkdir -p "$INSTALL_DIR/relay_stats"
+OFFSET_FILE="$INSTALL_DIR/relay_stats/tg_offset"
+ADMINS_FILE="$INSTALL_DIR/admins.conf"
+
+MTPROXYMAX_SOURCE_ONLY=true source "$(dirname "${BASH_SOURCE[0]}")/../mtproxymax.sh"
+set +e
+trap 'rm -rf "$TEST_TMPDIR"' EXIT
+
+TESTS_RUN=0
+TESTS_FAILED=0
+
+assert_eq() {
+    local name="$1" want="$2" got="$3"
+    TESTS_RUN=$((TESTS_RUN + 1))
+    if [ "$got" = "$want" ]; then
+        printf '  PASS  %s\n' "$name"
+    else
+        TESTS_FAILED=$((TESTS_FAILED + 1))
+        printf '  FAIL  %s (got=%q want=%q)\n' "$name" "$got" "$want"
+    fi
+}
+
+assert_ok() {
+    local name="$1"; shift
+    TESTS_RUN=$((TESTS_RUN + 1))
+    if "$@" >/dev/null 2>&1; then
+        printf '  PASS  %s\n' "$name"
+    else
+        TESTS_FAILED=$((TESTS_FAILED + 1))
+        printf '  FAIL  %s (expected success)\n' "$name"
+    fi
+}
+
+assert_rejects() {
+    local name="$1"; shift
+    TESTS_RUN=$((TESTS_RUN + 1))
+    if "$@" >/dev/null 2>&1; then
+        TESTS_FAILED=$((TESTS_FAILED + 1))
+        printf '  FAIL  %s (expected rejection)\n' "$name"
+    else
+        printf '  PASS  %s\n' "$name"
+    fi
+}
+
+# ── Extract the codec from the daemon that actually ships ────────────────────
+telegram_generate_service_script
+DAEMON="$INSTALL_DIR/mtproxymax-telegram.sh"
+CODEC="$TEST_TMPDIR/codec.sh"
+# _CB_MAX is a top-level assignment in the daemon, so the function extractor
+# below would not pick it up — pull it explicitly, and assert it so that a
+# future move fails loudly here instead of as an obscure arithmetic error.
+grep -m1 '^_CB_MAX=' "$DAEMON" > "$CODEC"
+for _fn in _cb_label_ok _cb_enc _cb_dec; do
+    awk "/^${_fn}\\(\\)/,/^}\$/" "$DAEMON" >> "$CODEC"
+done
+assert_eq "codec extraction is valid bash" 0 \
+    "$(bash -n "$CODEC" 2>/dev/null; echo $?)"
+source "$CODEC"
+assert_eq "callback_data cap is 64 bytes" 64 "${_CB_MAX:-}"
+
+echo "Telegram callback_data codec tests"
+
+# ── _cb_label_ok ─────────────────────────────────────────────────────────────
+assert_ok       "label 'alice' is valid"            _cb_label_ok "alice"
+assert_ok       "label 'a-b_c9' is valid"           _cb_label_ok "a-b_c9"
+assert_ok       "32-char label is valid"            _cb_label_ok "0123456789012345678901234567890a"
+assert_rejects  "33-char label is rejected"         _cb_label_ok "0123456789012345678901234567890ab"
+assert_rejects  "empty label is rejected"           _cb_label_ok ""
+assert_rejects  "label with ':' is rejected"        _cb_label_ok "alice:bob"
+assert_rejects  "label with space is rejected"      _cb_label_ok "al ice"
+assert_rejects  "label with '\$(' is rejected"      _cb_label_ok 'a$(id)'
+assert_rejects  "label with ';' is rejected"        _cb_label_ok "alice;rm"
+assert_rejects  "label with '*' is rejected"        _cb_label_ok "alice*"
+assert_rejects  "label with '/' is rejected"        _cb_label_ok "a/b"
+
+# ── _cb_enc ──────────────────────────────────────────────────────────────────
+assert_eq "encodes a bare no-op"        "n"                 "$(_cb_enc n "" "" "")"
+assert_eq "encodes hub:help"            "m:h"               "$(_cb_enc m h "" "")"
+assert_eq "encodes a list page"         "u:l:2"             "$(_cb_enc u l 2 "")"
+assert_eq "encodes a detail card"       "u:s:alice:0"       "$(_cb_enc u s alice 0)"
+assert_eq "encodes an action request"   "a:disable:alice"   "$(_cb_enc a disable alice "")"
+assert_eq "encodes a confirmed action"  "c:remove:alice"    "$(_cb_enc c remove alice "")"
+assert_eq "encodes a traffic window"    "t:w:24h"           "$(_cb_enc t w 24h "")"
+
+assert_rejects "enc refuses a ':' in the target"  _cb_enc a disable "ali:ce" ""
+assert_rejects "enc refuses a 33-char target"     _cb_enc a disable "0123456789012345678901234567890ab" ""
+assert_rejects "enc refuses an injected target"   _cb_enc a disable 'a$(id)' ""
+assert_rejects "enc refuses an empty target"      _cb_enc a disable "" ""
+
+# Every verb against a maximal label must stay inside the 64-byte cap.
+for _verb in enable disable rotate remove; do
+    _p=$(_cb_enc a "$_verb" "0123456789012345678901234567890a" "")
+    TESTS_RUN=$((TESTS_RUN + 1))
+    if [ -n "$_p" ] && [ "${#_p}" -le 64 ]; then
+        printf '  PASS  maximal %s payload is within 64 bytes (%d)\n' "$_verb" "${#_p}"
+    else
+        TESTS_FAILED=$((TESTS_FAILED + 1))
+        printf '  FAIL  maximal %s payload is within 64 bytes (got %d)\n' "$_verb" "${#_p}"
+    fi
+    _rt=$(_cb_enc a "$_verb" "0123456789012345678901234567890a" "")
+    assert_eq "maximal ${_verb} payload round-trips" \
+        "a:${_verb}:0123456789012345678901234567890a" "$_rt"
+done
+
+# ── _cb_dec ──────────────────────────────────────────────────────────────────
+decode() {
+    _CB_NS=""; _CB_ACT=""; _CB_TGT=""; _CB_PAGE=""
+    _cb_dec "$1" || return 1
+    printf '%s|%s|%s|%s' "$_CB_NS" "$_CB_ACT" "$_CB_TGT" "$_CB_PAGE"
+}
+
+assert_eq "decodes a bare no-op"       "n|||"              "$(decode n)"
+assert_eq "decodes hub:help"           "m|h||"             "$(decode m:h)"
+assert_eq "decodes a list page"        "u|l|2|"            "$(decode u:l:2)"
+assert_eq "decodes a detail card"      "u|s|alice|0"       "$(decode u:s:alice:0)"
+assert_eq "decodes an action request"  "a|disable|alice|"  "$(decode a:disable:alice)"
+assert_eq "decodes a traffic window"   "t|w|24h|"          "$(decode t:w:24h)"
+
+assert_rejects "dec rejects an empty payload"        _cb_dec ""
+assert_rejects "dec rejects an empty field"          _cb_dec "a:disable:"
+assert_rejects "dec rejects an uppercase namespace"  _cb_dec "A:disable:alice"
+assert_rejects "dec rejects a 3-char namespace"      _cb_dec "tool:l"
+assert_rejects "dec rejects too many fields"         _cb_dec "u:l:2:3:4"
+assert_rejects "dec rejects an over-long field"      _cb_dec "u:s:0123456789012345678901234567890ab"
+assert_rejects "dec rejects an over-long payload"    _cb_dec "u:s:alice:0:extra:more:junk:padding:aaaaaaaaaaaaaaaaaaaaaaaaa"
+
+# An over-long payload must be refused, never truncated: truncation would
+# decode into a different, still-valid target.
+_pad=$(printf 'a%.0s' $(seq 1 80))
+assert_rejects "dec rejects an 80-byte payload"      _cb_dec "$_pad"
+
+# A forged payload is inert data — never evaluated, never decoded into a target
+# that could reach a shell.
+assert_rejects "dec rejects a forged \$( ) payload"  _cb_dec 'a:disable:$(id)'
+
+# ── Round-trip ───────────────────────────────────────────────────────────────
+# Field is 3rd-positional, so these specs carry no trailing ':' (read would
+# absorb it into the last variable).
+for _spec in "n" "m:h" "u:l:2" "u:s:alice:0" "a:disable:alice" "c:remove:alice" \
+             "t" "t:w:7d" "t:u:30d" "y" "y:e"; do
+    IFS=':' read -r _ns _act _tgt _pg <<< "$_spec"
+    _enc=$(_cb_enc "$_ns" "$_act" "$_tgt" "$_pg")
+    _dec=$(decode "$_enc")
+    assert_eq "round-trip $_spec" "$_ns|$_act|$_tgt|$_pg" "$_dec"
+done
+
+printf '\n%d tests, %d failures\n' "$TESTS_RUN" "$TESTS_FAILED"
+[ "$TESTS_FAILED" -eq 0 ]
diff --git a/tests/test_telegram_callback_dispatch.sh b/tests/test_telegram_callback_dispatch.sh
new file mode 100644
index 0000000..9760b28
--- /dev/null
+++ b/tests/test_telegram_callback_dispatch.sh
@@ -0,0 +1,278 @@
+#!/bin/bash
+# Tests for the inline-keyboard callback dispatcher.
+#
+# The security property under test is that a button must never grant more than
+# typing the equivalent command would. _process_cmd is the reference: public
+# commands run before any role check, an unauthenticated chatter is ignored
+# SILENTLY, a recognised-but-underprivileged role is refused loudly, and an
+# unrecognised role string (admins.conf is hand-editable) fails closed.
+#
+# The dispatcher must reproduce all four behaviours, because callback_data is
+# entirely attacker-controlled — a user can send any payload they like.
+set -o pipefail
+
+if [ "${BASH_VERSINFO[0]:-0}" -lt 4 ]; then
+    echo "SKIP: bash 4+ required (got ${BASH_VERSION:-unknown})" >&2
+    exit 0
+fi
+
+TEST_TMPDIR=$(mktemp -d)
+INSTALL_DIR="$TEST_TMPDIR/install"
+mkdir -p "$INSTALL_DIR/relay_stats"
+OFFSET_FILE="$INSTALL_DIR/relay_stats/tg_offset"
+ADMINS_FILE="$INSTALL_DIR/admins.conf"
+AUDIT_LOG="$INSTALL_DIR/audit.log"
+SECRETS_FILE="$INSTALL_DIR/secrets.conf"
+
+printf 'alice|%s|1700000000|true|0|0|0|0||\n' "$(printf 'a%.0s' $(seq 1 32))" > "$SECRETS_FILE"
+printf 'bob|%s|1700000000|false|0|0|0|0||\n' "$(printf 'b%.0s' $(seq 1 32))" >> "$SECRETS_FILE"
+
+MTPROXYMAX_SOURCE_ONLY=true source "$(dirname "${BASH_SOURCE[0]}")/../mtproxymax.sh"
+set +e
+trap 'rm -rf "$TEST_TMPDIR"' EXIT
+
+TESTS_RUN=0
+TESTS_FAILED=0
+
+assert_eq() {
+    local name="$1" want="$2" got="$3"
+    TESTS_RUN=$((TESTS_RUN + 1))
+    if [ "$got" = "$want" ]; then
+        printf '  PASS  %s\n' "$name"
+    else
+        TESTS_FAILED=$((TESTS_FAILED + 1))
+        printf '  FAIL  %s (got=%q want=%q)\n' "$name" "$got" "$want"
+    fi
+}
+assert_contains() {
+    local name="$1" needle="$2" haystack="$3"
+    TESTS_RUN=$((TESTS_RUN + 1))
+    if [[ "$haystack" == *"$needle"* ]]; then
+        printf '  PASS  %s\n' "$name"
+    else
+        TESTS_FAILED=$((TESTS_FAILED + 1))
+        printf '  FAIL  %s (missing %q in %q)\n' "$name" "$needle" "$haystack"
+    fi
+}
+assert_not_contains() {
+    local name="$1" needle="$2" haystack="$3"
+    TESTS_RUN=$((TESTS_RUN + 1))
+    if [[ "$haystack" == *"$needle"* ]]; then
+        TESTS_FAILED=$((TESTS_FAILED + 1))
+        printf '  FAIL  %s (unexpected %q in %q)\n' "$name" "$needle" "$haystack"
+    else
+        printf '  PASS  %s\n' "$name"
+    fi
+}
+
+# ── Extract the shipped dispatcher ───────────────────────────────────────────
+telegram_generate_service_script
+DAEMON="$INSTALL_DIR/mtproxymax-telegram.sh"
+FNS="$TEST_TMPDIR/daemon-fns.sh"
+: > "$FNS"
+# NOTE: _check_tg_role is deliberately NOT extracted. Role resolution is
+# exercised elsewhere; here it is stubbed, and extracting the real one would
+# silently clobber that stub and make every role resolve to "none".
+for _fn in _tg_security_log _cb_label_ok _cb_enc _cb_dec; do
+    awk "/^${_fn}\\(\\)/,/^}\$/" "$DAEMON" >> "$FNS"
+done
+# The menu block is delimited by markers so the test exercises exactly what
+# ships rather than a copy that can silently drift.
+awk '/^# >>> TG_MENU_BEGIN$/,/^# <<< TG_MENU_END$/' "$DAEMON" >> "$FNS"
+assert_eq "dispatcher extraction is valid bash" 0 \
+    "$(bash -n "$FNS" 2>/dev/null; echo $?)"
+assert_eq "menu block was found in the daemon" 1 \
+    "$(grep -c '^# >>> TG_MENU_BEGIN$' "$FNS")"
+
+# ── Stubs ────────────────────────────────────────────────────────────────────
+ANSWERS="$TEST_TMPDIR/answers.log"
+EDITS="$TEST_TMPDIR/edits.log"
+SENDS="$TEST_TMPDIR/sends.log"
+CALLS="$TEST_TMPDIR/calls.log"
+ROLE_TO_RETURN="superadmin"
+
+_check_tg_role() { echo "$ROLE_TO_RETURN"; }
+tg_answer_cb() { printf '%s|%s|%s\n' "$1" "$2" "$3" >> "$ANSWERS"; }
+# $4 is the keyboard markup — the assertions about which buttons a view offers
+# read it, so it must be captured alongside the body.
+tg_edit() { printf 'edit|%s|%s|%s|%s\n' "$1" "$2" "$3" "$4" >> "$EDITS"; }
+tg_edit_markup() { printf 'markup|%s|%s|%s\n' "$1" "$2" "$3" >> "$EDITS"; }
+tg_send_to() { printf '%s|%s\n' "$1" "$2" >> "$SENDS"; }
+tg_send() { printf 'admin|%s\n' "$*" >> "$SENDS"; }
+load_tg_settings() { :; }
+is_running() { return 1; }
+log_warn() { :; }
+get_cached_ip() { echo "203.0.113.9"; }
+_tg_metrics_raw() { printf ''; }
+
+cat > "$INSTALL_DIR/mtproxymax" <<'EOS'
+#!/bin/bash
+printf '%s\n' "$*" >> "$MTPX_CALLS"
+exit 0
+EOS
+chmod +x "$INSTALL_DIR/mtproxymax"
+export MTPX_CALLS="$CALLS"
+
+source "$FNS"
+
+run_cb() {   # run_cb <role> <chat> <payload>
+    : > "$ANSWERS"; : > "$EDITS"; : > "$SENDS"; : > "$CALLS"
+    ROLE_TO_RETURN="$1"
+    _process_callback "$2" 77 "cb-1" "$3" 2>/dev/null
+}
+audit_now() { cat "$AUDIT_LOG" 2>/dev/null || printf ''; }
+reset_audit() { : > "$AUDIT_LOG"; }
+
+echo "Telegram callback dispatcher tests"
+
+# ── Every path answers the callback exactly once ─────────────────────────────
+# Without this the client spins forever, so it must hold on denial, error and
+# stale-menu paths too — not just the happy path.
+for _case in "superadmin:111:m" "reseller:333:m" "none:999:m" \
+             "operator:444:m" "superadmin:111:a:disable:alice" \
+             "reseller:333:a:disable:alice" "superadmin:111:u:s:ghost:0" \
+             "superadmin:111:not-a-real-payload" "superadmin:111:zz"; do
+    _r="${_case%%:*}"; _p="${_case#*:}"; _c="${_p%%:*}"; _data="${_p#*:}"
+    run_cb "$_r" "$_c" "$_data"
+    assert_eq "answers exactly once (role=$_r data=$_data)" 1 "$(wc -l < "$ANSWERS" | tr -d ' ')"
+done
+
+# ── A reseller cannot drive the control plane from a button ──────────────────
+reset_audit
+run_cb reseller 333 "a:disable:alice"
+assert_eq "reseller button cannot disable a secret" "" "$(cat "$CALLS")"
+assert_contains "reseller button denial is toasted" "Permission denied" "$(cat "$ANSWERS")"
+assert_contains "reseller button denial is logged" "SECURITY" "$(audit_now)"
+assert_contains "log records the offending chat" "333" "$(audit_now)"
+assert_contains "log records the payload" "a:disable:alice" "$(audit_now)"
+assert_eq "reseller button denial does not edit the message" "" "$(cat "$EDITS")"
+
+reset_audit
+run_cb reseller 333 "u:s:alice:0"
+assert_contains "reseller cannot open a user detail card" "Permission denied" "$(cat "$ANSWERS")"
+assert_contains "user-list denial is logged" "SECURITY" "$(audit_now)"
+assert_eq "user-list denial does not edit" "" "$(cat "$EDITS")"
+
+reset_audit
+run_cb reseller 333 "c:remove:alice"
+assert_contains "reseller cannot confirm a removal" "Permission denied" "$(cat "$ANSWERS")"
+assert_eq "reseller confirmed removal never runs" "" "$(cat "$CALLS")"
+
+# ── The rendered hub must not advertise what the role cannot do ──────────────
+reset_audit
+run_cb reseller 333 "m"
+_hub_reseller="$(cat "$EDITS")"
+assert_not_contains "reseller hub hides the user list" "u:l" "$_hub_reseller"
+assert_not_contains "reseller hub hides disable"     "a:disable" "$_hub_reseller"
+assert_not_contains "reseller hub hides removal"     "a:remove" "$_hub_reseller"
+assert_not_contains "reseller hub hides lockdown"    "lockdown" "$_hub_reseller"
+
+run_cb superadmin 111 "m"
+_hub_super="$(cat "$EDITS")"
+assert_contains "superadmin hub offers the user list" "u:l" "$_hub_super"
+
+# ── An unauthenticated chatter is answered but ignored silently ──────────────
+# This mirrors _process_cmd, where role "none" returns before any reply and
+# before any audit entry.
+reset_audit
+run_cb none 999 "a:disable:alice"
+assert_eq "unauthenticated callback runs nothing" "" "$(cat "$CALLS")"
+assert_eq "unauthenticated callback is not logged" "" "$(audit_now)"
+assert_eq "unauthenticated callback does not edit" "" "$(cat "$EDITS")"
+assert_eq "unauthenticated callback is still answered" 1 "$(wc -l < "$ANSWERS" | tr -d ' ')"
+
+# ── Unrecognised roles fail closed ───────────────────────────────────────────
+for _role in operator administrator root SUPERADMIN superadmin2; do
+    reset_audit
+    run_cb "$_role" 444 "a:disable:alice"
+    assert_eq "role '$_role' cannot disable a secret" "" "$(cat "$CALLS")"
+    assert_contains "role '$_role' is refused" "Permission denied" "$(cat "$ANSWERS")"
+    assert_contains "role '$_role' refusal is logged" "SECURITY" "$(audit_now)"
+done
+
+# ── Destructive actions require an explicit confirmation ─────────────────────
+# A destructive button must never be one tap away: the a: namespace only
+# renders a confirmation, and only c: executes.
+reset_audit
+run_cb superadmin 111 "a:disable:alice"
+assert_eq "action request does not mutate anything" "" "$(cat "$CALLS")"
+assert_contains "action request renders a confirmation" "c:disable:alice" "$(cat "$EDITS")"
+assert_contains "confirmation names the target" "alice" "$(cat "$EDITS")"
+
+run_cb superadmin 111 "c:disable:alice"
+assert_contains "confirmed action reaches the manager" "secret disable alice" "$(cat "$CALLS")"
+assert_eq "confirmed action runs exactly once" 1 "$(grep -c 'secret disable' "$CALLS")"
+
+run_cb superadmin 111 "c:enable:alice"
+assert_contains "confirmed enable reaches the manager" "secret enable alice" "$(cat "$CALLS")"
+
+run_cb superadmin 111 "c:rotate:alice"
+assert_contains "confirmed rotate reaches the manager" "secret rotate alice" "$(cat "$CALLS")"
+
+run_cb superadmin 111 "c:remove:alice"
+assert_contains "confirmed remove reaches the manager" "secret remove alice" "$(cat "$CALLS")"
+
+# ── A stale label must not reach the manager ─────────────────────────────────
+# secrets.conf is editable and a menu can outlive the secret it names.
+reset_audit
+run_cb superadmin 111 "c:disable:ghost"
+assert_eq "confirmed action on an unknown label runs nothing" "" "$(cat "$CALLS")"
+assert_contains "unknown label is reported" "not found" "$(cat "$ANSWERS")"
+
+reset_audit
+run_cb superadmin 111 "u:s:ghost:0"
+assert_eq "detail card for an unknown label runs nothing" "" "$(cat "$CALLS")"
+assert_contains "unknown label detail card is answered with a toast" "not found" "$(cat "$ANSWERS")"
+
+# ── An injected payload is inert ─────────────────────────────────────────────
+reset_audit
+run_cb superadmin 111 'a:disable:$(id)'
+assert_eq "injected payload runs nothing" "" "$(cat "$CALLS")"
+assert_eq "injected payload is answered" 1 "$(wc -l < "$ANSWERS" | tr -d ' ')"
+
+# ── Capability parity with _process_cmd ──────────────────────────────────────
+# The table both the renderer and the enforcer read must not drift from the
+# gates _process_cmd applies, or a button becomes a privilege-escalation path.
+cap_leaks() {
+    local line key cap _ns _rest
+    while IFS= read -r line; do
+        [ -z "$line" ] && continue
+        key="${line%%=*}"; cap="${line#*=}"
+        case "$key" in
+            # Destructive verbs must be superadmin because _process_cmd
+            # re-checks superadmin inside /mp_remove.
+            a:remove|c:remove)
+                [ "$cap" = "superadmin" ] || { printf '%s=%s\n' "$key" "$cap"; } ;;
+            a:enable|a:disable|a:rotate|c:enable|c:disable|c:rotate|u:l|u:s|t|t:w|t:u|y|y:e|s)
+                [ "$cap" = "admin" ] || { printf '%s=%s\n' "$key" "$cap"; } ;;
+            # Per-secret management. Every one of these mirrors an admin-tier
+            # CLI verb (secret setlimit / extend / quota-reset / template apply),
+            # and none of them is reachable by a reseller, whose only surface
+            # stays the voucher commands.
+            u:m|u:t|e|e:q|e:c|e:i|e:x|e:r|e:n|e:a|e:t|e:z|\
+            c:setq|c:setc|c:seti|c:setx|c:setr|c:tpl)
+                [ "$cap" = "admin" ] || { printf '%s=%s\n' "$key" "$cap"; } ;;
+            # The server console and the template section: read-mostly views
+            # mirroring admin-tier CLI verbs.
+            y:d|y:p|y:f|y:v|y:u|g|g:a|g:b|k|k:e|k:p|k:a|k:s|k:d|k:n)
+                [ "$cap" = "admin" ] || { printf '%s=%s\n' "$key" "$cap"; } ;;
+            # The four verbs _process_cmd re-checks superadmin for inline:
+            # /mp_remove, /mp_restart, /mp_update, /mp_lockdown.
+            a:rotall|c:rotall|a:restart|c:restart|a:update|c:update|a:lockdown|c:lockdown)
+                [ "$cap" = "superadmin" ] || { printf '%s=%s\n' "$key" "$cap"; } ;;
+            n|m|m:h|p|p:x)
+                [ "$cap" = "public" ] || { printf '%s=%s\n' "$key" "$cap"; } ;;
+            *)
+                printf 'unclassified:%s\n' "$key" ;;
+        esac
+    done <<< "$TG_CB_CAPS"
+}
+assert_eq "capability table matches _process_cmd's gates" "" "$(cap_leaks)"
+
+# Every namespace the renderers can emit must have a capability, or the
+# dispatcher would fail open on an unclassified action.
+assert_contains "capability table covers a:disable" "a:disable=admin" "$TG_CB_CAPS"
+assert_contains "capability table covers c:remove"  "c:remove=superadmin" "$TG_CB_CAPS"
+
+printf '\n%d tests, %d failures\n' "$TESTS_RUN" "$TESTS_FAILED"
+[ "$TESTS_FAILED" -eq 0 ]
diff --git a/tests/test_telegram_commands.sh b/tests/test_telegram_commands.sh
new file mode 100644
index 0000000..831bcc2
--- /dev/null
+++ b/tests/test_telegram_commands.sh
@@ -0,0 +1,221 @@
+#!/bin/bash
+# Regression tests for the Telegram bot command menu (setMyCommands).
+#
+# The bot registers its command list with Telegram so clients render a tappable
+# "/" menu. Lists are scoped: everyone gets the public self-service commands,
+# admins get the admin control plane, superadmins additionally get the four
+# commands the dispatcher gates to superadmin.
+set -o pipefail
+
+if [ "${BASH_VERSINFO[0]:-0}" -lt 4 ]; then
+    echo "SKIP: bash 4+ required (got ${BASH_VERSION:-unknown})" >&2
+    exit 0
+fi
+
+TEST_TMPDIR=$(mktemp -d)
+INSTALL_DIR="$TEST_TMPDIR/install"
+mkdir -p "$INSTALL_DIR/relay_stats"
+ADMINS_FILE="$INSTALL_DIR/admins.conf"
+SETTINGS_FILE="$INSTALL_DIR/settings.conf"
+
+MTPROXYMAX_SOURCE_ONLY=true source "$(dirname "${BASH_SOURCE[0]}")/../mtproxymax.sh"
+set +e
+trap 'rm -rf "$TEST_TMPDIR"' EXIT
+
+TESTS_RUN=0
+TESTS_FAILED=0
+
+assert_eq() {
+    local name="$1" want="$2" got="$3"
+    TESTS_RUN=$((TESTS_RUN + 1))
+    if [ "$got" = "$want" ]; then
+        printf '  PASS  %s\n' "$name"
+    else
+        TESTS_FAILED=$((TESTS_FAILED + 1))
+        printf '  FAIL  %s (got=%q want=%q)\n' "$name" "$got" "$want"
+    fi
+}
+
+check_root() { :; }
+load_settings() { :; }
+log_info() { :; }
+log_success() { :; }
+log_error() { LAST_ERROR="$*"; }
+log_warn() { :; }
+
+# ── Telemetry: record every Bot API call the code under test makes ───────────
+CALLS_FILE="$TEST_TMPDIR/calls.tsv"
+CALL_N=0
+
+# Sorted, comma-separated normalisation so assertions do not depend on the
+# order the tables happen to be written in.
+sorted_csv() {
+    printf '%s' "$1" | tr ',' '\n' | LC_ALL=C sort | tr '\n' ',' | sed 's/,$//'
+}
+
+curl() {
+    local _cfg="" _body="" _prev="" _a
+    for _a in "$@"; do
+        case "$_prev" in
+            -K) _cfg="$_a" ;;
+            -d) _body="$_a" ;;
+        esac
+        _prev="$_a"
+    done
+    local _url=""
+    [ -n "$_cfg" ] && [ -f "$_cfg" ] && _url=$(sed -n 's/^url = "\(.*\)"$/\1/p' "$_cfg" 2>/dev/null)
+    local _method="${_url##*/}"
+    local _chat
+    _chat=$(printf '%s' "$_body" | grep -o '"chat_id":[0-9-]*' | head -1 | cut -d: -f2)
+    [ -z "$_chat" ] && _chat="-"
+    local _cmds
+    _cmds=$(printf '%s' "$_body" | grep -o '"command":"[a-z0-9_]*"' | sed 's/"command":"//;s/"//' | tr '\n' ',' | sed 's/,$//')
+    # curl runs inside a command-substitution subshell, so a counter would not
+    # survive back to this shell. mktemp gives each call a unique body file.
+    local _bf
+    _bf=$(mktemp "$TEST_TMPDIR/body.XXXXXX")
+    printf '%s' "$_body" > "$_bf"
+    printf '%s\t%s\t%s\n' "$_method" "$_chat" "$_cmds" >> "$CALLS_FILE"
+    if [ "${CURL_OK:-true}" = "true" ]; then
+        printf '{"ok":true,"result":true}\n'
+    else
+        printf '{"ok":false,"error_code":401,"description":"Unauthorized"}\n'
+    fi
+}
+
+# Command list registered for a scope. "-" is the default (all users) scope.
+scope_commands() {
+    awk -F'\t' -v c="$1" '$1=="setMyCommands" && $2==c {print $3}' "$CALLS_FILE" | head -1
+}
+call_methods() { awk -F'\t' '{print $1}' "$CALLS_FILE"; }
+call_count() { wc -l < "$CALLS_FILE" 2>/dev/null | tr -d ' '; }
+# grep -c . counts non-empty lines, avoiding the trailing-newline off-by-one.
+csv_count() { printf '%s' "$1" | tr ',' '\n' | grep -c .; }
+csv_uniq_count() { printf '%s' "$1" | tr ',' '\n' | sort -u | grep -c .; }
+
+PUBLIC="my_status,redeem,start,support,voucher"
+ADMIN="mp_add,mp_broadcast,mp_digest,mp_disable,mp_enable,mp_fleet,mp_health,mp_help,
+mp_limits,mp_link,mp_rotate,mp_secrets,mp_setlimit,mp_status,mp_traffic,mp_upstreams,mp_voucher,reply"
+ADMIN=$(printf '%s' "$ADMIN" | tr -d '\n')
+SUPERADMIN="mp_add,mp_broadcast,mp_digest,mp_disable,mp_enable,mp_fleet,mp_health,mp_help,
+mp_limits,mp_link,mp_lockdown,mp_remove,mp_restart,mp_rotate,mp_secrets,mp_setlimit,mp_status,mp_traffic,mp_update,mp_upstreams,mp_voucher,reply"
+SUPERADMIN=$(printf '%s' "$SUPERADMIN" | tr -d '\n')
+
+# ── Fixtures ─────────────────────────────────────────────────────────────────
+TELEGRAM_ENABLED="true"
+TELEGRAM_BOT_TOKEN="123456:TESTTOKEN"
+TELEGRAM_CHAT_ID="111"
+printf '222|superadmin|Ops|2025-01-01\n333|reseller|Shop|2025-01-02\n' > "$ADMINS_FILE"
+
+echo "Telegram command menu tests"
+
+# ── Happy path ───────────────────────────────────────────────────────────────
+: > "$CALLS_FILE"
+CURL_OK=true
+telegram_sync_commands
+assert_eq "sync returns success" 0 "$?"
+
+assert_eq "all users get the public commands" "$PUBLIC" "$(sorted_csv "$(scope_commands -)")"
+assert_eq "root admin chat gets superadmin commands" "$SUPERADMIN" "$(sorted_csv "$(scope_commands 111)")"
+assert_eq "admins.conf superadmin gets superadmin commands" "$SUPERADMIN" "$(sorted_csv "$(scope_commands 222)")"
+assert_eq "reseller gets the reduced admin commands" "$ADMIN" "$(sorted_csv "$(scope_commands 333)")"
+
+# The scoping guarantee: a reseller must not be shown privileged commands.
+for _c in mp_remove mp_restart mp_update mp_lockdown; do
+    assert_eq "reseller is not offered /$_c" "" "$(scope_commands 333 | tr ',' '\n' | grep -x "$_c")"
+done
+# ...while the superadmin must be.
+for _c in mp_remove mp_restart mp_update mp_lockdown; do
+    assert_eq "superadmin is offered /$_c" "$_c" "$(scope_commands 111 | tr ',' '\n' | grep -x "$_c")"
+done
+
+assert_eq "every registered command is namespaced correctly" "" "$(scope_commands 111 | tr ',' '\n' | grep -vE '^(reply|mp_[a-z_]+)$')"
+assert_eq "no duplicate commands are registered" \
+    "$(csv_uniq_count "$(scope_commands 111)")" "$(csv_count "$(scope_commands 111)")"
+
+# ── Failure and disabled paths are never fatal ───────────────────────────────
+CURL_OK=false
+: > "$CALLS_FILE"
+telegram_sync_commands
+assert_eq "sync survives a Bot API failure" 0 "$?"
+assert_eq "sync still attempts the public scope on failure" "setMyCommands" "$(call_methods | head -1)"
+
+CURL_OK=true
+TELEGRAM_ENABLED=false
+: > "$CALLS_FILE"
+telegram_sync_commands
+assert_eq "disabled bot is a no-op" 0 "$(call_count)"
+
+TELEGRAM_ENABLED=true
+_SAVED_TOKEN="$TELEGRAM_BOT_TOKEN"
+TELEGRAM_BOT_TOKEN=""
+: > "$CALLS_FILE"
+telegram_sync_commands
+assert_eq "missing token is a no-op" 0 "$(call_count)"
+TELEGRAM_BOT_TOKEN="$_SAVED_TOKEN"
+
+# ── Revoking an admin clears their menu ──────────────────────────────────────
+: > "$CALLS_FILE"
+telegram_clear_commands 333
+assert_eq "clearing an admin uses deleteMyCommands" "deleteMyCommands" "$(call_methods | head -1)"
+assert_eq "clearing targets the removed admin chat" "333" "$(awk -F'\t' '{print $2}' "$CALLS_FILE" | head -1)"
+
+# ── Request bodies are well-formed JSON ──────────────────────────────────────
+# Dependency-free structural check: always runs, and catches unbalanced braces
+# or a truncated payload.
+json_shape_ok() {
+    local b="$1"
+    [ -n "$b" ] || return 1
+    [ "${b#\{}" != "$b" ] || return 1
+    [ "${b%\}}" != "$b" ] || return 1
+    [ "$(printf '%s' "$b" | tr -cd '{' | wc -c)" = "$(printf '%s' "$b" | tr -cd '}' | wc -c)" ] || return 1
+    [ "$(printf '%s' "$b" | tr -cd '[' | wc -c)" = "$(printf '%s' "$b" | tr -cd ']' | wc -c)" ] || return 1
+    return 0
+}
+
+# Note: the Windows Store ships a python3.exe alias that exists on PATH but
+# cannot execute, so probe with a real invocation rather than `command -v`.
+PY=""
+if python3 -c 'import json' >/dev/null 2>&1; then
+    PY="python3"
+elif python -c 'import json' >/dev/null 2>&1; then
+    PY="python"
+fi
+
+_shape_bad=0
+_parsed_bad=0
+_validated=0
+for _f in "$TEST_TMPDIR"/body.*; do
+    [ -f "$_f" ] || continue
+    _validated=$((_validated + 1))
+    json_shape_ok "$(cat "$_f")" || _shape_bad=$((_shape_bad + 1))
+    if [ -n "$PY" ]; then
+        "$PY" -c 'import json,sys; json.load(open(sys.argv[1]))' "$_f" 2>/dev/null || _parsed_bad=$((_parsed_bad + 1))
+    fi
+done
+# Guard against a vacuous pass: with no captured bodies the loop never runs.
+assert_eq "request bodies were captured for validation" "yes" \
+    "$([ "$_validated" -gt 0 ] && echo yes || echo no)"
+assert_eq "every request body is structurally valid JSON" "0" "$_shape_bad"
+if [ -n "$PY" ]; then
+    assert_eq "every request body parses as JSON ($PY)" "0" "$_parsed_bad"
+fi
+
+# Telegram rejects the whole list if a single entry is malformed, so a stray
+# control character or quote in a description must not corrupt the payload.
+if [ -n "$PY" ]; then
+    _tricky=$(printf 'weird|He said "hi" in C:\\path\tand a\rCR')
+    assert_eq "descriptions with quotes, backslashes and control chars stay valid JSON" "ok" \
+        "$(_tg_commands_json "$_tricky" | "$PY" -c 'import json,sys; json.loads(sys.stdin.read()); print("ok")' 2>/dev/null || echo bad)"
+fi
+
+# ── The generated daemon re-syncs the menu on boot ───────────────────────────
+telegram_generate_service_script
+_DAEMON="$INSTALL_DIR/mtproxymax-telegram.sh"
+assert_eq "daemon script is generated" "yes" "$([ -f "$_DAEMON" ] && echo yes || echo no)"
+assert_eq "daemon syncs the command menu on boot" "yes" \
+    "$(grep -q 'telegram sync-commands' "$_DAEMON" && echo yes || echo no)"
+assert_eq "generated daemon is valid bash" 0 "$(bash -n "$_DAEMON" 2>/dev/null; echo $?)"
+
+printf '\n%d tests, %d failures\n' "$TESTS_RUN" "$TESTS_FAILED"
+[ "$TESTS_FAILED" -eq 0 ]
diff --git a/tests/test_telegram_history.sh b/tests/test_telegram_history.sh
new file mode 100644
index 0000000..43ba8dd
--- /dev/null
+++ b/tests/test_telegram_history.sh
@@ -0,0 +1,267 @@
+#!/bin/bash
+# Tests for the rolling history store and the analytics computed from it.
+#
+# The store records DELTAS, not cumulative counters, so an engine restart or a
+# traffic reset simply yields a smaller bucket instead of poisoning every
+# window that spans it. These tests use hand-written fixtures rather than
+# fixtures generated by the code under test, so the expected values are
+# checkable by eye.
+set -o pipefail
+
+if [ "${BASH_VERSINFO[0]:-0}" -lt 4 ]; then
+    echo "SKIP: bash 4+ required (got ${BASH_VERSION:-unknown})" >&2
+    exit 0
+fi
+
+TEST_TMPDIR=$(mktemp -d)
+INSTALL_DIR="$TEST_TMPDIR/install"
+mkdir -p "$INSTALL_DIR/relay_stats/history"
+OFFSET_FILE="$INSTALL_DIR/relay_stats/tg_offset"
+
+# busybox ships a flock applet that accepts -n but NOT -w. Putting one on PATH reproduces
+# Alpine's behaviour here, so the history-prune regression is caught on every platform
+# rather than only on busybox hosts.
+FAKEBIN="$TEST_TMPDIR/bin"
+mkdir -p "$FAKEBIN"
+cat >"$FAKEBIN/flock" <<'FLOCK_EOF'
+#!/bin/bash
+for _a in "$@"; do
+    case "$_a" in
+    -w*) echo "flock: unrecognized option: w" >&2; exit 1 ;;
+    esac
+done
+exit 0
+FLOCK_EOF
+chmod +x "$FAKEBIN/flock"
+PATH="$FAKEBIN:$PATH"
+export PATH
+
+MTPROXYMAX_SOURCE_ONLY=true source "$(dirname "${BASH_SOURCE[0]}")/../mtproxymax.sh"
+set +e
+trap 'rm -rf "$TEST_TMPDIR"' EXIT
+
+TESTS_RUN=0
+TESTS_FAILED=0
+assert_eq() {
+    local name="$1" want="$2" got="$3"
+    TESTS_RUN=$((TESTS_RUN + 1))
+    if [ "$got" = "$want" ]; then printf '  PASS  %s\n' "$name"
+    else TESTS_FAILED=$((TESTS_FAILED + 1)); printf '  FAIL  %s\n         got=%q\n        want=%q\n' "$name" "$got" "$want"; fi
+}
+assert_ok() {
+    local name="$1" cond="$2"
+    TESTS_RUN=$((TESTS_RUN + 1))
+    if [ "$cond" -eq 0 ] 2>/dev/null; then printf '  PASS  %s\n' "$name"
+    else TESTS_FAILED=$((TESTS_FAILED + 1)); printf '  FAIL  %s\n' "$name"; fi
+}
+
+telegram_generate_service_script
+DAEMON="$INSTALL_DIR/mtproxymax-telegram.sh"
+FNS="$TEST_TMPDIR/history.sh"
+awk '/^# >>> TG_HISTORY_BEGIN$/,/^# <<< TG_HISTORY_END$/' "$DAEMON" > "$FNS"
+assert_eq "history block found in the daemon" 1 \
+    "$(grep -c '^# >>> TG_HISTORY_BEGIN$' "$FNS")"
+assert_eq "history extraction is valid bash" 0 \
+    "$(bash -n "$FNS" 2>/dev/null; echo $?)"
+source "$FNS"
+
+HIST="$INSTALL_DIR/relay_stats/history"
+NOW=1000000
+
+echo "Telegram history store tests"
+
+# ── Summary: window sums, period-over-period, peak and average ───────────────
+# window = 1000s, so cur covers epoch >= 999000 and prev covers 998000..998999.
+#   prev in = 200+200 = 400, prev out = 300+300 = 600, prev total = 1000
+#   cur  in = 400+600 = 1000, cur out = 600+400 = 1000, cur total = 2000
+#   pct = (2000-1000)*100/1000 = +100
+#   intervals: 998500->998800 gap 300 delta 500  = 1.67 B/s
+#              998800->999500 gap 700 delta 1000 = 1.43 B/s
+#              999500->999800 gap 300 delta 1000 = 3.33 B/s   <- peak
+#   span = 999800-999500 = 300 (cur window), total 2000 -> avg 6
+cat > "$HIST/global.tsv" <<'EOF'
+998500|200|300|5|-
+998800|200|300|6|-
+999500|400|600|7|-
+999800|600|400|8|-
+EOF
+: > "$HIST/users.tsv"
+
+assert_eq "summary reports the current and previous windows" \
+    "1000|1000|400|600|100|3|6|2|300" "$(history_summary 1000 "$NOW")"
+
+# A window with nothing in the previous period reports "n/a" — never inf/nan,
+# and never a numeric sentinel that a real -1% would collide with.
+cat > "$HIST/global.tsv" <<'EOF'
+999500|400|600|7|-
+999800|600|400|8|-
+EOF
+_sum=$(history_summary 1000 "$NOW")
+assert_eq "period-over-period is n/a when there is no previous window" \
+    "n/a" "$(printf '%s' "$_sum" | cut -d'|' -f5)"
+assert_ok "no inf or nan leaks into the summary" \
+    "$(printf '%s' "$_sum" | grep -qE 'inf|nan' && echo 1 || echo 0)"
+
+# A genuine decrease is still numeric, and distinguishable from n/a.
+# prev total 1250, cur total 1000 -> -20%
+cat > "$HIST/global.tsv" <<'EOF'
+998500|600|650|5|-
+999500|400|600|7|-
+999800|0|0|0|-
+EOF
+assert_eq "a real decrease is reported numerically" \
+    "-20" "$(history_summary 1000 "$NOW" | cut -d'|' -f5)"
+
+# An empty store must not crash or emit garbage.
+: > "$HIST/global.tsv"
+assert_eq "an empty store yields a zeroed summary" \
+    "0|0|0|0|n/a|0|0|0|0" "$(history_summary 1000 "$NOW")"
+
+# ── Peak must use the REAL inter-sample gap, not the nominal interval ────────
+# 1000 bytes over a 100s gap is 10 B/s. Assuming a nominal 300s bucket would
+# report 3 B/s, so this pins the honest calculation.
+cat > "$HIST/global.tsv" <<'EOF'
+999000|0|0|0|-
+999100|1000|0|0|-
+999800|1000|0|0|-
+EOF
+assert_eq "peak uses the actual gap between samples" \
+    "10" "$(history_summary 1000 "$NOW" | cut -d'|' -f6)"
+
+# ── An engine-restart marker must not be summed as traffic ───────────────────
+cat > "$HIST/global.tsv" <<'EOF'
+999500|400|600|7|-
+999600|0|0|0|R
+999800|600|400|8|-
+EOF
+assert_eq "restart rows still contribute their delta" \
+    "1000" "$(history_summary 1000 "$NOW" | cut -d'|' -f1)"
+
+# ── Per-user windows, in one pass, including users with no history ───────────
+cat > "$HIST/users.tsv" <<'EOF'
+998800|alice|100|100
+999500|alice|300|200
+999800|bob|50|50
+999800|alice|100|100
+EOF
+_u=$(history_users 1000 "$NOW" alice bob carol)
+assert_eq "per-user window sums are exact" \
+    "alice|400|300
+bob|50|50
+carol|0|0" "$_u"
+
+# Requesting no labels must not hang or error.
+assert_eq "an empty label list yields nothing" "" "$(history_users 1000 "$NOW")"
+
+# ── Hourly buckets ───────────────────────────────────────────────────────────
+cat > "$HIST/global.tsv" <<'EOF'
+999500|400|600|7|-
+999800|600|400|8|-
+EOF
+_h=$(history_hourly 1000 "$NOW")
+assert_eq "hourly series has 24 buckets" 24 "$(printf '%s\n' "$_h" | tr ' ' '\n' | grep -c .)"
+assert_eq "hourly buckets sum to the window total" 2000 \
+    "$(printf '%s\n' "$_h" | tr ' ' '\n' | awk '{s+=$1} END{printf "%.0f", s+0}')"
+
+# ── Top talkers ──────────────────────────────────────────────────────────────
+cat > "$HIST/users.tsv" <<'EOF'
+999500|alice|100|100
+999500|bob|500|500
+999500|carol|300|300
+EOF
+assert_eq "top talkers are ordered by volume" \
+    "bob|1000
+carol|600
+alice|200" "$(history_top 1000 "$NOW" 3)"
+assert_eq "top talkers honours the limit" 1 "$(history_top 1000 "$NOW" 1 | wc -l | tr -d ' ')"
+
+# ── Appending a sample ───────────────────────────────────────────────────────
+rm -f "$HIST/global.tsv" "$HIST/users.tsv"
+_bucket_in=111; _bucket_out=222; _bucket_marker="-"; _bucket_conns=0
+# carol is wholly idle in both directions so she must produce no row at all.
+declare -A _bucket_user_in=([alice]=10 [carol]=0)
+declare -A _bucket_user_out=([alice]=30 [carol]=0)
+history_sample 5000
+history_sample 5300
+assert_eq "each sample appends one global row" 2 "$(wc -l < "$HIST/global.tsv" | tr -d ' ')"
+assert_eq "global rows carry five pipe-separated fields" \
+    "5" "$(awk -F'|' 'NR==1{print NF}' "$HIST/global.tsv")"
+assert_eq "the global row holds the bucket totals" "5000|111|222|0|-" "$(head -1 "$HIST/global.tsv")"
+
+# A user with a zero delta is omitted: a mostly-idle fleet must not write a row
+# per user per sample.
+# The first sample consumes the bucket, so the second writes no user row.
+assert_eq "active users are written once per sample" 1 "$(grep -c 'alice' "$HIST/users.tsv")"
+assert_ok "a zero-delta user gets no row" \
+    "$(grep -q '^5000|carol|' "$HIST/users.tsv" && echo 1 || echo 0)"
+
+# The buckets must be zeroed after a sample, or the next one double-counts.
+assert_eq "sampling resets the global bucket" "0:0" "${_bucket_in}:${_bucket_out}"
+assert_eq "sampling resets the per-user bucket" "0:0" "${_bucket_user_in[alice]:-0}:${_bucket_user_out[alice]:-0}"
+
+# ── The record format's field count is a contract ────────────────────────────
+assert_eq "user rows carry four pipe-separated fields" \
+    "4" "$(awk -F'|' 'NR==1{print NF}' "$HIST/users.tsv")"
+
+# ── Concurrent appends ───────────────────────────────────────────────────────
+# The daemon is the only appender, so these need no lock — but O_APPEND must
+# still not interleave rows.
+rm -f "$HIST/global.tsv"
+for _i in $(seq 1 20); do
+    ( _bucket_in=$_i; _bucket_out=$_i; _bucket_marker="-"; history_sample "$(( 6000 + _i ))" ) &
+done
+wait
+assert_eq "20 concurrent appends produce 20 well-formed rows" 20 \
+    "$(awk -F'|' 'NF==5' "$HIST/global.tsv" | wc -l | tr -d ' ')"
+assert_eq "concurrent appends produce no extra rows" 20 \
+    "$(wc -l < "$HIST/global.tsv" | tr -d ' ')"
+
+# ── Pruning ──────────────────────────────────────────────────────────────────
+rm -f "$HIST/global.tsv" "$HIST/users.tsv"
+for _d in $(seq 0 9); do
+    printf '%s|10|10|1|-\n' "$(( NOW - _d * 86400 ))" >> "$HIST/global.tsv"
+    printf '%s|alice|10|10\n' "$(( NOW - _d * 86400 ))" >> "$HIST/users.tsv"
+done
+history_prune 7 "$NOW"
+assert_ok "pruning keeps samples inside the retention window" \
+    "$([ "$(wc -l < "$HIST/global.tsv" | tr -d ' ')" -ge 7 ] && echo 0 || echo 1)"
+assert_ok "pruning drops samples older than the window" \
+    "$(awk -F'|' -v c=$(( NOW - 7 * 86400 )) '$1 < c' "$HIST/global.tsv" | grep -q . && echo 1 || echo 0)"
+assert_eq "pruning leaves no blank lines" 0 \
+    "$(grep -c '^$' "$HIST/global.tsv")"
+assert_ok "pruning keeps every surviving row well-formed" \
+    "$(awk -F'|' 'NF!=5' "$HIST/global.tsv" | grep -q . && echo 1 || echo 0)"
+
+# Pruning twice must change nothing.
+_before=$(cat "$HIST/global.tsv")
+history_prune 7 "$NOW"
+assert_eq "pruning is idempotent" "$_before" "$(cat "$HIST/global.tsv")"
+
+# 10 daily samples with 7-day retention leaves day 0 through day 7 inclusive.
+assert_eq "pruning keeps exactly the retained days" 8 \
+    "$(wc -l < "$HIST/global.tsv" | tr -d ' ')"
+assert_eq "per-user rows are pruned on the same boundary" 8 \
+    "$(wc -l < "$HIST/users.tsv" | tr -d ' ')"
+
+# ── Sparkline ────────────────────────────────────────────────────────────────
+assert_eq "sparkline of an idle series is all floor" "▁▁▁" "$(_tg_spark "0 0 0")"
+assert_eq "sparkline scales to its own peak" "▃▅█" "$(_tg_spark "1 2 3")"
+assert_eq "sparkline of nothing is empty" "" "$(_tg_spark "")"
+# Each bar glyph is 3 UTF-8 bytes, and this host runs a C locale where wc -m
+# counts bytes — so byte length is the locale-independent way to count glyphs.
+# It is also the regression guard for the multibyte hazard: a byte-wise split
+# of the glyph table would yield a wrong byte count here.
+assert_eq "sparkline emits one glyph per bucket" 9 \
+    "$(printf '%s' "$(_tg_spark "1 2 3")" | wc -c | tr -d ' ')"
+assert_eq "sparkline length matches the series" 72 \
+    "$(_tg_spark "$(history_hourly 1000 "$NOW")" | wc -c | tr -d ' ')"
+
+# ── Percentage formatting ────────────────────────────────────────────────────
+assert_eq "an increase is shown with an up arrow" "  ▲12%" "$(_tg_pct_str 12)"
+assert_eq "a decrease is shown with a down arrow" "  ▼7%" "$(_tg_pct_str -7)"
+assert_eq "no change is shown as flat" "  ▬0%" "$(_tg_pct_str 0)"
+assert_eq "n/a prints nothing at all" "" "$(_tg_pct_str "n/a")"
+assert_eq "garbage prints nothing at all" "" "$(_tg_pct_str "")"
+
+printf '\n%d tests, %d failures\n' "$TESTS_RUN" "$TESTS_FAILED"
+[ "$TESTS_FAILED" -eq 0 ]
diff --git a/tests/test_telegram_menu_render.sh b/tests/test_telegram_menu_render.sh
new file mode 100644
index 0000000..44f00d2
--- /dev/null
+++ b/tests/test_telegram_menu_render.sh
@@ -0,0 +1,230 @@
+#!/bin/bash
+# Tests for inline-keyboard rendering: shape, payload bounds, and pagination.
+#
+# The Bot API validates reply_markup as a whole, so one bad button loses the
+# entire keyboard — and one malformed JSON string loses the whole message.
+# These tests check every view a role can reach, across all roles.
+set -o pipefail
+
+if [ "${BASH_VERSINFO[0]:-0}" -lt 4 ]; then
+    echo "SKIP: bash 4+ required (got ${BASH_VERSION:-unknown})" >&2
+    exit 0
+fi
+
+TEST_TMPDIR=$(mktemp -d)
+INSTALL_DIR="$TEST_TMPDIR/install"
+mkdir -p "$INSTALL_DIR/relay_stats"
+OFFSET_FILE="$INSTALL_DIR/relay_stats/tg_offset"
+ADMINS_FILE="$INSTALL_DIR/admins.conf"
+AUDIT_LOG="$INSTALL_DIR/audit.log"
+SECRETS_FILE="$INSTALL_DIR/secrets.conf"
+
+# 13 users: enough to force three pages at a page size of six.
+: > "$SECRETS_FILE"
+for _i in $(seq 1 13); do
+    _state="true"; [ $(( _i % 3 )) -eq 0 ] && _state="false"
+    printf 'user%02d|%s|1700000000|%s|0|0|0|0||\n' "$_i" "$(printf '%032d' "$_i")" "$_state" >> "$SECRETS_FILE"
+done
+
+# One well-formed template, plus one whose name can never be a button payload —
+# the second is what proves the list says so instead of dropping it silently.
+TEMPLATES_FILE="$INSTALL_DIR/templates.conf"
+printf 'vip|100|5|53687091200|2027-01-01|top tier\n' > "$TEMPLATES_FILE"
+printf 'not a button|10|2|1073741824|0|x\n' >> "$TEMPLATES_FILE"
+
+MTPROXYMAX_SOURCE_ONLY=true source "$(dirname "${BASH_SOURCE[0]}")/../mtproxymax.sh"
+set +e
+trap 'rm -rf "$TEST_TMPDIR"' EXIT
+
+TESTS_RUN=0
+TESTS_FAILED=0
+assert_ok() {
+    local name="$1" cond="$2"
+    TESTS_RUN=$((TESTS_RUN + 1))
+    if [ "$cond" -eq 0 ] 2>/dev/null; then printf '  PASS  %s\n' "$name"
+    else TESTS_FAILED=$((TESTS_FAILED + 1)); printf '  FAIL  %s\n' "$name"; fi
+}
+assert_eq() {
+    local name="$1" want="$2" got="$3"
+    TESTS_RUN=$((TESTS_RUN + 1))
+    if [ "$got" = "$want" ]; then printf '  PASS  %s\n' "$name"
+    else TESTS_FAILED=$((TESTS_FAILED + 1)); printf '  FAIL  %s (got=%q want=%q)\n' "$name" "$got" "$want"; fi
+}
+
+telegram_generate_service_script
+DAEMON="$INSTALL_DIR/mtproxymax-telegram.sh"
+FNS="$TEST_TMPDIR/daemon-fns.sh"
+: > "$FNS"
+for _fn in _tg_security_log _cb_label_ok _cb_enc _cb_dec _esc _iso_to_epoch; do
+    awk "/^${_fn}\\(\\)/,/^}\$/" "$DAEMON" >> "$FNS"
+done
+awk '/^# >>> TG_MENU_BEGIN$/,/^# <<< TG_MENU_END$/' "$DAEMON" >> "$FNS"
+# The traffic view renders windowed analytics, so it needs the history block too.
+awk '/^# >>> TG_HISTORY_BEGIN$/,/^# <<< TG_HISTORY_END$/' "$DAEMON" >> "$FNS"
+assert_eq "menu render extraction is valid bash" 0 \
+    "$(bash -n "$FNS" 2>/dev/null; echo $?)"
+
+ROLE_TO_RETURN="superadmin"
+_check_tg_role() { echo "$ROLE_TO_RETURN"; }
+EDIT="$TEST_TMPDIR/edit.txt"
+tg_edit() { printf '%s\n%s' "$3" "$4" > "$EDIT"; }
+tg_edit_markup() { printf '%s' "$3" > "$EDIT"; }
+tg_answer_cb() { :; }
+tg_send_to() { :; }
+tg_send() { :; }
+# The server-console views read live state; the render test only cares about
+# their SHAPE, so these answer with fixed values rather than reaching for
+# docker or the metrics endpoint.
+get_uptime() { echo "98201"; }
+get_active_connections() { echo "3"; }
+get_cached_ip() { echo "203.0.113.9"; }
+is_proxy_running() { return 0; }
+get_container_uptime() { echo "98201"; }
+load_tg_settings() { :; }
+is_running() { return 1; }
+get_cached_ip() { echo "203.0.113.9"; }
+_tg_metrics_raw() { printf ''; }
+source "$FNS"
+_CB_CHAT=111; _CB_MID=77
+
+# Render one view and echo "<text>\n<markup>".
+render() {
+    _UI_ROLE="$1"; _CB_ROLE="$1"
+    _CB_NS=""; _CB_ACT=""; _CB_TGT=""; _CB_PAGE=""
+    case "$2" in
+        hub)      _cb_render_hub ;;
+        help)     _cb_render_help ;;
+        list)     _cb_render_user_list "${3:-0}" ;;
+        detail)   _cb_render_user_detail "${3:-user01}" "${4:-0}" ;;
+        confirm)  _cb_render_confirm "${3:-disable}" "${4:-user01}" 0 ;;
+        traffic)  _cb_render_traffic 24h ;;
+        engine)   _cb_render_engine ;;
+        settings) _cb_render_settings ;;
+        manage)   _cb_render_user_manage "${3:-user01}" "${4:-0}" ;;
+        usertraffic) _cb_render_user_traffic "${3:-user01}" "${4:-0}" ;;
+        limits_q) _cb_render_limits q "${3:-user01}" "${4:-0}" ;;
+        limits_c) _cb_render_limits c "${3:-user01}" "${4:-0}" ;;
+        limits_i) _cb_render_limits i "${3:-user01}" "${4:-0}" ;;
+        limits_x) _cb_render_limits x "${3:-user01}" "${4:-0}" ;;
+        limits_r) _cb_render_limits r "${3:-user01}" "${4:-0}" ;;
+        tpl_list)   _cb_render_tpl_list ;;
+        tpl_edit)   _cb_render_tpl_edit "${3:-vip}" 0 ;;
+        tpl_field)  _cb_render_tpl_field "${3:-vip}" "${4:-q}" ;;
+        tpl_apply)  _cb_render_tpl_apply_picker "${3:-vip}" 0 ;;
+        tpl_picker) _cb_render_tpl_picker "${3:-user01}" 0 ;;
+        tools)     _cb_render_tools ;;
+        digest)    _cb_render_digest ;;
+        upstreams) _cb_render_upstreams ;;
+        fleet)     _cb_render_fleet ;;
+        vouchers)  _cb_render_vouchers ;;
+        update)    _cb_render_update "Installed version: test" ;;
+    esac
+    cat "$EDIT"
+}
+markup_of() { printf '%s' "$1" | tail -1; }
+cbs_of() { printf '%s' "$1" | grep -o '"callback_data":"[^"]*"' | sed 's/.*:"//;s/"$//'; }
+
+echo "Telegram menu render tests"
+
+VIEWS="hub help list detail confirm traffic engine settings manage usertraffic \
+limits_q limits_c limits_i limits_x limits_r \
+tpl_list tpl_edit tpl_field tpl_apply tpl_picker \
+tools digest upstreams fleet vouchers update"
+
+# ── Every view for every role is structurally sound ──────────────────────────
+for _role in superadmin reseller operator; do
+    for _v in $VIEWS; do
+        _out=$(render "$_role" "$_v")
+        _mk=$(markup_of "$_out")
+
+        # The markup must be a well-formed inline_keyboard object.
+        case "$_mk" in
+            '{"inline_keyboard":['*']}') _shape=0 ;;
+            *) _shape=1 ;;
+        esac
+        assert_ok "role=$_role view=$_v markup has inline_keyboard shape" "$_shape"
+
+        # Balanced brackets — an unbalanced one is a 400 and loses the message.
+        _open=$(printf '%s' "$_mk" | tr -cd '[' | wc -c | tr -d ' ')
+        _close=$(printf '%s' "$_mk" | tr -cd ']' | wc -c | tr -d ' ')
+        assert_eq "role=$_role view=$_v brackets balance" "$_open" "$_close"
+
+        # Every payload must fit 64 bytes and decode.
+        _bad=0
+        while IFS= read -r _p; do
+            [ -z "$_p" ] && continue
+            [ "${#_p}" -gt 64 ] && _bad=1
+            _cb_dec "$_p" || _bad=1
+        done < <(cbs_of "$_out")
+        assert_ok "role=$_role view=$_v payloads are valid and <=64 bytes" "$_bad"
+
+        # No row may exceed Telegram's 8-button limit.
+        _wide=0
+        while IFS= read -r _row; do
+            _n=$(printf '%s' "$_row" | grep -o '"text"' | wc -l | tr -d ' ')
+            [ "$_n" -gt 8 ] && _wide=1
+        done < <(printf '%s' "$_mk" | sed 's/\[/\n[/g')
+        assert_ok "role=$_role view=$_v no row exceeds 8 buttons" "$_wide"
+
+        # The body must fit one message (the chunker is tested separately).
+        _body=$(printf '%s' "$_out" | head -n -1)
+        assert_ok "role=$_role view=$_v body fits one message" \
+            "$([ "${#_body}" -le 4096 ] && echo 0 || echo 1)"
+    done
+done
+
+# ── A role never sees a button it cannot use ─────────────────────────────────
+_out=$(render reseller hub)
+assert_eq "reseller hub offers no action payloads" 0 "$(cbs_of "$_out" | grep -cE '^[ac]:')"
+assert_eq "reseller hub offers no user list" 0 "$(cbs_of "$_out" | grep -c '^u:')"
+
+_out=$(render operator hub)
+assert_eq "unrecognised role hub offers no action payloads" 0 "$(cbs_of "$_out" | grep -cE '^[ac]:')"
+
+_out=$(render superadmin hub)
+assert_ok "superadmin hub does offer the user list" \
+    "$([ "$(cbs_of "$_out" | grep -c '^u:l:')" -ge 1 ] && echo 0 || echo 1)"
+
+# ── A reseller's detail card must not carry destructive actions ──────────────
+# _cb_dispatch would refuse them anyway, but advertising them is misleading.
+_out=$(render reseller detail user01)
+assert_eq "reseller detail card hides destructive buttons" 0 \
+    "$(cbs_of "$_out" | grep -cE '^[ac]:(disable|remove|rotate)')"
+
+_out=$(render superadmin detail user01)
+assert_ok "superadmin detail card does offer actions" \
+    "$([ "$(cbs_of "$_out" | grep -cE '^a:')" -ge 1 ] && echo 0 || echo 1)"
+
+# ── Pagination ───────────────────────────────────────────────────────────────
+_p0=$(cbs_of "$(render superadmin list 0)")
+assert_eq "page 0 shows a full page of users" 6 "$(printf '%s\n' "$_p0" | grep -c '^u:s:')"
+assert_eq "page 0 has no Prev button" 0 "$(printf '%s\n' "$_p0" | grep -c '^u:l:$')"
+
+_p2=$(cbs_of "$(render superadmin list 2)")
+assert_eq "last page shows the remaining users" 1 "$(printf '%s\n' "$_p2" | grep -c '^u:s:')"
+
+# An out-of-range page must clamp rather than render an empty keyboard.
+_p9=$(cbs_of "$(render superadmin list 99)")
+assert_ok "an out-of-range page still renders users" \
+    "$([ "$(printf '%s\n' "$_p9" | grep -c '^u:s:')" -ge 1 ] && echo 0 || echo 1)"
+
+# A garbage page value must not produce garbage output.
+_px=$(render superadmin list "abc")
+assert_ok "a non-numeric page still renders a keyboard" \
+    "$(printf '%s' "$_px" | tail -1 | grep -q 'inline_keyboard' && echo 0 || echo 1)"
+
+# Back from a detail card returns to the page it came from.
+_cbs=$(cbs_of "$(render superadmin detail user07 1)")
+assert_ok "detail card carries its origin page into Back" \
+    "$(printf '%s\n' "$_cbs" | grep -q '^u:l:1$' && echo 0 || echo 1)"
+
+# ── A disabled secret offers Enable, not Disable ─────────────────────────────
+# user03 is disabled in the fixture.
+_cbs=$(cbs_of "$(render superadmin detail user03)")
+assert_ok "a disabled secret offers Enable" \
+    "$(printf '%s\n' "$_cbs" | grep -q '^a:enable:user03$' && echo 0 || echo 1)"
+assert_eq "a disabled secret does not offer Disable" 0 \
+    "$(printf '%s\n' "$_cbs" | grep -c '^a:disable:user03$')"
+
+printf '\n%d tests, %d failures\n' "$TESTS_RUN" "$TESTS_FAILED"
+[ "$TESTS_FAILED" -eq 0 ]
diff --git a/tests/test_telegram_message_primitives.sh b/tests/test_telegram_message_primitives.sh
new file mode 100644
index 0000000..f4e2e74
--- /dev/null
+++ b/tests/test_telegram_message_primitives.sh
@@ -0,0 +1,160 @@
+#!/bin/bash
+# Tests for the Bot API send primitives: chunking and the 400 fallback.
+#
+# Two behaviours matter here and neither existed before:
+#
+#   * Telegram caps a message at 4096 UTF-16 units and the bot builds messages
+#     by appending one line per secret, so a fleet with enough users silently
+#     produced a message that failed to send at all. There was no chunking.
+#   * A single malformed legacy-Markdown entity made Telegram reject the whole
+#     message with a 400. Retrying without parse_mode costs the formatting
+#     instead of the content.
+set -o pipefail
+
+if [ "${BASH_VERSINFO[0]:-0}" -lt 4 ]; then
+    echo "SKIP: bash 4+ required (got ${BASH_VERSION:-unknown})" >&2
+    exit 0
+fi
+
+TEST_TMPDIR=$(mktemp -d)
+INSTALL_DIR="$TEST_TMPDIR/install"
+mkdir -p "$INSTALL_DIR/relay_stats"
+OFFSET_FILE="$INSTALL_DIR/relay_stats/tg_offset"
+ADMINS_FILE="$INSTALL_DIR/admins.conf"
+
+MTPROXYMAX_SOURCE_ONLY=true source "$(dirname "${BASH_SOURCE[0]}")/../mtproxymax.sh"
+set +e
+trap 'rm -rf "$TEST_TMPDIR"' EXIT
+
+TESTS_RUN=0
+TESTS_FAILED=0
+
+assert_eq() {
+    local name="$1" want="$2" got="$3"
+    TESTS_RUN=$((TESTS_RUN + 1))
+    if [ "$got" = "$want" ]; then
+        printf '  PASS  %s\n' "$name"
+    else
+        TESTS_FAILED=$((TESTS_FAILED + 1))
+        printf '  FAIL  %s (got=%q want=%q)\n' "$name" "$got" "$want"
+    fi
+}
+
+assert_ok() {
+    local name="$1" cond="$2"
+    TESTS_RUN=$((TESTS_RUN + 1))
+    if [ "$cond" -eq 0 ] 2>/dev/null; then
+        printf '  PASS  %s\n' "$name"
+    else
+        TESTS_FAILED=$((TESTS_FAILED + 1))
+        printf '  FAIL  %s\n' "$name"
+    fi
+}
+
+telegram_generate_service_script
+DAEMON="$INSTALL_DIR/mtproxymax-telegram.sh"
+PRIMS="$TEST_TMPDIR/prims.sh"
+: > "$PRIMS"
+for _fn in _tg_chunk_text _tg_send_pieces _tg_msg_id; do
+    awk "/^${_fn}\\(\\)/,/^}\$/" "$DAEMON" >> "$PRIMS"
+done
+assert_eq "primitive extraction is valid bash" 0 \
+    "$(bash -n "$PRIMS" 2>/dev/null; echo $?)"
+source "$PRIMS"
+
+echo "Telegram message primitive tests"
+
+# The chunker separates records with 0x1f. NOTE: `tr '\x1f' ...` does not work
+# — GNU tr has no \xHH escape — and chunk bodies legitimately contain newlines,
+# so neither line-counting nor splitting on newlines is valid here.
+SEP=$'\x1f'
+n_chunks() {
+    local c n=0
+    while IFS= read -r -d "$SEP" c; do n=$((n + 1)); done < <(_tg_chunk_text "$2" "$1")
+    printf '%s' "$n"
+}
+# Reassemble every chunk, joining with the newline the split removed.
+joined() {
+    local c out=""
+    while IFS= read -r -d "$SEP" c; do
+        if [ -z "$out" ]; then out="$c"; else out="${out}"$'\n'"${c}"; fi
+    done < <(_tg_chunk_text "$2" "$1")
+    printf '%s' "$out"
+}
+
+# ── A body that fits stays a single chunk, unmodified ────────────────────────
+assert_eq "short body yields one chunk" 1 "$(n_chunks "hello world" 3800)"
+assert_eq "short body is passed through verbatim" "hello world" "$(joined "hello world" 3800)"
+
+# ── A long body is split, and nothing is lost ────────────────────────────────
+_long=$(seq 1 40 | awk '{printf "line %02d %s\n", $1, "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"}')
+assert_ok "long body splits into more than one chunk" \
+    "$([ "$(n_chunks "$_long" 300)" -gt 1 ] && echo 0 || echo 1)"
+
+_over=1
+while IFS= read -r -d "$SEP" _c; do
+    [ "${#_c}" -gt 300 ] && _over=0
+done < <(_tg_chunk_text 300 "$_long")
+assert_ok "no chunk exceeds the budget" "$([ "$_over" -eq 1 ] && echo 0 || echo 1)"
+
+# Reassembly must be lossless for unfenced content.
+assert_eq "splitting then rejoining is lossless" "$_long" "$(joined "$_long" 300)"
+
+# ── Fences are closed and reopened across a split ────────────────────────────
+# A sparkline is alignment-sensitive: a chunk that opens a fence without
+# closing it renders the remainder of that message as code.
+_fenced=$( { printf 'header\n```\n'; seq 1 30 | awk '{printf "bar %02d %s\n", $1, "yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy"}'; printf '```\ntail\n'; } )
+_bad=0
+while IFS= read -r -d "$SEP" _c; do
+    _n=$(printf '%s\n' "$_c" | grep -c '^```')
+    [ $(( _n % 2 )) -ne 0 ] && _bad=1
+done < <(_tg_chunk_text 250 "$_fenced")
+assert_ok "every chunk has balanced fences" "$([ "$_bad" -eq 0 ] && echo 0 || echo 1)"
+
+assert_ok "fenced body actually splits" \
+    "$([ "$(n_chunks "$_fenced" 250)" -gt 1 ] && echo 0 || echo 1)"
+
+# No fenced row may be dropped, whatever the split point.
+_rows=$(printf '%s' "$(joined "$_fenced" 250)" | grep -c '^bar ')
+assert_eq "all fenced rows survive the split" 30 "$_rows"
+
+# ── The 400 fallback drops parse_mode instead of the message ─────────────────
+POST_LOG="$TEST_TMPDIR/posts.log"
+POST_N=0
+_tg_post_method() {
+    printf '%s\n' "$*" >> "$POST_LOG"
+    POST_N=$((POST_N + 1))
+    if [ "$POST_N" -eq 1 ]; then
+        printf '{"ok":false,"error_code":400,"description":"Bad Request: can not parse entities"}'
+    else
+        printf '{"ok":true,"result":{"message_id":42,"chat":{"id":1}}}'
+    fi
+}
+: > "$POST_LOG"
+_tg_send_pieces "111" "" "bad *markdown" "" >/dev/null
+assert_eq "a 400 is retried exactly once" 2 "$(wc -l < "$POST_LOG" | tr -d ' ')"
+assert_ok "the first attempt uses Markdown" \
+    "$(grep -q 'parse_mode=Markdown' "$POST_LOG" && echo 0 || echo 1)"
+assert_ok "the retry omits parse_mode" \
+    "$(sed -n '2p' "$POST_LOG" | grep -qv 'parse_mode' && echo 0 || echo 1)"
+
+# A successful send must NOT be retried.
+: > "$POST_LOG"
+POST_N=99
+_tg_send_pieces "111" "" "fine" "" >/dev/null
+assert_eq "a successful send is not retried" 1 "$(wc -l < "$POST_LOG" | tr -d ' ')"
+
+# ── The keyboard rides on the final chunk only ───────────────────────────────
+: > "$POST_LOG"
+POST_N=99
+_tg_send_pieces "111" "" "$_long" '{"inline_keyboard":[[{"text":"x","callback_data":"n"}]]}' >/dev/null
+assert_eq "only the last chunk carries reply_markup" 1 "$(grep -c 'reply_markup' "$POST_LOG")"
+
+# ── message_id extraction ────────────────────────────────────────────────────
+assert_eq "extracts message_id from a send response" 42 \
+    "$(_tg_msg_id '{"ok":true,"result":{"message_id":42,"chat":{"id":1}}}')"
+assert_eq "returns empty when there is no message_id" "" \
+    "$(_tg_msg_id '{"ok":false}')"
+
+printf '\n%d tests, %d failures\n' "$TESTS_RUN" "$TESTS_FAILED"
+[ "$TESTS_FAILED" -eq 0 ]
diff --git a/tests/test_telegram_no_codebox.sh b/tests/test_telegram_no_codebox.sh
new file mode 100644
index 0000000..1266e27
--- /dev/null
+++ b/tests/test_telegram_no_codebox.sh
@@ -0,0 +1,269 @@
+#!/bin/bash
+# Tests that no bot reply renders inside a Markdown code fence.
+#
+# Telegram draws a fenced block as a monospace box with a copy button, which is
+# the wrong shape for a status reply: it reads as pasted console output, it
+# cannot wrap, and every line gets a tap target the reader did not ask for.
+#
+# The commands below used to dump CLI output straight into ```…```. The rule
+# this file pins is that they now emit one line per fact. The value must survive
+# the change, so each case asserts BOTH that no fence is present AND that the
+# data still reaches the reader — a rewrite that quietly dropped the content
+# would pass a fence-only check.
+set -o pipefail
+
+if [ "${BASH_VERSINFO[0]:-0}" -lt 4 ]; then
+    echo "SKIP: bash 4+ required (got ${BASH_VERSION:-unknown})" >&2
+    exit 0
+fi
+
+TEST_TMPDIR=$(mktemp -d)
+INSTALL_DIR="$TEST_TMPDIR/install"
+mkdir -p "$INSTALL_DIR/relay_stats"
+OFFSET_FILE="$INSTALL_DIR/relay_stats/tg_offset"
+ADMINS_FILE="$INSTALL_DIR/admins.conf"
+AUDIT_LOG="$INSTALL_DIR/audit.log"
+SECRETS_FILE="$INSTALL_DIR/secrets.conf"
+VOUCHERS_FILE="$INSTALL_DIR/vouchers.conf"
+UPSTREAMS_FILE="$INSTALL_DIR/upstreams.conf"
+
+printf 'alice|%s|1700000000|true|0|0|0|0||\n' "$(printf 'a%.0s' $(seq 1 32))" > "$SECRETS_FILE"
+
+# The voucher reply reads the vault rather than the CLI's padded table, so the
+# fixture has to look like a real one: code|quota_bytes|days|conns|ips|tier|
+# status|created|redeemed_by|redeemed_at.
+cat > "$VOUCHERS_FILE" <<'EOF'
+MTP-AAAA-BBBB|10737418240|30|15|5|standard|ACTIVE|2026-01-01 00:00:00 UTC|-|-
+MTP-CCCC-DDDD|5368709120|7|15|5|standard|ACTIVE|2026-01-02 00:00:00 UTC|-|-
+MTP-OLD1-OLD2|10737418240|30|15|5|standard|REDEEMED|2025-12-01 00:00:00 UTC|tg_5|2025-12-02 00:00:00 UTC
+EOF
+
+MTPROXYMAX_SOURCE_ONLY=true source "$(dirname "${BASH_SOURCE[0]}")/../mtproxymax.sh"
+set +e
+trap 'rm -rf "$TEST_TMPDIR"' EXIT
+
+TESTS_RUN=0
+TESTS_FAILED=0
+
+assert_not_contains() {
+    local name="$1" needle="$2" haystack="$3"
+    TESTS_RUN=$((TESTS_RUN + 1))
+    if [[ "$haystack" == *"$needle"* ]]; then
+        TESTS_FAILED=$((TESTS_FAILED + 1))
+        printf '  FAIL  %s (unexpected %q in %q)\n' "$name" "$needle" "$haystack"
+    else
+        printf '  PASS  %s\n' "$name"
+    fi
+}
+assert_contains() {
+    local name="$1" needle="$2" haystack="$3"
+    TESTS_RUN=$((TESTS_RUN + 1))
+    if [[ "$haystack" == *"$needle"* ]]; then
+        printf '  PASS  %s\n' "$name"
+    else
+        TESTS_FAILED=$((TESTS_FAILED + 1))
+        printf '  FAIL  %s (missing %q in %q)\n' "$name" "$needle" "$haystack"
+    fi
+}
+assert_eq() {
+    local name="$1" want="$2" got="$3"
+    TESTS_RUN=$((TESTS_RUN + 1))
+    if [ "$got" = "$want" ]; then
+        printf '  PASS  %s\n' "$name"
+    else
+        TESTS_FAILED=$((TESTS_FAILED + 1))
+        printf '  FAIL  %s (got=%q want=%q)\n' "$name" "$got" "$want"
+    fi
+}
+
+# ── Extract the shipped command dispatcher ───────────────────────────────────
+telegram_generate_service_script
+DAEMON="$INSTALL_DIR/mtproxymax-telegram.sh"
+FNS="$TEST_TMPDIR/daemon-fns.sh"
+: > "$FNS"
+for _fn in _tg_security_log _cb_label_ok _cb_enc _cb_dec _esc _process_cmd \
+           _tg_pending_file _tg_pending_set _tg_pending_take _tg_pending_clear \
+           _tg_pending_try _tg_pending_run _tg_new_secret_link; do
+    awk "/^${_fn}\\(\\)/,/^}\$/" "$DAEMON" >> "$FNS"
+done
+awk '/^# >>> TG_MENU_BEGIN$/,/^# <<< TG_MENU_END$/' "$DAEMON" >> "$FNS"
+# The analytics views read the rolling history, so their block comes too.
+awk '/^# >>> TG_HISTORY_BEGIN$/,/^# <<< TG_HISTORY_END$/' "$DAEMON" >> "$FNS"
+awk '/^# >>> TG_REPORT_BEGIN$/,/^# <<< TG_REPORT_END$/' "$DAEMON" >> "$FNS"
+assert_eq "dispatcher extraction is valid bash" 0 \
+    "$(bash -n "$FNS" 2>/dev/null; echo $?)"
+assert_eq "menu block was found in the daemon" 1 \
+    "$(grep -c '^# >>> TG_MENU_BEGIN$' "$FNS")"
+
+# ── Stubs ────────────────────────────────────────────────────────────────────
+SENDS="$TEST_TMPDIR/sends.log"
+CALLS="$TEST_TMPDIR/calls.log"
+
+_check_tg_role() { echo "superadmin"; }
+EDIT="$TEST_TMPDIR/edit.txt"
+tg_edit() { printf '%s\n%s' "$3" "$4" > "$EDIT"; }
+tg_edit_markup() { printf '%s' "$3" > "$EDIT"; }
+tg_answer_cb() { :; }
+tg_send() { printf 'admin|%s\n' "$*" >> "$SENDS"; }
+tg_send_to() { printf '%s|%s\n' "$1" "$2" >> "$SENDS"; }
+tg_send_kb() { printf 'admin|%s\n' "$1" >> "$SENDS"; }
+tg_send_to_kb() { printf '%s|%s\n' "$1" "$2" >> "$SENDS"; }
+load_tg_settings() { :; }
+is_running() { return 0; }
+is_proxy_running() { return 0; }
+log_warn() { :; }
+get_cached_ip() { echo "203.0.113.9"; }
+get_stats() { echo "1024 2048 7"; }
+get_uptime() { echo "98123"; }
+get_active_connections() { echo "7"; }
+get_container_uptime() { echo "98123"; }
+get_cum_user_traffic() { echo "1024 2048"; }
+format_duration() { echo "1d 3h 15m"; }
+get_stats_dummy() { :; }
+_esc() { printf '%s' "$1"; }
+_tg_metrics_raw() { printf ''; }
+mkdir -p "$INSTALL_DIR/relay_stats"
+load_traffic() { :; }
+
+# The manager stub reproduces the REAL output shape of each verb, padding
+# included, so the parsing in the rewritten handlers is exercised against
+# something that looks like what actually ships.
+cat > "$INSTALL_DIR/mtproxymax" <<'EOS'
+#!/bin/bash
+printf '%s\n' "$*" >> "$MTPX_CALLS"
+case "$1" in
+    voucher)
+        case "$2" in
+            list)
+                cat <<'OUT'
+CODE           QUOTA      DAYS  STATUS
+MTP-AAAA-BBBB  10.00 GB   30    active
+MTP-CCCC-DDDD  5.00 GB    7     active
+OUT
+                ;;
+            create) exit 0 ;;
+        esac
+        ;;
+    health)
+        cat <<'OUT'
+  Engine:          running
+  Port 443:        listening
+  Metrics:         ok
+  Secrets:         1 active
+OUT
+        ;;
+    update) echo "Already on the latest version (v1.4.1-LTS)" ;;
+    fleet)
+        cat <<'OUT'
+HOSTNAME       IP             USERS   TRAFFIC     LOAD
+node-a         203.0.113.9    42      12.30 GB    0.41
+node-b         198.51.100.4   7        1.10 GB    0.05
+OUT
+        ;;
+esac
+exit 0
+EOS
+chmod +x "$INSTALL_DIR/mtproxymax"
+export MTPX_CALLS="$CALLS"
+
+source "$FNS"
+
+PROXY_PORT=443
+PROXY_DOMAIN="cloudflare.com"
+MASKING_ENABLED="true"
+VERSION="v1.4.1-LTS"
+
+run_cmd() {   # run_cmd <text>
+    : > "$SENDS"; : > "$CALLS"
+    _process_cmd "1" "111" "$1" >/dev/null 2>&1
+    cat "$SENDS"
+}
+
+# ── /mp_voucher ──────────────────────────────────────────────────────────────
+_out=$(run_cmd "/mp_voucher list")
+assert_not_contains "voucher list draws no code box" '```' "$_out"
+assert_contains "voucher list still shows the codes" "MTP-AAAA-BBBB" "$_out"
+assert_contains "voucher list still shows the second code" "MTP-CCCC-DDDD" "$_out"
+assert_contains "voucher list still shows the quota" "10.00 GB" "$_out"
+assert_not_contains "voucher list hides redeemed codes" "MTP-OLD1-OLD2" "$_out"
+
+_out=$(run_cmd "/mp_voucher create 2 10G 30")
+assert_not_contains "voucher create draws no code box" '```' "$_out"
+assert_contains "voucher create still reaches the CLI" "voucher create 2 10G 30" "$(cat "$CALLS")"
+# The create reply must not repeat the two codes that were already there.
+assert_not_contains "voucher create does not re-announce the existing vault" "MTP-AAAA-BBBB" "$_out"
+
+# ── /mp_health ───────────────────────────────────────────────────────────────
+_out=$(run_cmd "/mp_health")
+assert_not_contains "health draws no code box" '```' "$_out"
+assert_contains "health still reports the engine state" "Engine" "$_out"
+assert_contains "health still reports the metrics check" "Metrics" "$_out"
+
+# ── /mp_update ───────────────────────────────────────────────────────────────
+_out=$(run_cmd "/mp_update")
+assert_not_contains "update draws no code box" '```' "$_out"
+assert_contains "update still reports the version" "v1.4.1-LTS" "$_out"
+
+# ── /mp_fleet ────────────────────────────────────────────────────────────────
+_out=$(run_cmd "/mp_fleet")
+assert_not_contains "fleet draws no code box" '```' "$_out"
+assert_contains "fleet still lists the first node" "node-a" "$_out"
+assert_contains "fleet still lists the second node" "node-b" "$_out"
+# Column padding only reads as columns inside a fence; outside one it is just a
+# ragged gap, so the rewritten view must not carry it.
+assert_not_contains "fleet does not smuggle back column padding" "     " "$_out"
+
+# ── /mp_lockdown usage ───────────────────────────────────────────────────────
+_out=$(run_cmd "/mp_lockdown status")
+assert_not_contains "lockdown usage draws no code box" '```' "$_out"
+
+# ── The whole surface, swept for fences ──────────────────────────────────────
+# A per-command check can miss a fence added to a command nobody thought to
+# list, so sweep every administrative command once.
+for _c in "/mp_help" "/mp_status" "/mp_secrets" "/mp_link" "/mp_limits" \
+          "/mp_traffic" "/mp_upstreams" "/mp_digest" "/mp_restart" "/mp_lockdown"; do
+    _out=$(run_cmd "$_c")
+    assert_not_contains "$_c draws no code box" '```' "$_out"
+done
+
+# ── The views reachable by button ────────────────────────────────────────────
+# ── The analytics views ──────────────────────────────────────────────────────
+# These two draw a sparkline. It used to sit in a fence "for monospace
+# alignment"; the glyphs are block elements, which share an advance width in a
+# proportional font, so the fence bought nothing and cost a code box.
+HISTORY="$TEST_TMPDIR/history"
+HISTORY_DIR="$HISTORY"
+mkdir -p "$HISTORY"
+_now=$(date +%s)
+for _i in $(seq 0 23); do
+    printf '%s|%s|%s|%s|-\n' "$(( _now - _i * 3600 ))" "$(( _i * 1024 ))" "$(( _i * 2048 ))" "3" >> "$HISTORY/global.tsv"
+done
+printf '%s|alice|5000|9000\n' "$_now" > "$HISTORY/users.tsv"
+
+EDIT="$TEST_TMPDIR/edit-traffic.txt"; : > "$EDIT"
+_cb_render_traffic "24h"
+assert_not_contains "the traffic view draws no code box" '```' "$(cat "$EDIT")"
+assert_contains "the traffic view still draws a sparkline" "▁" "$(cat "$EDIT")"
+
+# The periodic report is a push, not an edit — it goes out through tg_send_kb.
+: > "$SENDS"
+_tg_periodic_report "$_now" 86400
+assert_not_contains "the periodic report draws no code box" '```' "$(cat "$SENDS")"
+assert_contains "the periodic report still draws a sparkline" "▁" "$(cat "$SENDS")"
+
+for _v in hub help user_list engine settings; do
+    EDIT="$TEST_TMPDIR/edit-$_v.txt"
+    : > "$EDIT"
+    _CB_CHAT="111"; _CB_MID="77"; _CB_DATA=""; _UI_ROLE="superadmin"
+    case "$_v" in
+        hub)          _cb_render_hub ;;
+        help)         _cb_render_help ;;
+        user_list)    _cb_render_user_list 0 ;;
+        engine)       _cb_render_engine ;;
+        settings)     _cb_render_settings ;;
+    esac
+    assert_not_contains "$_v view draws no code box" '```' "$(cat "$EDIT")"
+done
+
+printf '\n%d tests, %d failures\n' "$TESTS_RUN" "$TESTS_FAILED"
+[ "$TESTS_FAILED" -eq 0 ]
diff --git a/tests/test_telegram_parity.sh b/tests/test_telegram_parity.sh
new file mode 100644
index 0000000..ceabb0f
--- /dev/null
+++ b/tests/test_telegram_parity.sh
@@ -0,0 +1,244 @@
+#!/bin/bash
+# Tests that every administrative command has a button route.
+#
+# The point of the button surface is that an operator never has to remember a
+# command, so a command that is reachable ONLY by typing is a gap, not a
+# nicety. The parity map is asserted directly: for each command there is a
+# payload somewhere in the menu graph that reaches the same CLI verb.
+#
+# The global verbs (rotate-all, restart, update, lockdown) are the dangerous
+# ones: they are targetless, so they carry a "_" placeholder where a secret
+# label would go, and they must stay behind a confirmation.
+set -o pipefail
+
+if [ "${BASH_VERSINFO[0]:-0}" -lt 4 ]; then
+    echo "SKIP: bash 4+ required (got ${BASH_VERSION:-unknown})" >&2
+    exit 0
+fi
+
+TEST_TMPDIR=$(mktemp -d)
+INSTALL_DIR="$TEST_TMPDIR/install"
+mkdir -p "$INSTALL_DIR/relay_stats"
+OFFSET_FILE="$INSTALL_DIR/relay_stats/tg_offset"
+ADMINS_FILE="$INSTALL_DIR/admins.conf"
+AUDIT_LOG="$INSTALL_DIR/audit.log"
+SECRETS_FILE="$INSTALL_DIR/secrets.conf"
+TEMPLATES_FILE="$INSTALL_DIR/templates.conf"
+
+printf 'alice|%s|1700000000|true|7|3|10737418240|2027-01-01||\n' "$(printf 'a%.0s' $(seq 1 32))" > "$SECRETS_FILE"
+# A secret genuinely called "_" — the global verbs use "_" as a placeholder for
+# "no label", and that must not take this secret's verbs away from it.
+printf '_|%s|1700000000|true|0|0|0|0||\n' "$(printf '9%.0s' $(seq 1 32))" >> "$SECRETS_FILE"
+printf 'vip|100|5|50G|2027-01-01|top tier\n' > "$TEMPLATES_FILE"
+
+MTPROXYMAX_SOURCE_ONLY=true source "$(dirname "${BASH_SOURCE[0]}")/../mtproxymax.sh"
+set +e
+trap 'rm -rf "$TEST_TMPDIR"' EXIT
+
+TESTS_RUN=0
+TESTS_FAILED=0
+
+assert_eq() {
+    local name="$1" want="$2" got="$3"
+    TESTS_RUN=$((TESTS_RUN + 1))
+    if [ "$got" = "$want" ]; then printf '  PASS  %s\n' "$name"
+    else TESTS_FAILED=$((TESTS_FAILED + 1)); printf '  FAIL  %s (got=%q want=%q)\n' "$name" "$got" "$want"; fi
+}
+assert_contains() {
+    local name="$1" needle="$2" haystack="$3"
+    TESTS_RUN=$((TESTS_RUN + 1))
+    if [[ "$haystack" == *"$needle"* ]]; then printf '  PASS  %s\n' "$name"
+    else TESTS_FAILED=$((TESTS_FAILED + 1)); printf '  FAIL  %s (missing %q in %q)\n' "$name" "$needle" "$haystack"; fi
+}
+assert_not_contains() {
+    local name="$1" needle="$2" haystack="$3"
+    TESTS_RUN=$((TESTS_RUN + 1))
+    if [[ "$haystack" == *"$needle"* ]]; then
+        TESTS_FAILED=$((TESTS_FAILED + 1)); printf '  FAIL  %s (unexpected %q in %q)\n' "$name" "$needle" "$haystack"
+    else printf '  PASS  %s\n' "$name"; fi
+}
+
+telegram_generate_service_script
+DAEMON="$INSTALL_DIR/mtproxymax-telegram.sh"
+FNS="$TEST_TMPDIR/daemon-fns.sh"
+: > "$FNS"
+for _fn in _tg_security_log _esc _cb_label_ok _cb_enc _cb_dec _iso_to_epoch; do
+    awk "/^${_fn}\\(\\)/,/^}\$/" "$DAEMON" >> "$FNS"
+done
+awk '/^# >>> TG_MENU_BEGIN$/,/^# <<< TG_MENU_END$/' "$DAEMON" >> "$FNS"
+assert_eq "extraction is valid bash" 0 "$(bash -n "$FNS" 2>/dev/null; echo $?)"
+
+SENDS="$TEST_TMPDIR/sends.log"
+CALLS="$TEST_TMPDIR/calls.log"
+EDITS="$TEST_TMPDIR/edits.log"
+ROLE_TO_RETURN="superadmin"
+
+_check_tg_role() { echo "$ROLE_TO_RETURN"; }
+tg_send() { printf 'admin|%s\n' "$*" >> "$SENDS"; }
+tg_send_to() { printf '%s|%s\n' "$1" "$2" >> "$SENDS"; }
+tg_send_kb() { printf 'admin|%s|%s\n' "$1" "$2" >> "$SENDS"; }
+tg_send_to_kb() { printf '%s|%s|%s\n' "$1" "$2" "$3" >> "$SENDS"; }
+tg_answer_cb() { :; }
+tg_edit() { printf '%s\n---\n%s\n' "$3" "$4" > "$EDITS"; }
+tg_edit_markup() { printf 'markup\n---\n%s\n' "$3" > "$EDITS"; }
+load_tg_settings() { :; }
+is_running() { return 0; }
+is_proxy_running() { return 0; }
+log_warn() { :; }
+get_cached_ip() { echo "203.0.113.9"; }
+get_stats() { echo "1024 2048 7"; }
+get_uptime() { echo "98123"; }
+get_active_connections() { echo "7"; }
+get_container_uptime() { echo "98123"; }
+get_cum_user_traffic() { echo "1024 2048"; }
+format_duration() { echo "1d 3h 15m"; }
+_tg_metrics_raw() { printf ''; }
+_tg_have_python() { return 1; }
+
+cat > "$INSTALL_DIR/mtproxymax" <<'EOS'
+#!/bin/bash
+printf '%s\n' "$*" >> "$MTPX_CALLS"
+case "$1" in
+    telegram)
+        # The /help view renders from the same list Telegram is told about,
+        # rather than a hand-maintained copy that can drift from it.
+        case "$2" in
+            commands)
+                printf 'mp_status|Proxy status\nmp_add|Add a new secret (usage: /mp_add <label>)\n'
+                ;;
+        esac
+        ;;
+esac
+exit 0
+EOS
+chmod +x "$INSTALL_DIR/mtproxymax"
+export MTPX_CALLS="$CALLS"
+
+source "$FNS"
+
+_UI_ROLE="superadmin"
+_CB_CHAT="111"; _CB_MID="77"
+
+prepare() {
+    local p
+    p=$(_cb_enc "$1" "$2" "$3" "$4") || { _CB_DATA=""; return 1; }
+    _CB_DATA="$p"; _CB_NS="$1"; _CB_ACT="$2"; _CB_TGT="$3"; _CB_PAGE="$4"
+    _CB_CHAT="111"; _CB_MID="77"; _CB_TOAST=""; _CB_ALERT="false"
+    : > "$EDITS"; : > "$CALLS"; : > "$SENDS"
+}
+render() { prepare "$1" "$2" "$3" "$4" && _cb_dispatch >/dev/null 2>&1; cat "$EDITS"; }
+commit() { prepare "$1" "$2" "$3" "$4" && _cb_dispatch >/dev/null 2>&1; cat "$CALLS"; }
+toast()  { prepare "$1" "$2" "$3" "$4" && _cb_dispatch >/dev/null 2>&1; printf '%s' "$_CB_TOAST"; }
+
+# ── The hub reaches every section ────────────────────────────────────────────
+_out=$(render "m" "" "" "")
+assert_contains "hub offers users"     "u:l:0" "$_out"
+assert_contains "hub offers traffic"   "t"     "$_out"
+assert_contains "hub offers the server console" "y" "$_out"
+assert_contains "hub offers templates" "k"     "$_out"
+assert_contains "hub offers tools"     "g"     "$_out"
+assert_contains "hub offers settings"  "s"     "$_out"
+assert_contains "hub offers help"      "m:h"   "$_out"
+assert_not_contains "hub draws no code box" '```' "$_out"
+
+# ── The server console reaches everything /mp_status, /mp_digest,
+#    /mp_upstreams and /mp_fleet used to be the only route to ────────────────
+_out=$(render "y" "" "" "")
+assert_contains "server console reaches the digest"    "y:d" "$_out"
+assert_contains "server console reaches upstreams"     "y:p" "$_out"
+assert_contains "server console reaches fleet"         "y:f" "$_out"
+assert_contains "server console reaches vouchers"      "y:v" "$_out"
+assert_contains "server console reaches the update check" "y:u" "$_out"
+
+for _v in d p f v u; do
+    _out=$(render "y" "$_v" "" "")
+    assert_not_contains "server sub-view $_v draws no code box" '```' "$_out"
+done
+
+# ── Tools reach the commands that need typed input ───────────────────────────
+_out=$(render "g" "" "" "")
+assert_contains "tools offer adding a user"   "g:a"   "$_out"
+assert_contains "tools offer rotate-all"      "a:rotall:_" "$_out"
+assert_contains "tools offer a broadcast"     "g:b"   "$_out"
+assert_contains "tools offer quarantine"      "a:lockdown:on" "$_out"
+assert_not_contains "tools do not execute lockdown on a single tap" "c:lockdown:on" "$_out"
+assert_contains "tools offer restart"         "a:restart:_" "$_out"
+assert_contains "tools offer update"          "a:update:_" "$_out"
+
+# ── Global verbs: confirmed first, and reaching the right CLI verb ───────────
+assert_contains "rotate-all asks first" "Rotate all" "$(render "a" "rotall" "_" "")"
+assert_eq "rotate-all does not run on the confirm tap" "" "$(cat "$CALLS")"
+assert_contains "restart asks first" "Restart" "$(render "a" "restart" "_" "")"
+assert_eq "restart does not run on the confirm tap" "" "$(cat "$CALLS")"
+
+assert_eq "rotate-all runs the bulk verb" "secret rotate --all" "$(commit "c" "rotall" "_" "")"
+assert_eq "restart runs the service verb" "restart"             "$(commit "c" "restart" "_" "")"
+assert_eq "update runs the self-update verb" "update"           "$(commit "c" "update" "_" "")"
+assert_eq "lockdown on reaches the CLI"  "lockdown on"          "$(commit "c" "lockdown" "on" "")"
+assert_eq "lockdown off reaches the CLI" "lockdown off"         "$(commit "c" "lockdown" "off" "")"
+assert_eq "a nonsense lockdown mode is refused" "" "$(commit "c" "lockdown" "maybe" "")"
+
+# The "_" placeholder must not leak into the secret verbs: a secret genuinely
+# named "_" is legal, and "disable _" must still mean that secret.
+assert_eq "a secret named _ is still a secret" \
+    "secret disable _" "$(commit "c" "disable" "_" "0")"
+
+# ── Typed-input flows arm a prompt and then land on the right verb ───────────
+arm() {   # arm <ns> <act> <tgt> <page> -> pending store line
+    prepare "$1" "$2" "$3" "$4" && _cb_dispatch >/dev/null 2>&1
+    cat "$INSTALL_DIR/relay_stats/.tg_pending" 2>/dev/null
+}
+
+assert_contains "add-user arms a prompt"   "|add|-|"    "$(arm "g" "a" "" "")"
+assert_contains "broadcast arms a prompt"  "|broadcast|-|" "$(arm "g" "b" "" "")"
+assert_contains "note arms a prompt"       "|note|alice|" "$(arm "e" "n" "alice" "0")"
+assert_contains "ad-tag arms a prompt"     "|adtag|alice|" "$(arm "e" "a" "alice" "0")"
+
+# And the typed answer reaches the matching CLI verb.
+answer() {   # answer <text>
+    : > "$CALLS"; : > "$SENDS"
+    _tg_pending_try "111" "$1" >/dev/null 2>&1
+    cat "$CALLS"
+}
+arm "e" "n" "alice" "0" >/dev/null
+assert_eq "a typed note reaches the note verb" "secret note alice hello there" "$(answer "hello there")"
+
+arm "e" "a" "alice" "0" >/dev/null
+assert_eq "a typed ad-tag reaches the adtag verb" \
+    "secret adtag alice 0123456789abcdef0123456789abcdef" "$(answer "0123456789abcdef0123456789abcdef")"
+
+arm "e" "a" "alice" "0" >/dev/null
+assert_eq "an ad-tag that is not 32 hex is refused" "" "$(answer "not-a-tag")"
+
+arm "g" "b" "" "" >/dev/null
+assert_eq "a typed broadcast reaches the broadcast verb" "broadcast hello all" "$(answer "hello all")"
+
+# A prompt for a secret that has since been removed must not write to it.
+arm "e" "n" "ghost" "0" >/dev/null
+assert_eq "a note for a removed secret is refused" "" "$(answer "hi")"
+
+# ── The escape hatch still works with these flows armed ──────────────────────
+arm "e" "n" "alice" "0" >/dev/null
+: > "$CALLS"
+_tg_pending_try "111" "/mp_status" >/dev/null 2>&1
+assert_eq "a command escapes the note prompt" "" "$(cat "$CALLS")"
+
+# ── The help view is the real command list, not a hand-kept copy ─────────────
+_out=$(render "m" "h" "" "")
+assert_contains "help lists the registered commands" "mp\\_status" "$_out"
+assert_contains "help lists the usage text too" "Add a new secret" "$_out"
+assert_not_contains "help escapes the underscores Telegram would italicise" "/mp_status" "$_out"
+assert_not_contains "help draws no code box" '```' "$_out"
+
+# ── Every action the new views can emit is known to the capability table ─────
+_missing=""
+for _k in m y:d y:p y:f y:v y:u g g:a g:b a:rotall c:rotall a:restart c:restart \
+          a:update c:update a:lockdown c:lockdown; do
+    _ns="${_k%%:*}"; _act="${_k#*:}"
+    [ "$_act" = "$_ns" ] && _act=""
+    [ -n "$(_tg_cap_for "$_ns" "$_act")" ] || _missing="${_missing} ${_k}"
+done
+assert_eq "every new global action has a capability" "" "$_missing"
+
+printf '\n%d tests, %d failures\n' "$TESTS_RUN" "$TESTS_FAILED"
+[ "$TESTS_FAILED" -eq 0 ]
diff --git a/tests/test_telegram_pending_input.sh b/tests/test_telegram_pending_input.sh
new file mode 100644
index 0000000..d7705eb
--- /dev/null
+++ b/tests/test_telegram_pending_input.sh
@@ -0,0 +1,200 @@
+#!/bin/bash
+# Tests for the pending-input primitive.
+#
+# Inline buttons cannot collect typed text, so a flow that needs a value (add a
+# user, set a custom limit, broadcast) arms a prompt for that chat and the next
+# plain message from that chat is consumed as the answer. The dangerous half is
+# the consumption: a stale or misfiled entry would swallow a user's next real
+# message. These tests pin both halves — that an armed prompt answers exactly
+# once, and that it can never eat a command or outlive its TTL.
+set -o pipefail
+
+if [ "${BASH_VERSINFO[0]:-0}" -lt 4 ]; then
+    echo "SKIP: bash 4+ required (got ${BASH_VERSION:-unknown})" >&2
+    exit 0
+fi
+
+TEST_TMPDIR=$(mktemp -d)
+INSTALL_DIR="$TEST_TMPDIR/install"
+mkdir -p "$INSTALL_DIR/relay_stats"
+OFFSET_FILE="$INSTALL_DIR/relay_stats/tg_offset"
+ADMINS_FILE="$INSTALL_DIR/admins.conf"
+AUDIT_LOG="$INSTALL_DIR/audit.log"
+SECRETS_FILE="$INSTALL_DIR/secrets.conf"
+
+printf 'alice|%s|1700000000|true|0|0|0|0||\n' "$(printf 'a%.0s' $(seq 1 32))" > "$SECRETS_FILE"
+
+MTPROXYMAX_SOURCE_ONLY=true source "$(dirname "${BASH_SOURCE[0]}")/../mtproxymax.sh"
+set +e
+trap 'rm -rf "$TEST_TMPDIR"' EXIT
+
+TESTS_RUN=0
+TESTS_FAILED=0
+
+assert_eq() {
+    local name="$1" want="$2" got="$3"
+    TESTS_RUN=$((TESTS_RUN + 1))
+    if [ "$got" = "$want" ]; then
+        printf '  PASS  %s\n' "$name"
+    else
+        TESTS_FAILED=$((TESTS_FAILED + 1))
+        printf '  FAIL  %s (got=%q want=%q)\n' "$name" "$got" "$want"
+    fi
+}
+assert_contains() {
+    local name="$1" needle="$2" haystack="$3"
+    TESTS_RUN=$((TESTS_RUN + 1))
+    if [[ "$haystack" == *"$needle"* ]]; then
+        printf '  PASS  %s\n' "$name"
+    else
+        TESTS_FAILED=$((TESTS_FAILED + 1))
+        printf '  FAIL  %s (missing %q in %q)\n' "$name" "$needle" "$haystack"
+    fi
+}
+assert_not_contains() {
+    local name="$1" needle="$2" haystack="$3"
+    TESTS_RUN=$((TESTS_RUN + 1))
+    if [[ "$haystack" == *"$needle"* ]]; then
+        TESTS_FAILED=$((TESTS_FAILED + 1))
+        printf '  FAIL  %s (unexpected %q in %q)\n' "$name" "$needle" "$haystack"
+    else
+        printf '  PASS  %s\n' "$name"
+    fi
+}
+
+# ── Extract the shipped primitive ────────────────────────────────────────────
+telegram_generate_service_script
+DAEMON="$INSTALL_DIR/mtproxymax-telegram.sh"
+FNS="$TEST_TMPDIR/daemon-fns.sh"
+: > "$FNS"
+for _fn in _tg_security_log _cb_label_ok _cb_enc _cb_dec; do
+    awk "/^${_fn}\\(\\)/,/^}\$/" "$DAEMON" >> "$FNS"
+done
+# The block is delimited by markers so the test exercises exactly what ships,
+# and so a function added to it later is picked up without editing this list.
+awk '/^# >>> TG_PENDING_BEGIN$/,/^# <<< TG_PENDING_END$/' "$DAEMON" >> "$FNS"
+assert_eq "pending-input extraction is valid bash" 0 \
+    "$(bash -n "$FNS" 2>/dev/null; echo $?)"
+assert_eq "the pending block was found in the daemon" 1 \
+    "$(grep -c '^# >>> TG_PENDING_BEGIN$' "$FNS")"
+# A missing function would silently make every later assertion vacuous.
+assert_contains "the primitive ships in the daemon" "_tg_pending_set()" "$(cat "$FNS")"
+
+# ── Stubs ────────────────────────────────────────────────────────────────────
+SENDS="$TEST_TMPDIR/sends.log"
+CALLS="$TEST_TMPDIR/calls.log"
+ROLE_TO_RETURN="superadmin"
+# Link building reads these; leaving them unset would make the assertion below
+# pass against a malformed "host:" string.
+PROXY_PORT=443
+PROXY_DOMAIN="cloudflare.com"
+MASKING_ENABLED="true"
+
+_check_tg_role() { echo "$ROLE_TO_RETURN"; }
+tg_send_to() { printf '%s|%s\n' "$1" "$2" >> "$SENDS"; }
+tg_send() { printf 'admin|%s\n' "$*" >> "$SENDS"; }
+tg_send_to_kb() { printf '%s|%s|%s\n' "$1" "$2" "$3" >> "$SENDS"; }
+load_tg_settings() { :; }
+get_cached_ip() { echo "203.0.113.9"; }
+domain_to_hex() { echo "0a0b0c0d"; }
+_esc() { printf '%s' "$1"; }
+format_bytes() { printf '%s' "$1"; }
+
+# The stub records the call AND performs the one side effect the flow reads
+# back — a created secret. Without that, the link-building half of the flow
+# would silently take its "not found" branch and never be exercised.
+cat > "$INSTALL_DIR/mtproxymax" <<'EOS'
+#!/bin/bash
+printf '%s\n' "$*" >> "$MTPX_CALLS"
+if [ "$1" = "secret" ] && [ "$2" = "add" ]; then
+    printf '%s|%s|1700000000|true|0|0|0|0||\n' "$3" "$(printf 'c%.0s' $(seq 1 32))" >> "$SECRETS_FILE"
+fi
+exit 0
+EOS
+chmod +x "$INSTALL_DIR/mtproxymax"
+export MTPX_CALLS="$CALLS" SECRETS_FILE
+
+source "$FNS"
+
+PENDING="$INSTALL_DIR/relay_stats/.tg_pending"
+reset_state() { : > "$SENDS"; : > "$CALLS"; rm -f "$PENDING"; }
+
+# ── Round trip ───────────────────────────────────────────────────────────────
+reset_state
+_tg_pending_set "111" "add" "-"
+assert_eq "an armed prompt reads back as verb|target" "add|-" "$(_tg_pending_take "111")"
+assert_eq "taking clears it, so it answers only once" 1 "$(_tg_pending_take "111" >/dev/null 2>&1; echo $?)"
+
+# ── Per-chat isolation ───────────────────────────────────────────────────────
+reset_state
+_tg_pending_set "111" "add" "-"
+_tg_pending_set "222" "limit" "alice"
+assert_eq "another chat's prompt is untouched" "add|-" "$(_tg_pending_take "111")"
+assert_eq "and its own still answers" "limit|alice" "$(_tg_pending_take "222")"
+
+# Re-arming must REPLACE, not append: a second set that left the first line in
+# place would answer with the stale verb.
+reset_state
+_tg_pending_set "111" "add" "-"
+_tg_pending_set "111" "limit" "alice"
+assert_eq "re-arming replaces the previous prompt" "limit|alice" "$(_tg_pending_take "111")"
+assert_eq "and leaves exactly one line on disk" 0 "$(grep -c . "$PENDING")"
+
+# ── Expiry ───────────────────────────────────────────────────────────────────
+reset_state
+_TG_PENDING_TTL=0 _tg_pending_set "111" "add" "-"
+assert_eq "an expired prompt does not answer" 1 "$(_tg_pending_take "111" >/dev/null 2>&1; echo $?)"
+assert_eq "and is pruned off disk" 0 "$(grep -c . "$PENDING")"
+
+# A prompt for another chat must not be swept by the prune above.
+reset_state
+_TG_PENDING_TTL=0 _tg_pending_set "111" "add" "-"
+_tg_pending_set "222" "limit" "alice"
+_tg_pending_take "111" >/dev/null 2>&1
+assert_eq "pruning one chat leaves the other armed" "limit|alice" "$(_tg_pending_take "222")"
+
+# ── Clear ────────────────────────────────────────────────────────────────────
+reset_state
+_tg_pending_set "111" "add" "-"
+_tg_pending_clear "111"
+assert_eq "clearing disarms the prompt" 1 "$(_tg_pending_take "111" >/dev/null 2>&1; echo $?)"
+
+# ── The escape hatch ─────────────────────────────────────────────────────────
+# This is the property that keeps a user from being trapped: any slash command
+# cancels the prompt and is then dispatched normally.
+reset_state
+_tg_pending_set "111" "add" "-"
+assert_eq "a command is not consumed as an answer" 1 "$(_tg_pending_try "111" "/mp_help"; echo $?)"
+assert_eq "and the prompt is disarmed rather than left dangling" 1 "$(_tg_pending_take "111" >/dev/null 2>&1; echo $?)"
+assert_eq "nothing was executed while escaping" "" "$(cat "$CALLS")"
+
+reset_state
+_tg_pending_set "111" "add" "-"
+assert_eq "a plain message IS consumed as an answer" 0 "$(_tg_pending_try "111" "carol"; echo $?)"
+assert_eq "and is not left armed afterwards" 1 "$(_tg_pending_take "111" >/dev/null 2>&1; echo $?)"
+
+reset_state
+assert_eq "with no prompt armed, a plain message passes through" 1 "$(_tg_pending_try "111" "hello"; echo $?)"
+
+# ── The add flow actually runs ───────────────────────────────────────────────
+# End-to-end for the one flow that exists at this layer: the typed value must
+# reach the CLI verb, and the reply must go back to the chat that typed it.
+reset_state
+_tg_pending_set "111" "add" "-"
+_tg_pending_try "111" "carol" >/dev/null
+assert_contains "the typed label reaches the CLI" "secret add carol" "$(cat "$CALLS")"
+assert_contains "and the chat is told about it" "111|" "$(cat "$SENDS")"
+# The new user is useless without a way to connect, so the flow must hand back
+# a link built from the freshly written secret — not just an acknowledgement.
+assert_contains "a connect link comes back" "203.0.113.9:443" "$(cat "$SENDS")"
+
+# A label that could never be a secret name is refused before reaching the CLI,
+# so a pasted link cannot be turned into a directory-traversing label.
+reset_state
+_tg_pending_set "111" "add" "-"
+_tg_pending_try "111" "../../etc/passwd" >/dev/null
+assert_eq "an invalid label never reaches the CLI" "" "$(cat "$CALLS")"
+assert_contains "and the user is told why" "❌" "$(cat "$SENDS")"
+
+printf '\n%d tests, %d failures\n' "$TESTS_RUN" "$TESTS_FAILED"
+[ "$TESTS_FAILED" -eq 0 ]
diff --git a/tests/test_telegram_per_secret_views.sh b/tests/test_telegram_per_secret_views.sh
new file mode 100644
index 0000000..8ac9e35
--- /dev/null
+++ b/tests/test_telegram_per_secret_views.sh
@@ -0,0 +1,223 @@
+#!/bin/bash
+# Tests for the per-secret management surface: the manage card, the limit
+# pickers behind it, and the commits those buttons make.
+#
+# The behaviour that matters most here is the WRITE PATH. The obvious way to set
+# one limit is `secret setlimits <label> <conns> <ips> <quota> <expires>`, but
+# secret_set_limits reads "0" as UNLIMITED, not as "leave alone" — so tapping
+# "quota: 10G" through that verb would silently wipe the connection and IP caps
+# too. Every commit below therefore has to reach the per-field
+# `secret setlimit <label> <field> <value>` form, and the assertions pin that.
+set -o pipefail
+
+if [ "${BASH_VERSINFO[0]:-0}" -lt 4 ]; then
+    echo "SKIP: bash 4+ required (got ${BASH_VERSION:-unknown})" >&2
+    exit 0
+fi
+
+TEST_TMPDIR=$(mktemp -d)
+INSTALL_DIR="$TEST_TMPDIR/install"
+mkdir -p "$INSTALL_DIR/relay_stats"
+OFFSET_FILE="$INSTALL_DIR/relay_stats/tg_offset"
+ADMINS_FILE="$INSTALL_DIR/admins.conf"
+AUDIT_LOG="$INSTALL_DIR/audit.log"
+SECRETS_FILE="$INSTALL_DIR/secrets.conf"
+
+printf 'alice|%s|1700000000|true|7|3|10737418240|2027-01-01|the note|%s\n' \
+    "$(printf 'a%.0s' $(seq 1 32))" "$(printf 'f%.0s' $(seq 1 32))" > "$SECRETS_FILE"
+printf 'bob|%s|1700000000|false|0|0|0|0||\n' "$(printf 'b%.0s' $(seq 1 32))" >> "$SECRETS_FILE"
+
+MTPROXYMAX_SOURCE_ONLY=true source "$(dirname "${BASH_SOURCE[0]}")/../mtproxymax.sh"
+set +e
+trap 'rm -rf "$TEST_TMPDIR"' EXIT
+
+TESTS_RUN=0
+TESTS_FAILED=0
+
+assert_eq() {
+    local name="$1" want="$2" got="$3"
+    TESTS_RUN=$((TESTS_RUN + 1))
+    if [ "$got" = "$want" ]; then printf '  PASS  %s\n' "$name"
+    else TESTS_FAILED=$((TESTS_FAILED + 1)); printf '  FAIL  %s (got=%q want=%q)\n' "$name" "$got" "$want"; fi
+}
+assert_contains() {
+    local name="$1" needle="$2" haystack="$3"
+    TESTS_RUN=$((TESTS_RUN + 1))
+    if [[ "$haystack" == *"$needle"* ]]; then printf '  PASS  %s\n' "$name"
+    else TESTS_FAILED=$((TESTS_FAILED + 1)); printf '  FAIL  %s (missing %q in %q)\n' "$name" "$needle" "$haystack"; fi
+}
+assert_not_contains() {
+    local name="$1" needle="$2" haystack="$3"
+    TESTS_RUN=$((TESTS_RUN + 1))
+    if [[ "$haystack" == *"$needle"* ]]; then
+        TESTS_FAILED=$((TESTS_FAILED + 1)); printf '  FAIL  %s (unexpected %q in %q)\n' "$name" "$needle" "$haystack"
+    else printf '  PASS  %s\n' "$name"; fi
+}
+
+# ── Extract the shipped menu block ───────────────────────────────────────────
+telegram_generate_service_script
+DAEMON="$INSTALL_DIR/mtproxymax-telegram.sh"
+FNS="$TEST_TMPDIR/daemon-fns.sh"
+: > "$FNS"
+for _fn in _tg_security_log _esc _cb_label_ok _cb_enc _cb_dec _iso_to_epoch; do
+    awk "/^${_fn}\\(\\)/,/^}\$/" "$DAEMON" >> "$FNS"
+done
+awk '/^# >>> TG_MENU_BEGIN$/,/^# <<< TG_MENU_END$/' "$DAEMON" >> "$FNS"
+assert_eq "extraction is valid bash" 0 "$(bash -n "$FNS" 2>/dev/null; echo $?)"
+
+# ── Stubs ────────────────────────────────────────────────────────────────────
+SENDS="$TEST_TMPDIR/sends.log"
+CALLS="$TEST_TMPDIR/calls.log"
+EDITS="$TEST_TMPDIR/edits.log"
+ROLE_TO_RETURN="superadmin"
+
+_check_tg_role() { echo "$ROLE_TO_RETURN"; }
+tg_send() { printf 'admin|%s\n' "$*" >> "$SENDS"; }
+tg_send_to() { printf '%s|%s\n' "$1" "$2" >> "$SENDS"; }
+tg_send_kb() { printf 'admin|%s|%s\n' "$1" "$2" >> "$SENDS"; }
+tg_send_to_kb() { printf '%s|%s|%s\n' "$1" "$2" "$3" >> "$SENDS"; }
+tg_answer_cb() { :; }
+tg_edit() { printf '%s\n---\n%s\n' "$3" "$4" > "$EDITS"; }
+tg_edit_markup() { printf 'markup\n---\n%s\n' "$3" > "$EDITS"; }
+load_tg_settings() { :; }
+is_running() { return 1; }
+log_warn() { :; }
+get_cached_ip() { echo "203.0.113.9"; }
+_tg_metrics_raw() { printf ''; }
+_tg_have_python() { return 1; }
+
+cat > "$INSTALL_DIR/mtproxymax" <<'EOS'
+#!/bin/bash
+printf '%s\n' "$*" >> "$MTPX_CALLS"
+exit 0
+EOS
+chmod +x "$INSTALL_DIR/mtproxymax"
+export MTPX_CALLS="$CALLS"
+
+source "$FNS"
+
+_UI_ROLE="superadmin"
+_CB_CHAT="111"; _CB_MID="77"
+
+render() {   # render <ns> <act> <tgt> <page>
+    : > "$EDITS"
+    _cb_dispatch_prepare "$1" "$2" "$3" "$4"
+    _cb_dispatch >/dev/null 2>&1
+    cat "$EDITS"
+}
+# Drive the dispatcher the way a real tap does: through the codec, so the
+# payload is validated exactly as it would be in production.
+_cb_dispatch_prepare() {
+    local p
+    p=$(_cb_enc "$1" "$2" "$3" "$4") || { _CB_DATA=""; return 1; }
+    _CB_DATA="$p"
+    _CB_NS="$1"; _CB_ACT="$2"; _CB_TGT="$3"; _CB_PAGE="$4"
+    _CB_CHAT="111"; _CB_MID="77"; _CB_TOAST=""; _CB_ALERT="false"
+}
+commit() {   # commit <act> <label> <value> -> manager calls
+    : > "$CALLS"
+    _cb_dispatch_prepare "c" "$1" "$2" "$3"
+    _cb_dispatch >/dev/null 2>&1
+    cat "$CALLS"
+}
+
+# ── The manage card is reachable from the user card ──────────────────────────
+_out=$(render "u" "s" "alice" "0")
+assert_contains "user card offers a manage entry" "u:m:alice:0" "$_out"
+
+_out=$(render "u" "m" "alice" "0")
+assert_contains "manage card offers the quota picker"  "e:q:alice:0" "$_out"
+assert_contains "manage card offers the conns picker"  "e:c:alice:0" "$_out"
+assert_contains "manage card offers the IPs picker"    "e:i:alice:0" "$_out"
+assert_contains "manage card offers the expiry picker" "e:x:alice:0" "$_out"
+assert_contains "manage card offers the note prompt"   "e:n:alice:0" "$_out"
+assert_contains "manage card offers the adtag prompt"  "e:a:alice:0" "$_out"
+assert_contains "manage card offers the template picker" "e:t:alice:0" "$_out"
+assert_contains "manage card goes back to the user card" "u:s:alice:0" "$_out"
+# The card is where the current values are read, so they have to be on it.
+assert_contains "manage card shows the current quota" "10.00 GB" "$_out"
+assert_contains "manage card shows the current conn cap" "7" "$_out"
+assert_contains "manage card shows the note" "the note" "$_out"
+
+# ── Pickers offer presets, and every payload is one Telegram will accept ─────
+for _f in q c i x r; do
+    _out=$(render "e" "$_f" "alice" "0")
+    _bad=""
+    while IFS= read -r _p; do
+        [ -z "$_p" ] && continue
+        case "$_p" in
+            c:*) ;;
+            *) continue ;;
+        esac
+        [ "${#_p}" -le 64 ] || _bad="${_bad} len:${_p}"
+        _cb_dec "$_p" || _bad="${_bad} unparseable:${_p}"
+    done < <(printf '%s' "$_out" | grep -oE 'c:[A-Za-z0-9_:.-]+')
+    assert_eq "every $_f preset is a payload Telegram will accept" "" "$_bad"
+    assert_not_contains "$_f picker draws no code box" '```' "$_out"
+done
+
+_out=$(render "e" "q" "alice" "0")
+assert_contains "quota picker offers 10G"   "c:setq:alice:10G" "$_out"
+assert_contains "quota picker offers unlimited" "c:setq:alice:0" "$_out"
+assert_contains "quota picker goes back to the manage card" "u:m:alice:0" "$_out"
+
+_out=$(render "e" "x" "alice" "0")
+assert_contains "expiry picker offers 30 days" "c:setx:alice:30" "$_out"
+assert_contains "expiry picker offers never"   "c:setx:alice:0" "$_out"
+
+_out=$(render "e" "r" "alice" "0")
+assert_contains "reset picker offers day 15" "c:setr:alice:15" "$_out"
+assert_contains "reset picker offers off"    "c:setr:alice:off" "$_out"
+
+# ── Commits hit the per-field verb, and only that field ──────────────────────
+assert_eq "quota commit uses the per-field verb" \
+    "secret setlimit alice quota 10G" "$(commit "setq" "alice" "10G")"
+assert_eq "conns commit uses the per-field verb" \
+    "secret setlimit alice conns 50" "$(commit "setc" "alice" "50")"
+assert_eq "IPs commit uses the per-field verb" \
+    "secret setlimit alice ips 5" "$(commit "seti" "alice" "5")"
+assert_eq "unlimited quota commits as 0" \
+    "secret setlimit alice quota 0" "$(commit "setq" "alice" "0")"
+
+# The whole reason for the per-field verb: setlimits with a 0 would read as
+# "unlimited" for the fields the tap never mentioned.
+assert_not_contains "a quota change never calls setlimits" \
+    "setlimits" "$(commit "setq" "alice" "10G")"
+
+# Expiry is relative ("+30d") for a real date and absolute ("never") for 0, and
+# the CLI already has a verb for the relative case.
+assert_eq "a relative expiry extends rather than rewriting limits" \
+    "secret extend alice 30" "$(commit "setx" "alice" "30")"
+assert_eq "never expiry clears the date" \
+    "secret setlimit alice expires 0" "$(commit "setx" "alice" "0")"
+
+assert_eq "reset-day commit reaches the CLI" \
+    "secret quota-reset alice 15" "$(commit "setr" "alice" "15")"
+assert_eq "reset-day off reaches the CLI" \
+    "secret quota-reset alice off" "$(commit "setr" "alice" "off")"
+
+# ── Bad input cannot reach the CLI ───────────────────────────────────────────
+assert_eq "an unknown commit verb is refused" "" "$(commit "setz" "alice" "10G")"
+assert_eq "a non-numeric conns value is refused" "" "$(commit "setc" "alice" "lots")"
+assert_eq "a non-numeric quota value is refused" "" "$(commit "setq" "alice" "abc")"
+assert_eq "a nonsense reset day is refused" "" "$(commit "setr" "alice" "99")"
+assert_eq "a missing label is refused" "" "$(commit "setq" "" "10G")"
+
+# ── A label off disk is re-validated before it is used as a pattern ──────────
+# The label comes back out of callback_data, which is attacker-controlled, and
+# out of secrets.conf, which is hand-editable. Neither is trusted.
+assert_eq "a label that is not a label never reaches the CLI" "" "$(commit "setq" "../../etc" "10G")"
+
+# ── RBAC: every action above is known to the capability table ────────────────
+_missing=""
+# Note and ad-tag are pending-input flows rather than c: commits (their text
+# cannot ride in callback_data), so they are entered through e: and not listed
+# here — _tg_pending_run owns their write path.
+for _k in u:m e:q e:c e:i e:x e:r e:n e:a e:t e:z c:setq c:setc c:seti c:setx c:setr c:tpl p:x; do
+    _ns="${_k%%:*}"; _act="${_k#*:}"
+    [ -n "$(_tg_cap_for "$_ns" "$_act")" ] || _missing="${_missing} ${_k}"
+done
+assert_eq "every new action has a capability" "" "$_missing"
+
+printf '\n%d tests, %d failures\n' "$TESTS_RUN" "$TESTS_FAILED"
+[ "$TESTS_FAILED" -eq 0 ]
diff --git a/tests/test_telegram_periodic_report.sh b/tests/test_telegram_periodic_report.sh
new file mode 100644
index 0000000..171164c
--- /dev/null
+++ b/tests/test_telegram_periodic_report.sh
@@ -0,0 +1,182 @@
+#!/bin/bash
+# Tests for the periodic report.
+#
+# The report used to send the same three facts every interval regardless of
+# activity: uptime, live connections, and two LIFETIME cumulative totals. Those
+# only ever grow, so the message could never answer "how much moved today, and
+# is that more or less than yesterday?". This pins the windowed, activity-aware
+# replacement.
+set -o pipefail
+
+if [ "${BASH_VERSINFO[0]:-0}" -lt 4 ]; then
+    echo "SKIP: bash 4+ required (got ${BASH_VERSION:-unknown})" >&2
+    exit 0
+fi
+
+TEST_TMPDIR=$(mktemp -d)
+INSTALL_DIR="$TEST_TMPDIR/install"
+mkdir -p "$INSTALL_DIR/relay_stats/history"
+OFFSET_FILE="$INSTALL_DIR/relay_stats/tg_offset"
+SECRETS_FILE="$INSTALL_DIR/secrets.conf"
+: > "$SECRETS_FILE"
+
+MTPROXYMAX_SOURCE_ONLY=true source "$(dirname "${BASH_SOURCE[0]}")/../mtproxymax.sh"
+set +e
+trap 'rm -rf "$TEST_TMPDIR"' EXIT
+
+TESTS_RUN=0
+TESTS_FAILED=0
+assert_contains() {
+    local name="$1" needle="$2" haystack="$3"
+    TESTS_RUN=$((TESTS_RUN + 1))
+    if [[ "$haystack" == *"$needle"* ]]; then printf '  PASS  %s\n' "$name"
+    else TESTS_FAILED=$((TESTS_FAILED + 1)); printf '  FAIL  %s (missing %q)\n' "$name" "$needle"; fi
+}
+assert_not_contains() {
+    local name="$1" needle="$2" haystack="$3"
+    TESTS_RUN=$((TESTS_RUN + 1))
+    if [[ "$haystack" == *"$needle"* ]]; then
+        TESTS_FAILED=$((TESTS_FAILED + 1)); printf '  FAIL  %s (unexpected %q)\n' "$name" "$needle"
+    else printf '  PASS  %s\n' "$name"; fi
+}
+assert_eq() {
+    local name="$1" want="$2" got="$3"
+    TESTS_RUN=$((TESTS_RUN + 1))
+    if [ "$got" = "$want" ]; then printf '  PASS  %s\n' "$name"
+    else TESTS_FAILED=$((TESTS_FAILED + 1)); printf '  FAIL  %s (got=%q want=%q)\n' "$name" "$got" "$want"; fi
+}
+
+telegram_generate_service_script
+DAEMON="$INSTALL_DIR/mtproxymax-telegram.sh"
+FNS="$TEST_TMPDIR/report.sh"
+: > "$FNS"
+for _fn in _esc format_bytes format_duration _iso_to_epoch _cb_label_ok _cb_enc _cb_dec token_not_a_function; do
+    awk "/^${_fn}\\(\\)/,/^}\$/" "$DAEMON" >> "$FNS"
+done
+for _blk in TG_MENU TG_HISTORY TG_REPORT; do
+    awk "/^# >>> ${_blk}_BEGIN\$/,/^# <<< ${_blk}_END\$/" "$DAEMON" >> "$FNS"
+done
+assert_contains "report block found in the daemon" "TG_REPORT_BEGIN" "$(cat "$FNS")"
+assert_contains "history block found in the daemon" "TG_HISTORY_BEGIN" "$(cat "$FNS")"
+TESTS_RUN=$((TESTS_RUN + 1))
+if bash -n "$FNS" 2>/dev/null; then printf '  PASS  report extraction is valid bash\n'
+else TESTS_FAILED=$((TESTS_FAILED + 1)); printf '  FAIL  report extraction is valid bash\n'; fi
+
+SENT="$TEST_TMPDIR/sent.txt"
+_check_tg_role() { echo "superadmin"; }
+get_uptime() { echo 3600; }
+get_active_connections() { echo 5; }
+get_cached_ip() { echo "203.0.113.9"; }
+tg_send_kb() { printf '%s\n' "$1" > "$SENT"; }
+tg_send() { printf '%s\n' "$1" > "$SENT"; }
+tg_edit() { :; }
+tg_edit_markup() { :; }
+tg_answer_cb() { :; }
+load_tg_settings() { :; }
+HISTORY_DIR="$INSTALL_DIR/relay_stats/history"
+source "$FNS"
+
+NOW=1000000
+report() {
+    : > "$SENT"
+    TELEGRAM_REPORT_DETAIL="$1" _tg_periodic_report "$NOW" 86400
+    cat "$SENT"
+}
+
+echo "Telegram periodic report tests"
+
+# ── Idle window collapses to a heartbeat ─────────────────────────────────────
+cat > "$HISTORY_DIR/global.tsv" <<'EOF'
+999000|0|0|0|-
+999600|0|0|0|-
+EOF
+: > "$HISTORY_DIR/users.tsv"
+_body=$(report auto)
+assert_contains "an idle window reports a heartbeat" "idle" "$_body"
+assert_not_contains "an idle window omits the sparkline" '📉' "$_body"
+assert_not_contains "an idle window omits the lifetime totals line" "24h ↓" "$_body"
+assert_contains "the heartbeat still proves liveness" "alive" "$_body"
+
+# ── An active window produces the full report ────────────────────────────────
+cat > "$HISTORY_DIR/global.tsv" <<'EOF'
+999000|0|0|0|-
+999600|5000000|3000000|7|-
+EOF
+cat > "$HISTORY_DIR/users.tsv" <<'EOF'
+999600|alice|4000000|2000000
+999600|bob|1000000|1000000
+EOF
+_body=$(report auto)
+assert_contains "an active window reports the 24h totals" "24h ↓" "$_body"
+assert_contains "an active window reports a peak rate" "Peak" "$_body"
+assert_contains "an active window draws a sparkline" '📉' "$_body"
+assert_contains "an active window names top talkers" "alice" "$_body"
+assert_not_contains "an active window is not a heartbeat" "alive, idle" "$_body"
+
+# Regression: the two lifetime totals the old report always sent must no longer
+# be the whole message. The window figure has to be present.
+assert_contains "the report is windowed, not lifetime" "24h" "$_body"
+
+# ── The sparkline is inline, unescaped, and never fenced ─────────────────────
+# It used to sit inside a code fence "for monospace alignment". The glyphs are
+# block elements and share an advance width in a proportional font, so the fence
+# bought nothing and cost a monospace box with a copy button on every report.
+assert_not_contains "the report draws no code box" '```' "$_body"
+# Any of the eight block glyphs counts: with a single non-zero bucket the series
+# is flat, so which glyph a bar gets depends on the scale, not on correctness.
+_spark_line=""
+while IFS= read -r _l; do
+    case "$_l" in *📉*) _spark_line="$_l"; break ;; esac
+done <<< "$_body"
+if [[ "$_spark_line" =~ ([▁▂▃▄▅▆▇█]+) ]]; then
+    _spark_glyphs="${BASH_REMATCH[1]}"
+else
+    _spark_glyphs=""
+fi
+assert_eq "the sparkline still draws bars" 1 "$([ -n "$_spark_glyphs" ] && echo 1 || echo 0)"
+# Bars are U+2581..U+2588 and contain no Markdown metacharacter, so escaping the
+# run would render literal backslashes inside it for no benefit. The check is on
+# the glyph run rather than the whole line: the body carries its newlines as
+# literal \n, so the line has backslashes in it either way.
+assert_not_contains "the inline sparkline is not Markdown-escaped" '\' "$_spark_glyphs"
+
+# ── Verbosity override ───────────────────────────────────────────────────────
+_body=$(report summary)
+assert_not_contains "detail=summary suppresses the full report when busy" "Peak" "$_body"
+
+cat > "$HISTORY_DIR/global.tsv" <<'EOF'
+999000|0|0|0|-
+999600|0|0|0|-
+EOF
+_body=$(report full)
+assert_contains "detail=full reports even when idle" "24h ↓" "$_body"
+
+# ── Quota pressure and expiry watch ──────────────────────────────────────────
+# Quota is measured against the same _cum_user_* the enforcement loop uses, and
+# expiry against the same _iso_to_epoch, so the two can never disagree.
+cat > "$HISTORY_DIR/global.tsv" <<'EOF'
+999000|0|0|0|-
+999600|5000000|3000000|7|-
+EOF
+declare -A _cum_user_in=([alice]=900) _cum_user_out=([alice]=0)
+printf 'alice|%032d|1700000000|true|0|0|1000|0||\n' 1 > "$SECRETS_FILE"
+_body=$(report auto)
+assert_contains "a user at or above 80% quota is flagged" "80% quota" "$_body"
+
+declare -A _cum_user_in=([alice]=100) _cum_user_out=([alice]=0)
+_body=$(report auto)
+assert_not_contains "a user below the quota threshold is not flagged" "80% quota" "$_body"
+
+# An expiry three days out must be counted; ten days out must not.
+_far=$(( NOW + 10 * 86400 ))
+_near=$(date -u -d "@$(( NOW + 2 * 86400 ))" '+%Y-%m-%d' 2>/dev/null)
+if [ -n "$_near" ]; then
+    printf 'alice|%032d|1700000000|true|0|0|0|%s||\n' 1 "$_near" > "$SECRETS_FILE"
+    _body=$(report auto)
+    assert_contains "a secret expiring within 3 days is flagged" "expiring within 3 days" "$_body"
+else
+    printf '  SKIP  expiry assertions (date -d unavailable)\n'
+fi
+
+printf '\n%d tests, %d failures\n' "$TESTS_RUN" "$TESTS_FAILED"
+[ "$TESTS_FAILED" -eq 0 ]
diff --git a/tests/test_telegram_qr_and_limits.sh b/tests/test_telegram_qr_and_limits.sh
new file mode 100644
index 0000000..a53c22b
--- /dev/null
+++ b/tests/test_telegram_qr_and_limits.sh
@@ -0,0 +1,198 @@
+#!/bin/bash
+# Two fixes that the button work exposed but did not cause.
+#
+# 1. /mp_setlimit silently wiped limits. It called
+#    `secret setlimits <label> <conns> <ips> <quota> <expires>`, and
+#    secret_set_limits reads "0" as UNLIMITED rather than "leave alone" — so
+#    `/mp_setlimit alice 100` also cleared alice's IP cap and quota.
+#
+# 2. Every QR code handed the credential to a third party. The proxy link IS the
+#    key (server, port and secret), and it was posted to api.qrserver.com for
+#    Telegram to fetch — on every /mp_link, every /start, and every voucher
+#    redemption, including to the customer's own chat.
+set -o pipefail
+
+if [ "${BASH_VERSINFO[0]:-0}" -lt 4 ]; then
+    echo "SKIP: bash 4+ required (got ${BASH_VERSION:-unknown})" >&2
+    exit 0
+fi
+
+TEST_TMPDIR=$(mktemp -d)
+INSTALL_DIR="$TEST_TMPDIR/install"
+mkdir -p "$INSTALL_DIR/relay_stats"
+OFFSET_FILE="$INSTALL_DIR/relay_stats/tg_offset"
+ADMINS_FILE="$INSTALL_DIR/admins.conf"
+AUDIT_LOG="$INSTALL_DIR/audit.log"
+SECRETS_FILE="$INSTALL_DIR/secrets.conf"
+
+printf 'alice|%s|1700000000|true|7|3|10737418240|2027-01-01||\n' "$(printf 'a%.0s' $(seq 1 32))" > "$SECRETS_FILE"
+
+MTPROXYMAX_SOURCE_ONLY=true source "$(dirname "${BASH_SOURCE[0]}")/../mtproxymax.sh"
+set +e
+trap 'rm -rf "$TEST_TMPDIR"' EXIT
+
+TESTS_RUN=0
+TESTS_FAILED=0
+
+assert_eq() {
+    local name="$1" want="$2" got="$3"
+    TESTS_RUN=$((TESTS_RUN + 1))
+    if [ "$got" = "$want" ]; then printf '  PASS  %s\n' "$name"
+    else TESTS_FAILED=$((TESTS_FAILED + 1)); printf '  FAIL  %s (got=%q want=%q)\n' "$name" "$got" "$want"; fi
+}
+assert_contains() {
+    local name="$1" needle="$2" haystack="$3"
+    TESTS_RUN=$((TESTS_RUN + 1))
+    if [[ "$haystack" == *"$needle"* ]]; then printf '  PASS  %s\n' "$name"
+    else TESTS_FAILED=$((TESTS_FAILED + 1)); printf '  FAIL  %s (missing %q in %q)\n' "$name" "$needle" "$haystack"; fi
+}
+assert_not_contains() {
+    local name="$1" needle="$2" haystack="$3"
+    TESTS_RUN=$((TESTS_RUN + 1))
+    if [[ "$haystack" == *"$needle"* ]]; then
+        TESTS_FAILED=$((TESTS_FAILED + 1)); printf '  FAIL  %s (unexpected %q in %q)\n' "$name" "$needle" "$haystack"
+    else printf '  PASS  %s\n' "$name"; fi
+}
+
+# ── Extract the shipped daemon code ──────────────────────────────────────────
+telegram_generate_service_script
+DAEMON="$INSTALL_DIR/mtproxymax-telegram.sh"
+FNS="$TEST_TMPDIR/daemon-fns.sh"
+: > "$FNS"
+for _fn in _tg_security_log _esc _cb_label_ok _cb_enc _cb_dec _process_cmd \
+           _tg_pending_file _tg_pending_set _tg_pending_take _tg_pending_clear \
+           _tg_pending_try _tg_pending_run _tg_new_secret_link \
+           _qr_png _proxy_link _tg_send_photo_file _send_qr \
+           send_proxy_qr send_proxy_qr_to; do
+    awk "/^${_fn}\\(\\)/,/^}\$/" "$DAEMON" >> "$FNS"
+done
+awk '/^# >>> TG_MENU_BEGIN$/,/^# <<< TG_MENU_END$/' "$DAEMON" >> "$FNS"
+assert_eq "extraction is valid bash" 0 "$(bash -n "$FNS" 2>/dev/null; echo $?)"
+
+SENDS="$TEST_TMPDIR/sends.log"
+CALLS="$TEST_TMPDIR/calls.log"
+CURLS="$TEST_TMPDIR/curls.log"
+CURLCFG="$TEST_TMPDIR/curlcfg.log"
+QRDIR="$TEST_TMPDIR/qr"
+
+_check_tg_role() { echo "superadmin"; }
+tg_send() { printf 'admin|%s\n' "$*" >> "$SENDS"; }
+tg_send_to() { printf '%s|%s\n' "$1" "$2" >> "$SENDS"; }
+tg_send_kb() { printf 'admin|%s\n' "$1" >> "$SENDS"; }
+tg_send_to_kb() { printf '%s|%s\n' "$1" "$2" >> "$SENDS"; }
+load_tg_settings() { :; }
+is_running() { return 0; }
+log_warn() { :; }
+get_cached_ip() { echo "203.0.113.9"; }
+format_bytes() { printf '%s' "$1"; }
+format_duration() { echo "1d"; }
+domain_to_hex() { echo "0a0b0c0d"; }
+_tg_have_python() { return 1; }
+_tg_metrics_raw() { printf ''; }
+# Record the curl invocation instead of performing it. The URL — which carries
+# the bot token — travels in a -K config file, so argv and the config are logged
+# separately: the point of the config file is that argv holds no secret.
+curl() {
+    printf '%s\n' "$*" >> "$CURLS"
+    local _f
+    while [ $# -gt 0 ]; do
+        case "$1" in
+            -K) _f="$2"; [ -r "$_f" ] && cat "$_f" >> "$CURLCFG" ;;
+        esac
+        shift
+    done
+    return 0
+}
+
+cat > "$INSTALL_DIR/mtproxymax" <<'EOS'
+#!/bin/bash
+printf '%s\n' "$*" >> "$MTPX_CALLS"
+exit 0
+EOS
+chmod +x "$INSTALL_DIR/mtproxymax"
+export MTPX_CALLS="$CALLS"
+
+source "$FNS"
+
+PROXY_PORT=443
+PROXY_DOMAIN="cloudflare.com"
+MASKING_ENABLED="true"
+TELEGRAM_BOT_TOKEN="111:AAA"
+TELEGRAM_CHAT_ID="555"
+TELEGRAM_SERVER_LABEL="TestBox"
+
+run_cmd() {   # run_cmd <text>
+    : > "$SENDS"; : > "$CALLS"
+    _process_cmd "1" "111" "$1" >/dev/null 2>&1
+    cat "$SENDS"
+}
+
+echo "Telegram limit + QR tests"
+
+# ── /mp_setlimit changes only what it was given ──────────────────────────────
+_out=$(run_cmd "/mp_setlimit alice 100")
+assert_contains "a one-field set reaches the CLI" "secret setlimit alice conns 100" "$(cat "$CALLS")"
+assert_not_contains "and never uses the all-fields verb" "setlimits" "$(cat "$CALLS")"
+
+: > "$CALLS"
+run_cmd "/mp_setlimit alice 100 5" >/dev/null
+assert_contains "a two-field set sends the connection cap" "secret setlimit alice conns 100" "$(cat "$CALLS")"
+assert_contains "a two-field set sends the IP cap" "secret setlimit alice ips 5" "$(cat "$CALLS")"
+assert_not_contains "and still never uses the all-fields verb" "setlimits" "$(cat "$CALLS")"
+
+: > "$CALLS"
+run_cmd "/mp_setlimit alice 100 5 10G" >/dev/null
+assert_contains "a three-field set sends the quota" "secret setlimit alice quota 10G" "$(cat "$CALLS")"
+assert_not_contains "and still never uses the all-fields verb" "setlimits" "$(cat "$CALLS")"
+
+# An empty field is "leave it alone", so nothing at all must be sent for it —
+# the whole point of the fix.
+: > "$CALLS"
+run_cmd "/mp_setlimit alice 0 0 10G" >/dev/null
+assert_contains "an explicit 0 still reaches the CLI as a real 0" "secret setlimit alice conns 0" "$(cat "$CALLS")"
+
+_out=$(run_cmd "/mp_setlimit alice")
+assert_contains "a set with no fields is refused" "❌" "$_out"
+assert_eq "and reaches the CLI not at all" "" "$(cat "$CALLS")"
+
+# (A bare /mp_setlimit matches no case arm and stays silent. That is how the
+# dispatcher has always treated it, and changing it is not part of this fix.)
+
+# ── The QR is rendered here, not fetched from a third party ──────────────────
+mkdir -p "$QRDIR" "$TEST_TMPDIR/bin"
+# A stand-in renderer: it only has to prove the PNG path is taken.
+cat > "$TEST_TMPDIR/bin/qrencode" <<'EOS'
+#!/bin/bash
+out=""
+while [ $# -gt 0 ]; do
+    case "$1" in -o) out="$2"; shift 2 ;; *) shift ;; esac
+done
+[ -n "$out" ] && printf 'PNGDATA' > "$out"
+exit 0
+EOS
+chmod +x "$TEST_TMPDIR/bin/qrencode"
+PATH="$TEST_TMPDIR/bin:$PATH"
+
+: > "$CURLS"; : > "$CURLCFG"
+send_proxy_qr_to "777" "203.0.113.9" "443" "eeaaaa0a0b0c0d" "scan me"
+_curl_args="$(cat "$CURLS")"
+_curl_cfg="$(cat "$CURLCFG")"
+
+assert_not_contains "the QR never goes to a third-party renderer" "qrserver" "$_curl_args$_curl_cfg"
+assert_contains "the upload targets sendPhoto" "sendPhoto" "$_curl_cfg"
+assert_contains "the QR is uploaded from a file on this host" "photo=@" "$_curl_args"
+assert_contains "the upload is multipart, not a URL parameter" "-F" "$_curl_args"
+assert_contains "the upload goes to the chat that asked for it" "chat_id=777" "$_curl_args"
+# The bot token must travel in the curl config, never in argv where `ps` shows it.
+assert_not_contains "the bot token is not on the command line" "111:AAA" "$_curl_args"
+
+# With no renderer at all, the link is still delivered — as the tappable link,
+# never by falling back to the third party.
+rm -f "$TEST_TMPDIR/bin/qrencode"
+: > "$SENDS"; : > "$CURLS"; : > "$CURLCFG"
+send_proxy_qr_to "777" "203.0.113.9" "443" "eeaaaa0a0b0c0d" "scan me"
+assert_not_contains "no renderer still means no third party" "qrserver" "$(cat "$CURLS")$(cat "$CURLCFG")"
+assert_contains "the fallback still delivers a usable link" "t.me/proxy?server=203.0.113.9" "$(cat "$SENDS")"
+
+printf '\n%d tests, %d failures\n' "$TESTS_RUN" "$TESTS_FAILED"
+[ "$TESTS_FAILED" -eq 0 ]
diff --git a/tests/test_telegram_reseller_rbac.sh b/tests/test_telegram_reseller_rbac.sh
index 385b3db..6f30bac 100644
--- a/tests/test_telegram_reseller_rbac.sh
+++ b/tests/test_telegram_reseller_rbac.sh
@@ -18,6 +18,8 @@ mkdir -p "$INSTALL_DIR/relay_stats"
 OFFSET_FILE="$INSTALL_DIR/relay_stats/tg_offset"
 ADMINS_FILE="$INSTALL_DIR/admins.conf"
 AUDIT_LOG="$INSTALL_DIR/audit.log"
+VOUCHERS_FILE="$INSTALL_DIR/vouchers.conf"
+printf 'MTP-SEED-0001|10737418240|30|15|5|standard|ACTIVE|2026-01-01 00:00:00 UTC|-|-\n' > "$VOUCHERS_FILE"
 
 MTPROXYMAX_SOURCE_ONLY=true source "$(dirname "${BASH_SOURCE[0]}")/../mtproxymax.sh"
 set +e
@@ -29,7 +31,7 @@ TESTS_FAILED=0
 assert_contains() {
     local name="$1" needle="$2" haystack="$3"
     TESTS_RUN=$((TESTS_RUN + 1))
-    if printf '%s' "$haystack" | grep -qF -- "$needle"; then
+    if [[ "$haystack" == *"$needle"* ]]; then
         printf '  PASS  %s\n' "$name"
     else
         TESTS_FAILED=$((TESTS_FAILED + 1))
@@ -40,7 +42,7 @@ assert_contains() {
 assert_not_contains() {
     local name="$1" needle="$2" haystack="$3"
     TESTS_RUN=$((TESTS_RUN + 1))
-    if printf '%s' "$haystack" | grep -qF -- "$needle"; then
+    if [[ "$haystack" == *"$needle"* ]]; then
         TESTS_FAILED=$((TESTS_FAILED + 1))
         printf '  FAIL  %s (unexpected %q in %q)\n' "$name" "$needle" "$haystack"
     else
@@ -66,27 +68,43 @@ ROLE_TO_RETURN="reseller"
 _check_tg_role() { echo "$ROLE_TO_RETURN"; }
 tg_send() { printf 'admin|%s\n' "$*" >> "$REPLIES"; }
 tg_send_to() { printf 'to:%s|%s\n' "$1" "$2" >> "$REPLIES"; }
+# The replies that carry an inline keyboard go through these instead, so they
+# must be captured too or those assertions silently see an empty log.
+tg_send_kb() { printf 'admin|%s\n' "$*" >> "$REPLIES"; }
+tg_send_to_kb() { printf 'to:%s|%s\n' "$1" "$2" >> "$REPLIES"; }
 load_tg_settings() { :; }
 is_running() { return 1; }
 log_warn() { :; }
 
 # Stand-in for the manager binary the voucher handler shells out to.
+#
+# The voucher reply reads the vault file rather than the CLI's padded table, so
+# this stub has to do what the real manager does — append to vouchers.conf — and
+# not merely print a table. A stub that only printed would let the reply look
+# correct while reading a file the manager never writes.
 cat > "$INSTALL_DIR/mtproxymax" <<'EOS'
 #!/bin/bash
 case "$1 $2" in
-    # Three lines so the create path (which does `tail -n +3`) still yields one.
     "voucher list") printf 'HEADER\nSEPARATOR\nMTP-AAAA-BBBB\n' ;;
-    "voucher create"|"voucher redeem") : ;;
+    "voucher create")
+        printf 'MTP-NEW1-NEW2|10737418240|30|15|5|standard|ACTIVE|2026-01-02 00:00:00 UTC|-|-\n' >> "$VOUCHERS_FILE"
+        ;;
+    "voucher redeem") : ;;
     *) : ;;
 esac
 EOS
 chmod +x "$INSTALL_DIR/mtproxymax"
+export VOUCHERS_FILE
 
 # Exercise the exact dispatcher shipped in the generated bot daemon.
 telegram_generate_service_script
 DAEMON="$INSTALL_DIR/mtproxymax-telegram.sh"
 awk '/^_tg_security_log\(\)/,/^}$/' "$DAEMON" > "$TEST_TMPDIR/daemon-fns.sh"
 awk '/^_process_cmd\(\)/,/^}$/' "$DAEMON" >> "$TEST_TMPDIR/daemon-fns.sh"
+# Reply handlers build their button bar via _tg_button_bar, so the menu block
+# has to resolve too. It does not define _check_tg_role, so the role stub above
+# survives.
+awk '/^# >>> TG_MENU_BEGIN$/,/^# <<< TG_MENU_END$/' "$DAEMON" >> "$TEST_TMPDIR/daemon-fns.sh"
 assert_eq "daemon helper extraction is valid bash" 0 \
     "$(bash -n "$TEST_TMPDIR/daemon-fns.sh" 2>/dev/null; echo $?)"
 source "$TEST_TMPDIR/daemon-fns.sh"
@@ -126,8 +144,12 @@ for _cmd in "/mp_voucher list" "/mp_voucher create 5 10G 30"; do
     run reseller 333 "$_cmd"
     assert_not_contains "reseller is allowed $_cmd" "Permission denied" "$(cat "$REPLIES")"
     assert_eq "allowed $_cmd is not logged as a violation" "" "$(audit_now)"
-    assert_contains "allowed $_cmd reaches the voucher engine" "MTP-AAAA-BBBB" "$(cat "$REPLIES")"
 done
+# The list reply shows the standing inventory; the create reply shows only the
+# codes it just generated, so the two reach the vault in different ways and need
+# different evidence.
+assert_contains "a reseller can read the vault" "MTP-SEED-0001" "$(run reseller 333 "/mp_voucher list" >/dev/null; cat "$REPLIES")"
+assert_contains "a reseller can add to the vault" "MTP-NEW1-NEW2" "$(run reseller 333 "/mp_voucher create 5 10G 30" >/dev/null; cat "$REPLIES")"
 
 reset_audit
 run reseller 333 "/start"
diff --git a/tests/test_telegram_settings_roundtrip.sh b/tests/test_telegram_settings_roundtrip.sh
new file mode 100644
index 0000000..bcd64fe
--- /dev/null
+++ b/tests/test_telegram_settings_roundtrip.sh
@@ -0,0 +1,109 @@
+#!/bin/bash
+# Tests that the Telegram settings keys survive a save/load round trip.
+#
+# There are FOUR places a key must be registered, and the fourth is the one
+# that gets missed: the bot daemon carries its OWN load_tg_settings whitelist,
+# independent of the manager's load_settings. A key added to only one of them
+# means the daemon silently runs on the default while `telegram status` reports
+# the configured value — a wrong-behaviour bug with no error anywhere.
+set -o pipefail
+
+if [ "${BASH_VERSINFO[0]:-0}" -lt 4 ]; then
+    echo "SKIP: bash 4+ required (got ${BASH_VERSION:-unknown})" >&2
+    exit 0
+fi
+
+TEST_TMPDIR=$(mktemp -d)
+INSTALL_DIR="$TEST_TMPDIR/install"
+mkdir -p "$INSTALL_DIR/relay_stats"
+SETTINGS_FILE="$INSTALL_DIR/settings.conf"
+OFFSET_FILE="$INSTALL_DIR/relay_stats/tg_offset"
+
+MTPROXYMAX_SOURCE_ONLY=true source "$(dirname "${BASH_SOURCE[0]}")/../mtproxymax.sh"
+set +e
+trap 'rm -rf "$TEST_TMPDIR"' EXIT
+
+TESTS_RUN=0
+TESTS_FAILED=0
+assert_eq() {
+    local name="$1" want="$2" got="$3"
+    TESTS_RUN=$((TESTS_RUN + 1))
+    if [ "$got" = "$want" ]; then printf '  PASS  %s\n' "$name"
+    else TESTS_FAILED=$((TESTS_FAILED + 1)); printf '  FAIL  %s (got=%q want=%q)\n' "$name" "$got" "$want"; fi
+}
+
+echo "Telegram settings round-trip tests"
+
+KEYS="TELEGRAM_HISTORY_ENABLED TELEGRAM_HISTORY_INTERVAL_MIN TELEGRAM_HISTORY_RETENTION_DAYS TELEGRAM_REPORT_DETAIL"
+
+# ── save_settings writes them ────────────────────────────────────────────────
+TELEGRAM_HISTORY_ENABLED="false"
+TELEGRAM_HISTORY_INTERVAL_MIN="11"
+TELEGRAM_HISTORY_RETENTION_DAYS="3"
+TELEGRAM_REPORT_DETAIL="full"
+save_settings 2>/dev/null
+
+for _k in $KEYS; do
+    TESTS_RUN=$((TESTS_RUN + 1))
+    if grep -q "^${_k}=" "$SETTINGS_FILE" 2>/dev/null; then
+        printf '  PASS  %s is written to settings.conf\n' "$_k"
+    else
+        TESTS_FAILED=$((TESTS_FAILED + 1))
+        printf '  FAIL  %s is written to settings.conf\n' "$_k"
+    fi
+done
+
+# ── load_settings reads them back ────────────────────────────────────────────
+TELEGRAM_HISTORY_ENABLED="true"
+TELEGRAM_HISTORY_INTERVAL_MIN="5"
+TELEGRAM_HISTORY_RETENTION_DAYS="7"
+TELEGRAM_REPORT_DETAIL="auto"
+load_settings 2>/dev/null
+
+assert_eq "load_settings restores TELEGRAM_HISTORY_ENABLED" "false" "$TELEGRAM_HISTORY_ENABLED"
+assert_eq "load_settings restores TELEGRAM_HISTORY_INTERVAL_MIN" "11" "$TELEGRAM_HISTORY_INTERVAL_MIN"
+assert_eq "load_settings restores TELEGRAM_HISTORY_RETENTION_DAYS" "3" "$TELEGRAM_HISTORY_RETENTION_DAYS"
+assert_eq "load_settings restores TELEGRAM_REPORT_DETAIL" "full" "$TELEGRAM_REPORT_DETAIL"
+
+# ── The daemon's own whitelist must know them too ────────────────────────────
+telegram_generate_service_script
+DAEMON="$INSTALL_DIR/mtproxymax-telegram.sh"
+FNS="$TEST_TMPDIR/daemon-settings.sh"
+awk '/^load_tg_settings\(\)/,/^}$/' "$DAEMON" > "$FNS"
+assert_eq "load_tg_settings extraction is valid bash" 0 \
+    "$(bash -n "$FNS" 2>/dev/null; echo $?)"
+source "$FNS"
+
+for _k in $KEYS; do
+    TESTS_RUN=$((TESTS_RUN + 1))
+    if grep -q "$_k" "$FNS"; then
+        printf '  PASS  the daemon whitelists %s\n' "$_k"
+    else
+        TESTS_FAILED=$((TESTS_FAILED + 1))
+        printf '  FAIL  the daemon whitelists %s\n' "$_k"
+    fi
+done
+
+# And it must actually pick the configured value up, not just name the key.
+TELEGRAM_HISTORY_ENABLED="unset-sentinel"
+TELEGRAM_HISTORY_INTERVAL_MIN="unset-sentinel"
+TELEGRAM_HISTORY_RETENTION_DAYS="unset-sentinel"
+TELEGRAM_REPORT_DETAIL="unset-sentinel"
+load_tg_settings
+
+assert_eq "the daemon picks up TELEGRAM_HISTORY_ENABLED" "false" "$TELEGRAM_HISTORY_ENABLED"
+assert_eq "the daemon picks up TELEGRAM_HISTORY_INTERVAL_MIN" "11" "$TELEGRAM_HISTORY_INTERVAL_MIN"
+assert_eq "the daemon picks up TELEGRAM_HISTORY_RETENTION_DAYS" "3" "$TELEGRAM_HISTORY_RETENTION_DAYS"
+assert_eq "the daemon picks up TELEGRAM_REPORT_DETAIL" "full" "$TELEGRAM_REPORT_DETAIL"
+
+# No clamp is needed on the interval: sampling is driven from inside the 60s
+# traffic tick, so the tick itself is the floor however the config is set.
+TELEGRAM_HISTORY_INTERVAL_MIN="unset-sentinel"
+printf "TELEGRAM_HISTORY_INTERVAL_MIN='0'\n" > "$SETTINGS_FILE"
+load_tg_settings
+assert_eq "a zero interval passes through the parser" "0" "$TELEGRAM_HISTORY_INTERVAL_MIN"
+assert_eq "the tick bounds sampling to one per minute" 1 \
+    "$(grep -c '_last_hist_sample )) -ge' "$DAEMON")"
+
+printf '\n%d tests, %d failures\n' "$TESTS_RUN" "$TESTS_FAILED"
+[ "$TESTS_FAILED" -eq 0 ]
diff --git a/tests/test_telegram_update_parser.sh b/tests/test_telegram_update_parser.sh
new file mode 100644
index 0000000..2ff4a8f
--- /dev/null
+++ b/tests/test_telegram_update_parser.sh
@@ -0,0 +1,157 @@
+#!/bin/bash
+# Tests for the getUpdates parser.
+#
+# Two production bugs motivate this file:
+#
+#   1. The no-python3 fallback extracted text and chat id in two INDEPENDENT
+#      `grep | tail -1` passes and paired them by position. A batch of two
+#      updates therefore lost all but the last, and could pair update A's text
+#      with update B's chat id.
+#   2. callback_query updates were never parsed at all, so the offset advanced
+#      and Telegram never redelivered them.
+#
+# Both extractors must emit byte-identical records, because the awk path is the
+# only one available on a host without python3 (e.g. Alpine, which this project
+# supports via OpenRC).
+set -o pipefail
+
+if [ "${BASH_VERSINFO[0]:-0}" -lt 4 ]; then
+    echo "SKIP: bash 4+ required (got ${BASH_VERSION:-unknown})" >&2
+    exit 0
+fi
+
+TEST_TMPDIR=$(mktemp -d)
+INSTALL_DIR="$TEST_TMPDIR/install"
+mkdir -p "$INSTALL_DIR/relay_stats"
+OFFSET_FILE="$INSTALL_DIR/relay_stats/tg_offset"
+ADMINS_FILE="$INSTALL_DIR/admins.conf"
+
+MTPROXYMAX_SOURCE_ONLY=true source "$(dirname "${BASH_SOURCE[0]}")/../mtproxymax.sh"
+set +e
+trap 'rm -rf "$TEST_TMPDIR"' EXIT
+
+TESTS_RUN=0
+TESTS_FAILED=0
+
+assert_eq() {
+    local name="$1" want="$2" got="$3"
+    TESTS_RUN=$((TESTS_RUN + 1))
+    if [ "$got" = "$want" ]; then
+        printf '  PASS  %s\n' "$name"
+    else
+        TESTS_FAILED=$((TESTS_FAILED + 1))
+        printf '  FAIL  %s\n         got=%q\n        want=%q\n' "$name" "$got" "$want"
+    fi
+}
+
+assert_contains() {
+    local name="$1" needle="$2" haystack="$3"
+    TESTS_RUN=$((TESTS_RUN + 1))
+    if [[ "$haystack" == *"$needle"* ]]; then
+        printf '  PASS  %s\n' "$name"
+    else
+        TESTS_FAILED=$((TESTS_FAILED + 1))
+        printf '  FAIL  %s (missing %q)\n' "$name" "$needle"
+    fi
+}
+
+# ── Extract both extractors from the daemon that actually ships ──────────────
+telegram_generate_service_script
+DAEMON="$INSTALL_DIR/mtproxymax-telegram.sh"
+PARSER="$TEST_TMPDIR/parser.sh"
+: > "$PARSER"
+for _fn in _tg_have_python _tg_parse_updates_py _tg_parse_updates_awk; do
+    awk "/^${_fn}\\(\\)/,/^}\$/" "$DAEMON" >> "$PARSER"
+done
+assert_eq "parser extraction is valid bash" 0 \
+    "$(bash -n "$PARSER" 2>/dev/null; echo $?)"
+source "$PARSER"
+
+echo "Telegram update parser tests"
+
+# ── Fixtures ─────────────────────────────────────────────────────────────────
+# Three updates in one batch. The second message's text deliberately embeds
+# escaped quotes, braces and a backslash so that a scanner which does not track
+# JSON string state will mis-slice the batch.
+F_MAIN="$TEST_TMPDIR/main.json"
+cat > "$F_MAIN" <<'JSON'
+{"ok":true,"result":[{"update_id":1001,"message":{"message_id":11,"chat":{"id":111,"type":"private"},"text":"/mp_status"}},{"update_id":1002,"message":{"message_id":12,"chat":{"id":222,"type":"private"},"text":"tricky \"chat\":{\"id\":999} and } and \\ backslash"}},{"update_id":1003,"callback_query":{"id":"cb-abc","data":"u:s:alice:0","message":{"message_id":13,"chat":{"id":111,"type":"private"}}}}]}
+JSON
+
+# The text decodes to: tricky "chat":{"id":999} and } and \ backslash
+EXPECT_MAIN=$(printf '1001\tmsg\t111\t11\t-\t/mp_status\n1002\tmsg\t222\t12\t-\ttricky "chat":{"id":999} and } and \\ backslash\n1003\tcb\t111\t13\tcb-abc\tu:s:alice:0')
+
+# An update with no message/callback at all must still yield a record, so the
+# consumer advances past it. Otherwise Telegram redelivers it forever.
+F_BARE="$TEST_TMPDIR/bare.json"
+cat > "$F_BARE" <<'JSON'
+{"ok":true,"result":[{"update_id":2000},{"update_id":2001,"message":{"message_id":21,"chat":{"id":333,"type":"private"},"text":"/start"}}]}
+JSON
+EXPECT_BARE=$(printf '2000\tmsg\t\t\t-\t\n2001\tmsg\t333\t21\t-\t/start')
+
+# A truncated response must yield nothing at all — never a partial record.
+F_TRUNC="$TEST_TMPDIR/truncated.json"
+printf '{"ok":true,"result":[{"update_id":9,"message":{"message_id":1,' > "$F_TRUNC"
+
+# text containing a real newline escape: only the first line is the command.
+F_MULTILINE="$TEST_TMPDIR/multiline.json"
+cat > "$F_MULTILINE" <<'JSON'
+{"ok":true,"result":[{"update_id":3000,"message":{"message_id":31,"chat":{"id":444,"type":"private"},"text":"/mp_add alice\nsecond line ignored"}}]}
+JSON
+EXPECT_MULTILINE=$(printf '3000\tmsg\t444\t31\t-\t/mp_add alice')
+
+# ── The awk extractor (always available) ─────────────────────────────────────
+assert_eq "awk parses a 3-update batch in order" "$EXPECT_MAIN" "$(_tg_parse_updates_awk "$(cat "$F_MAIN")")"
+assert_eq "awk advances past updates with no message" "$EXPECT_BARE" "$(_tg_parse_updates_awk "$(cat "$F_BARE")")"
+assert_eq "awk emits nothing for truncated JSON" "" "$(_tg_parse_updates_awk "$(cat "$F_TRUNC")")"
+assert_eq "awk keeps only the first line of text" "$EXPECT_MULTILINE" "$(_tg_parse_updates_awk "$(cat "$F_MULTILINE")")"
+assert_eq "awk emits nothing for empty input" "" "$(_tg_parse_updates_awk "")"
+assert_eq "awk emits nothing for non-JSON input" "" "$(_tg_parse_updates_awk "not json at all")"
+
+# The mis-pairing regression: update 1002's chat must be 222, not 111 or 999.
+_awk_main=$(_tg_parse_updates_awk "$(cat "$F_MAIN")")
+assert_contains "awk pairs text with its own chat id" "$(printf '1002\tmsg\t222\t12')" "$_awk_main"
+assert_eq "awk does not leak a chat id embedded in text" 3 "$(printf '%s\n' "$_awk_main" | wc -l | tr -d ' ')"
+assert_eq "awk does not mistake embedded text for the chat id" 0 \
+    "$(printf '%s\n' "$_awk_main" | grep -c $'^1002\tmsg\t999\t')"
+
+# ── 5000-char text is truncated to 512 ───────────────────────────────────────
+F_LONG="$TEST_TMPDIR/long.json"
+_LONG=$(printf 'A%.0s' $(seq 1 5000))
+printf '{"ok":true,"result":[{"update_id":9,"message":{"message_id":1,"chat":{"id":5,"type":"private"},"text":"%s"}}]}' \
+    "$_LONG" > "$F_LONG"
+_LONG_OUT=$(_tg_parse_updates_awk "$(cat "$F_LONG")")
+_LONG_PAY=$(printf '%s' "$_LONG_OUT" | cut -f6)
+assert_eq "awk truncates a 5000-char text to 512" 512 "${#_LONG_PAY}"
+
+# ── The python extractor, when a working python3 exists ──────────────────────
+# `command -v python3` is not enough: the Windows Store ships a python3.exe
+# alias that is on PATH but fails the moment it runs, so probe by executing it.
+# Where only `python` exists, stand up a shim so the parity contract below is
+# still exercised instead of quietly skipping the assertions that matter most.
+if ! _tg_have_python && command -v python >/dev/null 2>&1 && python -c '' >/dev/null 2>&1; then
+    _PY_REAL=$(command -v python)
+    mkdir -p "$TEST_TMPDIR/bin"
+    printf '#!/bin/bash\nexec "%s" "$@"\n' "$_PY_REAL" > "$TEST_TMPDIR/bin/python3"
+    chmod +x "$TEST_TMPDIR/bin/python3"
+    PATH="$TEST_TMPDIR/bin:$PATH"
+    printf '  NOTE  python3 shimmed to %s for parity checks\n' "$_PY_REAL"
+fi
+
+if _tg_have_python; then
+    assert_eq "python parses a 3-update batch in order" "$EXPECT_MAIN" "$(_tg_parse_updates_py "$(cat "$F_MAIN")")"
+    assert_eq "python advances past updates with no message" "$EXPECT_BARE" "$(_tg_parse_updates_py "$(cat "$F_BARE")")"
+    assert_eq "python emits nothing for truncated JSON" "" "$(_tg_parse_updates_py "$(cat "$F_TRUNC")")"
+    assert_eq "python keeps only the first line of text" "$EXPECT_MULTILINE" "$(_tg_parse_updates_py "$(cat "$F_MULTILINE")")"
+
+    # The contract that keeps the fallback honest.
+    for _f in "$F_MAIN" "$F_BARE" "$F_TRUNC" "$F_MULTILINE" "$F_LONG"; do
+        assert_eq "extractors agree byte-for-byte on $(basename "$_f")" \
+            "$(_tg_parse_updates_awk "$(cat "$_f")")" "$(_tg_parse_updates_py "$(cat "$_f")")"
+    done
+else
+    printf '  SKIP  python extractor assertions (no working python3)\n'
+fi
+
+printf '\n%d tests, %d failures\n' "$TESTS_RUN" "$TESTS_FAILED"
+[ "$TESTS_FAILED" -eq 0 ]
diff --git a/tests/test_telegram_user_traffic.sh b/tests/test_telegram_user_traffic.sh
new file mode 100644
index 0000000..140a1fe
--- /dev/null
+++ b/tests/test_telegram_user_traffic.sh
@@ -0,0 +1,158 @@
+#!/bin/bash
+# Tests for the per-user traffic card.
+#
+# users.tsv has been written since the history subsystem landed, but nothing
+# ever read it back per user: the user card showed only the cumulative total
+# since the last reset, which cannot answer "how much did they move today, and
+# is that up or down?". This pins the per-user reader and the card that shows
+# it, including the two ways a per-user series goes wrong — counting another
+# user's rows, and going missing (rather than reporting zero) for a user with no
+# rows at all, which is the common case for a quiet account.
+set -o pipefail
+
+if [ "${BASH_VERSINFO[0]:-0}" -lt 4 ]; then
+    echo "SKIP: bash 4+ required (got ${BASH_VERSION:-unknown})" >&2
+    exit 0
+fi
+
+TEST_TMPDIR=$(mktemp -d)
+INSTALL_DIR="$TEST_TMPDIR/install"
+mkdir -p "$INSTALL_DIR/relay_stats/history"
+OFFSET_FILE="$INSTALL_DIR/relay_stats/tg_offset"
+ADMINS_FILE="$INSTALL_DIR/admins.conf"
+AUDIT_LOG="$INSTALL_DIR/audit.log"
+SECRETS_FILE="$INSTALL_DIR/secrets.conf"
+HISTORY_DIR="$INSTALL_DIR/relay_stats/history"
+
+printf 'alice|%s|1700000000|true|7|3|10737418240|2027-01-01||\n' "$(printf 'a%.0s' $(seq 1 32))" > "$SECRETS_FILE"
+printf 'quiet|%s|1700000000|true|0|0|0|0||\n' "$(printf 'q%.0s' $(seq 1 32))" >> "$SECRETS_FILE"
+
+MTPROXYMAX_SOURCE_ONLY=true source "$(dirname "${BASH_SOURCE[0]}")/../mtproxymax.sh"
+set +e
+trap 'rm -rf "$TEST_TMPDIR"' EXIT
+
+TESTS_RUN=0
+TESTS_FAILED=0
+
+assert_eq() {
+    local name="$1" want="$2" got="$3"
+    TESTS_RUN=$((TESTS_RUN + 1))
+    if [ "$got" = "$want" ]; then printf '  PASS  %s\n' "$name"
+    else TESTS_FAILED=$((TESTS_FAILED + 1)); printf '  FAIL  %s (got=%q want=%q)\n' "$name" "$got" "$want"; fi
+}
+assert_contains() {
+    local name="$1" needle="$2" haystack="$3"
+    TESTS_RUN=$((TESTS_RUN + 1))
+    if [[ "$haystack" == *"$needle"* ]]; then printf '  PASS  %s\n' "$name"
+    else TESTS_FAILED=$((TESTS_FAILED + 1)); printf '  FAIL  %s (missing %q in %q)\n' "$name" "$needle" "$haystack"; fi
+}
+assert_not_contains() {
+    local name="$1" needle="$2" haystack="$3"
+    TESTS_RUN=$((TESTS_RUN + 1))
+    if [[ "$haystack" == *"$needle"* ]]; then
+        TESTS_FAILED=$((TESTS_FAILED + 1)); printf '  FAIL  %s (unexpected %q in %q)\n' "$name" "$needle" "$haystack"
+    else printf '  PASS  %s\n' "$name"; fi
+}
+
+telegram_generate_service_script
+DAEMON="$INSTALL_DIR/mtproxymax-telegram.sh"
+FNS="$TEST_TMPDIR/daemon-fns.sh"
+: > "$FNS"
+for _fn in _tg_security_log _esc _cb_label_ok _cb_enc _cb_dec _iso_to_epoch; do
+    awk "/^${_fn}\\(\\)/,/^}\$/" "$DAEMON" >> "$FNS"
+done
+awk '/^# >>> TG_MENU_BEGIN$/,/^# <<< TG_MENU_END$/' "$DAEMON" >> "$FNS"
+awk '/^# >>> TG_HISTORY_BEGIN$/,/^# <<< TG_HISTORY_END$/' "$DAEMON" >> "$FNS"
+assert_eq "extraction is valid bash" 0 "$(bash -n "$FNS" 2>/dev/null; echo $?)"
+assert_contains "the user-traffic reader ships in the daemon" "history_user_series()" "$(cat "$FNS")"
+
+SENDS="$TEST_TMPDIR/sends.log"
+EDITS="$TEST_TMPDIR/edits.log"
+_check_tg_role() { echo "superadmin"; }
+tg_send() { printf 'admin|%s\n' "$*" >> "$SENDS"; }
+tg_send_to() { printf '%s|%s\n' "$1" "$2" >> "$SENDS"; }
+tg_send_kb() { printf 'admin|%s\n' "$1" >> "$SENDS"; }
+tg_send_to_kb() { printf '%s|%s\n' "$1" "$2" >> "$SENDS"; }
+tg_answer_cb() { :; }
+tg_edit() { printf '%s\n---\n%s\n' "$3" "$4" > "$EDITS"; }
+tg_edit_markup() { :; }
+load_tg_settings() { :; }
+is_running() { return 1; }
+log_warn() { :; }
+get_cached_ip() { echo "203.0.113.9"; }
+_tg_metrics_raw() { printf ''; }
+_tg_have_python() { return 1; }
+
+source "$FNS"
+
+NOW=1000000
+# alice: a rising ramp across the last 24h, all in 4 hourly buckets.
+# Another user's rows sit in the same file to prove the reader filters.
+: > "$HISTORY_DIR/users.tsv"
+for _i in 1 2 3 4; do
+    printf '%s|alice|%s|%s\n' "$(( NOW - _i * 3600 ))" "$(( _i * 1000 ))" "$(( _i * 2000 ))" >> "$HISTORY_DIR/users.tsv"
+    printf '%s|bob|%s|%s\n' "$(( NOW - _i * 3600 ))" "$(( _i * 999999 ))" "$(( _i * 999999 ))" >> "$HISTORY_DIR/users.tsv"
+done
+
+# ── The reader ───────────────────────────────────────────────────────────────
+_series=$(history_user_series alice 86400 "$NOW" 24)
+assert_eq "the series has one bucket per slot" 24 "$(printf '%s' "$_series" | wc -w | tr -d ' ')"
+# alice's four buckets total 1000+2000+3000+4000 = 10000 in, 20000 out.
+assert_eq "the series sums only this user's rows" "30000" \
+    "$(printf '%s' "$_series" | tr ' ' '\n' | awk '{s+=$1} END {printf "%d", s+0}')"
+assert_eq "another user's rows are not counted" "0" \
+    "$(printf '%s' "$(history_user_series alice 86400 "$NOW" 24)" | grep -c '999999' || true)"
+
+# A user with no rows must report zeros, not nothing: an empty string would make
+# the card lose its sparkline row silently rather than drawing a flat one.
+_quiet=$(history_user_series quiet 86400 "$NOW" 24)
+assert_eq "a silent user still yields a full series" 24 "$(printf '%s' "$_quiet" | wc -w | tr -d ' ')"
+assert_eq "and it is all zeros" "0" "$(printf '%s' "$_quiet" | tr ' ' '\n' | awk '{s+=$1} END {printf "%d", s+0}')"
+
+# ── The card ─────────────────────────────────────────────────────────────────
+# The card reads the wall clock (a real tap has no other notion of "now"), so
+# the fixture has to be laid down relative to it rather than to the fixed epoch
+# the reader tests above use.
+_now=$(date +%s)
+: > "$HISTORY_DIR/users.tsv"
+for _i in 1 2 3 4; do
+    printf '%s|alice|%s|%s\n' "$(( _now - _i * 3600 ))" "$(( _i * 1000 ))" "$(( _i * 2000 ))" >> "$HISTORY_DIR/users.tsv"
+    printf '%s|bob|%s|%s\n' "$(( _now - _i * 3600 ))" "$(( _i * 999999 ))" "$(( _i * 999999 ))" >> "$HISTORY_DIR/users.tsv"
+done
+
+_UI_ROLE="superadmin"; _CB_CHAT="111"; _CB_MID="77"
+render_detail() { : > "$EDITS"; _cb_render_user_detail "${1:-alice}" 0; cat "$EDITS"; }
+render_card()   { : > "$EDITS"; _cb_render_user_traffic "${1:-alice}" 0 2>/dev/null; cat "$EDITS"; }
+
+_out=$(render_detail)
+assert_contains "the user card offers the traffic view" "u:t:alice:0" "$_out"
+
+_out=$(render_card)
+assert_contains "the traffic card reports the 24h window" "24h" "$_out"
+assert_contains "the traffic card reports the 7d window"  "7d"  "$_out"
+assert_contains "the traffic card reports the 30d window" "30d" "$_out"
+# 1000+2000+3000+4000 = 10000 bytes in and 20000 out, which format_bytes
+# renders in binary units: 9.8 KB up, 19.5 KB down.
+assert_contains "the traffic card reports this user's upload"   "↑ 9.8 KB"  "$_out"
+assert_contains "the traffic card reports this user's download" "↓ 19.5 KB" "$_out"
+assert_not_contains "the traffic card does not count another user" "3.8 MB" "$_out"
+assert_not_contains "the traffic card draws no code box" '```' "$_out"
+assert_contains "the traffic card goes back to the user card" "u:s:alice:0" "$_out"
+_bars=0
+for _g in ▁ ▂ ▃ ▄ ▅ ▆ ▇ █; do [[ "$_out" == *"$_g"* ]] && { _bars=1; break; }; done
+assert_eq "the traffic card draws a sparkline" 1 "$_bars"
+
+# A quiet user gets a flat line, not a missing row.
+_out=$(render_card quiet)
+assert_contains "a silent user still gets a card" "quiet" "$_out"
+assert_not_contains "a silent user's card draws no code box" '```' "$_out"
+
+# A label that is not a secret must not render a card. The label arrives through
+# callback_data, so it is attacker-controlled.
+assert_eq "a non-secret label renders nothing" "" "$(render_card '../etc')"
+
+# ── RBAC ─────────────────────────────────────────────────────────────────────
+assert_eq "the traffic card has a capability" "admin" "$(_tg_cap_for u t)"
+
+printf '\n%d tests, %d failures\n' "$TESTS_RUN" "$TESTS_FAILED"
+[ "$TESTS_FAILED" -eq 0 ]