Expand project documentation for users and agents

DOCS_AI.md

@@ -2,13 +2,30 @@
 
 **Версия:** 2.5.0
 **Репозиторий:** `anten-ka/gotelegram_pro`
-**Активная ветка:** `alfa-test` (ветка `test` заморожена и содержит stable для конечных пользователей)
+**Активная ветка:** `main` — основной код и продакшен. `beta` и `alpha` существуют для следующих сборок.
 **Целевая ОС:** Ubuntu 20.04+, Debian 11+
 
 Этот документ описывает устройство проекта с максимальным количеством нюансов — все ловушки, на которые мы уже наступали, все причины «почему именно так», формат всех внешних интерфейсов, и checklist действий для типовых задач. Цель: чтобы новый агент мог продолжить работу без повторения ошибок и без регрессий.
 
 ---
 
+## 0. Быстрый старт для нового ИИ
+
+Если ты агент, который впервые открыл репозиторий:
+
+1. Не трогай токены, ключи VPS и BotFather-токены в истории диалога; не печатай их в ответах и не клади в файлы.
+2. Основной код устанавливается из `main`; `bootstrap.sh` по умолчанию скачивает `main`, если не задан `GOTELEGRAM_BRANCH`.
+3. Рабочая модель веток: `alpha` для ранних экспериментов, `beta` для проверочных сборок, `main` для продакшена.
+4. Главный код установки — `install.sh` + `lib/*.sh`. Не исправляй Telegram-бот или web-admin в отрыве от bash-слоя: все три интерфейса должны показывать одно и то же состояние.
+5. Главный конфиг пользователя — `/opt/gotelegram/config.json`; главный runtime-конфиг ядра — `/etc/telemt/config.toml`.
+6. `telemt` использует TOML v3, не совместимый со старым `mtg`. Не возвращай старые секции `[security]`, `[[users]]`, `bind_to`.
+7. Любая bash-функция, которую вызывают через `$()`, обязана писать UI и логи в stderr (`>&2`), а в stdout возвращать только значение.
+8. Перед пушем запускай проверки из раздела 20. Для документации минимум: bash syntax, unit tests, py_compile, node check, `git diff --check`.
+9. Если меняешь поведение, обновляй `DOCS_HUMAN.md`, `DOCS_AI.md`, changelog и при необходимости `GOTELEGRAM_VERSION`.
+10. Если меняешь бэкапы, сохраняй обратную совместимость restore для старых архивов.
+
+---
+
 ## 1. Общая картина
 
 goTelegram Pro — это менеджер MTProxy для Telegram, собранный вокруг Rust-ядра **telemt** (порт mtproto-proxy с поддержкой fake-TLS, v3.3.x). Проект даёт три вещи:
@@ -43,18 +60,17 @@ tls_domain = google.com (или любой из QUICK_DOMAINS)
 
 ```
 anten-ka/gotelegram_pro
-├── test          ← frozen stable, пользователи ставятся отсюда через bootstrap.sh
+├── main          ← продакшен и дефолтная установка
-└── alfa-test     ← активная разработка, пуши туда
+├── beta          ← следующая публичная сборка для проверки пользователями
+└── alpha         ← ранние личные сборки владельца
 ```
 
-**Правило коммитов (из auto-memory):** все новые изменения идут ТОЛЬКО в `alfa-test`. `test` не трогаем без явной команды пользователя. Когда пользователь в диалоге скажет «влей в stable» — тогда мёржим alfa-test → test.
+**Правило коммитов:** новые рискованные изменения сначала идут в `alpha`, затем после ручной проверки в `beta`. В `main` попадает только код, который можно считать установочным по умолчанию. Перед любым рискованным переносом или force-update создавай rollback tag/release для текущего состояния целевой ветки.
 
-**Инструменты для коммитов (специфика окружения):**
+**Инструменты для коммитов:**
-- `git push` через Windows Git CLI **не работает** — credential helper вешает процесс.
+- Основной путь — обычный `git commit` + `git push` в нужную ветку после локальной проверки.
-- Linux sandbox **не имеет доступа к github.com** — прокси возвращает 403 на raw.githubusercontent.com и api.github.com.
+- Если окружение не может пушить напрямую, используй GitHub REST API с PAT из переменной окружения `GOTELEGRAM_PAT`.
-- **Единственный работающий путь:** Python-скрипт через GitHub REST API, запускаемый через Desktop Commander с `shell="cmd.exe"` (НЕ powershell, иначе не захватывается stdout).
+- Workflow через GitHub API: `POST git/blobs` для каждого файла → `POST git/trees` (с `base_tree` от текущего HEAD) → `POST git/commits` (parents=[текущий HEAD]) → `PATCH git/refs/heads/<main|beta|alpha>` (sha=новый commit) → при необходимости `POST /releases`.
-- PAT токен — см. CLAUDE.md.
-- Workflow: `POST git/blobs` для каждого файла → `POST git/trees` (с `base_tree` от текущего HEAD) → `POST git/commits` (parents=[текущий HEAD]) → `PATCH git/refs/heads/alfa-test` (sha=новый commit) → при необходимости `PATCH git/refs/tags/vX.Y.Z`.
 - **Важно про `base_tree`:** при частичном обновлении (1-2 файла) ОБЯЗАТЕЛЬНО передавать `base_tree` — иначе дерево получится только из переданных файлов, и все остальные файлы пропадут из коммита. `base_tree` можно опускать только при коммите с полным набором файлов.
 
 ---
@@ -62,12 +78,13 @@ anten-ka/gotelegram_pro
 ## 3. Карта файлов
 
 ```
-install.sh                     главная точка входа, CLI-меню из 14 пунктов
+install.sh                     главная точка входа, CLI-меню из 5 разделов
 install_gotelegram_bot.sh      legacy-установщик бота (функционал продублирован в install.sh)
 bootstrap.sh                   установщик приватного репо через raw.githubusercontent.com с PAT
 templates_catalog.json         каталог 1801 шаблонов, 18 категорий, 4 источника (~460KB)
 DOCS_HUMAN.md                  документация для пользователя (этот каталог)
 DOCS_AI.md                     этот файл
+README.md                      короткая входная точка проекта
 
 lib/common.sh                  цвета, log_*, confirm, select_option, _valid_ip, config_get,
                                save_gotelegram_config, get_server_ip, run_with_spinner,
@@ -91,7 +108,12 @@ gotelegram-bot/bot.py          Telegram-бот (python-telegram-bot v21+)
 gotelegram-bot/config.example.env
 gotelegram-bot/requirements.txt
 gotelegram-bot/README.md
-gotelegram-bot/locales/*.json  99 ключей i18n для бота с per-user persistence
+gotelegram-bot/lang/*.json     i18n для бота с per-user persistence
+
+admin-web/server.py            backend локальной админки на Python stdlib
+admin-web/static/index.html    shell интерфейса админки
+admin-web/static/app.js        frontend логика, API calls, графики, таблицы
+admin-web/static/styles.css    responsive light/dark UI
 ```
 
 **Где что лежит на VPS после установки:**
