diff --git a/README.md b/README.md
new file mode 100644
index 0000000..b6b9b1b
--- /dev/null
+++ b/README.md
@@ -0,0 +1,68 @@
+# domain_hunt
+
+Скрипт для отслеживания освобождения доменов. Периодически проверяет список доменов через `whois` и присылает отчёт на почту.
+
+## Требования
+
+- Python 3
+- Системная утилита `whois` (в macOS уже установлена: `/usr/bin/whois`)
+
+## Настройка
+
+Отредактируйте `config.json`:
+
+```json
+{
+  "domains": ["example.com", "example.net"],
+  "check_interval_minutes": 60,
+  "smtp": {
+    "host": "smtp.gmail.com",
+    "port": 587,
+    "use_tls": true,
+    "username": "your_account@gmail.com",
+    "password": "app_password_here",
+    "from": "your_account@gmail.com",
+    "to": ["your_account@gmail.com"]
+  }
+}
+```
+
+- `domains` — список доменов для отслеживания.
+- `check_interval_minutes` — как часто проверять (в минутах). Конфиг перечитывается перед каждой проверкой, так что список доменов можно менять без перезапуска скрипта.
+- `smtp.use_tls` — `true` для STARTTLS (обычно порт 587), `false` для SSL (обычно порт 465).
+- `smtp.password` — для Gmail нужен app password, а не обычный пароль аккаунта.
+
+## Запуск
+
+Разовая проверка:
+
+```bash
+python3 domain_check.py --once
+```
+
+Постоянный мониторинг (проверяет и спит `check_interval_minutes`, повторяя бесконечно; останавливается по Ctrl+C):
+
+```bash
+python3 domain_check.py
+```
+
+Свой путь к конфигу:
+
+```bash
+python3 domain_check.py --config /path/to/config.json
+```
+
+## Как определяется статус
+
+Скрипт разбирает ответ `whois`:
+
+- Если в ответе встречаются фразы вроде `no match`, `not found`, `no data found`, `status: available` и т.п. — домен считается **свободен**.
+- Иначе домен считается **занят**, и скрипт пытается найти дату истечения регистрации (`expiry date`, `expiration date`, `registry expiry date`, `paid-till`, `renewal date`) — тогда в письме будет «занят до `<дата>`».
+- Если `whois` не ответил или дату не удалось разобрать, домен помечается как «занят» без даты или «не удалось проверить».
+
+Формат ответов whois различается между регистраторами и TLD, поэтому распознавание — эвристическое и не гарантирует 100% точность для всех зон.
+
+## Письмо
+
+- Тема: `Проверка доменов`, либо `Проверка доменов (есть свободные)`, если хотя бы один домен свободен.
+- Тело: список доменов, для каждого — `свободен`, `занят` или `занят до <дата>`.