feat: generate OpenAPI without peer repositories

.ai/architecture.md

@@ -39,11 +39,12 @@ connection generation. Integration clients владеют protocol/deadline/retr
 provider records преобразуются перед чистыми domain calculations.
 Пользовательский `tbank-connection` не владеет низкоуровневым gRPC client.
 
-Runtime OpenAPI из Nest → предоставленный frontend snapshot → generated types.
+Nest DTO/metadata → `npm run openapi:generate` → игнорируемый Git `openapi.json`
+для публичных consumers.
 Problem Details фильтруются общей HTTP boundary; StructuredLogger добавляет
 request context и ограничивает поля событий. Jest unit tests, изолированные
 SQLite/HTTP suites и OpenAPI parity доказывают разные части поведения.
-Системные потоки и ADR выбираются через [Источники](../AGENTS.md#источники).
+Локальные источники выбираются через [Источники](../AGENTS.md#источники).
 
 ## Module-first organization
 
@@ -216,7 +217,7 @@ Mapping и stable codes — по [Errors](conventions/error-handling.md).
 сводкой через repository и чистый расчёт. Не разрывай денежную transaction,
 общий cache/limiter или pending promises при extraction.
 
-Расширение abstractions — по [change scope](../../.ai/conventions/code-health.md#change-scope).
+Расширение abstractions — по [change scope](conventions/engineering.md#change-scope).
 
 ## Common
 
@@ -230,7 +231,7 @@ protobuf units/nano conversion — T-Bank integration. Domain используе
 ## Domain literals and magic values
 
 Общий выбор symbolic values и числовых policies —
-[Domain values](../../.ai/conventions/code-health.md#domain-values).
+[Domain values](conventions/engineering.md#domain-values).
 Сохраняй strict TS и explicit boundary types. Для недоверенного input выбирай
 `unknown` + runtime narrowing; отключённый lint `no-explicit-any` не делает
 `any` нормой domain/application model. `declare` допустим для заполняемых извне
@@ -239,8 +240,7 @@ DTO fields, не для сокрытия неинициализированно
 OpenAPI enum metadata и runtime validation должны читать тот же vocabulary,
 что application/domain. Например, `BankOperationKind` принадлежит bank-cards/domain,
 а DTO получает допустимые значения через `Object.values(BankOperationKind)`.
-Frontend переиспользует generated OpenAPI types/values по возможностям генератора,
-а не определяет независимый backend-owned словарь. Внешние/generated enums
+Публичные enum values входят в OpenAPI artifact. Внешние/generated enums
 сохраняй; generated Prisma/protocol code вручную не меняй.
 
 `@typescript-eslint/no-magic-numbers` включён как error; базовое ESLint rule

.ai/conventions/data.md

@@ -51,16 +51,16 @@ application checks. Предварительный lookup не заменяет
 Transaction не охватывает сетевой T-Bank вызов как будто это одна atomic DB
 операция. Планируй порядок и compensation по текущей задаче; не удерживай DB
 lock во время retry внешней сети. Access/cache generation semantics — у
-[T-Bank source](../../../docs/integrations/tbank.md#граница-финансового-кэша).
+[T-Bank integration](integrations.md#retry-cache-и-protocol).
 
 ## Деньги и точность
 
 Для денежных значений используй existing decimal helpers и строковый wire value,
 не JS floating-point арифметику для сумм. Currency — отдельная часть Money;
 разные валюты не складываются без явно заданного conversion contract.
-Источник: [Money](../../../docs/glossary.md#money),
-пример: [decimal.ts](../../src/common/decimal.ts). UI formatting не меняет
-backend ownership расчётов и доменную семантику.
+Источник формы — `src/common/money.types.ts`;
+пример точной арифметики: [decimal.ts](../../src/common/decimal.ts).
+Форматирование ответа не меняет доменную семантику и точность расчёта.
 
 ## Schema и migration
 
@@ -73,8 +73,8 @@ client обновляй из schema. Не переписывай уже прим
 
 **Безопасный путь:** additive изменение, заполнение/проверка данных и только затем
 удаление прежней формы, если задача этого требует. Примеры schema/migrations:
-[Prisma source](../../prisma/schema.prisma); исторический rationale —
-[ADR 001](../../../docs/adr/001-prisma-sqlite-local-mvp.md), не текущий список таблиц.
+[Prisma source](../../prisma/schema.prisma). SQLite — embedded storage текущего
+приложения; файл БД и encryption key требуют согласованного backup/restore.
 
 ## Проверка
 

.ai/conventions/engineering.md

@@ -0,0 +1,74 @@
+# Работа в репозитории
+
+## Граница и порядок работы
+
+Репозиторий сам содержит инструкции, исходники, конфигурацию и входы своих
+проверок. Сборка, 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
+содержит одну связанную задачу. Root другого checkout не управляет этим repo.
+Прямой push в `main`, force-push и перенос опубликованных тегов не входят в
+обычную работу. Перед release/hotfix прочитай местный README, раздел «Релизы».

.ai/conventions/error-handling.md

@@ -9,7 +9,7 @@ application/domain outcome → application mapping → HttpExceptionFilter
 
 Сохраняй принятый профиль RFC 9457: `status`, стабильный публичный `code`,
 для validation — `errors: [{ pointer, detail }]`. Точный контракт и известное
-расхождение validation описаны в [HTTP API](../../../docs/architecture/http-api.md).
+расхождение validation описаны в [HTTP API](http-api.md#источник-контракта).
 Не добавляй `type/title/instance` как обязательные поля без contract change.
 
 Чистый domain не импортирует Nest HTTP exceptions. Существующий application
@@ -21,7 +21,7 @@ error framework/registry. Если domain outcome требует HTTP interpreta
 
 - Используй existing code владельца, не сравнивай внутренние сообщения.
   Новое значение имеет один symbolic owner; metadata/validation и consumers
-  согласуются по [domain values](../../../.ai/conventions/code-health.md#domain-values).
+  согласуются по [domain values](engineering.md#domain-values).
 - Общий envelope, default status mapping и unexpected errors принадлежат
   [HttpExceptionFilter](../../src/common/filters/http-exception.filter.ts).
   Не дублируй `res.status().json()` в controllers/services.

.ai/conventions/http-api.md

@@ -3,8 +3,8 @@
 ## Выбор boundary
 
 Сначала определи, меняется wire contract или только реализация существующего
-use case. Для route/request/response/status/error shape читай
-[HTTP semantics и источник контракта](../../../docs/architecture/http-api.md).
+use case. Для route/request/response/status/error shape используй
+[локальный публичный контракт](#источник-контракта) и configured HTTP tests.
 
 | Проверка | Где выполнять |
 | --- | --- |
@@ -57,11 +57,32 @@ helper ради первого endpoint. Новая pagination явно опре
 
 [Operations controller](../../src/modules/investments/operations/presentation/brokerage-operations.controller.ts)
 показывает guard, user.sub, DTO query и service delegation.
-Для нового field обновляй canonical source и generated artifacts в определённом
-направлении; body type frontend не исправляется вручную.
+Для нового field обновляй Nest DTO/metadata и публикуемый OpenAPI artifact.
+Потребители получают публичный контракт независимо от внутреннего устройства API.
 
 Проверь happy path и применимые invalid input/access/not-found/domain/upstream
 errors на boundary, где они возникают. Unit вызов controller не запускает pipes,
 guards или serialization. `npm run test:openapi-contract` проверяет schema parity,
 но не поведение invalid request; выбирай соответствующий test по
 [Testing](testing.md). Финальный gate не заменяет semantic review ошибок.
+
+## Источник контракта
+
+Nest DTO/controllers/Swagger metadata определяют публичный HTTP API.
+`npm run openapi:generate` собирает backend и записывает корневой `openapi.json`.
+Nest preview читает metadata без запуска HTTP-порта, провайдеров, БД и T-Bank;
+команда не требует deployment environment. Artifact исключён из Git.
+
+При изменении API обнови DTO/metadata и выполни генерацию. Потребители получают
+artifact отдельно; backend не читает их репозитории. `test:openapi-contract`
+сравнивает вывод генератора с runtime schema configured app во временном каталоге.
+Проверка подтверждает правильность генерации, но без versioned baseline не
+выявляет breaking change относительно предыдущего выпуска. Для такого изменения
+согласуй переход consumers и проверь relevant HTTP behavior.
+
+HTTP prefix — `/api/v1`; Swagger доступен согласно `src/config/swagger.config.ts`.
+Общий error response — `application/problem+json` со `status` и публичным `code`.
+Validation требует `400 / VALIDATION_ERROR` и `errors: [{ pointer, detail }]`.
+Известное ограничение: ValidationPipe сейчас формирует строковые сообщения,
+а filter ожидает структурированные field errors; schema parity не доказывает
+правильность `errors`. Изменение требует проверки реального HTTP pipeline.

.ai/conventions/integrations.md

@@ -5,10 +5,9 @@
 T-Bank gRPC принадлежит TbankClient; MOEX metadata — MoexClient; NCR ratings —
 NcrRatingsClient. Сервисы use case
 используют объявленные клиентом records; SDK clients, metadata и transport errors
-остаются внутри integration. Frontend не вызывает
-T-Bank и не получает credentials/proto client. Reference source —
-[ADR 003](../../../docs/adr/003-tbank-server-side-grpc-boundary.md) и
-[connection behavior](../../../docs/integrations/tbank.md).
+остаются внутри integration. Credentials и proto client не входят в публичный
+HTTP API. Connection lifecycle проверяется на границе соответствующего module
+и [Security](security-auth.md).
 
 `modules/investments/tbank-connection` — пользовательская capability чтения,
 создания/замены и удаления подключения. `integrations/tbank` — технические
@@ -39,7 +38,8 @@ Existing client уже владеет bounded FIFO queue, rate limit, deadline
 классификацией. Новый RPC проходит тот же путь; не добавляй вложенный retry loop
 в service. Не отключай TLS verification ради окружения: используй документированный
 CA mechanism. Точные параметры и ограничения принадлежат
-[connection configuration](../../../docs/integrations/tbank.md#конфигурация-и-ограничения).
+[validated environment](../../src/config/env.validation.ts) и
+[TbankClient](../../src/integrations/tbank/tbank.client.ts).
 
 Эта queue/retry policy относится к T-Bank. MOEX/NCR HTTP clients используют
 собственный bounded timeout и безопасный unavailable outcome; не приписывай им
@@ -47,9 +47,10 @@ gRPC retry policy. При изменении upstream сначала прочи
 
 При query/cache change установи key, user/account/generation ownership,
 freshness и поведение late response. Старый результат не может обслужить новую
-connection generation. Client Cached Snapshot frontend отличается от backend
-cache/stale policy; semantics конкретного use case читай через
-[feature index](../../../docs/README.md#предметные-области).
+connection generation. Успешная замена/deletion подключения меняет generation
+даже при сохранении прежнего token; ошибка оставляет прежнее подключение.
+Кэш конкретного use case принадлежит его service и tests. Не переноси
+сохранённый snapshot между пользователями или поколениями подключения.
 
 Внешний auth failure и временная недоступность имеют разные public codes;
 raw gRPC exception не уходит клиенту. Existing translation — в TbankTokenService

.ai/conventions/observability.md

@@ -17,8 +17,6 @@
 - Для ошибки используй public code и безопасный context операции/попыток;
   [error mapping](error-handling.md) не отдаёт внутренние детали клиенту.
 
-Причины — [ADR 008](../../../docs/adr/008-pino-backend-logging.md), системное
-поведение — [HTTP observability](../../../docs/architecture/http-api.md#наблюдаемость).
 Проверяй новые поля/redaction/correlation existing logging tests; не добавляй
 тест на каждую строку log. Existing ESLint не запрещает все вызовы `console`
 отдельным правилом: до настройки встроенного `no-console` это semantic review.

.ai/conventions/security-auth.md

@@ -10,21 +10,20 @@ account access/connection generation — TbankAccessService; token crypto —
 TbankTokenService/TbankCrypto. Расширяй существующую boundary, не добавляй
 второй JWT middleware, decrypt helper или refresh coordinator.
 
-[Authentication](../../../docs/domains/authentication/overview.md) и
-[ADR 006](../../../docs/adr/006-auth-session-policy.md)/[009](../../../docs/adr/009-concurrent-refresh-rotation-policy.md)
-задают session semantics. Access хранится только в памяти frontend; refresh
-передаётся httpOnly cookie. Source code конфигурации cookie —
+Access проверяется JWT strategy; refresh передаётся httpOnly cookie.
+Сроки token/session принадлежат auth source и configured HTTP tests.
+Source code конфигурации cookie —
 [AuthController](../../src/modules/auth/presentation/auth.controller.ts); изменение flags/path требует
 проверки browser/HTTP поведения, не только TypeScript.
 
 Refresh rotation атомарна: один победитель, проигравший/superseded token получает
 401, но сам по себе не отзывает session победителя. Не вводи replay history/grace
-или иной security contract без текущей задачи. Logout идемпотентен; in-memory
-frontend session/cache очищается и при network failure.
+или иной security contract без текущей задачи. Logout идемпотентен, отзывает
+сессию и очищает refresh cookie на HTTP-границе.
 
 ## Trust boundaries
 
-Frontend не является security boundary. DTO runtime validation выполняется
+Клиентский интерфейс не является security boundary. DTO runtime validation выполняется
 server-side; whitelist не заменяет access checks. Environment/secret inputs
 проверяет existing config owner; реальные credentials не попадают в fixtures.
 
@@ -36,8 +35,10 @@ cases для соответствующего изменения.
 T-Bank credentials остаются server-side и хранятся encrypted. Используй
 existing AES-256-GCM boundary с validated 32-byte key; не печатай plaintext,
 шифротекст, cookie, Authorization или connection generation в logs/errors/API.
-[Connection source](../../../docs/integrations/tbank.md) определяет
-cache invalidation при замене/deletion и ограничение key rotation.
+Успешная замена/deletion меняет connection generation и инвалидирует её кэши;
+ошибка сохраняет прежнее подключение. Ключ не ротируется автоматически:
+новый ключ не расшифрует сохранённые credentials. Нужен исходный ключ или
+повторное сохранение token пользователем; сохраняй ключ отдельно от backup БД.
 
 Не передавай Prisma User/Session целиком наружу; выбирай public DTO. Пароль
 обрабатывает существующий bcrypt flow. Не копируй требования о нормализации
@@ -56,5 +57,5 @@ cache invalidation при замене/deletion и ограничение key ro
 message безопасным.
 
 Targeted auth/access/crypto/logging tests + [Testing](testing.md).
-Cookie/guard/HTTP changes требуют configured HTTP proof; frontend Bearer/retry
-проверяется MSW. Schema parity не доказывает отсутствие утечки secret.
+Cookie/guard/HTTP changes требуют configured HTTP proof.
+Schema parity не доказывает отсутствие утечки secret.

.ai/conventions/testing.md

@@ -1,7 +1,7 @@
 # Backend testing
 
 Перед нетривиальными тестами сформулируй
-[общий Test Intent](../../../.ai/conventions/testing.md); отдельный документ
+[общий Test Intent](engineering.md#test-intent); отдельный документ
 не требуется. Trivial low-risk изменения обходятся без него.
 
 ## Выбор уровня
@@ -15,7 +15,7 @@
 | Pure mapper/decimal/domain branch | Unit со значимыми edge cases |
 | Service orchestration/access/retry policy | Jest с mocks внешних boundaries и observable outcome |
 | Pipe/guard/cookie/status/HTTP error | Configured Nest HTTP boundary; прямого вызова метода controller недостаточно |
-| OpenAPI metadata/wire schema | `test:openapi-contract` + потребительский contract check |
+| OpenAPI metadata/wire schema | `test:openapi-contract` + configured HTTP tests |
 | DB constraint/CAS/transaction/migration | Integration с изолированной реальной DB |
 | Только DTO declarations/thin wiring | Existing contract/type/build без искусственного unit test |
 
@@ -29,7 +29,7 @@ Unit specs colocated в `src/**/*.spec.ts`; HTTP/integration — `test/`.
 - [BrokerageAccountsService tests](../../src/modules/investments/brokerage-accounts/brokerage-accounts.service.spec.ts): отсутствие connection не вызывает upstream, нормализация и точные суммы.
 - [AuthService tests](../../src/modules/auth/application/auth.service.spec.ts): invalid/expired/superseded token и concurrent rotation; mock race test не является доказательством DB transaction.
 - [HTTP filter tests](../../src/common/filters/http-exception.filter.spec.ts): безопасный error envelope.
-- [OpenAPI integration](../../test/openapi-contract.e2e-spec.ts): configured app + frontend snapshot, без записи snapshot и без T-Bank.
+- [OpenAPI integration](../../test/openapi-contract.e2e-spec.ts): генератор без сервера + configured app; временный JSON, без versioned snapshot и без T-Bank.
 
 При bug сначала воспроизведи именно его исход, затем исправь responsible owner.
 Не создавай tests для каждой декларации, logs строки или поведения Prisma/Nest