specs/openspec/changes/archive/2026-08-24-refresh-project-documentation-and-agent-entrypoints/design.md

Context

См. мотивацию в proposal.md. В текущем workspace durable documentation уже разделена на architecture, development, features, adr и audits, но README frontend/backend остаются template-страницами, indexes неполны, а корневые MVP.md и CONTEXT.md создают отдельный маршрут поиска фактов. Canonical OpenSpec store уже закреплён, поэтому новый change не создаёт параллельных requirements или planning artifacts в docs.

Goals / Non-Goals

Goals:

• Сделать docs единственной точкой входа для фактической архитектурной карты, domain glossary и navigation по delivered features.
• Сделать README каждого application repository компактным, воспроизводимым onboarding entrypoint для разработчика и AI-агента.
• Удалить завершённую MVP-карту и обновить ссылки так, чтобы durable docs и scoped instructions не противоречили delivered поведению.
• Сохранить precise glossary terms и единственный detailed источник статуса deferred Prisma e2e — remediation registry.

Non-Goals:

• Не менять runtime-код, HTTP contract, зависимости, generated artifacts, CI/CD или Prisma e2e implementation.
• Не вводить постоянный docs-linter, второй verification interface или новый ADR: relocation glossary и документационная навигация не являются необратимым архитектурным решением.
• Не переписывать immutable audit snapshots и historical OpenSpec archives.

Decisions

docs/architecture владеет обзором и glossary

docs/architecture/system-overview.md будет короткой factual map: delivered capabilities, локальные границы и два Mermaid data flow. Рядом domain-glossary.md заменит корневой CONTEXT.md без переименования терминов. docs/architecture/README.md свяжет оба документа и ADR index.

Альтернатива — оставить CONTEXT.md в root — отвергнута: она сохраняет параллельную и плохо discoverable точку входа. Альтернатива — встроить glossary в overview — отвергнута: glossary изменяется независимо и ухудшит навигацию.

README остаются тонкими, специализированные документы — владельцами деталей

frontend/README.md и backend/README.md будут содержать назначение, prerequisites, .env/bootstrap, короткий перечень gates и ссылки на authoritative docs. FSD, API, testing, OpenAPI и detailed Prisma diagnosis остаются в уже существующих JIT/development документах.

Альтернатива — повторить полные инструкции в каждом README — отвергнута: она создаёт новый источник дрейфа.

Deferment Prisma описывается единожды

README backend и system overview кратко отмечают, что e2e не является passing gate, и ссылаются на docs/development/audit-remediation.md. Реестр остаётся владельцем версии Prisma, воспроизведения и review trigger.

Альтернатива — скрыть e2e из onboarding — отвергнута: это создаёт ложный зелёный verdict. Альтернатива — дублировать diagnostics — отвергнута из-за drift risk.

Проверка остаётся review-oriented

Tasks потребуют read-only link/path check, git diff --check, OpenSpec validation и независимый review; новая постоянная documentation-linter команда не добавляется по согласованному scope.

Risks / Trade-offs

• [Удаление root файлов оставит входящие ссылки] → выполнить repository-wide read-only search и обновить только активные entrypoints; historical audit и archive paths сохранятся как исторические evidence.
• [Overview продублирует OpenSpec или feature docs] → ограничить его картой capabilities, boundaries и ссылками, не requirements/API details.
• [README снова устареют] → держать detailed policy в designated durable/JIT docs и проверять README против фактических package scripts и .env.example в рамках change review.
• [Prisma deferment будет прочитано как разрешение игнорировать e2e] → явно назвать e2e deferred, указать registry и не объявлять общий workspace verdict.

Migration Plan

1. Создать и проверить новую документационную навигацию и README entrypoints.
2. Переместить glossary content в docs/architecture/domain-glossary.md, обновить active links и удалить root CONTEXT.md и MVP.md.
3. Выполнить non-mutating documentation/SDD checks и independent review.
4. После успешного archive добавить terminal evidence WL-P2-10 в remediation registry; history и immutable audit snapshots не переписывать.