@@ -325,7 +347,7 @@ Fallback: если по известным правилам index.html не на
 
 ## 10. История багов (не наступать на те же грабли)
 
-Все решены в текущем HEAD (`alfa-test`). Перечисление для того, чтобы новый агент не «чинил» то, что уже починено, и понимал контекст.
+Все решены в текущем HEAD (`main`). Перечисление для того, чтобы новый агент не «чинил» то, что уже починено, и понимал контекст.
 
 1. `telemt.sh grep` — URL формат `telemt-x86_64-linux-gnu.tar.gz`, arch перед `linux`. Нужен `grep -iE "$arch_pattern"` + цепочка фильтров (`grep -i linux`, `grep -v sha256`, `grep gnu`, `head -1`).
 2. `bot.py safe_edit_message` — обёртка для `query.edit_message_text`, ловит `BadRequest: message is not modified`.
@@ -365,12 +387,13 @@ Fallback: если по известным правилам index.html не на
 Ключевые моменты:
 - **Admin ID** — бот отвечает только пользователю с `ADMIN_TG_ID` из `.env`. Всё остальное игнорируется.
 - **safe_edit_message** — обёртка над `query.edit_message_text` + `query.edit_message_caption`, глотает `BadRequest: message is not modified`. Начиная с v2.4.2 принимает опциональный `disable_web_page_preview` — не забудь прокинуть его если показываешь ссылку-превью (раньше вызов с этим kwarg ловил TypeError в runtime). Используй её всегда вместо прямого вызова.
