docs: reorganize system knowledge by domain

README.md

@@ -1,59 +1,74 @@
-# WealthLedger: документация проекта
+# WealthLedger: документация системы
 
-WealthLedger помогает частному инвестору понимать состав портфеля, исполненные
-операции, полученные доходы и будущие выплаты по счетам T-Bank. Приложение
-работает локально; данные брокера получает backend. Здесь объясняются понятия,
-границы системы, ключевые сценарии и причины решений.
+WealthLedger помогает частному инвестору понимать состав портфеля T-Bank,
+исполненные операции, полученный доход и будущие выплаты. Здесь объясняются
+продукт, понятия, функции, взаимодействия и причины архитектурных решений.
+Основной текст можно читать без исходников; технические ссылки нужны для
+дальнейшей проверки и изменения системы.
 
 ## Первое знакомство
 
-1. Прочитайте [обзор системы](architecture/system-overview.md): пользователи,
-   внешние системы, исполняемые части и движение данных.
-2. Откройте [карту возможностей](features/README.md): выберите предметную
-   область и найдите её поведение, ограничения и ответственность компонентов.
-3. Сверяйте незнакомые понятия с [глоссарием](architecture/domain-glossary.md).
-   Особенно важны различия между User, Session, подключением и брокерским
-   счётом, между полученным доходом и прогнозом выплаты.
-4. Изучите [локальное окружение](development/local-workspace.md) и один
-   сценарий: вход → подключение T-Bank → счёт → портфель → доходы или события.
+1. [Обзор продукта](overview.md) — задачи пользователя и границы приложения.
+2. [Глоссарий](glossary.md) — пользователь, сессия, подключение, счёт,
+   портфель, полученный доход и прогноз выплаты.
+3. [Контекст](architecture/context.md) — WealthLedger и внешние системы.
+4. [Контейнеры](architecture/containers.md) — браузерное приложение, API,
+   локальное хранение и обмен данными.
+5. [Портфель](domains/portfolio/overview.md) и [его загрузка](domains/portfolio/flows/portfolio-loading.md)
+   — как источник превращается в позиции, суммы и состояние свежести.
 
-После этого вы должны уметь объяснить, откуда приходит финансовое значение,
-какой компонент им владеет и где проверить его ограничения.
+После этого читатель должен уметь объяснить происхождение финансового
+показателя и отличить данные брокера, расчёт сервера и сохранённый экран.
 
-## Найти ответ по задаче
+## Предметные области
 
-| Вопрос | Начать здесь |
+Папки областей группируют знания; они не объявляют отдельные сервисы.
+
+| Тема | Что здесь искать |
 | --- | --- |
-| Как части проекта работают вместе? | [Обзор и схемы](architecture/system-overview.md) |
-| Как устроена конкретная возможность и кто за неё отвечает? | [Карта возможностей](features/README.md) |
-| Что означает термин или финансовый показатель? | [Глоссарий](architecture/domain-glossary.md) |
-| Почему выбраны эти архитектурные ограничения? | [Решения ADR](adr/README.md) |
-| Какие условия нужны для работы и как понимать локальные ошибки? | [Окружение и восстановление](development/local-workspace.md) |
-| Где точные API-типы, статусы и правила изменения контракта? | [HTTP API](architecture/http-api.md) и [генерация контракта](development/runtime-openapi-verification.md) |
-| Как проверяются согласованность и качество системы? | [Сопровождение](development/README.md) |
-| Как обновлять знания вместе с кодом? | [Ведение документации](development/documentation.md) |
+| [Аутентификация](domains/authentication/overview.md) | Регистрация, вход, восстановление и завершение сессии |
+| [Счета](domains/accounts/overview.md) | Доступные счета, сводки и состояния каждого счёта |
+| [Портфель](domains/portfolio/overview.md) | Позиции, остатки, суммы, структура и свежесть |
+| [Все счета](domains/portfolio/all-accounts.md) | Общий портфель, происхождение строк и сводные разделы |
+| [Операции](domains/operations/overview.md) | Исполненные операции, фильтры и пагинация |
+| [Доход](domains/income/overview.md) | Полученные купоны и дивиденды, периоды и состав расчёта |
+| [Будущие выплаты](domains/income/upcoming-events.md) | Календарь по текущим позициям и ограничения прогноза |
+| [Акции](domains/instruments/stocks.md) и [облигации](domains/instruments/bonds.md) | Поиск выпуска, рыночные показатели и личная история |
 
