diff --git a/README.md b/README.md
new file mode 100644
index 0000000..7f11f08
--- /dev/null
+++ b/README.md
@@ -0,0 +1,76 @@
+# XM Player
+
+Плагин для Wild Commander (ZX Evolution / TS-Conf), проигрывающий XM, XMZ
+(запакованный gzip'ом XM) и S3M модули через ESP32-сопроцессор платы. Z80
+только передаёт файл на ESP32 и отображает окно со статусом; сам разбор
+модуля и синтез звука выполняет прошивка ESP32.
+
+> ⚠️ **Несовместим со стандартным ftview.** Оригинальный (стандартный)
+> плагин `ftview` сам регистрируется на расширения `.XM` и `.XMZ` — ровно
+> те же, что и у этого плагина. У Wild Commander таблица "расширение →
+> плагин" статическая, зашита в заголовок при сборке, и если файл поставить
+> вместе со стандартным `ftview`, они будут конфликтовать за одни и те же
+> расширения. Используйте переработанную версию `ftview` (расширения `.XM`
+> и `.XMZ` из неё убраны, воспроизведение вынесено в этот плагин) —
+> она лежит отдельным репозиторием: https://git.alexkorochinskiy.ru/alex/ftview.git
+
+## Требования
+
+- ZX Evolution / TS-Conf с прошитым ESP32-сопроцессором
+- Wild Commander (заголовок плагина версии 10+, есть в текущих сборках)
+- переработанная версия `ftview` (см. предупреждение выше), а не стандартная
+
+## Возможности
+
+- Проигрывание `.XM`, `.XMZ`, `.S3M`
+- Окно с живым статусом: имя файла, статус загрузки/воспроизведения,
+  паттерн, строка, BPM, прошедшее/общее время, прогресс-бар
+- Ошибки выводятся прямо в строке статуса (с кодом ошибки ESP32, например
+  `Playback error (0x90)`), без отдельного всплывающего окна
+- Автоматический переход к следующему файлу по окончании трека
+- Параметр `stoponerror` в ini — остановка на ошибке вместо автоперехода,
+  удобно, чтобы найти, какой именно файл в подборке вызывает проблему
+
+## Управление
+
+| Клавиша      | Действие                                    |
+|--------------|----------------------------------------------|
+| PgDn, Enter  | Следующий файл                                |
+| PgUp         | Предыдущий файл                               |
+| Esc          | Остановить воспроизведение и выйти            |
+| Space        | Выйти, не останавливая текущее воспроизведение |
+
+## Установка
+
+Скопировать `xmplay.wmf` в каталог плагинов Wild Commander. Плагин сам
+регистрируется на расширения `.XM`, `.XMZ` и `.S3M`.
+
+Чтобы при ошибке воспроизведения плагин останавливался, а не переходил
+сразу к следующему файлу, добавить в `wc.ini`:
+
+```
+XMPLAY.WMF -stoponerror=1
+```
+
+(`0` или отсутствие параметра — поведение по умолчанию: автопереход при ошибке.)
+
+## Сборка
+
+Нужен [SDCC](http://sdcc.sourceforge.net/) версии 4.6.0 (зафиксирована в
+`build.bat`) и `hex2bin` — оба есть в тулчейне SDK ZX Evolution.
+
+```
+build.bat
+```
+
+Результат — `xmplay.wmf` в корне проекта.
+
+## Благодарности
+
+Собран на основе `wc_api.lib` из `demyanenko-d/VGMPLAY.WMF` — используется
+для доступа к API Wild Commander (окна, вывод текста, клавиатура, ini-параметры).
+
+## Статус
+
+Проверено на реальном железе: воспроизведение, живая статистика,
+прогресс-бар, обработка ошибок и управление с клавиатуры.