docs: make English the primary README, add Chinese, keep Russian

Promote English to README.md with a language switcher, add a Simplified
Chinese translation (README.zh-CN.md) and move the Russian version to
README.ru.md. Document the uv project workflow, container usage, the SESSION
variable and the development commands; bump the stated Python floor to 3.11.

Assisted-By: Claude <noreply@anthropic.com>
Signed-off-by: Aleksei Sviridkin <f@lex.la>

Author: lexfrei

.env.example

@@ -5,5 +5,6 @@ API_ID=12345678
 API_HASH=1a2b3c4d5e6f1239983abcdef
 MUTE_TIMEOUT=3600
 SUMMARY_PREFIX="I've put together your %d messages:\n"
-# Session name or path; Telethon stores auth at $SESSION.session
-SESSION=userbot
+# Optional. Session name or path; Telethon stores auth at $SESSION.session.
+# Leave unset to use the default ("userbot"; the container image uses /data/userbot).
+# SESSION=userbot

README.md

@@ -1,55 +1,89 @@
 # Telegram Abridger Userbot
 
-[English version](README_en.md)
+**English** · [中文](README.zh-CN.md) · [Русский](README.ru.md)
 
-## Что делает бот
-
-Юзербот входит в Telegram от имени пользователя и следит за входящими сообщениями во всех чатах, которые не заглушены и не находятся в архиве (чаты с topics игнорируются).
-
-Для каждого отправителя ведётся скользящее окно `COOLDOWN_INTERVAL` секунд:
-
-- Все входящие сообщения автоматически отмечаются прочитанными и накапливаются в буфер
-- Когда окно истекает, буфер склеивается через `MESSAGE_CONCAT_STRING` и отправляется в тот же чат без уведомления (silently); если задан `SUMMARY_PREFIX`, он добавляется в начало (`%d` → число сообщений)
-- Если отправитель превышает `MESSAGE_FREQUENCY_LIMIT` сообщений за окно, он сразу заглушается на `MUTE_TIMEOUT` секунд, а накопленный буфер отправляется досрочно
-- Если за `COOLDOWN_INTERVAL` в том же чате были исходящие сообщения (т.е. пользователь сам отвечал), суммари не отправляется — это нормальный ход разговора
+A self-account (MTProto) userbot that watches incoming messages, buffers them per sender over a sliding window, and—when a sender floods the window—joins the buffered messages into one silent summary and mutes the sender's notifications. If you reply in the chat yourself, the summary is suppressed: the conversation is clearly active.
 
 ## Requirements
 
