diff --git a/AGENT.md b/AGENT.md
index adb6e91..4937006 100644
--- a/AGENT.md
+++ b/AGENT.md
@@ -112,3 +112,11 @@ docker exec lampac sh -c '...'  # осмотр состояния в конте
 ### 10. Безопасность (не публиковать)
 
 `config/passwd`, cookie `accspasswd`, заголовок `lcrqpasswd`, `bot_token` в `TelegramBot`. Маршруты `/adminpanel`, `/weblog`, `Tracks`, `Catalog`, `DLNA`, proxy-модули — только для доверенной сети без WAF не открывать.
+
+### 11. Tg-notify.bot (Telegram-бот)
+
+- Механика: long polling по `TelegramBot.bot_token`; если токен пуст — polling не стартует (в логе `[TelegramBot] Установите bot_token…`, сервер работает). После правки секции: `docker compose restart lampac`.
+- Три подсистемы: трекер серий (Trakt→TMDB), трекер озвучек (параллельно Mirage/Collaps/VideoHub через `lampac_host`: `/lite/mirage`, `/lite/collaps`, `/lite/cdnvideohub`), клиентский плагин `tg-notify.js` (вкладка «TG Подписки», перехват 🔔). Полный разбор — в README.md.
+- Данные подписок: `database/tgnotify/{users.json,subscriptions.json}` (том `./database/`, в .gitignore). Не «чинить» вручную — это живые данные бота.
+- Диагностика: `GET /tg-notify.js` (200 без авторизации), `GET /api/tg/voices` (200), `/api/tg/*` остальной — требует `user_uid`. Озвучки могут не работать, если балансеры недоступны (проверить `GET /lite/mirage` — тело `disable`/ошибка, `/lite/collaps` — 503); тогда уведомления приходят только о выходе серий.
+- `kp_api_key` опционален: без него VideoHub резолвит `kinopoisk_id` только через мост `/externalids` (покрытие ~40%), иначе — молча пропускается, Mirage/Collaps работают.
diff --git a/README.md b/README.md
index 98e3344..25cfafa 100644
--- a/README.md
+++ b/README.md
@@ -113,21 +113,83 @@ rm -rf cache/static/59   # bucket /extensions; либо rm -rf cache/static
 
 Перезапуск контейнера при этом **не требуется** (маршрут читает файл при каждом запросе, если нет кеш-записи).
 
-## Tg-notify.bot: настройка бота
+## Tg-notify.bot: Telegram-бот уведомлений о новых сериях
 
-Секция `TelegramBot` в `config/init.conf`:
+Фоновый Telegram-бот (long polling): пользователь подписывается на сериал прямо из карточки Lampa, бот отслеживает выход новых эпизодов и появление выбранной озвучки и шлёт в Telegram уведомление с обложкой, номером серии и описанием из TMDB.
+
+Модуль объединяет три подсистемы:
+1. **Трекер новых серий** — Trakt API (если задан `trakt_client_id`), иначе TMDB.
+2. **Трекер озвучек** — параллельный опрос встроенных балансиров **Mirage**, **Collaps** и **VideoHub** через `lampac_host` (`/lite/mirage`, `/lite/collaps`, `/lite/cdnvideohub`); берётся максимальный эпизод из всех источников.
+3. **Клиентский плагин** `tg-notify.js` — вкладка «TG Подписки», перехват кнопки 🔔 в карточке, меню выбора озвучки.
+
+### Как это работает (поток)
+
+1. **Привязка аккаунта** — во вкладке «TG Подписки» в Lampa выдаётся deep-link `/start link_{uid}` (для UID вида email — `/start link64_{base64url(uid)}`). После `/start` бот сохраняет связку `chat_id ↔ lampac_uid` в `database/tgnotify/users.json`; подписки становятся общими для всех устройств этого аккаунта.
+2. **Подписка** — в карточке сериала кнопка 🔔 перехватывается плагином, показывается меню озвучек (`GET /api/tg/voices`), выбор уходит на `POST /api/tg/subscribe` и сохраняется в `subscriptions.json`.
+3. **Фоновый цикл `CheckAll`** — раз в `check_interval_minutes` (первый прогон — через 2 минуты после старта, вручную — `/check`): новые серии через Trakt→TMDB; если выбрана конкретная озвучка — параллельно Mirage + Collaps + VideoHub.
+4. **Уведомление** — сообщение вида:
+
+   ```
+   🎬 Название
+   🎙 Озвучка
+   📺 S05E08 — Название эпизода
+
+   Описание (до 300 символов)
+   ```
+
+   с обложкой кадра из TMDB (`still_path`), если есть.
+
+### Конфигурация (секция `TelegramBot` в `config/init.conf`)
 
 | Поле | Назначение |
 |---|---|
