easy-png-tools2/docs/README.md

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

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

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

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

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

| Документ                           | Когда читать                                       | Статус |
| ---------------------------------- | -------------------------------------------------- | ------ |
| `AGENTS.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–10                    | 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 |

`docs/plan-domain.local.md` исключён из git через `.gitignore` (выбранное имя
домена не должно попасть в историю до покупки). Ссылки на него в `plan-seo.md` и
`backlog.md` при клонировании репозитория не разрешаются — это ожидаемо.

## Правила

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