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

> Статус: **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/plan-domain.local.md`        | Чек-лист переименования бренда и покупки домена    | 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` не разрешаются. Строка
в таблице оставлена, чтобы задачу R1/R2 можно было найти по индексу; сам
чек-лист лежит только на машине разработчика.

## Правила

- У каждой темы ровно один владелец: остальные документы ссылаются на него, а не
  пересказывают. Новый документ создаётся, только если темы нет в существующем.
- У документа есть статус (`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/plan-domain.local.md` (файл вне git). Всё остальное
  неразрешимое — ошибка.
- Протокол «остановиться и показать изменения» — `docs/agent-workflow.md`,
  раздел 6.