docs/CONTRIBUTING.md

# Ведение документации

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 и репозиторию. Отчёт различает синтаксис, ссылки, рендер,
смысловую сверку и оставшиеся ограничения.