docs: make frontend instructions self-contained

.ai/architecture.md

@@ -62,9 +62,8 @@ public API `shared/theme`. Storybook показывает synthetic presentation
 не использует application API. RTL/MSW проверяют поведение приложения отдельно.
 
 Existing route-aware AppShell расположен в shared/ui; это legacy placement,
-а не образец нового shared primitive. Общий план улучшений читается только
-при migration через [router](../AGENTS.md).
-При изменении foundation прочитай [design system](../../docs/design/overview.md).
+а не образец нового shared primitive. При изменении foundation прочитай
+[UI](conventions/ui.md#визуальная-основа) и [Storybook](conventions/storybook.md).
 
 ## Примеры
 

.ai/conventions/data.md

@@ -28,7 +28,7 @@ client, runtime schema, hash/checksum registry или дополнительны
 без отдельной текущей потребности; existing OpenAPI flow уже владеет генерацией. Frontend-команды не читают соседний
 backend checkout и не проверяют backend runtime OpenAPI; изменение wire
 shape/status/route сохраняет
-[границу HTTP-контракта](../../../docs/architecture/http-api.md#источник-контракта).
+публичный контракт предоставленного snapshot.
 Одна UI-модель не требует менять API. `openapi:generate` работает offline от snapshot;
 `openapi:check` генерирует во временный каталог и сравнивает, не меняя tracked files.
 
@@ -40,18 +40,23 @@ Authorization. Auth endpoints исключены из Bearer/retry middleware. R
 Не добавляй собственный refresh/retry loop в caller.
 
 Protected queries используют existing session-aware boundary; logout очищает
-session-scoped cache. При auth/token change читай [security](../../../backend/.ai/conventions/security-auth.md)
-и [authentication](../../../docs/domains/authentication/overview.md).
+session-scoped cache. Access token хранится только в памяти, refresh передаётся
+httpOnly cookie с `credentials: include`. Не сохраняй tokens в localStorage,
+URL, логах или fixtures. Logout очищает локальную session/cache и при ошибке
+сети; до окончания auth bootstrap показывай neutral state. Перед auth change
+прочитай shared client, session owner и их tests.
 Успешная connection mutation коммитит подтверждённый status и сбрасывает financial
 GET subtree; ошибка mutation не меняет generation/cache. Это отдельная граница
-от обычного фонового refetch: [connection policy](../../../docs/integrations/tbank.md#граница-финансового-кэша).
+от обычного фонового refetch. Даже повторное сохранение того же token начинает
+новую generation; поздний ответ прежней generation не попадает в новый кэш.
 
 Mutations используют существующий generated client и query-key owner;
 после успеха обновляй/invalidируй только связанные данные. Optimistic update
 нужен конкретному UX и обязан иметь rollback/error behavior.
 
-Default focus refetch выключен; freshness и retry определяются существующей
-[query policy](../../../docs/adr/007-react-query-fetch-policy.md) и feature source.
+Default focus refetch выключен; freshness и retry задаются существующими
+query options у entity/feature owner. После `staleTime` повторное открытие
+экрана может запустить background refetch; focus сам по себе его не запускает.
 При обычном refetch сохраняй Client Cached Snapshot, при session/connection
 смене не показывай данные прежнего владельца. UI presentation — в UI convention.
 
@@ -76,5 +81,5 @@ Network/unknown error получает безопасное локальное
 Изменяя header/retry/invalidation, проверяй наблюдаемое поведение через MSW и
 [Testing](testing.md); не обращайся к реальному T-Bank.
 `npm run openapi:check`, `npm run typecheck` и targeted tests проверяют разные
-части решения. Для API semantics нужны exact docs и проверки наблюдаемого
-HTTP-поведения на стороне backend.
+части решения. Для поведения API-клиента используй сценарии MSW на публичной
+HTTP-границе; реализация сервера не является входом frontend-проверок.

.ai/conventions/engineering.md

@@ -0,0 +1,76 @@
+# Работа в репозитории
+
+## Граница и порядок работы
+
+Репозиторий сам содержит инструкции, исходники, конфигурацию и входы своих
+проверок. Сборка, CI и обязательный маршрут чтения работают без соседних
+checkout. Внешний API задаётся предоставленным публичным контрактом;
+исходники или инструкции его реализации не являются зависимостью разработки.
+При нехватке требования сообщи, какое решение не определено, до его реализации.
+
+Начни с результата и affected areas. До edits проследи flow/invariants, найди
+owner и 1–3 примера. Код показывает механизм; случайный аналог не меняет контракт.
+Работай напрямую; OpenSpec/SDD lifecycle — только по явному запросу.
+Перед Node-командами активируй местную `.nvmrc`: `nvm use --silent`.
+Сохраняй чужие staged/unstaged/untracked изменения и read-only архивы.
+
+## Change scope
+
+Сначала расширь существующего владельца. Иначе используй standard library,
+платформу или установленную dependency; небольшая новая реализация допустима
+при собственной ответственности. Не создавай helper/interface/wrapper ради
+возможного reuse. Общее имя не означает общую бизнес-ответственность.
+Сохраняй validation, authorization, atomicity, accessibility и migration safety.
+
+После diff выполни Boy Scout review: проверь новое дублирование, owner, callers,
+небольшие связанные legacy issues и соответствие local conventions. Исправляй
+непосредственно связанные low-risk проблемы; широкий cleanup — отдельная задача.
+
+## Domain values
+
+Finite business vocabulary принадлежит одному domain/module/entity owner.
+Переиспользуй его symbols; для нового словаря без аналога — `as const` + union.
+Сохраняй wire values; generated/external enums не переписывай вручную.
+Numeric policy называй по смыслу и единицам. Индексы, `Math.max(value, 0)` и
+обычные labels не выноси в constants без semantic benefit.
+Локальный TypeScript/lint профиль определяет дополнительные ограничения.
+
+## Dependencies
+
+Проверь аналоги и direct dependencies в местном manifest до добавления пакета.
+Новая dependency оправдана текущей потребностью и меньшей общей сложностью;
+оцени compatibility, runtime/bundle и maintenance/security. Импортируемый пакет
+объявляется напрямую; транзитивная установка не является контрактом.
+Сохраняй exact versions и lockfile; воспроизводимая установка — `npm ci`.
+Peer-конфликт решай совместимыми версиями без `--force`/`--legacy-peer-deps`.
+Используй существующий analyzer; не добавляй второй для той же проверки.
+
+## Test Intent
+
+Перед нетривиальным тестом кратко определи наблюдаемый исход, regression risk,
+значимые edge/error/concurrency cases и самую дешёвую надёжную boundary.
+Отдельный artifact не нужен. Проверяй результат, а не private call order,
+декларации, тривиальные wrappers или поведение framework.
+При bug сначала воспроизведи исход. Mock race не доказывает DB atomicity.
+Уровни и runnable commands выбирай по местной testing convention.
+
+## Проверки и завершение
+
+Code/dependency change: `npm ci`, полный `npm run verify` и дополнительные
+risk checks из местной testing convention. Targeted tests ускоряют итерацию,
+но не заменяют финальный gate. `lint:fix`/format — edits, не proof.
+Markdown-only: проверь новые/изменённые тексты, локальные ссылки/якоря, маршруты
+чтения и `git diff --check`; application build ради текста не нужен.
+Повтори routing по staged/unstaged/new files. Запиши краткие команды, результаты
+и ограничения. Зелёный lint не заменяет semantic/security review.
+
+## Git и релизы
+
+Работа — в `codex/<task>` от актуального `develop`, затем PR в `develop`.
+Сохраняй чужие изменения; перед commit просмотри staged paths и diff.
+Commits и PR titles — Conventional Commits; допустим `spec:`. Каждый commit
+содержит одну связанную задачу. При связанной issue добавь её номер в конец
+заголовка (`fix: … #12`); без issue номер не нужен. Root другого checkout
+не управляет этим repo.
+Прямой push в `main`, force-push и перенос опубликованных тегов не входят в
+обычную работу. Перед release/hotfix прочитай местный README, раздел «Релизы».

.ai/conventions/testing.md

@@ -1,7 +1,7 @@
 # Frontend testing
 
 Перед нетривиальными тестами сформулируй
-[общий Test Intent](../../../.ai/conventions/testing.md); отдельный документ
+[общий Test Intent](engineering.md#test-intent); отдельный документ
 не требуется. Trivial low-risk изменения обходятся без него.
 
 ## Выбор проверки
@@ -35,7 +35,7 @@ MSW запускается только Vitest setup в `src/test/`, без brow
 экземпляр и seeded cache. Providers выбирай явно. Existing teardown выполняет
 RTL cleanup, auth reset и MSW reset: [test client](../../src/test/query.tsx).
 Тестовый клиент отключает retries запросов и мутаций для предсказуемого исхода;
-это не меняет [политику обновления приложения](../../../docs/adr/007-react-query-fetch-policy.md).
+это не меняет [политику обновления приложения](data.md#auth-и-invalidation).
 
 ## Важные случаи
 

.ai/conventions/typescript-react.md

@@ -32,7 +32,7 @@ Container/VM/view и state owners — в [UI](ui.md).
 ## Domain literals and magic values
 
 Общее правило ownership и символических значений —
-[Domain values](../../../.ai/conventions/code-health.md#domain-values).
+[Domain values](engineering.md#domain-values).
 Backend vocabulary бери из generated `paths`, не создавай ручную копию enum.
 Текущий `schema.d.ts` содержит только types: typed wire literals допустимы,
 когда generator не предоставляет runtime values.

.ai/conventions/ui.md

@@ -18,7 +18,7 @@ components живут у feature/entity/page, даже при повторном
 
 Wrapper нужен для проектной ответственности, а не ради нового имени
 для Button. Локальный CSS module принадлежит component; общий token вводи для
-реально общей роли через [design system](../../../docs/design/overview.md).
+реально общей роли в [визуальной основе](#визуальная-основа).
 
 | Состояние | Владелец |
 | --- | --- |
@@ -104,3 +104,13 @@ Type/style: `npm run typecheck`, `npm run lint`. Для risk behavior/измен
 используй [Testing](testing.md). UI: keyboard, narrow viewport,
 loading/error/empty/loaded и recovery по применимости. [Storybook](storybook.md) задаёт выбор stories и изоляцию каталога;
 сверяй UI с задачей отдельно от build.
+
+## Визуальная основа
+
+Общая тема живёт в `src/shared/theme`: `tokens.json` задаёт переносимые значения,
+`theme.ts` адаптирует их к Mantine. Используй public API темы и её semantic roles,
+без отдельной палитры в page/component. Поддерживается светлая схема.
+Цвет дополняет подпись или знак; проверяй контраст конкретной пары text/background.
+Warning не используй для мелкого текста на белом. Деньги сохраняют валюту, знак
+и различие между нулём и неизвестной суммой. Общие состояния демонстрирует
+Storybook; presentation stories используют synthetic data без application API.