-- **Language per-user** — файл `locales/users.json` хранит `{user_id: "ru"/"en"}`. При каждом сообщении бот читает язык пользователя и подставляет строку через `t(key, lang)`.
+- **Language per-user** — файл `/opt/gotelegram-bot/user_langs.json` хранит `{user_id: "ru"/"en"}`. При каждом сообщении бот читает язык пользователя и подставляет строку через `t(user_id, key)` / `tf(user_id, key, ...)`.
 - **QR-коды** — генерятся в `/tmp/gotelegram_qr_*.png`, отправляются как `InputFile`, удаляются в `finally`.
 - **Шаблон preview в HTML** — URL экранируется через `html.escape(url, quote=True)` (баг #11).
 - **Системные действия (v2.4.2+)** — бот реально умеет менять шаблон и домен маскировки. Хелпер `run_bot_action(action, **kwargs)` вызывает `subprocess.run(["/opt/gotelegram/install.sh", "--action=X", "--json", ...])` и парсит JSON. Два коллбэка: `cb_pro_confirm` (change-template) и `cb_lite_domain` (change-lite-domain). Оба обёрнуты в `async with _BOT_ACTION_LOCK` (глобальный `asyncio.Lock()`) — сериализуют параллельные callback'и внутри процесса бота. Входы валидируются ДО subprocess: `_TPL_ID_RE = r"^[A-Za-z0-9_-]{1,64}$"`, `_DOMAIN_RE` (RFC-like). Малформный ввод отвергается с понятным сообщением, не доходя до shell.
 - **Поле `template_id` в config.json** — канонический ключ для текущего шаблона. Раньше (до v2.4.2) бот читал `config['template']` и писал в него же в `handle_text_message`, но `save_gotelegram_config` всегда писал `template_id` → поле статуса никогда не отображалось. Используй только `template_id`.
-- **Устанавливается** из меню `install.sh → 12) Telegram-бот → Установить`. Пользователь вводит BotFather token + свой Telegram ID, `.env` пишется в `/opt/gotelegram-bot/.env`.
+- **Устанавливается** из меню `install.sh → 4) Telegram-бот → Установить`. Пользователь вводит BotFather token + свой Telegram ID, `.env` пишется в `/opt/gotelegram-bot/.env`.
+- **Обновляется автоматически (v2.5.0+)** при повторном bootstrap/update: `auto_update_bot_if_possible` сравнивает новые файлы в `$SCRIPT_DIR/gotelegram-bot/` с установленными `/opt/gotelegram-bot/{bot.py,i18n.py,requirements.txt,lang/*.json}`. Если есть отличия и сервис уже установлен, вызывается `bot_install >/dev/null`, `.env` сохраняется, зависимости обновляются, systemd unit переписывается и `gotelegram-bot` перезапускается. Это закрывает сценарий 2.4.x → 2.5.0, где bootstrap обновлял `/opt/gotelegram/gotelegram-bot/`, но рабочий сервис продолжал запускать старый `/opt/gotelegram-bot/bot.py`.
 
 ### 11.1 Non-interactive action bridge (install.sh ↔ bot)
 
@@ -476,11 +499,11 @@ Traffic retention: обе CSV-истории хранятся максимум 3
 
 Отключённые ключи хранятся в `/opt/gotelegram/disabled_users.json`: active keys остаются в `/etc/telemt/config.toml` под `[access.users]`, disabled keys удаляются из active block и могут быть возвращены обратно без потери secret. `main` защищён от удаления и отключения. Лимит уникальных IP сохраняется в `[access.user_max_unique_ips]` и не теряется при disable/enable; при удалении ключа строка лимита удаляется. Операции с ключами в web-admin и Telegram-боте берут общий file lock `/run/gotelegram/admin-users.lock`, TOML пишется через temp+replace и quoted keys (`"a.b"`), а telemt restart для add/delete/enable/disable/IP-limit ставится через `systemctl --no-block restart`, чтобы switch в UI не зависал на `wait_tcp_port`.
 
-`install_admin_web` вызывается при установке Telegram-бота. `auto_install_admin_web_if_possible` подхватывает админку после bootstrap/update, если Python уже установлен и файлы отличаются. При установке админки скрипт пытается установить/перезапустить `gotelegram-stats`; если это не удалось, оператор может нажать Restart collector в Traffic. Backup v1.6 сохраняет `admin_web/server.py`, `admin_web/static/`, `disabled_users.json`, `stats_history.csv`, `user_stats_history.csv`, `backup_schedule.json` и `shared-443.json`, restore возвращает их, удаляет legacy `admin_web/token` и пробует перезапустить `gotelegram-admin`.
+`install_admin_web` вызывается при установке Telegram-бота. `auto_install_admin_web_if_possible` подхватывает админку после bootstrap/update, если Python уже установлен и файлы отличаются. `auto_update_bot_if_possible` аналогично подхватывает уже установленный Telegram-бот и обновляет рабочий `/opt/gotelegram-bot` без запроса токена. При установке админки скрипт пытается установить/перезапустить `gotelegram-stats`; если это не удалось, оператор может нажать Restart collector в Traffic. Backup v1.6 сохраняет `admin_web/server.py`, `admin_web/static/`, `disabled_users.json`, `stats_history.csv`, `user_stats_history.csv`, `backup_schedule.json` и `shared-443.json`, restore возвращает их, удаляет legacy `admin_web/token` и пробует перезапустить `gotelegram-admin`.
 
 ### 13.2 Upgrade migration (v2.5.0)
 
-`install.sh` вызывает `auto_migrate_legacy_state` перед интерактивным меню и перед non-interactive `--action=...` для бота. Цель — комфортно обновляться даже с кривой старой логики без переустановки прокси:
+`install.sh` вызывает `auto_migrate_legacy_state` перед интерактивным меню и перед non-interactive `--action=...` для бота. В интерактивном запуске после миграции также вызываются `auto_update_bot_if_possible` и `auto_install_admin_web_if_possible`, чтобы повторный bootstrap обновлял не только исходники в `/opt/gotelegram`, но и реально запущенные сервисы `/opt/gotelegram-bot` и `/opt/gotelegram/admin-web`. Цель — комфортно обновляться даже с кривой старой логики без переустановки прокси:
 
 - перед изменениями создаётся `/opt/gotelegram/backups/preupgrade_2.5.0_*.tar.gz`;
 - из старого `/etc/telemt/config.toml` вытаскиваются все строки `[access.users]`, а не только `main`;
@@ -504,7 +527,7 @@ Traffic retention: обе CSV-истории хранятся максимум 3
    import os, base64, json, urllib.request, ssl
    TOKEN = os.environ["GOTELEGRAM_PAT"]
    REPO = "anten-ka/gotelegram_pro"
-   BRANCH = "alfa-test"
+   BRANCH = "main"  # или beta/alpha для соответствующей ветки
    API = f"https://api.github.com/repos/{REPO}"
    headers = {
        "Authorization": f"Bearer {TOKEN}",
@@ -623,7 +646,15 @@ with socket.create_connection(("95.163.176.222", 443), timeout=5) as s:
 ## 16. Меню (install.sh)
 
 ```
-── Прокси ──
+Главный экран:
+ 1) submenu_proxy        (установка, статус, ссылка, share, restart, logs, change mode)
+ 2) submenu_stats        (show_traffic_stats, toggle_stats, install_stats_collector)
+ 3) submenu_manage       (backup, restore, update_telemt, website/SSL, remove, language)
+ 4) menu_bot             (install/start/stop/logs/change token/remove bot, installs admin web)
+ 5) submenu_about        (version info, promo)
+ 0) exit
+
+Раздел Proxy:
  1) menu_install         (Lite/Pro выбор, domain, template, certbot)
  2) menu_status          (telemt_status + show_proxy_info)
  3) menu_link            (ссылка + QR)
@@ -632,18 +663,13 @@ with socket.create_connection(("95.163.176.222", 443), timeout=5) as s:
  6) menu_logs            (telemt_logs 40)
  7) menu_change_mode     (lite↔pro, смена шаблона, смена домена маскировки)
 
-── Управление ──
+Раздел Management:
- 8) interactive_backup   (create_backup)
+ 1) interactive_backup   (create_backup)
- 9) interactive_restore  (select_backup + restore_backup)
+ 2) interactive_restore  (select_backup + restore_backup)
-10) update_telemt        (check_telemt_update → download → restart)
+ 3) update_telemt        (check_telemt_update → download → restart)
-11) menu_website         (nginx restart, certbot renew)
+ 4) menu_website         (nginx restart, certbot renew)
-
+ 5) menu_remove          (только прокси / только бот / всё)
-── Бот и прочее ──
+ 6) menu_language        (switch_language ru|en)
-12) menu_bot             (install_bot / start / stop / logs / change_token / remove)
-13) menu_remove          (только прокси / только бот / всё)
-14) menu_promo           (подарочные ссылки — маркетинг)
-
- 0) exit
 ```
 
 Диспатчер в `install.sh` (`bot_action_dispatch`) принимает `--action=` для автоматизации из бота. Полный контракт описан в разделе 11.1.
@@ -652,7 +678,7 @@ with socket.create_connection(("95.163.176.222", 443), timeout=5) as s:
 
 ## 17. Changelog
 
-- **2.5.0 (2026-04-24)** — крупный maintenance pass в ветке `codex`: единая версия `2.5.0` в runtime и документации; удалён дефолтный PAT из `bootstrap.sh` (токен теперь только через `GOTELEGRAM_PAT`); `generate_telemt_toml` добавляет `[server.api]` на `127.0.0.1:9091` и metrics на `127.0.0.1:9090`, что нужно для управления пользователями и статистики; Telegram-бот получил меню `🔑 Keys` для `[access.users]` (добавить/отключить/включить/удалить/показать ссылку/QR/runtime info/IP-limit); добавлена локальная web-админка goTelegram Pro `gotelegram-admin` на `127.0.0.1:1984` с SSH-tunnel инструкцией в боте без отдельного web-admin токена, вкладочной UI-навигацией, иконками, блоком реальных TCP/UDP-слушателей 443, promo-modal раз в 24 часа, i18n от языка установки, ручным переключателем RU/EN, site check на HTTP 200, structured journal logs, light/dark theme, адаптивом, быстрыми switch-переключателями ключей, настройкой `[access.user_max_unique_ips]`, QR-кодами, traffic history 15m/1h/24h/month с переключением график/строки, per-user traffic history из `telemt total_octets` и stats collector restart endpoint; исправлено чтение traffic CSV в боте (header больше не ломает parsing); бот сам делает `stats_collect` перед показом статистики; `iptables` добавлен в optional deps и stats collector пытается установить его; CLI-смена шаблона теперь обновляет `config.json.template_id`, чтобы бот не показывал первый установленный шаблон; backup/restore версии `1.6` сохраняет bot `.env`, bot lang files, disabled user keys, backup schedule, web-admin server/static, custom templates, templates catalog, stats history, user stats history, shared-443 config и полноценную структуру Let's Encrypt (`live/archive/renewal`) для переезда на новый сервер; добавлен безопасный детект 3x-ui/Xray на 443 и управляемый nginx stream shared-443 dispatcher.
+- **2.5.0 (2026-04-24)** — крупный maintenance pass в `main`: единая версия `2.5.0` в runtime и документации; удалён дефолтный PAT из `bootstrap.sh` (токен теперь только через `GOTELEGRAM_PAT`); повторный bootstrap/update автоматически обновляет уже установленный `/opt/gotelegram-bot` и перезапускает `gotelegram-bot`, сохраняя `.env`; `generate_telemt_toml` добавляет `[server.api]` на `127.0.0.1:9091` и metrics на `127.0.0.1:9090`, что нужно для управления пользователями и статистики; Telegram-бот получил меню `🔑 Keys` для `[access.users]` (добавить/отключить/включить/удалить/показать ссылку/QR/runtime info/IP-limit); добавлена локальная web-админка goTelegram Pro `gotelegram-admin` на `127.0.0.1:1984` с SSH-tunnel инструкцией в боте без отдельного web-admin токена, вкладочной UI-навигацией, иконками, блоком реальных TCP/UDP-слушателей 443, promo-modal раз в 24 часа, i18n от языка установки, ручным переключателем RU/EN, site check на HTTP 200, structured journal logs, light/dark theme, адаптивом, быстрыми switch-переключателями ключей, настройкой `[access.user_max_unique_ips]`, QR-кодами, traffic history 15m/1h/24h/month с переключением график/строки, per-user traffic history из `telemt total_octets` и stats collector restart endpoint; исправлено чтение traffic CSV в боте (header больше не ломает parsing); бот сам делает `stats_collect` перед показом статистики; `iptables` добавлен в optional deps и stats collector пытается установить его; CLI-смена шаблона теперь обновляет `config.json.template_id`, чтобы бот не показывал первый установленный шаблон; backup/restore версии `1.6` сохраняет bot `.env`, bot lang files, disabled user keys, backup schedule, web-admin server/static, custom templates, templates catalog, stats history, user stats history, shared-443 config и полноценную структуру Let's Encrypt (`live/archive/renewal`) для переезда на новый сервер; добавлен безопасный детект 3x-ui/Xray на 443 и управляемый nginx stream shared-443 dispatcher.
 - **2.4.6 (2026-04-10)** — universal `apt_lock_wait` helper: ожидание dpkg/apt lock при unattended-upgrades, исправляет установку nginx/certbot/python на свежих VPS.
 - **2.4.3 (2026-04-10)** — iter3-фикс: `bot_action_dispatch` оборачивается во `flock -w 30` на `/var/lock/gotelegram-bot-action.lock`. Обнаружена гонка: параллельные `change-lite-domain` получали `"no secret in config"`, потому что один процесс читал `config.json`, пока другой делал `jq ... > tmp && mv`. `util-linux` (содержит `flock`) добавлен в `critical` deps, `check_deps_present` и маппинги `apt_pkg_for_cmd`/`dnf_pkg_for_cmd`.
 - **2.4.2 (2026-04-10)** — реализация non-interactive `bot_action_*` в install.sh (change-template + change-lite-domain с JSON-ответом). bot.py подключает `run_bot_action()` и делает реальную работу вместо stub'ов. Критфиксы: (a) `safe_edit_message` принимает `disable_web_page_preview` (иначе TypeError в success-пути cb_pro_confirm); (b) чтение/запись `config['template_id']` вместо `config['template']` (save_gotelegram_config всегда писал `template_id`, бот смотрел не туда); (c) `bot_update_config_field` использует shell `date -Iseconds` вместо `jq now|todate` (jq 1.5 совместимость для Debian 10); (d) `asyncio.Lock _BOT_ACTION_LOCK` сериализует callback'и в процессе бота; (e) валидация `_TPL_ID_RE`/`_DOMAIN_RE` до subprocess. Полный аудит и автоустановка зависимостей: `ensure_deps` разделяет critical/optional, дедуплицирует пакеты, re-verify после install; `apt_pkg_for_cmd` и `dnf_pkg_for_cmd` мапят команды на пакеты (dig→dnsutils/bind-utils, xxd→xxd/vim-common, flock→util-linux). `check_deps_present` — быстрый чек без `apt-get update`.
@@ -707,7 +733,7 @@ with socket.create_connection(("95.163.176.222", 443), timeout=5) as s:
 
 ## 20. Контрольные точки и инварианты
 
-Перед любым пушем в `alfa-test`:
+Перед любым пушем в `main`/`beta`/`alpha`:
 1. `bash -n install.sh lib/*.sh` — синтаксис bash ОК.
 2. Все новые `$()`-вызываемые функции пишут UI через `>&2`.
 3. Все пути к lib/ идут через `$SCRIPT_DIR/lib/...`, а `SCRIPT_DIR` — через `readlink -f`.
@@ -717,8 +743,8 @@ with socket.create_connection(("95.163.176.222", 443), timeout=5) as s:
 7. `generate_telemt_toml` не роняет telemt v3 (проверить `telemt run --check config.toml`).
 
 После пуша:
-1. Подождать пока `alfa-test` обновится (GitHub API мгновенно, raw кеш ~30 сек).
+1. Подождать пока нужная ветка обновится (GitHub API мгновенно, raw кеш ~30 сек).
-2. На VPS: `bash bootstrap.sh?token=...&ref=alfa-test` (или ручной `git pull` в клоне) + `sed -i 's/\r$//'` + `chmod +x` + `systemctl restart telemt`.
+2. На VPS: повторить bootstrap из целевой ветки с `GOTELEGRAM_PAT` и при необходимости `GOTELEGRAM_BRANCH=beta|alpha|main`; скрипт сам скачает файлы, обновит установленный бот/админку и покажет меню.
 3. `telemt_status` → running. `journalctl -u telemt` → нет ошибок. Ссылка открывается в Telegram-клиенте.
 
 ---

DOCS_HUMAN.md

@@ -4,6 +4,8 @@
 **Репозиторий:** `anten-ka/gotelegram_pro`
 **Для кого:** владельцы VPS, которым нужен надёжный MTProxy для Telegram с маскировкой под обычный HTTPS-сайт.
 
+Если ты впервые видишь проект: установщик сам скачивает нужные файлы, ставит ядро прокси, создаёт меню `gotelegram`, умеет выпустить SSL-сертификат, поднять сайт-маскировку, Telegram-бота, локальную web-админку и бэкапы. Для обычной работы не нужно вручную редактировать `/etc/telemt/config.toml`.
+
 ---
 
 ## 1. Что это такое
@@ -14,7 +16,16 @@ goTelegram Pro — это готовый менеджер прокси-серв
 2. Запускает рядом обычный HTTPS-сайт на настоящем домене, так что провайдеру со стороны всё выглядит как посещение безобидного лендинга — а на самом деле в том же соединении ходит Telegram-трафик. Это называется «stealth» или «Pro-режим».
 3. Даёт Telegram-бота, через которого можно управлять прокси со смартфона: ссылка, статус, перезапуск, бекап, смена маскировочного домена, выбор шаблона сайта.
 
-Всё управляется одним меню из 14 пунктов (`gotelegram` в терминале) — не нужно лазить по конфигам.
+Всё управляется одним меню `gotelegram` в терминале. Внутри есть 5 понятных разделов: прокси, статистика, управление, Telegram-бот и информация о проекте.
+
+### Простая модель в голове
+
+- **telemt** — само ядро MTProxy, принимает Telegram-клиентов.
+- **nginx** — показывает обычный сайт, когда на домен заходит браузер.
+- **config.json** — память goTelegram Pro: режим, домен, язык, шаблон, настройки.
+- **Telegram-бот** — мобильное управление без SSH.
+- **Web-админка** — красивая локальная панель через SSH-туннель.
+- **Бэкап** — архив с ключами, сайтом, ботом, сертификатами, настройками и статистикой.
 
 ---
 
@@ -23,22 +34,22 @@ goTelegram Pro — это готовый менеджер прокси-серв
 На чистом Ubuntu/Debian VPS под root:
 
 ```bash
-bash <(curl -sL "https://raw.githubusercontent.com/anten-ka/gotelegram_pro/test/bootstrap.sh?token=YOUR_PAT")
+export GOTELEGRAM_PAT="YOUR_PAT"; bash <(curl -sL -H "Authorization: token $GOTELEGRAM_PAT" "https://raw.githubusercontent.com/anten-ka/gotelegram_pro/main/bootstrap.sh")
 ```
 
-Для приватного репозитория безопаснее передавать токен через переменную окружения:
+Если нужно поставить строго зафиксированный релиз или тег, укажи ветку/тег явно:
 
 ```bash
-GOTELEGRAM_PAT=YOUR_PAT bash <(curl -sL "https://raw.githubusercontent.com/anten-ka/gotelegram_pro/test/bootstrap.sh")
+export GOTELEGRAM_PAT="YOUR_PAT" GOTELEGRAM_BRANCH="v2.5.0"; bash <(curl -sL -H "Authorization: token $GOTELEGRAM_PAT" "https://raw.githubusercontent.com/anten-ka/gotelegram_pro/v2.5.0/bootstrap.sh")
 ```
 
 `bootstrap.sh` скачает все файлы из приватного репозитория, создаст симлинк `/usr/local/bin/gotelegram` и запустит главное меню. Через минуту команда `gotelegram` уже будет работать откуда угодно.
 
 Дальше в меню:
 
-- **1) Установить / обновить** — ставит прокси, спрашивает режим (Lite или Pro) и домен маскировки.
+- **1) Прокси → 1) Установить / обновить** — ставит прокси, спрашивает режим Lite/Pro, домен и шаблон.
-- **2) Статус** — показывает, жив ли telemt, IP, порт, маскировку и готовую `tg://proxy?...` ссылку.
+- **1) Прокси → 2) Подробный статус** — показывает, жив ли telemt, IP, порт, режим и домен.
-- **3) Ссылка** — тот же ключ отдельно, вместе с QR-кодом.
+- **1) Прокси → 3) Ссылка** — показывает `tg://proxy?...` и QR-код.
 
 Дальше можно открыть Telegram → Настройки → Данные и память → Прокси → добавить по ссылке. Готово.
 
