diff --git a/README.md b/README.md
new file mode 100644
index 0000000..4752dc4
--- /dev/null
+++ b/README.md
@@ -0,0 +1,145 @@
+## PepperBot — Telegram‑бот для отслеживания скидок с Pepper.ru
+
+PepperBot периодически опрашивает Pepper.ru, ищет новые скидки и отправляет их в Telegram:
+- в **общий чат**, указанный в `TELEGRAM_CHAT_ID`;
+- в **личные подписки пользователей** по ключевым словам.
+
+Бот умеет управлять подписками прямо из Telegram через меню и кнопки.
+
+### Возможности
+
+- **Отправка новых скидок в Telegram**
+  - Формирование читаемого сообщения по скидке (цена, старая цена, процент скидки, магазин, ссылка).
+  - Отправка в общий канал/группу (`TELEGRAM_CHAT_ID`).
+- **Персональные подписки по ключевым словам**
+  - Для каждой скидки ищутся совпадения по названию и магазину.
+  - Если совпало с ключевым словом подписки — скидка уходит в соответствующий чат.
+- **Управление подписками через меню в Telegram**
+  - Команда `/menu` открывает меню с кнопками:
+    - `Добавить подписку`
+    - `Удалить подписку`
+    - `Список подписок`
+  - Добавление подписок по кейвордам.
+  - Удаление через inline‑кнопки.
+  - Просмотр всех активных подписок.
+- **Health‑endpoint**
+  - `GET /health` — используется для проверки работоспособности (например, оркестратором).
+
+### Архитектура (вкратце)
+
+- `PepperBot` — единственный проект (консольное ASP.NET Core приложение).
+- **Слои:**
+  - `Application` — интерфейсы и доменные сервисы (`DealService`, `ISubscriptionRepository`, `ITelegramNotifier` и т.п.).
+  - `Domain` — простые модели (`Deal`, `Subscription` и др.).
+  - `Infrastructure`
+    - `Data` — хранение в SQLite (`SqliteDealRepository`, `SqliteSubscriptionRepository`, файл БД `data/pepper_bot.db`).
+    - `Pepper` — клиент Pepper (`IPepperClient` / `PepperClient`).
+    - `Telegram` — вся работа с Telegram через библиотеку `Telegram.Bot` (`TelegramNotifier`).
+  - `Presentation`
+    - `BotWorker` — фоновой воркер, который:
+      - инициализирует репозитории;
+      - запускает работу `TelegramNotifier` (приём сообщений);
+      - каждые 30 секунд опрашивает Pepper и рассылает новые скидки.
+
+### Зависимости
+
+- .NET `10.0` (Target Framework: `net10.0`).
+- ASP.NET Core (через `Microsoft.AspNetCore.App`).
+- `Microsoft.Data.Sqlite` — для локальной БД.
+- `Telegram.Bot` — работа с Telegram Bot API.
+
+### Переменные окружения
+
+- **`TELEGRAM_BOT_TOKEN`** — токен Telegram‑бота.
+- **`TELEGRAM_CHAT_ID`** — ID чата/канала/группы для общей рассылки (можно оставить пустым, если общий канал не нужен).
+- **`ASPNETCORE_URLS`** — адрес, на котором слушается HTTP (по умолчанию в `docker-compose.yml` `http://0.0.0.0:8080`).
+
+### Запуск локально (без Docker)
+
+1. Установите .NET SDK 10.0.
+2. В корне репозитория задайте переменные окружения (пример для PowerShell):
+
+```powershell
+$env:TELEGRAM_BOT_TOKEN = "ваш_токен_бота"
+$env:TELEGRAM_CHAT_ID = "ид_чата_для_общей_рассылки" # можно не задавать
+```
+
+3. Запустите приложение:
+
+```powershell
+cd PepperBot
+dotnet run
+```
+
+Приложение поднимет HTTP‑сервер (endpoint `/health`) и запустит фонового воркера с Telegram‑ботом.
+
+### Запуск через Docker
+
+В корне репозитория уже есть `Dockerfile` и `docker-compose.yml`.
+
+#### Быстрый старт
+
+1. Задайте переменные окружения в системе или в `.env` рядом с `docker-compose.yml`:
+
+```env
+TELEGRAM_BOT_TOKEN=ваш_токен_бота
+TELEGRAM_CHAT_ID=ид_чата_для_общей_рассылки
+```
+
+2. Запустите контейнер:
+
+```bash
+docker compose up -d --build
+```
+
+Что делает `docker-compose.yml`:
+- собирает образ по `Dockerfile`;
+- пробрасывает переменные окружения внутрь контейнера;
+- монтирует `./data` на `/app/data` (там хранится SQLite‑база);
+- прокидывает порт `9001` на `8080` контейнера (health‑endpoint будет доступен по `http://localhost:9001/health`).
+
+### Как пользоваться ботом в Telegram
+
+1. Создайте бота через `@BotFather` и пропишите его токен в `TELEGRAM_BOT_TOKEN`.
+2. Запустите приложение (локально или в Docker).
+3. Откройте диалог с ботом в Telegram.
+
+#### Меню управления подписками
+
+- Отправьте `/menu` — появится клавиатура:
+  - **Добавить подписку**
+    - Бот попросит отправить одно или несколько ключевых слов.
+    - Пример: `PLA ABS`, или `PLA, ABS, PETG`.
+    - Каждое слово станет отдельной подпиской.
+  - **Список подписок**
+    - Бот выведет все активные подписки в формате `[Id] keyword`.
+  - **Удалить подписку**
+    - Бот покажет inline‑кнопки по существующим подпискам.
+    - Нажмите на кнопку с нужным ключом — подписка будет деактивирована.
+
+#### Как приходят уведомления
+
+- Раз в 30 секунд бот опрашивает Pepper.ru.
+- Для каждой новой скидки:
+  - отправляет сообщение в общий чат (`TELEGRAM_CHAT_ID`), если задан;
+  - подбирает все подписки, у которых ключ входит в `Title` или `StoreName` скидки (без учёта регистра);
+  - отправляет сообщение в соответствующие личные/групповые чаты.
+
+### Полезное для разработки
+
+- Сборка:
+
+```bash
+cd PepperBot
+dotnet build
+```
+
+- Запуск:
+
+```bash
+cd PepperBot
+dotnet run
+```
+
+- БД `data/pepper_bot.db` создаётся автоматически при первом запуске.
+