docs: reorganize system knowledge by domain

CONTRIBUTING.md

@@ -0,0 +1,165 @@
+# Ведение документации
+
+Docs даёт самостоятельное понимание продукта, понятий, функций и архитектуры.
+За актуальность затронутого объяснения отвечает автор изменения; review
+сопоставляет текст с требованиями, реализацией и принятыми решениями.
+
+## Владельцы фактов
+
+| Вид знания | Где поддерживается |
+| --- | --- |
+| Согласованное проверяемое поведение: требования и сценарии | [Основные спецификации](../specs/AI_INDEX.md) в `specs/openspec/specs/` |
+| Предложения изменений, их проектирование и задачи | OpenSpec changes в существующем Store `wealth-ledger-specs`, `specs/openspec/changes/` |
+| Понимание системы, областей и взаимодействий | Тематические страницы docs |
+| Принятые решения и подтверждённые причины | Единственный журнал [docs/adr](adr/README.md) |
+| Конкретная реализация и технические контракты | Код, тесты, схемы, конфигурация; публичный OpenAPI формирует backend |
+| Размещение кода, conventions, команды разработки и проверки | Локальные инструкции frontend/backend |
+| Выбор репозитория и типа знания | Корневой [AGENTS](../AGENTS.md) |
+
+Основные спецификации описывают и согласованное текущее поведение.
+Различие specs и docs не является разделением на будущее и настоящее.
+Docs объясняет смысл контракта, не вводя независимо редактируемые требования.
+OpenSpec применяется по явному запросу согласно [принятому процессу](development/openspec-authority-and-lifecycle.md).
+
+## Потребность читателя и структура
+
+Используем Diátaxis для задачи страницы, тематическую структуру для размещения:
+
+| Потребность | Содержание |
+| --- | --- |
+| Разобраться — explanation | Понятия, связи, ответственность, потоки и подтверждённые причины |
+| Найти точные сведения — reference | Определения, значения, единицы, состояния и ограничения интерпретации |
+| Решить задачу — how-to | Условия применения, предпосылки, действия, проверка результата и известные отклонения |
+| Научиться через действие — tutorial | Учебная цель, безопасные исходные данные, последовательность и наблюдаемый результат |
+
+У страницы одна основная потребность; краткий контекст и перекрёстные ссылки
+допустимы. Обзор и маршрут чтения не называются tutorial. Если безопасного
+учебного сценария нет, достаточно честного маршрута чтения.
+
+Отдельный файл нужен самостоятельной теме или задаче, которой тесно в существующем
+объяснении. Не создаём четыре жанра для каждой области, пустые каталоги и заглушки.
+Отчёты аудитов и исследований не размещаются в docs. По итогам исследования
+принятое значимое решение с основаниями, альтернативами и последствиями
+оформляется в ADR; подтверждённые системные знания включаются в тематические
+страницы. Исследование без принятого решения не становится ADR автоматически.
+Архитектура остаётся общей: нет параллельных деревьев frontend/backend, arc42/C4
+или второго архитектурного руководства. Папка области не означает микросервис.
+
+Текст и новые редакционные инструкции пишем по-русски, сохраняя технические
+идентификаторы. Обычные новые файлы — английский `kebab-case.md`, служебные —
+`README.md`, `CONTRIBUTING.md`, `AGENTS.md`. Один термин имеет краткое определение
+в [глоссарии](glossary.md), развёрнутое объяснение — в своей области.
+Имена исторических решений и язык нормативных спецификаций сохраняются.
+
+## Факты, неизвестность и расхождения
+
+До существенного утверждения установи, что его подтверждает: спецификация
+фиксирует договорённость, код и проверки — механизм, ADR — причины выбора.
+Незавершённый change подтверждает намерение. Учитывай локальную ветку и diff;
+текущая ветка не становится автоматически проверенным состоянием всей системы.
+
+Основная ветка docs должна описывать последнее согласованное и проверенное
+реализованное состояние workspace. Предложения находятся в change-артефактах
+или рабочих ветках. При поставке только части сценария не обещай готовность целого.
+
+При конфликте различай устаревшие docs, устаревшую спецификацию, дефект реализации
+и незавершённое изменение. Исправляй подтверждённо устаревшее объяснение.
+Спорное требование или дефект не меняй скрытно; существенное расхождение отметь
+рядом с описанием, если без него читатель будет введён в заблуждение.
+Отсутствие найденного доказательства формулируй как «не удалось подтвердить».
+
+Не выводи мотивацию из факта использования технологии. Retries, TTL, лимиты,
+формулы, гарантии, роли и окружения описывай только по подтверждённому источнику.
+Локальная конфигурация не доказывает production-топологию. Примеры используют
+вымышленные данные или безопасные fixtures; секреты и реальные брокерские данные
+не входят в документацию или диагностические отчёты.
+
+## Ссылки и единые определения
+
+Основной материал объясняет систему без открытия исходников или conventions.
+Адресная ссылка на требование, ADR, репозиторий или технический артефакт дополняет
+объяснение. Не копируй DTO, весь OpenAPI или внешний API reference.
+Нужные точные значения сопровождай определяющим источником, чтобы не создать
+конкурирующую норму. Паспорта страниц, Evidence-секции и номера строк не требуются.
+
+Внутри docs используем относительные Markdown-ссылки. Между репозиториями —
+относительный путь через соседний корень, например `../specs/AI_INDEX.md` из README.
+Проверяй регистр, файл и якорь в фактическом workspace. Перенос требует исправить
+входящие ссылки активных Markdown-документов; исторические архивы и dated audits
+сохраняют адреса своего времени. Короткий указатель оставляем только при реальной
+необходимости совместимости, без второй копии содержания.
+
+Все содержательные страницы достижимы из подходящего тематического входа.
+Общий вход — [README](README.md); второй ручной индекс с той же картой не нужен.
+
+## Архитектура, диаграммы и ADR
+
+arc42 служит проверкой полноты вопросов: цели, ограничения, контекст, стратегия,
+структура, runtime, размещение, сквозные концепции, решения, качество, риски
+и термины. [Архитектурный вход](architecture/README.md) ведёт к раскрытым вопросам;
+пробелы обозначаются без выдуманных SLA, стейкхолдеров и quality tree.
+
+C4 Context показывает WealthLedger одной системой, пользователей и внешние
+системы. Container показывает приложения и хранилища с технологиями и связями.
+Embedded SQLite не является сетевым сервером; генерация OpenAPI-клиента относится
+к разработке, не к runtime. Детализация Component нужна только для существенного
+вопроса. Deployment описывает конкретное подтверждённое окружение.
+
+Новые диаграммы — Mermaid в Markdown: `flowchart` для структуры,
+`sequenceDiagram` для взаимодействий. Рядом укажи название, уровень или область,
+типы участников и смысл; подпиши связи, протоколы — только на уместном уровне.
+Одно представление имеет один поддерживаемый источник, другие страницы ссылаются
+на него. При конвертации прежней схемы сохраняй содержание и проверяй замену
+до удаления исходника. Синтаксис, рендер и согласованность с текстом проверяются
+отдельно; отсутствие рендерера явно указывается в отчёте.
+
+Журнал ADR один: `adr/`. Сохраняй идентификатор, исторический контекст, статус,
+причины и связи решения. Подтверждённо заменённое решение связывается с новым,
+а не переписывается под текущее устройство. Новый ADR нужен принятому значимому
+решению с подтверждёнными причинами, не редакционному перемещению файла.
+
+## Обновление вместе с кодом
+
+| Фаза работы | Docs-impact |
+| --- | --- |
+| Анализ | Определи затронутые понятия, потоки и ограничения |
+| Спецификация | При согласовании требований включи нужные обновления docs в существующие задачи |
+| Реализация | Готовь текст параллельно, сохраняя различие поставленного и незавершённого поведения |
+| Проверка | Сопоставь требования, реализацию, текст и диаграммы |
+| Завершение | Закончи связанные обновления либо обоснуй отсутствие docs-impact |
+
+Изменение понимания системы требует обновления docs. Локальный рефакторинг без
+изменения смысла, сценариев и ограничений может его не требовать. Если есть
+OpenSpec change ID, используй его как общую ссылку связанных изменений
+репозиториев; отдельная система идентификаторов не вводится.
+
+Review проверяет сохранность уникальных знаний, верность терминов и финансовых
+единиц, границы доступа, поведение ошибок, самостоятельность текста, нужные ссылки
+и отсутствие обещаний по незавершённым изменениям. Успешный lint этого не доказывает.
+
+## Проверки
+
+Из корня docs с уже установленными зависимостями:
+
+```bash
+nvm use --silent
+npm run verify
+```
+
+Существующий gate запускает Markdown lint с проверкой относительных ссылок
+и якорей, затем `git diff --check`. Он охватывает новые Markdown-файлы;
+обычный diff их не показывает, поэтому отдельно просмотри untracked-содержание.
+При изменениях соседних репозиториев выполни там `git diff --check` и проверь
+затронутые ссылки. Markdown-only правки не требуют тестов всего приложения.
+
+Точный scope исключений задан существующими `package.json` и конфигурацией lint:
+исторические свидетельства не обязаны разрешать прежние адреса.
+Правило relative-links не проверяет внешние URL и HTML-ссылки. Mermaid-рендер
+в gate не входит; используй доступный локальный рендерер без отправки материалов
+наружу, установки стека или добавления новых валидаторов. Публикационного
+генератора в текущем docs не настроено.
+
+Вручную пройди затронутые маршруты: новичок от продукта к ключевой области;
+разработчик от вопроса к объяснению и требованию; агент от типа задачи к нужным
+ограничениям, ADR и репозиторию. Отчёт различает синтаксис, ссылки, рендер,
+смысловую сверку и оставшиеся ограничения.