diff --git a/README.md b/README.md
new file mode 100644
index 0000000..f54b896
--- /dev/null
+++ b/README.md
@@ -0,0 +1,98 @@
+# py-export-api-docs
+
+Экспорт Markdown-документации API для пакетов из `requirements.txt`.
+
+Скрипт создаёт временное виртуальное окружение (не трогает системный Python), устанавливает зависимости и генерирует документацию через [pydoc-markdown](https://github.com/NiklasRosenstein/pydoc-markdown) 4.x.
+
+## Требования
+
+- Python 3 с модулем `venv` (на Debian/Ubuntu: `python3-venv`)
+- `pip` внутри создаваемого venv (устанавливается автоматически)
+
+## Использование
+
+Запускайте из каталога, куда нужно положить папку `docs/`:
+
+```bash
+./py-export-api-docs.py requirements.txt
+./py-export-api-docs.py /path/to/requirements.txt --recreate-venv
+./py-export-api-docs.py requirements.txt --strict
+```
+
+Или через интерпретатор:
+
+```bash
+python3 py-export-api-docs.py requirements.txt
+```
+
+### Опции
+
+| Опция | Описание |
+|-------|----------|
+| `requirements` | Путь к файлу `requirements.txt` (обязательный аргумент) |
+| `--venv-dir PATH` | Каталог виртуального окружения. По умолчанию: `/tmp/export-api-docs-<uid>-<hash>`, где `hash` — SHA256 от текущей рабочей директории |
+| `--recreate-venv` | Удалить и пересоздать venv, переустановить пакеты |
+| `--strict` | Завершить с кодом 1, если хотя бы один пакет или модуль не удалось экспортировать |
+
+## Результат
+
+В текущей рабочей директории создаётся:
+
+```
+docs/
+├── README.md          # индекс: таблица модулей и ссылок
+├── <import-module>/
+│   └── api.md         # документация модуля
+└── ...
+```
+
+Для каждого пакета определяются корневые import-модули (из `top_level.txt` в метаданных дистрибутива, из встроенных fallback-таблиц или по эвристике). Каждый модуль экспортируется один раз, даже если несколько пакетов его предоставляют.
+
+## Поддерживаемые строки requirements.txt
+
+**Обрабатываются:**
+
+- PEP 508 спецификации имён пакетов (`requests>=2.28`, `flask[async]`, с маркерами окружения после `;`)
+- Включения `-r other.txt` — только если файл лежит внутри дерева каталога, где находится корневой `requirements.txt`
+
+**Устанавливаются pip'ом, но не экспортируются** (имя пакета не извлекается):
+
+- `-e` (editable installs)
+- Прямые URL и прочие pip-опции, начинающиеся с `-`
+
+## Кэширование venv
+
+Переустановка пакетов пропускается, если:
+
+- venv уже существует;
+- хеш дерева requirements-файлов (все `-r` включения) совпадает с сохранённым в `.requirements.sha256` внутри venv.
+
+При изменении `requirements.txt` или включённых файлов зависимости переустанавливаются автоматически. Флаг `--recreate-venv` принудительно пересоздаёт окружение.
+
+## Коды выхода
+
+| Код | Причина |
+|-----|---------|
+| `0` | Документация экспортирована (в не-strict режиме допускаются предупреждения) |
+| `1` | Файл requirements не найден; нет имён пакетов; ничего не экспортировано; или `--strict` и были ошибки |
+
+## Предупреждения
+
+Скрипт продолжает работу при частичных сбоях (без `--strict`):
+
+- пакет не установился в venv;
+- не удалось определить import-модуль;
+- небезопасное имя модуля;
+- ошибка `pydoc-markdown` при экспорте.
+
+Для пакетов без `top_level.txt` используется guess по имени дистрибутива (`my-package ` → `my_lib`) или встроенные соответствия (`python-gitlab` → `gitlab`, `pyyaml` → `yaml`, `pillow` → `PIL` и др.).
+
+## Пример вывода
+
+```
+Creating virtualenv: /tmp/export-api-docs-1000-a1b2c3d4e5f6
+Installing packages into temporary virtualenv…
+requests -> requests
+  wrote docs/requests/api.md (42 KiB)
+Done. Documentation in /home/user/project/docs
+```