-[Тематический индекс](AI_INDEX.md) связывает вопросы с соответствующими
-объяснениями. Читать весь репозиторий для ответа на один вопрос не требуется.
+## Найти материал по задаче
 
-## Какому источнику доверять
+| Потребность | Маршрут |
+| --- | --- |
+| Разобраться в системе | [Архитектура](architecture/README.md), нужная область выше, [внешние интеграции](integrations/README.md) |
+| Найти точные сведения | [Глоссарий](glossary.md), [показатели портфеля](domains/portfolio/data-reference.md), [HTTP API](architecture/http-api.md) |
+| Разобрать расхождение в суммах | [Диагностика портфеля](domains/portfolio/how-to/investigate-discrepancy.md) |
+| Проверить условия локальной работы | [Окружение и восстановление](development/local-workspace.md) |
+| Понять ошибку или старые данные | [Состояния интерфейса](architecture/cross-cutting/ui-resilience.md), [свежесть данных](architecture/cross-cutting/data-freshness.md) |
+| Найти визуальные роли и примеры | [Дизайн-система](development/design-system.md), [UI-каталог](development/ui-catalog.md) |
+| Узнать причину архитектурного решения | [Журнал ADR](adr/README.md) |
+| Изменить или проверить систему | [Сопровождение](development/README.md), затем инструкции нужного репозитория |
 
-Документация объясняет текущее устройство и поведение системы. Точный публичный
-HTTP-контракт публикует backend в OpenAPI; ADR сохраняют причины принятых решений.
-Требования и предложения изменений могут отдельно согласовываться в OpenSpec,
-но для понимания описанных сценариев доступ к нему не нужен.
-[Карта владельцев фактов](development/documentation.md#владельцы-фактов)
-помогает различать назначение этих знаний и разрешать расхождения.
+Практический tutorial первого финансового сценария пока не подготовлен:
+он требует подключения брокера, а запуск на новой базе имеет известное
+ограничение. Маршрут первого знакомства выше — чтение, не учебный запуск.
+UI-каталог содержит безопасные вымышленные примеры и поясняет границы их использования.
 
-Текущие объяснения находятся в `architecture` и `features`; руководства — в
-`development`. [Исследования](research/README.md) содержат проверенные наблюдения
-и варианты, [аудиты](audits/README.md) — исторические свидетельства.
-Наличие рекомендации в исследовании или требования в старом change ещё не
-означает, что возможность реализована. Статус каждого ADR указан в
-[журнале решений](adr/README.md).
+## Границы знаний
 
-Основная документация читается самостоятельно, без исходников других
-репозиториев. [Исторические свидетельства](development/README.md#исторические-свидетельства)
-сохраняют исходные технические адреса своего времени и не являются
-обязательным чтением для понимания системы. Документы используют Markdown,
-схемы — Mermaid.
+[Основные спецификации](../specs/AI_INDEX.md) сохраняют согласованное проверяемое
+поведение, а OpenSpec changes — предложения, дизайн и задачи изменений.
+Фактический Store находится в `specs/openspec/`, основные требования — в
+`specs/openspec/specs/`. Docs объясняет систему; код, тесты, схемы и конфигурация
+задают конкретный механизм, а [ADR](adr/README.md) сохраняют принятые решения.
+Локальные инструкции [frontend](../frontend/AGENTS.md) и [backend](../backend/AGENTS.md)
+описывают изменение реализации и её проверки.
+
+Эти источники дополняют друг друга. Найденный незавершённый change не доказывает
+реализованную функцию; расхождение кода и требования требует разбора.
+Итоги исследований входят в ADR, когда принято значимое решение, и в тематические
+страницы, когда уточняют знания о системе. Исходные исследовательские отчёты
+в docs не хранятся. [Исторические свидетельства](development/README.md#исторические-свидетельства)
+сохраняют результаты своего времени и не заменяют текущее описание системы.
+
+Правила изменения текста, диаграмм, ссылок и проверки docs-impact находятся
+в [CONTRIBUTING](CONTRIBUTING.md).