docs: clarify domain and agent authority

AGENTS.md

@@ -2,7 +2,13 @@
 
 ## Назначение и authority
 
-Этот репозиторий хранит durable as-built документацию WealthLedger. Canonical OpenSpec store — `wealth-ledger-specs` в `../specs/openspec`; OpenSpec commands, читающие или изменяющие change, всегда выполняются с `--store wealth-ledger-specs`. Proposal, Delta Specs, Design, Tasks и другие versioned planning artifacts вне canonical store запрещены, включая `superpowers/plans`; `../references/**` read-only.
+Этот репозиторий хранит durable as-built документацию WealthLedger. Shared SDD
+policy, common reading pointers, audit routing и `../references/**` policy
+задаёт root `AGENTS.md`.
+
+Canonical SDD authority находится в `wealth-ledger-specs`, физически в
+`../specs/openspec` от этого репозитория. Любая OpenSpec command, читающая или
+изменяющая change, должна использовать `--store wealth-ledger-specs`.
 
 Docs обновляется до фактического проверенного состояния affected change и не представляет planned behavior как поставленное. Artifact ownership и Completion Evidence определены в [`development/engineering-governance.md`](development/engineering-governance.md); audit-derived работа начинается с [`development/audit-remediation.md`](development/audit-remediation.md).
 