@@ -71,25 +82,43 @@ GOTELEGRAM_PAT=YOUR_PAT bash <(curl -sL "https://raw.githubusercontent.com/anten
 ## 4. Меню целиком
 
 ```
-── Прокси ──
+Главный экран
- 1) Установить / обновить    — первый раз или апгрейд
+ 1) Прокси
- 2) Статус                    — IP, порт, маскировка, живость
+ 2) Статистика
- 3) Ссылка                    — tg://proxy?... + QR
+ 3) Управление
- 4) Поделиться                — текстовое сообщение «для друзей»
+ 4) Telegram-бот
- 5) Перезапуск                — systemctl restart telemt
+ 5) О программе
- 6) Логи                      — последние 40 строк telemt
+ 0) Выход
- 7) Сменить режим / шаблон    — Lite↔Pro, сменить сайт-шаблон
 
-── Управление ──
+Раздел 1) Прокси
- 8) Бекап                     — tar.gz всех конфигов и ключей
+ 1) Установить / обновить     — первый запуск или повторная установка
- 9) Восстановить              — откат из бекапа
+ 2) Подробный статус          — IP, порт, режим, домен, состояние telemt
-10) Обновить telemt           — скачать свежий бинарник
+ 3) Ссылка                    — tg://proxy?... и QR
-11) Сайт (SSL)                — ручная перегенерация сертификата
+ 4) Поделиться                — готовое сообщение для пользователя
+ 5) Перезапуск                — restart telemt
+ 6) Логи                      — последние строки journalctl -u telemt
+ 7) Сменить режим             — Lite/Pro, домен, шаблон
+ 0) Назад
 
-── Бот и прочее ──
+Раздел 2) Статистика
-12) Telegram-бот              — установить / настроить бота
+ 1) Включить/выключить сбор   — переключает stats_enabled
-13) Удалить всё               — снести прокси / бота / вообще всё
+ 2) Сборщик статистики        — установка/перезапуск gotelegram-stats
-14) Промо                     — подарочные ссылки
+ 0) Назад
+
+Раздел 3) Управление
+ 1) Бэкап                     — создать архив состояния
+ 2) Восстановить              — восстановить из архива
+ 3) Обновить telemt           — обновить только бинарник ядра
+ 4) Сайт / SSL                — операции с сайтом и сертификатом
+ 5) Удалить                   — удалить прокси, бота или всё целиком
+ 6) Язык                      — русский / английский
+ 0) Назад
+
+Раздел 4) Telegram-бот
+  Установка, токен BotFather, admin ID, статус, логи, перезапуск.
+
+Раздел 5) О программе
+  Версия, стек, промо-раздел.
 
  0) Выход
 ```
@@ -98,7 +127,7 @@ GOTELEGRAM_PAT=YOUR_PAT bash <(curl -sL "https://raw.githubusercontent.com/anten
 
 ## 5. Telegram-бот
 
-Пункт меню **12) Telegram-бот** разворачивает отдельный Python-сервис (`python-telegram-bot` v21+), который:
+Раздел **4) Telegram-бот** разворачивает отдельный Python-сервис (`python-telegram-bot` v21+), который:
 
 - Показывает статус прокси, ссылку и QR.
 - Умеет перезапускать telemt прямо из чата.