-- Python 3.10+
-- `telethon`
+- Python 3.11+
+- [uv](https://docs.astral.sh/uv/)
 - Telegram API credentials (`API_ID`, `API_HASH`)
 
-### Получение API_ID и API_HASH
+### Getting API_ID and API_HASH
 
-1. Открыть https://my.telegram.org и войти по номеру телефона
-2. Перейти в **API development tools**
-3. Создать приложение (название и платформа — любые)
-4. Скопировать `App api_id` → `API_ID` и `App api_hash` → `API_HASH`
+1. Go to https://my.telegram.org and sign in with your phone number
+2. Navigate to **API development tools**
+3. Create an application (name and platform can be anything)
+4. Copy `App api_id` → `API_ID` and `App api_hash` → `API_HASH`
 
-### Config (env vars or `.env`)
+### Configuration (environment variables or `.env`)
 
 | Variable | Default | Description |
-|---|---|---|
-| `API_ID` | — | Telegram API ID |
-| `API_HASH` | — | Telegram API Hash |
-| `COOLDOWN_INTERVAL` | `300` | Окно наблюдения в секундах |
-| `MESSAGE_FREQUENCY_LIMIT` | `5` | Макс. сообщений за окно до mute |
-| `MESSAGE_CONCAT_STRING` | `, ` | Разделитель при склейке сообщений |
-| `MUTE_TIMEOUT` | `3600` | Длительность mute в секундах |
-| `SUMMARY_PREFIX` | _(нет)_ | Префикс перед склеенным сообщением; `%d` заменяется числом сообщений (например, `"Собрано %d сообщений:\n"`) |
+| --- | --- | --- |
+| `API_ID` | — | Telegram API ID (required) |
+| `API_HASH` | — | Telegram API hash (required) |
+| `COOLDOWN_INTERVAL` | `300` | Observation window in seconds |
+| `MESSAGE_FREQUENCY_LIMIT` | `5` | Max messages per window before muting |
+| `MESSAGE_CONCAT_STRING` | `, ` | Delimiter used to join buffered messages |
+| `MUTE_TIMEOUT` | `3600` | Mute duration in seconds |
+| `SUMMARY_PREFIX` | _(none)_ | Optional prefix prepended to the summary; `%d` is replaced with the message count (e.g. `"I've put together your %d messages:\n"`) |
+| `SESSION` | `userbot` | Telethon session name or path; auth is stored at `$SESSION.session` |
 
 ## Usage
 
 ```bash
-cp .env.example .env  # заполни API_ID и API_HASH
+cp .env.example .env  # fill in API_ID and API_HASH
 uv run bot.py
 ```
 
-`uv` сам установит зависимости из inline-метаданных скрипта (PEP 723) в изолированное окружение.
+`uv run` resolves and installs the dependencies from `pyproject.toml`/`uv.lock` into an isolated environment automatically — no manual setup is needed.
+
+On first run, Telethon will prompt for your phone number and a confirmation code, then write a `*.session` file. That file holds your authentication secret — keep it private and never commit it.
+
+## Running in a container
+
+The image builds dependencies in a `uv` stage and ships a slim, non-root runtime. The session is persisted on the `/data` volume so authentication survives restarts.
+
+```bash
+# Build
+docker build --tag telegram-abridger --file Containerfile .
+
+# First run: authenticate interactively, persisting the session to a named volume
+docker run --interactive --tty \
+  --env-file .env \
+  --volume abridger-session:/data \
+  telegram-abridger
+
+# Subsequent runs (already authenticated)
+docker run --detach --restart unless-stopped \
+  --env-file .env \
+  --volume abridger-session:/data \
+  telegram-abridger
+```
+
+The image sets `SESSION=/data/userbot`; leave `SESSION` unset in your `.env` so the session lands on the volume.
+
+## How it works
+
+The userbot monitors incoming messages from non-muted, non-archived chats (forum/topics chats are excluded). For each sender it maintains a sliding window of `COOLDOWN_INTERVAL` seconds:
 
-При первом запуске Telethon запросит номер телефона и код подтверждения.
+- Incoming messages are marked as read and added to a per-sender buffer
+- If a sender exceeds `MESSAGE_FREQUENCY_LIMIT` messages within the window, they are muted for `MUTE_TIMEOUT` seconds via Telegram's notification settings and their buffer is flushed immediately
+- Buffered messages are concatenated with `MESSAGE_CONCAT_STRING` and sent silently in the same chat; if `SUMMARY_PREFIX` is set, it is prepended to the summary (`%d` → message count)
+- Buffers are also flushed periodically once a sender's window goes quiet
+- If you sent any message in the same chat within `COOLDOWN_INTERVAL`, the summary is suppressed — the conversation is already active
+
+## Development
+
+```bash
+uv sync          # install runtime + dev dependencies
+uv run pytest    # run the test suite
+uv run ruff check . && uv run ruff format --check .
+uv run mypy bot.py
+```
 
-## Output / Result Files
+## Output / result files
 
-- `userbot.session` — файл сессии Telethon (не коммитить)
-- Логи выводятся в stdout
+- `$SESSION.session` (default `userbot.session`) — Telethon session file (do not commit)
+- Logs go to stdout

README.ru.md

@@ -0,0 +1,89 @@
+# Telegram Abridger Userbot
+
+[English](README.md) · [中文](README.zh-CN.md) · **Русский**
+
+Юзербот (MTProto, от имени аккаунта), который следит за входящими сообщениями, копит их по отправителю в скользящем окне и — когда отправитель заваливает окно — склеивает накопленные сообщения в одно беззвучное саммари и заглушает уведомления от него. Если ты сам ответил в этом чате, саммари не отправляется: разговор очевидно идёт.
+
+## Требования
+
+- Python 3.11+
+- [uv](https://docs.astral.sh/uv/)
+- Учётные данные Telegram API (`API_ID`, `API_HASH`)
+
+### Получение API_ID и API_HASH
+
+1. Открыть https://my.telegram.org и войти по номеру телефона
+2. Перейти в **API development tools**
+3. Создать приложение (название и платформа — любые)
+4. Скопировать `App api_id` → `API_ID` и `App api_hash` → `API_HASH`
+
+### Конфигурация (переменные окружения или `.env`)
+
+| Переменная | По умолчанию | Описание |
+| --- | --- | --- |
+| `API_ID` | — | Telegram API ID (обязательно) |
+| `API_HASH` | — | Telegram API hash (обязательно) |
+| `COOLDOWN_INTERVAL` | `300` | Окно наблюдения в секундах |
+| `MESSAGE_FREQUENCY_LIMIT` | `5` | Максимум сообщений за окно до mute |
+| `MESSAGE_CONCAT_STRING` | `, ` | Разделитель при склейке сообщений |
+| `MUTE_TIMEOUT` | `3600` | Длительность mute в секундах |
+| `SUMMARY_PREFIX` | _(нет)_ | Необязательный префикс перед саммари; `%d` заменяется числом сообщений (например, `"Собрано %d сообщений:\n"`) |
+| `SESSION` | `userbot` | Имя или путь сессии Telethon; авторизация хранится в `$SESSION.session` |
+
+## Запуск
+
+```bash
+cp .env.example .env  # заполни API_ID и API_HASH
+uv run bot.py
+```
+
+`uv run` сам разрешает и устанавливает зависимости из `pyproject.toml`/`uv.lock` в изолированное окружение — ручная настройка не нужна.
+
+При первом запуске Telethon запросит номер телефона и код подтверждения, затем создаст файл `*.session`. Этот файл содержит секрет авторизации — храни его в тайне и никогда не коммить.
+
+## Запуск в контейнере
+
+Образ собирает зависимости в стадии `uv` и поставляется как тонкий non-root рантайм. Сессия хранится на томе `/data`, поэтому авторизация переживает перезапуски.
+
+```bash
+# Сборка
+docker build --tag telegram-abridger --file Containerfile .
+
+# Первый запуск: интерактивная авторизация с сохранением сессии в именованный том
+docker run --interactive --tty \
+  --env-file .env \
+  --volume abridger-session:/data \
+  telegram-abridger
+
+# Последующие запуски (авторизация уже выполнена)
+docker run --detach --restart unless-stopped \
+  --env-file .env \
+  --volume abridger-session:/data \
+  telegram-abridger
+```
+
+Образ задаёт `SESSION=/data/userbot`; не задавай `SESSION` в своём `.env`, чтобы сессия попадала на том.
+
+## Как это работает
+
+Юзербот отслеживает входящие сообщения из не заглушённых и не архивных чатов (чаты с форумами/топиками исключаются). Для каждого отправителя ведётся скользящее окно `COOLDOWN_INTERVAL` секунд:
+
+- Входящие сообщения отмечаются прочитанными и добавляются в буфер по отправителю
+- Если отправитель превышает `MESSAGE_FREQUENCY_LIMIT` сообщений за окно, он заглушается на `MUTE_TIMEOUT` секунд через настройки уведомлений Telegram, а его буфер отправляется досрочно
+- Сообщения буфера склеиваются через `MESSAGE_CONCAT_STRING` и беззвучно отправляются в тот же чат; если задан `SUMMARY_PREFIX`, он добавляется в начало саммари (`%d` → число сообщений)
+- Буферы также периодически сбрасываются, когда окно отправителя затихает
+- Если ты отправил любое сообщение в этом же чате за `COOLDOWN_INTERVAL`, саммари подавляется — разговор уже активен
+
+## Разработка
+
+```bash
+uv sync          # установка runtime- и dev-зависимостей
+uv run pytest    # запуск тестов
+uv run ruff check . && uv run ruff format --check .
+uv run mypy bot.py
+```
+
+## Выходные файлы
+
+- `$SESSION.session` (по умолчанию `userbot.session`) — файл сессии Telethon (не коммитить)
+- Логи выводятся в stdout

README.zh-CN.md

@@ -0,0 +1,89 @@
+# Telegram Abridger Userbot
+
+[English](README.md) · **中文** · [Русский](README.ru.md)
+
+一个以用户账号身份运行的 MTProto userbot：它监听收到的消息，按发送者在滑动时间窗内缓存消息；当某个发送者在窗口内刷屏时，将缓存的消息合并为一条静默的摘要发出，并静音该发送者的通知。如果你自己在该聊天里回复过，则不会发送摘要——对话显然正在进行中。
+
+## 环境要求
+
+- Python 3.11+
+- [uv](https://docs.astral.sh/uv/)
+- Telegram API 凭据（`API_ID`、`API_HASH`）
+
+### 获取 API_ID 和 API_HASH
+
+1. 打开 https://my.telegram.org 并用手机号登录
+2. 进入 **API development tools**
+3. 创建一个应用（名称和平台任意）
+4. 复制 `App api_id` → `API_ID`，`App api_hash` → `API_HASH`
+
+### 配置（环境变量或 `.env`）
+
+| 变量 | 默认值 | 说明 |
+| --- | --- | --- |
+| `API_ID` | — | Telegram API ID（必填） |
+| `API_HASH` | — | Telegram API hash（必填） |
+| `COOLDOWN_INTERVAL` | `300` | 观察窗口，单位秒 |
+| `MESSAGE_FREQUENCY_LIMIT` | `5` | 触发静音前每个窗口允许的最大消息数 |
+| `MESSAGE_CONCAT_STRING` | `, ` | 拼接缓存消息时使用的分隔符 |
+| `MUTE_TIMEOUT` | `3600` | 静音时长，单位秒 |
+| `SUMMARY_PREFIX` | _（无）_ | 可选的摘要前缀；`%d` 会被替换为消息数量（例如 `"I've put together your %d messages:\n"`） |
+| `SESSION` | `userbot` | Telethon 会话名称或路径；认证信息保存在 `$SESSION.session` |
+
+## 使用方法
+
+```bash
+cp .env.example .env  # 填入 API_ID 和 API_HASH
+uv run bot.py
+```
+
+`uv run` 会自动根据 `pyproject.toml`/`uv.lock` 解析并安装依赖到隔离环境中，无需手动配置。
+
+首次运行时，Telethon 会要求输入手机号和验证码，然后写入一个 `*.session` 文件。该文件包含你的认证密钥——请妥善保管，切勿提交到版本库。
+
+## 在容器中运行
+
+镜像在 `uv` 构建阶段安装依赖，并以精简的非 root 运行时发布。会话保存在 `/data` 卷上，因此重启后认证依然有效。
+
+```bash
+# 构建
+docker build --tag telegram-abridger --file Containerfile .
+
+# 首次运行：交互式登录，并将会话持久化到命名卷
+docker run --interactive --tty \
+  --env-file .env \
+  --volume abridger-session:/data \
+  telegram-abridger
+
+# 之后运行（已完成登录）
+docker run --detach --restart unless-stopped \
+  --env-file .env \
+  --volume abridger-session:/data \
+  telegram-abridger
+```
+
+镜像已设置 `SESSION=/data/userbot`；请在 `.env` 中不要设置 `SESSION`，以便会话保存到卷上。
+
+## 工作原理
+
+userbot 监听来自未静音、未归档聊天的收到消息（排除论坛/话题类聊天）。它为每个发送者维护一个 `COOLDOWN_INTERVAL` 秒的滑动窗口：
+
+- 收到的消息会被标记为已读，并加入按发送者区分的缓冲区
+- 如果某个发送者在窗口内超过 `MESSAGE_FREQUENCY_LIMIT` 条消息，则通过 Telegram 的通知设置将其静音 `MUTE_TIMEOUT` 秒，并立即清空其缓冲区
+- 缓存的消息用 `MESSAGE_CONCAT_STRING` 拼接后，在同一聊天里静默发送；若设置了 `SUMMARY_PREFIX`，则将其加在摘要前面（`%d` → 消息数量）
+- 当某个发送者的窗口安静下来后，缓冲区也会被定期清空
+- 如果你在 `COOLDOWN_INTERVAL` 内于同一聊天发送过任何消息，摘要将被抑制——对话正在进行中
+
+## 开发
+
+```bash
+uv sync          # 安装运行时与开发依赖
+uv run pytest    # 运行测试
+uv run ruff check . && uv run ruff format --check .
+uv run mypy bot.py
+```
+
+## 输出 / 结果文件
+
+- `$SESSION.session`（默认 `userbot.session`）—— Telethon 会话文件（不要提交）
+- 日志输出到 stdout