diff --git a/README.md b/README.md
new file mode 100644
index 0000000..f48edf5
--- /dev/null
+++ b/README.md
@@ -0,0 +1,77 @@
+# PerfectKachalka
+
+Бот для мини-игры со шкалой навыка (skill-check): синяя полупрозрачная шкала
+с движущимся курсором и двумя цветными зонами. Бот распознаёт шкалу, зону и
+курсор по экрану и нажимает `E` в нужный момент.
+
+## Требования
+
+- Игра запущена в режиме **Exclusive Fullscreen** (не оконный безрамочный) -
+  это нужно для `bettercam`, который умеет захватывать такой режим.
+- Зависимости уже установлены в `.venv` (`opencv-python`, `numpy`,
+  `bettercam`, `pydirectinput`, `keyboard`, `mss`). При необходимости
+  переустановить: `.venv\Scripts\python.exe -m pip install -r requirements.txt`.
+
+## Проверка детекции (опционально, но рекомендуется)
+
+```
+.venv\Scripts\python.exe debug_snapshot.py
+```
+
+- Скрипт ждёт 5 секунд - успейте переключиться в игру так, чтобы шкала
+  мини-игры была видна на экране.
+- После снимка он напечатает найденные координаты шкалы/зоны/курсора и
+  сохранит `debug_snapshot.png` с нарисованными рамками: синяя рамка - шкала,
+  красная - узкая (целевая) зона, пурпурная линия - курсор.
+- Если что-то не нашлось, скрипт сохранит `debug_full.png` (полный кадр без
+  рамок) - по нему можно подправить пороги в `config.py`.
+
+## Запуск бота
+
+```
+.venv\Scripts\python.exe bot.py
+```
+
+- В консоли появится строка `Захват экрана: bettercam` (или `mss`, если
+  bettercam не сработал - тогда эксклюзивный фуллскрин может не
+  захватываться).
+- Переключитесь в игру.
+- **F6** - включить/выключить бота. При включении он один раз сканирует
+  экран на наличие шкалы (повторяет попытку раз в секунду, если шкала пока
+  не видна).
+- **Ctrl+C** в консоли - полностью завершить программу.
+
+## Если игра запущена с правами администратора
+
+`pydirectinput` может не достучаться до окна игры из-за защиты Windows
+(UIPI), если игра имеет более высокие привилегии, чем консоль. В этом случае
+запускайте терминал/`bot.py` от имени администратора.
+
+## Подстройка таймингов
+
+При каждом нажатии E в консоли печатается строка вида:
+
+```
+[Bot] E нажата | cursor_x=... predicted_x=... zone=(...,...) | задержка цикла=... мс
+```
+
+- Если E срабатывает **позже**, чем курсор визуально входит в узкую зону -
+  увеличьте `CURSOR_LEAD_TIME` в `config.py`, шаг ~0.02-0.03.
+- Если E срабатывает **раньше** входа в зону - уменьшите его.
+- Если "задержка цикла" заметно больше ~16 мс - система не успевает за
+  60 FPS, это тоже добавляет задержку.
+- Если в одном проходе курсора через зону E срабатывает несколько раз -
+  потребуется сглаживание скорости курсора (сообщите, чтобы добавить).
+
+Изменения в `config.py` применяются после перезапуска `bot.py`.
+
+## Структура проекта
+
+- `bot.py` - основной цикл: поиск шкалы, отслеживание курсора, нажатие `E`,
+  переключение по F6.
+- `vision.py` - распознавание шкалы/зон/курсора по кадру (OpenCV/HSV).
+- `capture.py` - захват экрана (`bettercam`, с откатом на `mss`).
+- `input_sender.py` - отправка нажатия клавиши (`pydirectinput`).
+- `config.py` - все настраиваемые пороги и параметры.
+- `debug_snapshot.py` - однократный снимок экрана с визуализацией найденных
+  шкалы/зоны/курсора, для отладки.