diff --git a/README.md b/README.md
new file mode 100644
index 0000000..8c87e78
--- /dev/null
+++ b/README.md
@@ -0,0 +1,82 @@
+# max2telegram
+
+Мост для пересылки сообщений из Max в Telegram.
+
+## Что умеет
+
+- Слушает входящие сообщения в Max через `PyMax`.
+- Пересылает в Telegram:
+  - текст;
+  - фото;
+  - видео.
+- Для нескольких вложений отправляет единым альбомом (`sendMediaGroup`).
+- В тексте указывает источник в формате: `MAX: <ник> / <название чата>`.
+- Защищает от дублей через SQLite (`forwarded_messages`).
+
+## Логика выбора чата в Telegram
+
+1. Берется название чата из Max.
+2. Если у бота найден Telegram-чат с таким же названием, сообщение отправляется туда.
+3. Если совпадения нет, сообщение уходит в личку на `TELEGRAM_FALLBACK_USER_ID`.
+
+## Важно про поиск чатов
+
+Поиск чатов выполняется через `getUpdates`, поэтому:
+
+- бот должен быть добавлен в нужные Telegram-чаты;
+- в этих чатах должен быть хотя бы один апдейт (сообщение/событие), чтобы чат появился в апдейтах.
+
+## Переменные окружения
+
+Используется файл `.env` в корне проекта.
+
+Пример смотри в `.env.sample`.
+
+Обязательные переменные:
+
+- `MAX_PHONE` - номер телефона аккаунта Max;
+- `MAX_WORK_DIR` - директория сессии Max (обычно `cache`);
+- `TELEGRAM_BOT_TOKEN` - токен Telegram-бота;
+- `TELEGRAM_FALLBACK_USER_ID` - id пользователя Telegram для fallback отправки;
+- `SQLITE_PATH` - путь к SQLite базе (например `max2telegram.db`).
+
+Дополнительно:
+
+- `TZ` - таймзона контейнера;
+- `PYTHONUNBUFFERED` - режим буферизации вывода Python.
+
+## Быстрый старт (Docker)
+
+1. Скопировать шаблон:
+   - `copy .env.sample .env` (Windows)
+2. Заполнить `.env` своими значениями.
+3. Запустить:
+   - `docker compose up -d --build`
+4. Логи:
+   - `docker compose logs -f`
+
+## Запуск локально (без Docker)
+
+1. Установить зависимости:
+   - `pip install -r src/requirements.txt`
+2. Создать `.env` на основе `.env.sample`.
+3. Запустить приложение:
+   - `python src/main.py`
+
+## Структура проекта
+
+- `src/main.py` - точка входа, инициализация клиентов.
+- `src/bridge.py` - основная логика маршрутизации и отправки.
+- `src/telegram_api.py` - Telegram Bot API клиент.
+- `src/max_parser.py` - разбор входящих сообщений Max.
+- `src/storage.py` - SQLite слой для дедупликации.
+- `src/config.py` - загрузка конфигурации из окружения.
+
+## Типичные проблемы
+
+- Фото/видео не приходят:
+  - проверь, что бот имеет доступ к целевому чату;
+  - проверь валидность URL вложений и токена бота.
+- Сообщения идут только в fallback:
+  - бот еще не видел апдейты из нужного чата;
+  - название чата в Max и Telegram не совпадает.