@@ -110,6 +139,8 @@ GOTELEGRAM_PAT=YOUR_PAT bash <(curl -sL "https://raw.githubusercontent.com/anten
 
 Чтобы запустить бота, нужны только два параметра — токен от `@BotFather` и твой Telegram ID (чтобы никто кроме тебя бота не использовал). Меню подсказывает где что ввести.
 
+При обновлении goTelegram Pro установленный бот обновляется автоматически: новые `bot.py`, `i18n.py`, языковые файлы и `requirements.txt` копируются в `/opt/gotelegram-bot/`, зависимости проверяются, сервис `gotelegram-bot` перезапускается. Файл `/opt/gotelegram-bot/.env` с токеном и администраторами сохраняется.
+
 ---
 
 ## 6. Язык интерфейса
@@ -125,9 +156,9 @@ CLI и бот переведены на русский и английский.
 
 ## 7. Бекап и восстановление
 
-Пункт 8 делает один файл `.tar.gz` со всем, что нужно: `/etc/telemt/config.toml`, `/opt/gotelegram/config.json`, `/opt/gotelegram/disabled_users.json`, данные nginx-сайта, сертификаты Let's Encrypt (`live/archive/renewal`), пользовательские шаблоны, каталог шаблонов, историю трафика, состояние Telegram-бота и локальной web-админки. По умолчанию архивы лежат в `/opt/gotelegram/backups/`.
+Раздел **3) Управление → 1) Бэкап** делает один файл `.tar.gz` со всем, что нужно: `/etc/telemt/config.toml`, `/opt/gotelegram/config.json`, `/opt/gotelegram/disabled_users.json`, данные nginx-сайта, сертификаты Let's Encrypt (`live/archive/renewal`), пользовательские шаблоны, каталог шаблонов, историю трафика, состояние Telegram-бота и локальной web-админки. По умолчанию архивы лежат в `/opt/gotelegram/backups/`.
 