-| `bot_token` | Токен от [@BotFather](https://t.me/BotFather). **Обязателен** — без него long polling не стартует (в логе будет предупреждение, сервер продолжит работать) |
-| `tmdb_api_key` | Ключ TMDB v3 для обложек и описаний эпизодов |
-| `trakt_client_id` | Client ID Trakt (основной источник новых серий; если пуст — только TMDB) |
-| `lampac_host` | Базовый URL Lampac, по умолчанию `http://127.0.0.1:9118` |
-| `lampac_token` | Токен `accsdb`, нужен если включена защита |
-| `check_interval_minutes` | Период фоновой проверки (дефолт 60, первый прогон через 2 минуты) |
-| `data_dir` | Каталог подписок, дефолт `database/tgnotify` |
+| `bot_token` | Токен от [@BotFather](https://t.me/BotFather). **Обязателен** — без него long polling не стартует (в логе предупреждение, сервер работает) |
+| `tmdb_api_key` | Ключ TMDB v3: обложки, описания эпизодов, определение актуального сезона |
+| `trakt_client_id` | Client ID Trakt; основной источник новых серий (если пуст — только TMDB) |
+| `lampac_host` | Базовый URL Lampac для запросов к балансерам; в Docker — `http://127.0.0.1:9118` |
+| `lampac_token` | Токен `accsdb`; обязателен, если включена защита (иначе балансеры вернут ошибку входа) |
+| `kp_api_key` | Ключ kinopoiskapiunofficial.tech — резолвинг `tmdb_id → kinopoisk_id` по названию для VideoHub (опционально; без него покрытие ~40% через мост `/externalids`) |
+| `check_interval_minutes` | Период фоновой проверки (дефолт 60) |
+| `tmdb_lang` | Язык метаданных TMDB (дефолт `ru-RU`, фоллбэк `en-US`) |
+| `data_dir` | Каталог `users.json`/`subscriptions.json` (дефолт `database/tgnotify` — у нас это том `./database/`, переживает рестарты) |
 
-Привязка аккаунта: в Lampa во вкладке «TG Подписки» — deep-link `/start link_{uid}`. Команды бота: `/start`, `/list`, `/check`, `/help`, `/unlink`.
+### Быстрый старт
+
+1. [@BotFather](https://t.me/BotFather) → `/newbot` → получить токен.
+2. `config/init.conf` → `TelegramBot.bot_token` = токен.
+3. `docker compose restart lampac` (по желанию — заполнить `tmdb_api_key` и `trakt_client_id`).
+4. В Lampa (http://localhost:9118) вкладка «TG Подписки» → deep-link → `/start` у бота.
+5. В карточке сериала — 🔔, выбрать озвучку (или «без озвучки» — уведомление о самом факте выхода серии).
+
+### Команды бота
+
+| Команда | Действие |
+|---|---|
+| `/start` | Приветствие; `/start link_{uid}` — привязка аккаунта |
+| `/list` | Список активных подписок |
+| `/check` | Принудительная проверка в фоне |
+| `/help` | Справка |
+| `/unlink` | Отвязать аккаунт |
+
+### HTTP API
+
+| Метод | Маршрут | Назначение |
+|---|---|---|
+| `GET` | `/tg-notify.js` | Раздача клиентского плагина (AllowAnonymous) |
+| `POST` | `/api/tg/subscribe` | Подписка на сериал/озвучку |
+| `POST` | `/api/tg/unsubscribe` | Отписка |
+| `GET` | `/api/tg/status?tmdb_id=` | Статус подписки текущего пользователя |
+| `GET` | `/api/tg/voices?title=&year=&season=&tmdb_id=` | Доступные озвучки (Mirage + Collaps + VideoHub) |
+| `GET` | `/api/tg/link` | Deep-link для привязки бота |
+| `GET` | `/api/tg/subscriptions` | Все подписки пользователя с метаданными |
+
+Все маршруты, кроме `/tg-notify.js` и `/api/tg/voices`, требуют `requestInfo.user_uid` (вход в аккаунт).
+
+### Состояние на нашем инстансе
+
+- Модуль загружен, `/tg-notify.js` → 200, плагин уже в `LampaWeb.customPlugins`, вкладка «TG Подписки» видна.
+- `bot_token` **пуст** → long polling не работает (лог: `[TelegramBot] Установите bot_token…`); уведомления придут только после заполнения токена.
+- Трекинг озвучек зависит от балансиров: на текущий момент `GET /lite/mirage` → тело `disable`, `GET /lite/collaps` → `503` — до тех пор, пока они не будут доступны (или не включится `lampac_token` при защите), бот будет уведомлять только о выходе серий (TMDB/Trakt).
 
 ## Обновление Lampac