docs: make project documentation self-contained

development/documentation.md

@@ -0,0 +1,88 @@
+# Ведение документации
+
+Документация объясняет систему независимо от размещения исходного кода.
+За актуальность затронутого объяснения отвечает автор изменения предметной
+области; проверка сопоставляет изложение с фактическим поведением и принятыми
+решениями. Ответственность подсистем описана в [карте возможностей](../features/README.md).
+
+## Владельцы фактов
+
+| Тип знания | Где объясняется | Граница достоверности |
+| --- | --- | --- |
+| Устройство и взаимодействие системы | [Обзор](../architecture/system-overview.md) | Описывает существующие подсистемы, данные и потоки |
+| Наблюдаемое поведение | [Возможности](../features/README.md) | Сценарий, инвариант, ошибка и ограничение объясняются здесь полностью |
+| Значение терминов | [Глоссарий](../architecture/domain-glossary.md) | Одно определение, ссылки из связанных сценариев |
+| HTTP-контракт | [HTTP API](../architecture/http-api.md), публичный OpenAPI backend | Объяснение семантики не создаёт второй независимо редактируемый wire contract |
+| Причины значимого решения | [ADR](../adr/README.md) | Контекст, решение и последствия относятся к указанному статусу решения |
+| Окружение и восстановление | [Локальное окружение](local-workspace.md) | Предпосылки и ограничения описаны без знания устройства репозиториев |
+| Принципы сопровождения | [Engineering governance](engineering-governance.md) | Объясняют согласованность и доказательства результата |
+| Гипотезы и внешние наблюдения | [Исследования](../research/README.md) | Рекомендация не означает реализованную возможность |
+| Результаты прежних проверок | [Исторические свидетельства](README.md#исторические-свидетельства) | Действительны для состояния и условий своего времени |
+
+Поведенческие требования и предложения изменений могут отдельно согласовываться
+в OpenSpec. Их роль описана [здесь](openspec-authority-and-lifecycle.md);
+понимание текущего сценария не требует доступа к хранилищу спецификаций.
+
+При конфликте возможны устаревший текст, нарушение договорённости реализацией
+или незавершённое изменение. Текущее поведение не отменяет согласованное
+требование автоматически. Неустановленный смысл явно отмечается для ручного
+решения; особенно это важно для безопасности, данных и публичного контракта.
+
+## Куда поместить знание
+
+Объяснение принадлежит существующему документу о соответствующей области.
+Понятие определяется в глоссарии; сценарий связывает его с поведением и
+ограничениями; ADR сохраняет причину выбора; исследование — ещё не принятый
+вариант и его источники. Новый документ нужен для самостоятельного вопроса,
+которому нет подходящего места. Навигация делает его доступным из индекса.
+
+Один факт имеет одно полное объяснение, на которое ссылаются остальные страницы.
+Ссылка внутри документации уточняет контекст, а не скрывает необходимое условие
+понимания за внутренним файлом другого репозитория.
+
+## Содержание страницы
+
+Связное объяснение содержит назначение, ответственность компонентов,
+предпосылки и инварианты, основной поток, ошибки, восстановление и ограничения.
+Диаграмма нужна, когда помогает понять взаимодействие. Это ориентир, а не
+обязательный набор пустых разделов.
+
+Вместо имён классов, внутренних вспомогательных функций и настроек разработки
+излагается их архитектурный или функциональный смысл. Публичные API, единицы
+показателей, внешние системы и принятые технологические решения остаются
+частью объяснения, если нужны читателю. Детали разработки и инструкции
+инструментам не входят в описание системы.
+
+Статус понятен из вступления или индекса: текущее поведение, объяснение решения,
+исследование или история. Дата наблюдения не гарантирует актуальность спустя
+время. Для замены принятого решения сохраняются его прежний контекст и ссылка
+на последующее решение.
+
+## Обновление вместе с кодом
+
+| Что изменилось в системе | Какое знание затронуто |
+| --- | --- |
+| Сценарий, инвариант, ошибка или восстановление | Объяснение возможности и её ограничений |
+| Ответственность, внешний источник или поток данных | Обзор, схема и причина значимого решения |
+| Значение понятия | Глоссарий и связанные сценарии |
+| Окружение, диагностика или граница проверки | Материалы сопровождения |
+| Новая возможность | Карта возможностей и тематический индекс |
+| Только внутреннее устройство без изменения описанных знаний | Изменение документации может не требоваться |
+
+Изменения нескольких компонентов относятся к общей задаче; объяснение
+поставленного результата не должно обещать ещё отсутствующую часть.
+Смысловая согласованность важнее совпадения названий задач и формальных отметок.
+
+## Проверка
+
+Проверка охватывает Markdown, внутренние ссылки и якоря, доступность страниц
+через навигацию и чтение основной документации без соседних репозиториев.
+Внешние URL и HTML-ссылки не проверяются правилом относительных ссылок.
+Исторические аудиты, журнал устранения замечаний и свидетельства завершения
+сохраняют исходные адреса отдельно от основной книги.
+
+Смысловая проверка подтверждает, что читатель понимает ответственность,
+инвариант и ограничение; будущая возможность не выдана за существующую;
+API и архитектура не изменены редакторским пересказом. Непонятный смысл
+внешней ссылки отмечается для ручной проверки, а не восполняется догадкой.
+Успешная синтаксическая проверка не доказывает актуальность знания.