-Пункт 9 принимает такой архив и восстанавливает всё обратно (конфиг, сервис, ссылка — всё то же, что было). Перед восстановлением из админки или Telegram-бота автоматически создаётся свежий safety-бекап текущего состояния.
+Раздел **3) Управление → 2) Восстановить** принимает такой архив и восстанавливает всё обратно (конфиг, сервис, ссылка — всё то же, что было). Перед восстановлением из админки или Telegram-бота автоматически создаётся свежий safety-бекап текущего состояния.
 
 В web-админке и Telegram-боте есть сценарии автобэкапов: выключено, каждый день, каждую неделю или каждый месяц. Это systemd timer `gotelegram-backup.timer`; автоматическая чистка оставляет последние 30 архивов, чтобы каталог не рос бесконечно. Старые простые архивы `backup_*.tar.gz`, которые создавал ранний Telegram-бот только из двух конфигов, тоже распознаются при восстановлении как legacy-формат.
 
@@ -145,6 +176,19 @@ CLI и бот переведены на русский и английский.
 - есть светлая/тёмная тема, вкладки и адаптивная вёрстка под desktop/mobile;
 - Telegram-бот показывает инструкцию для Termius и обычную команду `ssh -L 1984:127.0.0.1:1984 root@SERVER`.
 
+Как открыть через Termius:
+
+1. Открой нужный Host или создай новый.
+2. Укажи `Address` = IP сервера, `Username` = `root`, пароль или ключ SSH.
+3. Открой настройки Host → `Port Forwarding` / `Tunnels`.
+4. Добавь tunnel типа `Local`.
+5. `Local host`: `localhost`.
+6. `Local port`: `1984`.
+7. `Destination host`: `127.0.0.1`.
+8. `Destination port`: `1984`.
+9. Подключись к серверу через этот Host.
+10. Открой в браузере `http://localhost:1984`.
+
 В админке есть dashboard, проверка сайта `https://домен/` на HTTP 200, статус сервисов, полезный блок «кто слушает порт 443» по данным `ss`, управление ключами `[access.users]` с добавлением, удалением и быстрым отключением через switch, лимит одновременных уникальных IP на ключ через `[access.user_max_unique_ips]` (`0` — безлимит), генерация ссылок и QR-кодов для импорта в Telegram, traffic history по периодам 15 минут / 1 час / 24 часа / месяц с переключателем график/строки, такая же статистика по каждому ключу, кнопка разового обновления статистики, кнопка перезапуска сборщика, список/создание/восстановление бекапов, расписание автобэкапов и просмотр логов с количеством строк и статусом `journalctl`.
 
 История трафика хранится максимум 1 год. Чтобы файлы не разрастались, последние 31 день пишутся поминутно, а более старая история автоматически уплотняется до одной точки в час. Для обычного просмотра 15 минут / 1 час / 24 часа / месяц детализация остаётся полной.
@@ -173,7 +217,7 @@ goTelegram Pro не переписывает базу 3x-ui автоматиче
 Два типа обновлений:
 
 - **Обновление ядра telemt** (пункт 10) — тянет свежий бинарник с GitHub Releases `telemt/telemt`, сохраняет старый в `.bak`, перезапускает сервис. Конфиг остаётся как был.
-- **Обновление самого goTelegram Pro** (пункт 1) — переустанавливает скрипты и lib/. Файл `config.json` не трогается, ключ и домен не меняются.
+- **Обновление самого goTelegram Pro** (повторный запуск bootstrap или пункт 1 после скачивания новых файлов) — переустанавливает скрипты и `lib/`, обновляет локальную web-админку и уже установленный Telegram-бот. `config.json`, ключи, домен и `/opt/gotelegram-bot/.env` не трогаются.
 
 Bootstrap.sh умеет сам обновлять всё, если запустить его повторно.
 
@@ -251,13 +295,13 @@ A: Сам MTProxy — да, это публичная технология из
 
 - Баги и пожелания — issues в репозитории `anten-ka/gotelegram_pro`.
 - Владелец: Vitalii (`anten-ka`).
-- Ветки: `test` (заморожена, stable для пользователей), `alfa-test` (активная разработка).
+- Ветки: `main` — основная стабильная установка; `beta` — следующая публичная сборка для проверки; `alpha` — ранние личные эксперименты владельца.
 
 ---
 
 ## Changelog (коротко)
 
