diff --git a/README.md b/README.md
new file mode 100644
index 0000000..d0b47cf
--- /dev/null
+++ b/README.md
@@ -0,0 +1,53 @@
+# Wallenc
+
+Android-приложение для **защищённого хранения** файлов и секретов: шифрование выполняется на устройстве до выгрузки во внешнее хранилище. Собственного backend нет — клиент и API провайдеров (Яндекс.Диск и др.).
+
+## Задача
+
+Иерархия **VaultsManager → vault → storage → файлы**:
+
+| Уровень | Смысл |
+|---------|--------|
+| Локальный vault | Один на устройстве, список storage |
+| Удалённый vault | Подключение по OAuth (Яндекс) |
+| Storage | Папка/контейнер с файлами, метаданные в Room |
+| Шифрование | AES на storage; ключ не передаётся провайдеру |
+| Sync | Журнал изменений, группы storage, фоновые задачи |
+| Секреты / 2FA | Текстовые записи и TOTP внутри открытого storage |
+
+Провайдер хранилища и сеть считаются недоверенными. Room хранит только служебные данные (метаданные, токены, журнал sync), не пользовательский контент в открытом виде.
+
+## Модули
+
+```
+app/                    — точка входа, Hilt, навигация
+domain/                 — интерфейсы и доменные модели
+usecases/               — сценарии (шифрование, sync, CRUD storage)
+domain-vault/           — storage, Яндекс.Диск, Encryptor
+ui/                     — Jetpack Compose
+infrastructure-android/ — Room, DAO, платформенные реализации
+vault-contracts/        — контракты для новых провайдеров
+task-runtime/           — очередь длительных операций
+```
+
+**Архитектура:** MVVM + Clean Architecture (`ui` → `usecases` / `domain` → `domain-vault` / `infrastructure-android`).
+
+## Стек
+
+Kotlin · Jetpack Compose · Coroutines / Flow · Hilt · Room · WorkManager · клиентское AES
+
+## Сборка и тесты
+
+```bash
+./gradlew assembleDebug
+./gradlew test
+./gradlew connectedDebugAndroidTest   # устройство или эмулятор
+```
+
+JDK 21 рекомендуется (см. toolchain в Gradle).
+
+## Требования
+
+- Android с поддержкой Compose  
+- Для OAuth и удалённых vault — сеть  
+- Для фонового шифрования и sync — достаточно RAM под Worker и Room