docs: контракт для агентов, архитектура и план фаз

AGENTS.md — индекс, команды и обязательные ограничения (Decimal для денег, не
конвертировать валюту на записи, SDK T-Invest ровно в одном модуле, аналитика
читает только confirmed). docs/ai/ — архитектура, соглашения, эксплуатация и
полный план на шесть фаз с проверками для каждой.

docs/ai/README.md

@@ -0,0 +1,37 @@
+# docs/ai — обзор проекта
+
+## Назначение
+
+`fin-tracker` объединяет два мира личных финансов:
+
+- **ZenMoney** — повседневные счета и транзакции (синкается с банками сам), читаем через
+  `POST /v8/diff/`;
+- **брокеры** — T-Invest по gRPC API, Сбер и ВТБ через загрузку отчётов, прочее вручную/CSV;
+
+и считает поверх них то, за что раньше платили Snowball Income: позиции по всем брокерам,
+P&L, XIRR/TWR, аллокацию, календарь дивидендов и купонов с прогнозом, ребалансировку,
+бенчмарки, налоги — плюс net worth, cash flow и runway по ZenMoney.
+
+## Система в общих чертах
+
+```
+sources/* ──sync──▶ raw_* (JSONB, идемпотентно) ──map──▶ core (account, instrument, event, cash_txn…)
+                                                          │
+worker (APScheduler, advisory locks)                      ▼
+                                              ledger (лоты FIFO, дедуп, матчинг ZM↔брокер)
+                                                          │
+                                              analytics (polars, pyxirr) ──▶ metric_* ──▶ api ──▶ Flutter
+```
+
+- `backend/src/fintracker/sources/` — по одному пакету на источник, контракт в `base.py`.
+- `worker/` — планировщик и запуск синков (`runner.run_source`): lock, `sync_run`, курсор.
+- `api/` — FastAPI, `/api/v1`, ошибки RFC 7807, деньги строками.
+- `app/` — Flutter, клиент сгенерирован из `openapi/openapi.json`.
+
+## Документы
+
+- [architecture.md](architecture.md) — домен, модули, потоки данных, API.
+- [conventions.md](conventions.md) — деньги, валюты, идемпотентность, стиль.
+- [plan.md](plan.md) — фазы и чек-листы проверки.
+- [ops.md](ops.md) — деплой на VPS, бэкапы, секреты.
+- [links.md](links.md) — внешние API и референсы.