easy-png-tools2/docs/README.md

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

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

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

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

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

Документ	Когда читать	Статус
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/checklist-manual-testing.md	Ручная приёмка production UI	active
web/eslint-plugins/README.md	Правка lint-правил, токенов и их конфигов	active
docs/archive/README.md	Архивирование и удаление старых документов	active

Правила

• У каждой темы ровно один владелец: остальные документы ссылаются на него, а не пересказывают. Новый документ создаётся, только если темы нет в существующем.
• У документа есть статус (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/agent-workflow.md, раздел 6.