feat(bot): show actual response on failure, flap threshold, pause/rename/baseline, komodo fleet control and alert intake

README.md

@@ -1,3 +1,89 @@
 # healthbot
 
 [![AI Slop Inside](https://sladge.net/badge.svg)](https://sladge.net)
+
+Телеграм-бот, который следит за твоими сервисами и пишет в личку, когда
+что-то легло. Опционально умеет управлять флотом [Komodo](https://komo.do)
+и принимать его алерты.
+
+## Что умеет
+
+**Следит.** Присылаешь ссылку — бот запрашивает её и предлагает выбрать, за
+чем следить: HTTP-статус, тело целиком или конкретное поле JSON (по дереву
+ответа кликаешь мышкой, путь соберётся сам).
+
+**Объясняет.** Когда правило нарушено, в сообщении видно не только «json
+изменился», но и что ожидали, что пришло сейчас и сам ответ. Для режима
+«тело целиком» показывается diff — только изменившиеся строки, а не
+простыня на сотню.
+
+**Не будит зря.** Падение объявляется после `MONITOR__FAILURE_THRESHOLD`
+неудач подряд (по умолчанию 2). Одиночный провал — это почти всегда
+моргнувшая сеть, а не упавший сервис.
+
+**Считает** аптайм, инциденты, суммарный даунтайм и время отклика.
+
+**Кнопки в карточке:** проверить сейчас (покажет текущий ответ), поставить
+на паузу на время работ, переименовать, принять текущий ответ за новый
+эталон — если сервис изменился намеренно, не надо пересоздавать его и
+терять статистику.
+
+Админов может быть несколько: `ADMIN_IDS=[111,222]`.
+
+## Komodo
+
+Обе интеграции необязательные: без них бот работает как обычная звонилка.
+
+### Управление флотом
+
+```env
+KOMODO__URL=https://komodo.example.com
+KOMODO__KEY=...
+KOMODO__SECRET=...
+```
+
+Появляется `/fleet`: сервера с числом живых стеков, список стеков,
+карточка стека с кнопками **Deploy / Restart / Stop** и хвостом логов.
+Каждое действие спрашивает подтверждение — деплой прода с телефона
+слишком легко нажать случайно.
+
+Ключ создаётся в Komodo: *Settings → API Keys*. Права наследуются от
+пользователя, которым ключ создан, поэтому под бота стоит завести
+отдельного пользователя и выдать ему ровно то, чем он должен управлять.
+
+### Приём алертов
+
+```env
+WEB__ENABLED=true
+WEB__PORT=8080
+WEB__TOKEN=<любая длинная строка>
+```
+
+Бот поднимает HTTP-приёмник. В Komodo заводится Alerter с endpoint type
+**Custom** и URL:
+
+```
+http://healthbot:8080/komodo/alert?token=<WEB__TOKEN>
+```
+
+Токен принимается и заголовком `X-Alert-Token`, и query-параметром —
+второе потому, что Komodo произвольные заголовки к вебхуку не добавляет.
+
+**Порт лучше не публиковать.** Если Komodo и бот стоят в одной docker-сети,
+адрес выше резолвится внутри неё и наружу не выходит совсем. Для этого в
+`docker-compose.override.yml` пропиши сеть и алиас — пример лежит в
+`docker-compose.override.yml.example`.
+
+Алерты форматируются по-человечески: недоступный сервер, CPU/память/диск,
+смена состояния стека, расхождение git и Komodo, упавшие процедуры и
+сборки. Незнакомый тип не проглатывается, а показывается как есть.
+
+## Запуск
+
+```sh
+cp .env.example .env   # заполнить ADMIN_ID и BOT__TOKEN
+make up
+make logs
+```
+
+`make rebuild` — пересобрать образ, `make down` — остановить.