-- **2.5.0** — единая версия по коду и документации; удалён дефолтный PAT из `bootstrap.sh`; исправлена статистика в боте (CSV header больше не ломает чтение истории, бот сам обновляет snapshot); CLI-смена шаблона теперь обновляет `config.json.template_id`, поэтому бот показывает текущий шаблон; telemt TOML включает локальный API `127.0.0.1:9091` и metrics на `127.0.0.1:9090`; добавлено меню Telegram-бота для отдельных ключей пользователей (`[access.users]`): список, добавление, отключение/включение, удаление, ссылка, QR-код, текущий runtime, лимит уникальных IP через `[access.user_max_unique_ips]` и история трафика по ключу; добавлена локальная web-админка goTelegram Pro на `127.0.0.1:1984` под SSH tunnel без отдельного токена, с вкладками, иконками, promo-разделом раз в 24 часа, i18n от языка установки, ручным переключателем RU/EN, проверкой сайта на HTTP 200, тёмной темой, адаптивом, быстрыми switch-переключателями ключей, настройкой IP-лимита, QR-кодами, блоком реальных TCP/UDP-слушателей 443, подсказками к техническим терминам, traffic history по периодам 15 минут / 1 час / 24 часа / месяц и per-user traffic history; backup/restore сохраняет bot `.env`, языки бота, отключённые ключи, web-admin server/static, custom templates, stats history, user stats history, shared-443 config и структуру Let's Encrypt для переезда на новый VPS; добавлены ручные/ежедневные/еженедельные/ежемесячные бэкапы, восстановление из админки/бота с safety-бекапом и legacy-restore для старых `backup_*.tar.gz`; добавлен безопасный детект 3x-ui/Xray на 443 и управляемый nginx stream shared-443 dispatcher.
+- **2.5.0** — единая версия по коду и документации; удалён дефолтный PAT из `bootstrap.sh`; исправлена статистика в боте (CSV header больше не ломает чтение истории, бот сам обновляет snapshot); установленный Telegram-бот теперь автоматически обновляется при повторном bootstrap/update без потери `.env`; CLI-смена шаблона теперь обновляет `config.json.template_id`, поэтому бот показывает текущий шаблон; telemt TOML включает локальный API `127.0.0.1:9091` и metrics на `127.0.0.1:9090`; добавлено меню Telegram-бота для отдельных ключей пользователей (`[access.users]`): список, добавление, отключение/включение, удаление, ссылка, QR-код, текущий runtime, лимит уникальных IP через `[access.user_max_unique_ips]` и история трафика по ключу; добавлена локальная web-админка goTelegram Pro на `127.0.0.1:1984` под SSH tunnel без отдельного токена, с вкладками, иконками, promo-разделом раз в 24 часа, i18n от языка установки, ручным переключателем RU/EN, проверкой сайта на HTTP 200, тёмной темой, адаптивом, быстрыми switch-переключателями ключей, настройкой IP-лимита, QR-кодами, блоком реальных TCP/UDP-слушателей 443, подсказками к техническим терминам, traffic history по периодам 15 минут / 1 час / 24 часа / месяц и per-user traffic history; backup/restore сохраняет bot `.env`, языки бота, отключённые ключи, web-admin server/static, custom templates, stats history, user stats history, shared-443 config и структуру Let's Encrypt для переезда на новый VPS; добавлены ручные/ежедневные/еженедельные/ежемесячные бэкапы, восстановление из админки/бота с safety-бекапом и legacy-restore для старых `backup_*.tar.gz`; добавлен безопасный детект 3x-ui/Xray на 443 и управляемый nginx stream shared-443 dispatcher.
 - **2.4.6** — ожидание apt/dpkg lock на свежих Ubuntu/Debian, чтобы установка nginx/certbot/Python не падала во время unattended-upgrades.
 - **2.4.3** — фикс гонки в `bot_action_dispatch`: параллельные вызовы `change-lite-domain`/`change-template` (например, два пользователя бота одновременно) могли получить ошибку «no secret in config», если один процесс читал `config.json` в момент, когда другой его перезаписывал через `jq`. Теперь диспетчер оборачивается в `flock(1)` с таймаутом 30 с; `util-linux` (содержит `flock`) добавлен в критические зависимости.
 - **2.4.2** — смена шаблона и домена маскировки **прямо из Telegram-бота** без SSH. Раньше эти пункты меню показывали сообщение «сделай через CLI», теперь бот вызывает `install.sh --action=change-template --json` / `--action=change-lite-domain --json` и разбирает ответ. Плюс: безопасный `safe_edit_message` принимает `disable_web_page_preview`; поле статуса шаблона наконец-то отображается (раньше читалось не из того ключа JSON); полный аудит и автоустановка системных зависимостей при первом запуске (`curl jq openssl git xxd tar dig flock` + опциональные `qrencode bc`); `asyncio.Lock` в боте сериализует параллельные callback'и; валидация tpl\_id (`[A-Za-z0-9_-]{1,64}`) и домена до subprocess.

README.md

@@ -0,0 +1,80 @@
+# goTelegram Pro
+
+**goTelegram Pro** — установщик и панель управления Telegram MTProxy на базе ядра `telemt`. Проект ставит на VPS прокси, сайт-маскировку, Telegram-бота, локальную web-админку, сбор статистики и бэкапы.
+
+Главная идея: снаружи сервер выглядит как обычный HTTPS-сайт, а Telegram-клиенты используют тот же домен/порт для MTProxy. Управлять можно из SSH-меню, Telegram-бота или локальной web-панели через SSH-туннель.
+
+## Что Входит
+
+- ядро `telemt` с fake-TLS маскировкой;
+- CLI-меню `gotelegram`;
+- Lite-режим без домена и Pro-режим с доменом/сайтом/Let's Encrypt;
+- Telegram-бот для статуса, ссылок, QR, бэкапов, шаблонов, ключей и статистики;
+- локальная web-админка на `127.0.0.1:1984`;
+- глобальная и per-key история трафика;
+- ручные и scheduled бэкапы;
+- shared-443 схема для совместной работы с 3x-ui/Xray.
+
+## Установка
+
+Запускать под `root` на Ubuntu/Debian:
+
+```bash
+export GOTELEGRAM_PAT="YOUR_READ_ONLY_GITHUB_TOKEN"; bash <(curl -sL -H "Authorization: token $GOTELEGRAM_PAT" https://raw.githubusercontent.com/anten-ka/gotelegram_pro/main/bootstrap.sh)
+```
+
+`bootstrap.sh` скачает файлы в `/opt/gotelegram`, создаст `/usr/local/bin/gotelegram` и откроет главное меню.
+
+## Режимы
+
+**Lite** работает сразу без домена. Клиент подключается к `IP:443`, а прокси имитирует TLS под популярный домен вроде `google.com`.
+
+**Pro** требует домен, который указывает на VPS. Telegram-клиенты и обычные браузеры используют один публичный домен на `443`: Telegram-трафик идёт в `telemt`, браузер открывает сайт-маскировку через nginx.
+
+## Web-Админка
+
+Админка слушает только локально на сервере:
+
+```text
+127.0.0.1:1984
+```
+
+Открой через SSH-туннель:
+
+```bash
+ssh -L 1984:127.0.0.1:1984 root@SERVER_IP
+```
+
+Потом в браузере:
+
+```text
+http://127.0.0.1:1984/
+```
+
+Внутри есть dashboard, сервисы, проверка сайта, кто слушает `443`, графики трафика, ключи пользователей, QR, IP-лимиты, бэкапы, логи, переключение языка и светлая/тёмная тема.
+
+## Ветки
+
+- `main` — продакшен и ветка установки по умолчанию.
+- `beta` — публичная бета для следующих сборок и пользовательского тестирования.
+- `alpha` — ранние личные сборки владельца.
+
+Новые изменения сначала идут в `alpha`, потом после проверки в `beta`, и только затем в `main`.
+
+## Документация
+
+- [DOCS_HUMAN.md](DOCS_HUMAN.md) — человеческое руководство с нуля.
+- [DOCS_AI.md](DOCS_AI.md) — подробная техническая карта для ИИ-агентов и разработчиков.
+- [gotelegram-bot/README.md](gotelegram-bot/README.md) — заметки по Telegram-боту.
+
+## Проверки Перед Пушем
+
+Перед пушем:
+
+```bash
+bash -n bootstrap.sh install.sh lib/*.sh
+python3 -m unittest tests.test_admin_features tests.test_bot_features
+PYTHONPYCACHEPREFIX=/tmp/gotelegram-pycache python3 -m py_compile gotelegram-bot/bot.py admin-web/server.py
+node --check admin-web/static/app.js
+git diff --check
+```

