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

> Статус: **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 Q6c

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

- production registry содержит 122 инструмента;
- `pnpm --dir web check` проходит без ошибок и предупреждений;
- `pnpm --dir web test` — 42 test files / 455 tests;
- `pnpm --dir web test:rules` — 4 test files / 74 tests;
- `pnpm --dir web lint:all` — 0 errors и 0 i18n warnings; остаются 4 unused
  design tokens от token audit;
- `pnpm verify` проходит; production E2E — 112 passed, 0 skipped.

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

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

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