diff --git a/README.md b/README.md
index 5d89d91..3f1e2da 100644
--- a/README.md
+++ b/README.md
@@ -1 +1,45 @@
-Telegram bot to play secret santa.
+# SaintBotTg — Telegram‑бот для тайного Санты
+
+Бот на aiogram, который помогает собрать участников, обменять пожеланиями к подаркам и провести Тайного санту.
+
+## Возможности
+- создание комнат с ограничением по количеству, приглашение по коду `roomName:1234`;
+- редактирование настроек комнаты: бюджет, дата/время мероприятия, тип обмена;
+- участие как админа или гостя, удаление участников и закрытие комнаты;
+- запись пожеланий с текстом и фото, дублирование фото в резервный чат;
+- запуск розыгрыша и рассылка пар «кому даришь» всем участникам;
+
+## Требования
+- Python 3.11+ (Dockerfile использует 3.13);
+- зависимости из `requirements.txt`.
+
+## Настройка окружения
+Создайте файл `.env` в корне проекта:
+```
+BOT_TOKEN="<токен вашего Telegram-бота от @BotFather>"
+CHAT_ID="<ID технического чата/канала, куда бот дублирует фото желаний туда надо добавить бота с доступом к записи>"
+```
+- `BOT_TOKEN` — обязательный токен бота.
+- `CHAT_ID` — необязательный, но полезный ID чата/канала, куда бот отправляет копии фото из желаний, чтобы они не пропали из-за ограничений Telegram. Получить можно командой `/ID`, переслав боту сообщение из нужного чата/канала.
+
+Не храните `.env` в репозитории.
+
+## Запуск локально
+```bash
+python -m venv .venv
+source .venv/bin/activate  # Windows: .venv\Scripts\activate
+pip install -r requirements.txt
+python main.py
+```
+SQLite-база создаётся автоматически в `src/db/database.db`.
+
+## Запуск в Docker
+```bash
+docker build -t saint-bot .
+docker run --rm -it -e BOT_TOKEN=XXX -e CHAT_ID=YYY saint-bot
+```
+
+## Тесты
+```bash
+pytest
+```