# Как поддерживать документацию ## При каждом изменении 1. Определите затронутые компоненты по [карте архитектуры](ARCHITECTURE.md) и прочитайте их локальные `AGENTS.md`. 2. Если меняются наблюдаемое поведение, операция API, формат данных, конфигурация или способ запуска, обновите профильную документацию в том же наборе изменений. Для DM проверьте также документы о доставке, технических вставках и файлах; для Solana — формат PDA и инструкции инициализации. 3. Если изменился состав компонентов или поток данных, обновите `ARCHITECTURE.md`; если появился новый раздел, обновите этот каталог. Публичный README меняйте при изменении возможностей, статуса или способа запуска. 4. Запустите `python3 scripts/check_docs.py` из корня репозитория: он проверяет локальные ссылки в документах и соответствие индекса зарегистрированным WS-операциям. Затем проверьте точность команд/путей вручную. Сравните утверждения с конкретными файлами кода или конфигурации. Непроверенное обозначьте как «требует сверки», планы — как «планируется». 5. В описании изменения укажите, какие документы обновлены и что проверено. Если документацию менять не требуется, кратко объясните почему. Особые связки: изменение формата блоков требует обновления профильного файла в `Blockchain/` и `Blockchain/CHANGELOG.md`; изменение серверных операций — профильного файла в `API/` и индекса операций; изменение синхронизации Solana users — `Solana/SOLANA_USERS_SYNC_MODULE_DESIGN.md` и `../deploy/SOLANA_USERS_SYNC_SERVER_SETUP.md`; изменение экранов ESP32 — спецификации устройства и скетча. В журнале блокчейна не требуйте хэш ещё не созданного коммита: фиксируйте дату и суть изменения, а ссылку на коммит добавляйте после его появления, если она нужна. ## Источники и статусы - **Реализовано** — подтверждено кодом; укажите модуль и, если полезно, проверенный сценарий. - **Тестовый контур** — работает только с тестовыми значениями, ключами или namespace; не обещайте production-поведение. - **Планируется** — проектное решение, ещё не являющееся контрактом. - **История/архив** — полезно для контекста, но не для новых интеграций. Когда документы противоречат друг другу, сначала проверяйте код и тесты, затем правьте обе стороны противоречия. Точные форматы держите в профильной спецификации; обзорные файлы должны ссылаться на неё, а не копировать таблицы байтов или адреса. Для решений, меняющих протокол или требующих согласия на деплой, действуют ограничения из корневого и локальных `AGENTS.md`.