easy-png-tools2/docs/README.md

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

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

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

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

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

| Документ                           | Роль                                                 | Статус |
| ---------------------------------- | ---------------------------------------------------- | ------ |
| `AGENTS.md`                        | Краткий обязательный контракт для агента             | active |
| `docs/plan-codebase-quality.md`    | План quality gates, тестов и lint-правил             | draft  |
| `docs/agent-workflow.md`           | Подробный порядок исследования, изменения и проверки | active |
| `docs/testing-strategy.md`         | Locator, fixture, i18n и fixme-policy для e2e        | active |
| `docs/quality-gates.md`            | Команды проверки, warnings и CI                      | active |
| `docs/backlog.md`                  | Продуктовые, UX- и инфраструктурные задачи           | active |
| `docs/roadmap.md`                  | Общие направления развития                           | active |
| `docs/plan-redesign.md`            | Новый дизайн production UI                           | active |
| `docs/plan-seo.md`                 | SEO/GEO-план                                         | active |
| `docs/plan-platform.md`            | PWA/API/WASM-план                                    | active |
| `docs/checklist-manual-testing.md` | Ручная приёмка production UI                         | active |
| `docs/tools-map.md`                | Живая карта инструментов                             | active |
| `web/eslint-plugins/README.md`     | Детали custom lint rules и token policy              | active |
| `docs/archive/README.md`           | Правила архивирования и удаления старых документов   | active |

`docs/archive/` содержит временную историческую справку и не является текущим
источником критериев приёмки. Для старых документов действует срок хранения 30
дней; после него их удаляют, а при необходимости достают из git history.

## Где хранить новую информацию

- Поведение, которое агент обязан соблюдать сразу, — кратко в `AGENTS.md`.
- Точные команды, параметры скриптов и критерии качества — в
  `docs/quality-gates.md` или в README соответствующей подсистемы.
- Архитектура, потоки данных и границы модулей — в отдельном architecture-плане
  или документе, не дублируя существующие планы.
- Реализация lint-правил, fixtures и технические детали ESLint — в
  `web/eslint-plugins/README.md` и исходниках правил.
- Продуктовые решения и ручная приёмка — в backlog, плане и checklist.

Подробные материалы хранятся в `docs/`, а не в корне. Новый файл создаётся
только если темы нет в существующем документе; иначе обновляется источник
истины.

## Текущий baseline Q7a

На момент фиксации Q7a:

- production registry содержит 122 инструмента;
- `pnpm --dir web check` проходит без ошибок и предупреждений;
- `pnpm --dir web test` — 45 test files / 497 tests, включая тесты token audit и
  PostCSS HCT-плагина;
- `pnpm --dir web test:rules` — 4 test files / 74 tests;
- `pnpm --dir web lint:all` — 0 errors, 0 i18n warnings и 0 unused design tokens
  от token audit;
- coverage `src/lib` — statements 91.77%, branches 83.3%, functions 74.31%,
  lines 92.53% при порогах 90 / 82 / 72 / 91;
- `pnpm verify` проходит;
- `pnpm --dir web test:e2e` — 276 тестов в четырёх проектах: 276 passed, 0
  skipped, 0 failed. Отказ декодера битого PNG зафиксирован per-engine в
  `web/e2e/png-fixtures.spec.ts`.

Baseline и следующий шаг поддерживаются в `docs/plan-codebase-quality.md`.

## Правила актуальности

- У активного документа есть статус: `draft`, `active`, `completed` или
  `archived`.
- Ссылки на конкретный файл или команду проверяются при изменении источника
  истины.
- Архивный документ не возвращается в live-критерии без явной сверки.
- После каждого шага плана агент останавливается, показывает изменённые файлы,
  проверки и нерешённые решения, и ждёт ревью.