Документация проекта

Статус: active. Индекс документов. Обязательный краткий контракт — в AGENTS.md, подробные правила — в самих документах.

Порядок чтения

AGENTS.md — команды, инварианты и карта «что читать под задачу».
Этот файл — выбрать актуальный документ по теме.
Соответствующий план или checklist темы.
Исходники, конфигурация и тесты рядом с изменяемым кодом.

Активные документы

Документ	Когда читать	Статус
`AGENTS.md`	Всегда: контракт агента	active
`docs/README.md`	Индекс документов, правила ведения документации	active
`docs/architecture.md`	Слои, поток данных, новый инструмент/поле/маршрут	active
`docs/quality-gates.md`	Какие проверки запускать, пороги, coverage, CI	active
`docs/decisions.md`	Правка самих гейтов; чтение CI после пуша	active
`docs/agent-workflow.md`	Порядок работы, нагрузка на машину, протокол ревью	active
`docs/testing-strategy.md`	Правка e2e: locator-ы, fixtures, browser matrix	active
`docs/backlog.md`	Продуктовые, UX- и инфраструктурные задачи	active
`docs/roadmap.md`	Направления развития, фазы 1–11	active
`docs/tools-map.md`	Актуальный список инструментов против реестра	active
`docs/tools-audit.md`	Сырые UX/UI-находки по инструментам (вход аудита)	active
`docs/plan-fields-audit-fixes.md`	Разбивка аудита на волны правок	draft
`docs/plan-seo.md`	SEO/GEO-план	active
`docs/plan-platform.md`	API/PWA/шрифты-план	active
`docs/plan-domain.local.md`	Чек-лист переименования бренда и покупки домена	active
`docs/checklist-manual-testing.md`	Ручная приёмка production UI	active
`web/eslint-plugins/README.md`	Правка lint-правил, токенов и их конфигов	active
`docs/archive/README.md`	Архивирование и удаление старых документов	active

docs/plan-domain.local.md исключён из git через .gitignore: выбранное имя домена не должно попасть в историю до покупки. В клоне файла нет — это ожидаемо, и ссылки на него в plan-seo.md и backlog.md не разрешаются. Строка в таблице оставлена, чтобы задачу R1/R2 можно было найти по индексу; сам чек-лист лежит только на машине разработчика.

Правила

У каждой темы ровно один владелец: остальные документы ссылаются на него, а не пересказывают. Новый документ создаётся, только если темы нет в существующем.
У документа есть статус (draft, active, completed, archived) и понятная область применения. Ссылки на конкретный файл или команду проверяются при изменении источника истины.
Подробные материалы живут в docs/, а не в корне. Не создавать отдельные docs/commands.md или docs/known-issues.md: команды принадлежат quality-gates, известные проблемы — backlog и checklist. README.md в корне остаётся кратким обзором продукта, а не вторым руководством агента.
docs/backlog.md содержит только открытые задачи: выполненные удаляются, а критичные для проекта факты из них переносятся в тематический документ.
docs/archive/ — временная историческая справка, не источник критериев приёмки; срок хранения 30 дней, файлы восстановимы из git history. Единственный документ в архиве со статусом active — docs/archive/README.md: он описывает процедуру архивирования, а не архивный материал, поэтому не подлежит 30-дневному удалению.
Ссылаясь на инструмент, сверяться с реестром: внутреннее имя (id) — в web/src/lib/registry/tools/, адрес и имя страницы (slug) — в web/src/lib/registry/pages/; исторические названия в старых планах не действуют (docs/architecture.md, раздел 3).
Поиск по docs/ задевает docs/archive/: там вынесены завершённые планы и исследования, поэтому grep по docs/ даёт больше шума, чем пользы. Для правок production-кода архив не нужен: grep по docs/*.md без archive/.
Проверка ссылок в документации не автоматизирована; ожидаемо неразрешимыми считаются ссылки на docs/plan-domain.local.md (файл вне git). Всё остальное неразрешимое — ошибка.
Протокол «остановиться и показать изменения» — docs/agent-workflow.md, раздел 6.