@@ -16,11 +22,12 @@ npm run verify
 ```
 
 Gate non-mutating и запускает runtime preflight, committed Markdown rules и `git diff --check`. Auto-fix и network/browser link checking в gate не входят; local links affected documentation проверяются scoped review.
+Актуальные scripts проверять в `package.json`/`npm run`.
 
 ## Boundaries
 
 - `architecture/` — текущее устройство, `features/` — поставленное поведение, `adr/` — устойчивые решения, `development/` — процесс и Completion Evidence, `audits/` — immutable snapshots.
-- Перед изменением current state сверяться с [`architecture/system-overview.md`](architecture/system-overview.md) и [`architecture/domain-glossary.md`](architecture/domain-glossary.md); indexes должны вести к новым документам.
+- Indexes должны вести к новым документам.
 - Feature docs описывают фактический поток, API и ограничения, но не повторяют OpenSpec requirements/design/tasks.
 - Для диаграмм использовать Mermaid в Markdown. Не хранить application code, secrets или competing SDD artifacts.
 

architecture/domain-glossary.md

@@ -1,5 +1,30 @@
 # Глоссарий домена
 
+## User
+
+Локальный владелец данных WealthLedger, идентифицируемый `id` и
+нормализованным email. User владеет Session, T-Bank connection и видит только
+свои Brokerage Accounts.
+
+_Не использовать_: клиент T-Bank, инвестор T-Bank.
+
+## Session
+
+Локальная authenticated-сессия User: короткоживущий access token в браузере и
+server-side refresh token rotation через cookie. Session не является
+T-Bank connection и не подтверждает доступ к Brokerage Account без текущего
+Bearer token.
+
+_Не использовать_: T-Bank сессия, browser session.
+
+## Money
+
+Денежная сумма в одной ISO-валюте, передаваемая как `{ currency, value }`, где
+`value` — decimal string без экспоненциальной записи. Backend выполняет точные
+операции, frontend форматирует Money для отображения.
+
+_Не использовать_: number amount, MoneyDto как доменный термин.
+
 ## T-Bank connection
 
 Единственное принадлежащее User подключение к T-Bank Invest, содержащее
@@ -17,7 +42,8 @@ _Не использовать_: счёт T-Bank, банковский счёт.
 ## Investment Account Type
 
 Нормализованная категория Brokerage Account, независимая от upstream enum
-T-Bank.
+T-Bank: `BROKERAGE`, `INDIVIDUAL_INVESTMENT`, `INVEST_BOX` или
+`MONEY_MARKET_FUND`.
 
 _Не использовать_: тип аккаунта T-Bank, protobuf type.
 
@@ -35,6 +61,14 @@ _Не использовать_: общий портфель, баланс сч
 
 _Не использовать_: валютная позиция, виртуальная позиция.
 
+## Portfolio Position Type
+
+Нормализованный display type Portfolio Position, полученный из upstream
+instrument type: `STOCK`, `BOND`, `FUND`, `CURRENCY`, `FUTURE`, `OPTION`,
+`STRUCTURED_NOTE`, `DIGITAL_FINANCIAL_ASSET` или `OTHER`.
+
+_Не использовать_: upstream instrument type как доменный enum.
+
 ## Instrument
 
 Ценная бумага или иной торгуемый актив T-Bank, на который ссылается Portfolio
@@ -56,7 +90,7 @@ _Не использовать_: аватар актива, иконка бум
 ## Cash Balance
 
 Ненулевой доступный денежный остаток Portfolio в одной валюте; не является
-Portfolio Position.
+Portfolio Position и передаётся отдельно от `positions` в `cashBalances`.
 
 _Не использовать_: валютная позиция, заблокированные средства.
 
@@ -87,10 +121,19 @@ _Не использовать_: история Portfolio, баланс счёт
 
 Нормализованное представление одной операции T-Bank в Account Ledger; хранит
 исходные суммы и доступные детали операции, не создавая синтетических записей
-для комиссии сделки.
+для комиссии сделки. API/code сохраняют legacy names `BrokerageOperationDto`,
+`BrokerageOperationsPageDto` и `/operations`; в доменной документации primary
+term — Ledger Entry.
 
 _Не использовать_: проводка, рассчитанная операция.
 
+## Operation Category
+
+Нормализованная категория Ledger Entry для фильтрации и отображения:
+`trade`, `income`, `tax`, `fee`, `transfer` или `other`.
+
+_Не использовать_: upstream operation type как category.
+
 ## Ledger Page Cache
 
 Кэш страницы Account Ledger, отделённый от кэша отдельных операций.
@@ -124,6 +167,15 @@ _Не использовать_: активный refresh token, признак
 
 Прогнозируемое на ближайший период денежное или связанное корпоративное
 событие одного Brokerage Account, рассчитанное по текущей Portfolio Position;
-не является исполненной Ledger Entry.
+не является исполненной Ledger Entry. API/code сохраняют legacy names
+`UpcomingEventDto`, `UpcomingEventsDto`, `/events` и frontend `BrokerageEvent`;
+в доменной документации primary term — Future Cash Event.
 
 _Не использовать_: будущая операция, гарантированная выплата.
+
+## Future Cash Event Type
+
+Нормализованный тип Future Cash Event: `coupon`, `dividend`, `maturity` или
+`offer`.
+
+_Не использовать_: upstream dividend type, MOEX row name.

features/brokerage-account-ledger.md

@@ -31,6 +31,6 @@ sequenceDiagram
 - Запрашиваются только исполненные операции T-Bank.
 - Полный журнал фильтруется по периоду и категориям, а изменение фильтра сбрасывает cursor-пагинацию.
 - Полный журнал не показывает цену, количество, НКД и комиссию записи.
-- Backend хранит в памяти процесса до 100 страниц Account Ledger: свежая страница живёт до 30 секунд, а при переполнении вытесняется давно не использовавшаяся страница (LRU). Ключ включает пользователя, счёт, нормализованные период и categories, cursor и limit; отсутствующий `to` приводится к текущему 30-секундному bucket. Проверка подключения и доступа к счёту выполняется до выдачи кэшированной страницы. Операции не сохраняются и не синхронизируются локально.
+- Backend хранит в памяти процесса до 100 страниц Account Ledger: свежая страница живёт до 30 секунд, а при переполнении вытесняется давно не использовавшаяся страница (LRU). Ключ включает пользователя, счёт, нормализованные период и categories, cursor и limit; отсутствующий `to` приводится к текущему 30-секундному bucket. Проверка подключения и доступа к счёту выполняется до выдачи кэшированной страницы. Ключ не включает версию T-Bank token, поэтому после успешной замены T-Bank connection для того же User, Brokerage Account и query уже сохранённая страница может оставаться видимой до истечения 30-секундного TTL. Операции не сохраняются и не синхронизируются локально.
 - Журнал не рассчитывает остаток после операции, суммарные доходы или налоги, историческую стоимость Portfolio, конвертацию валют и рыночные изменения цены.
 - `409 TBANK_NOT_CONNECTED`, `400 INVALID_TBANK_TOKEN`, `404` недоступного счёта и `503 TBANK_UNAVAILABLE` используют существующую семантику ошибок T-Bank.