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

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

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

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

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

| Документ                           | Роль                                                 | Статус |
| ---------------------------------- | ---------------------------------------------------- | ------ |
| `AGENTS.md`                        | Краткий обязательный контракт для агента             | active |
| `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-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/`, чтобы не засорять
корень репозитория. Не создавать отдельные `docs/commands.md`,
`docs/known-issues.md` или копию backlog: команды принадлежат `quality-gates`,
известные проблемы — backlog и checklist. `README.md` в корне остаётся кратким
обзором продукта, а не вторым руководством агента.

Новый документ создаётся только когда темы нет в существующем файле; иначе
обновляется источник истины. Активный документ имеет статус (`draft`, `active`,
`completed`) и понятную область применения.

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

## Текущий baseline

- production registry содержит 122 инструмента;
- `pnpm --dir web check` проходит без ошибок и предупреждений;
- `pnpm --dir web test` — 46 test files / 534 tests, включая тесты token audit,
  PostCSS HCT-плагина и правил линтинга;
- `pnpm --dir web test:rules` — 5 test files / 104 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`.

Состав проверок и их семантика описаны в `docs/quality-gates.md`, тестовая
архитектура — в `docs/testing-strategy.md`. Baseline обновляется здесь при
изменении любого из гейтов.

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

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