added AGENTS.md and docs in root dir

AGENTS.md

@@ -0,0 +1,167 @@
+# AGENTS.md — корень монорепозитория Balance
+
+Этот файл — точка входа для AI-агентов и разработчиков, работающих в
+репозитории Balance. Он описывает, как устроены три подпроекта, как они
+связаны друг с другом, и куда идти за подробностями. **Каждый подпроект
+имеет собственный `AGENTS.md` с детальными правилами — читай его перед
+любым изменением внутри соответствующей папки.**
+
+## Что это за проект
+
+Balance — приложение для учёта личных финансов, доступное на пяти
+платформах, которые используют одну и ту же доменную модель и один и
+тот же протокол синхронизации:
+
+| Платформа | Папка | Стек |
+| --- | --- | --- |
+| iOS 17+ | `Balance/` | SwiftUI + SwiftData |
+| macOS 14+ | `Balance/` (`BalanceMac/`) | SwiftUI + SwiftData |
+| watchOS 10+ | `Balance/` (`BalanceWatch/`) | SwiftUI + SwiftData |
+| Android 8.0+ | `BalanceAndroid/` | Kotlin + Jetpack Compose + Room |
+| Web (встроен в сервер) | `BalanceServer/` | Go + embedded static client |
+| Сервер синхронизации | `BalanceServer/` | Go + SQLite |
+
+Все клиенты — iOS, macOS, watchOS, Android, web — синхронизируются через
+один и тот же self-hosted сервер (`BalanceServer`) по единому HTTP(S)
+API: регистрация, вход, refresh-токены, push/pull изменений с курсором,
+tombstone-удаления, пользовательские категории и месячные бюджеты.
+
+## Структура репозитория
+
+```text
+Balance/                    # монорепозиторий
+├── AGENTS.md                # этот файл — общие правила для агентов
+├── README.md                 # общий обзор и точки входа
+├── docs/                     # сводная документация по всему проекту
+│   ├── ARCHITECTURE.md       # как связаны клиенты и сервер
+│   ├── SYNC_PROTOCOL.md      # единый протокол синхронизации
+│   ├── DATA_MODEL.md         # сопоставление сущностей между платформами
+│   ├── SECURITY.md           # сквозные требования безопасности
+│   └── DEVELOPMENT.md        # как собрать и проверить все три проекта
+│
+├── Balance/                  # Xcode-проект: iOS + macOS + watchOS
+│   ├── AGENTS.md              # правила для Apple-клиента
+│   ├── README.md
+│   └── docs/                  # ARCHITECTURE, DATA_MODEL, SYNC, DEVELOPMENT, PRODUCT
+│
+├── BalanceAndroid/           # Android-проект (Gradle/Kotlin)
+│   ├── AGENTS.md              # правила для Android-клиента
+│   ├── README.md
+│   └── docs/                  # ARCHITECTURE, DATA_MODEL, SYNC, DEVELOPMENT, PRODUCT
+│
+└── BalanceServer/            # Go-сервер синхронизации + web-клиент
+    ├── AGENTS.md              # правила для сервера
+    ├── README.md
+    └── docs/                  # ARCHITECTURE, API, DATA_MODEL, SYNC, SECURITY, DEVELOPMENT, DEPLOYMENT, PRODUCT
+```
+
+## Как работать в этом репозитории
+
+### 1. Сначала пойми, в каком подпроекте изменение
+
+Каждый подпроект — независимый билд с собственными зависимостями,
+тестами и CI-шагами. Изменения в одной папке не должны требовать
+правок в другой, **кроме** случаев, когда меняется общий контракт:
+
+- HTTP API / формат sync-запросов и ответов (`BalanceServer`);
+- набор синхронизируемых полей сущности (транзакция, категория, бюджет);
+- правила финансовых расчётов (баланс, корректировки, аналитика).
+
+Если меняется общий контракт — обнови все три подпроекта согласованно
+и синхронизируй документацию (`docs/SYNC_PROTOCOL.md`, а также
+`docs/SYNC.md`/`docs/API.md`/`docs/DATA_MODEL.md` внутри каждой папки).
+
+### 2. Единая доменная модель
+
+Три клиента независимо реализуют одну и ту же модель на своём стеке
+(SwiftData / Room), но со семантически одинаковыми сущностями:
+
+- **Транзакция** (доход/расход, сумма, дата, заметка, категория —
+  хранится snapshot'ом имени/иконки/цвета категории на момент операции);
+- **Пользовательская категория** (имя, иконка/emoji, цвет);
+- **Месячный бюджет** (категория, месяц, лимит);
+- **Tombstone/deletion journal** для распространения удалений между
+  устройствами.
+
+Общие правила расчётов (баланс = доходы − расходы; корректировки
+баланса учитываются в общем балансе, но не в периодической аналитике;
+расходы группируются по имени категории) продублированы в:
+
+- `Balance/Balance/Utilities/FinanceCalculations.swift` (Apple);
+- `BalanceAndroid/.../data/FinanceMath.kt` (Android).
+
+При изменении этих правил на одной платформе — переноси изменение на
+другую и обновляй оба набора тестов
+(`BalanceTests/FinanceCalculationsTests.swift`, `FinanceMathTest`).
+
+### 3. Синхронизация — общий контракт
+
+Единый протокол описан в `docs/SYNC_PROTOCOL.md` (сводно) и подробно —
+в `BalanceServer/docs/API.md` и `BalanceServer/docs/SYNC.md`. Клиентские
+реализации:
+
+- Apple: `Balance/Balance/Shared/ServerSync.swift`;
+- Android: `BalanceAndroid/.../sync/SyncRepository.kt`.
+
+Изменение cursor/sequence semantics, JSON-полей или auth-заголовков —
+breaking change для всех клиентов сразу. Не меняй его в одном
+подпроекте, не проверив остальные два.
+
+### 4. Безопасность (сквозные требования)
+
+- Секреты (пароли, access/refresh токены) никогда не хранятся в
+  открытом виде: Keychain (Apple), Android Keystore + AES/GCM
+  (Android), Argon2id-хеши + SHA-256 refresh-token хеши (сервер).
+- HTTPS обязателен для удалённого сервера на всех клиентах; HTTP
+  разрешён только для `localhost`/`127.0.0.1`/`::1`.
+- Не логируй пароли, токены или заголовок `Authorization` ни в одном
+  из подпроектов.
+- Не коммить секреты, production-URL или credentials.
+
+Подробности — `docs/SECURITY.md` и `BalanceServer/docs/SECURITY.md`.
+
+### 5. Тестирование перед PR
+
+Запусти проверки для всех подпроектов, которые ты менял:
+
+```bash
+# Apple (из Balance/)
+xcodebuild -project Balance.xcodeproj -scheme Balance \
+  -destination 'platform=iOS Simulator,name=<available iPhone>' test
+
+# Android (из BalanceAndroid/)
+./gradlew clean test assembleDebug
+
+# Server (из BalanceServer/)
+go test ./...
+go vet ./...
+go build ./...
+```
+
+Если менялся общий контракт (API/sync/data model) — прогони проверки
+во всех трёх, а не только в изменённой папке.
+
+### 6. Документация
+
+- Меняешь контракт синхронизации → обнови `docs/SYNC_PROTOCOL.md` в
+  корне **и** `BalanceServer/docs/SYNC.md`/`API.md`, а также
+  `docs/SYNC.md` в `Balance/` и `BalanceAndroid/`.
+- Меняешь модель данных на любой платформе → обнови `docs/DATA_MODEL.md`
+  в корне и в затронутом подпроекте.
+- Меняешь способ сборки/запуска → обнови `docs/DEVELOPMENT.md` в
+  корне и соответствующий `README.md`/`docs/DEVELOPMENT.md` подпроекта.
+- Каждый подпроект содержит собственный подробный `AGENTS.md` — этот
+  файл не заменяет их, а даёт общую картину и правила координации между
+  платформами.
+
+## PR checklist (для изменений, затрагивающих несколько платформ)
+
+- [ ] Определены все подпроекты, которые затрагивает изменение.
+- [ ] Общий контракт (API/sync/data model) обновлён согласованно во
+      всех платформах, а не только в одной.
+- [ ] Финансовые расчёты остаются идентичными на Apple и Android.
+- [ ] Обновлены `docs/SYNC_PROTOCOL.md`, `docs/DATA_MODEL.md` в корне,
+      если менялась схема/протокол.
+- [ ] Секреты и токены не добавлены в репозиторий ни в одном подпроекте.
+- [ ] Тесты пройдены в каждом изменённом подпроекте.
+- [ ] Локальный `AGENTS.md` соответствующего подпроекта тоже соблюдён.