added AGENTS.md and docs in root dir

README.md

@@ -1,13 +1,85 @@
 # Balance — все платформы
 
-В архиве находятся нативные приложения личных финансов и общий self-hosted сервер синхронизации.
+Balance — приложение для учёта личных финансов с нативными клиентами
+для iOS, macOS, watchOS, Android и встроенным web-интерфейсом, а также
+self-hosted сервер синхронизации на Go. В архиве находится
+монорепозиторий из трёх независимо собираемых проектов.
 
-| Папка | Назначение |
+| Папка | Назначение | Стек |
+| --- | --- | --- |
+| [`Balance/`](Balance/README.md) | iOS 17+, macOS 14+ и watchOS 10+ | SwiftUI + SwiftData |
+| [`BalanceAndroid/`](BalanceAndroid/README.md) | Android 8.0+ | Kotlin + Jetpack Compose + Room |
+| [`BalanceServer/`](BalanceServer/README.md) | Go-сервер авторизации, синхронизации и встроенный web-клиент | Go + SQLite |
+
+Все пять клиентов — iOS, macOS, watchOS, Android и web — используют
+одну модель данных и один протокол сервера: операции, пользовательские
+категории, бюджеты, удаления, регистрация, вход, refresh-токены и
+постраничная двусторонняя синхронизация. Web-интерфейс открывается по
+адресу запущенного сервера и не требует отдельной установки.
+
+## Быстрый старт
+
+1. **Поднять сервер** — см. [`BalanceServer/README.md`](BalanceServer/README.md#quick-start-with-docker)
+   (Docker или локальная сборка Go-бинарника).
+2. **Открыть Apple-проект** — `open Balance/Balance.xcodeproj`, см.
+   [`Balance/README.md`](Balance/README.md).
+3. **Собрать Android-приложение** — `cd BalanceAndroid && ./gradlew assembleDebug`,
+   см. [`BalanceAndroid/README.md`](BalanceAndroid/README.md).
+4. В любом клиенте укажите адрес запущенного сервера в настройках
+   аккаунта, чтобы включить синхронизацию между устройствами.
+
+## Документация
+
+Документация организована на двух уровнях:
+
+- **Корневой уровень** (`docs/`) — то, что относится ко всем платформам
+  сразу: как устроена система в целом, единый протокол синхронизации,
+  сквозная модель данных и требования безопасности.
+- **Уровень подпроекта** (`Balance/docs/`, `BalanceAndroid/docs/`,
+  `BalanceServer/docs/`) — детали конкретной платформы: код, схемы,
+  сборка, деплой.
+
+| Документ | Описание |
 | --- | --- |
-| `Balance` | iOS 17+, macOS 14+ и watchOS 10+, SwiftUI + SwiftData |
-| `BalanceAndroid` | Android 8.0+, Kotlin + Jetpack Compose + Room |
-| `BalanceServer` | Go-сервер авторизации и синхронизации со встроенным web-приложением |
+| [`AGENTS.md`](AGENTS.md) | Правила для AI-агентов и разработчиков, работающих во всём репозитории |
+| [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) | Как связаны клиенты и сервер, общая схема системы |
+| [`docs/SYNC_PROTOCOL.md`](docs/SYNC_PROTOCOL.md) | Единый протокол синхронизации между всеми клиентами и сервером |
+| [`docs/DATA_MODEL.md`](docs/DATA_MODEL.md) | Сопоставление доменных сущностей между платформами |
+| [`docs/SECURITY.md`](docs/SECURITY.md) | Сквозные требования безопасности (токены, HTTPS, хранение секретов) |
+| [`docs/DEVELOPMENT.md`](docs/DEVELOPMENT.md) | Как собрать, запустить и протестировать все три проекта |
 
-Все пять клиентов — iOS, macOS, watchOS, Android и web — используют одну модель данных и один протокол сервера: операции, пользовательские категории, бюджеты, удаления, регистрация, вход, refresh-токены и постраничная двусторонняя синхронизация. Web-интерфейс открывается по адресу запущенного сервера и не требует отдельной установки.
+### Документация по подпроектам
 
-Инструкции по запуску находятся в `Balance/README.md`, `BalanceAndroid/README.md` и `BalanceServer/README.md`.
+- **Apple (`Balance/`):** [`AGENTS.md`](Balance/AGENTS.md) ·
+  [`docs/ARCHITECTURE.md`](Balance/docs/ARCHITECTURE.md) ·
+  [`docs/DATA_MODEL.md`](Balance/docs/DATA_MODEL.md) ·
+  [`docs/SYNC.md`](Balance/docs/SYNC.md) ·
+  [`docs/DEVELOPMENT.md`](Balance/docs/DEVELOPMENT.md) ·
+  [`docs/PRODUCT.md`](Balance/docs/PRODUCT.md)
+- **Android (`BalanceAndroid/`):** [`AGENTS.md`](BalanceAndroid/AGENTS.md) ·
+  [`docs/ARCHITECTURE.md`](BalanceAndroid/docs/ARCHITECTURE.md) ·
+  [`docs/DATA_MODEL.md`](BalanceAndroid/docs/DATA_MODEL.md) ·
+  [`docs/SYNC.md`](BalanceAndroid/docs/SYNC.md) ·
+  [`docs/DEVELOPMENT.md`](BalanceAndroid/docs/DEVELOPMENT.md) ·
+  [`docs/PRODUCT.md`](BalanceAndroid/docs/PRODUCT.md)
+- **Server (`BalanceServer/`):** [`AGENTS.md`](BalanceServer/AGENTS.md) ·
+  [`docs/ARCHITECTURE.md`](BalanceServer/docs/ARCHITECTURE.md) ·
+  [`docs/API.md`](BalanceServer/docs/API.md) ·
+  [`docs/DATA_MODEL.md`](BalanceServer/docs/DATA_MODEL.md) ·
+  [`docs/SYNC.md`](BalanceServer/docs/SYNC.md) ·
+  [`docs/SECURITY.md`](BalanceServer/docs/SECURITY.md) ·
+  [`docs/DEVELOPMENT.md`](BalanceServer/docs/DEVELOPMENT.md) ·
+  [`docs/DEPLOYMENT.md`](BalanceServer/docs/DEPLOYMENT.md) ·
+  [`docs/PRODUCT.md`](BalanceServer/docs/PRODUCT.md)
+
+## Структура репозитория
+
+```text
+Balance/
+├── AGENTS.md              # общие правила для агентов по всему репо
+├── README.md               # этот файл
+├── docs/                   # сводная документация по всем платформам
+├── Balance/                 # Xcode-проект: iOS + macOS + watchOS
+├── BalanceAndroid/          # Android (Gradle/Kotlin)
+└── BalanceServer/           # Go-сервер + встроенный web-клиент
+```