bootstrap.sh

@@ -5,7 +5,7 @@
 set -euo pipefail
 
 REPO="anten-ka/gotelegram_pro"
-BRANCH="${GOTELEGRAM_BRANCH:-test}"
+BRANCH="${GOTELEGRAM_BRANCH:-main}"
 PAT="${GOTELEGRAM_PAT:-}"
 INSTALL_DIR="/opt/gotelegram"
 # Use raw.githubusercontent.com (CDN) — faster and avoids Contents API caching

gotelegram-bot/README.md

@@ -31,6 +31,14 @@ Production-quality Telegram bot for managing MTProxy (telemt engine) on Linux se
 
 ## Installation
 
+Recommended installation path is the main CLI menu:
+
+```bash
+gotelegram
+```
+
+Then choose `12) Telegram-bot` → install/update. On repeat goTelegram Pro bootstrap/update, an already installed bot is refreshed automatically: code, i18n files and requirements are copied to `/opt/gotelegram-bot`, `.env` is preserved, dependencies are checked and `gotelegram-bot` is restarted.
+
 ### Prerequisites
 
 - Python 3.8+
@@ -73,11 +81,11 @@ After=network.target
 
 [Service]
 Type=simple
-User=gotelegram
+WorkingDirectory=/opt/gotelegram-bot
-WorkingDirectory=/opt/gotelegram/bot
+ExecStart=/opt/gotelegram-bot/venv/bin/python /opt/gotelegram-bot/bot.py
-ExecStart=/usr/bin/python3 /opt/gotelegram/bot/bot.py
 Restart=always
-RestartSec=10
+RestartSec=5
+Environment=PATH=/opt/gotelegram-bot/venv/bin:/usr/bin
 
 [Install]
 WantedBy=multi-user.target
@@ -89,6 +97,7 @@ WantedBy=multi-user.target
 
 - `BOT_TOKEN` - Telegram bot token (required)
 - `ALLOWED_IDS` - Comma-separated user IDs (optional, all users allowed if empty)
+- `BOT_LANG` - Default language inherited from goTelegram Pro install language
 
 ### System Paths
 

install.sh

@@ -963,6 +963,31 @@ bot_service_status() {
     fi
 }
 
+auto_update_bot_if_possible() {
+    [ -d "$SCRIPT_DIR/gotelegram-bot" ] || return 0
+    [ "$(bot_service_status)" = "not_installed" ] && return 0
+    [ -f "$BOT_DIR/.env" ] || return 0
+
+    local needs_update=0
+    [ -f "$SCRIPT_DIR/gotelegram-bot/bot.py" ] && \
+        ! cmp -s "$SCRIPT_DIR/gotelegram-bot/bot.py" "$BOT_DIR/bot.py" && needs_update=1
+    [ -f "$SCRIPT_DIR/gotelegram-bot/i18n.py" ] && \
+        ! cmp -s "$SCRIPT_DIR/gotelegram-bot/i18n.py" "$BOT_DIR/i18n.py" && needs_update=1
+    [ -f "$SCRIPT_DIR/gotelegram-bot/requirements.txt" ] && \
+        ! cmp -s "$SCRIPT_DIR/gotelegram-bot/requirements.txt" "$BOT_DIR/requirements.txt" && needs_update=1
+
+    local lang_file lang_name
+    for lang_file in "$SCRIPT_DIR"/gotelegram-bot/lang/*.json; do
+        [ -e "$lang_file" ] || continue
+        lang_name=$(basename "$lang_file")
+        ! cmp -s "$lang_file" "$BOT_DIR/lang/$lang_name" && needs_update=1
+    done
+
+    [ "$needs_update" = "1" ] || return 0
+    bot_install >/dev/null 2>&1 || \
+        log_warning "Telegram bot auto-update failed; run menu 12 → Telegram-bot → Install/update"
+}
+
 menu_bot() {
     local st
     st=$(bot_service_status)
@@ -1788,6 +1813,7 @@ main() {
     fi
 
     auto_migrate_legacy_state || true
+    auto_update_bot_if_possible || true
     auto_install_admin_web_if_possible || true
 
     # First-run language picker (before banner so banner appears in chosen lang)

tests/test_bot_features.py

@@ -7,6 +7,7 @@ from pathlib import Path
 ROOT = Path(__file__).resolve().parents[1]
 BOT_PATH = ROOT / "gotelegram-bot" / "bot.py"
 CATALOG_PATH = ROOT / "templates_catalog.json"
+INSTALL_PATH = ROOT / "install.sh"
 
 
 class BotFeatureTests(unittest.TestCase):
@@ -79,6 +80,23 @@ class BotFeatureTests(unittest.TestCase):
         self.assertIn("await get_telemt_version()", body)
         self.assertNotIn('sh("telemt", "--version")', body)
 
+    def test_installer_auto_updates_existing_bot_files(self):
+        source = INSTALL_PATH.read_text(encoding="utf-8")
+        auto_body = re.search(
+            r"auto_update_bot_if_possible\(\).*?(?=\n\n[A-Za-z0-9_]+\(\) |\n\n#)",
+            source,
+            flags=re.S,
+        )
+        self.assertIsNotNone(auto_body)
+
+        auto_text = auto_body.group(0)
+        self.assertIn('bot_service_status', auto_text)
+        self.assertIn('bot_install', auto_text)
+        self.assertIn('cmp -s "$SCRIPT_DIR/gotelegram-bot/bot.py" "$BOT_DIR/bot.py"', auto_text)
+        self.assertIn('cmp -s "$SCRIPT_DIR/gotelegram-bot/i18n.py" "$BOT_DIR/i18n.py"', auto_text)
+        self.assertIn('cmp -s "$SCRIPT_DIR/gotelegram-bot/requirements.txt" "$BOT_DIR/requirements.txt"', auto_text)
+        self.assertIn('auto_migrate_legacy_state || true\n    auto_update_bot_if_possible || true\n    auto_install_admin_web_if_possible || true', source)
+
 
 if __name__ == "__main__":
     unittest.main()