Карта документации проекта (issue #172, #178 / эпик #102, PR-13). Обзор и быстрый старт — в корневом README.
| Хочу… | Документ |
|---|---|
| Установить (pipx / из исходников), настроить OAuth, диагностика | installation.md |
| Запустить грейдер, режимы 1–4, CLI-флаги, web/IDE, скачать задачу | grader-workflow.md |
| WEB MVP: три блока (Проверка решений, Downloader, Глоссарий-модуль), микро-бенчмарк, error/action cards — что реализовано | web-current.md |
| WEB MVP: замыслы, отложенное, отклонённое | web-design.md |
Справочник HTTP API --serve: эндпоинты, лимиты, коды ответов, curl-примеры |
api.md |
Справочник: конфигурация ([tool.stepik-grader]), форматы тест-кейсов, ограничения и безопасность |
configuration.md |
Локальный глоссарий: формат JSON карточек/очереди, Python-API (stepik_grader.glossary) |
glossary.md |
| Понять архитектуру: модули, слои, граф зависимостей, «что умеет» | architecture.md |
| Контракт результата проверки (поля, вердикты) для CLI/Web/API | result-contract.md |
| Дизайн server mode: Runner-слой, API удалённого исполнения, sandbox | server-mode.md |
| Диагностический режим и лог-файл (редакция секретов, opt-in) | logging.md |
| Архитектурные решения (ADR) | adr/README.md |
| Посмотреть дерево файлов проекта | project-structure.md |
| Сравнить версии и отличия от оригинала | versions.md |
| Полный список изменений | ../CHANGELOG.md |
| Внести вклад: код-стайл, форматы тестов, версионирование | ../CONTRIBUTING.md |
| Инварианты ядра и правила для агентов | ../CLAUDE.md |
| Политика безопасности, ответственное раскрытие уязвимостей | ../SECURITY.md |
| Постановки будущих задач для Claude Code (#125/#186/#187/#129, версии #161/#163; #126 — foundation готов, доводка #191; #190 закрыт) | claude-handoff.md |
| История спринтов и roadmap (архив) | history.md |
Каждая тема живёт ровно в одном каноническом файле. Остальные документы ссылаются на него, а не копируют содержимое. При обновлении темы правь только её канонический файл (issue #178).
| Тема | Канонический источник | Не дублировать в |
|---|---|---|
| Обзор проекта, бейджи, основные возможности | README | docs/* |
| Установка, OAuth, secrets.json, диагностика | installation.md | README (только короткий quick start) |
| Режимы работы, CLI-флаги, web/IDE, скачивание задачи | grader-workflow.md | README, CONTRIBUTING |
| WEB MVP — что реализовано (два раздела / три блока: проверка + Downloader + Глоссарий-модуль, микро-бенчмарк, error/action cards) | web-current.md | grader-workflow.md (там — текущий --serve, не подробности UI) |
| WEB MVP — замыслы, отложенное, отклонённое (будущая архитектура web UI) | web-design.md | web-current.md (там — только реализованное) |
Справочник HTTP API (эндпоинты/параметры/лимиты/коды/curl для --serve) |
api.md | server-mode.md (там — дизайн будущего сетевого API, не справочник по текущим эндпоинтам) |
Конфигурация ([tool.stepik-grader]), форматы тест-кейсов, ограничения и безопасность |
configuration.md | README, CONTRIBUTING, grader-workflow.md |
Формат JSON локального глоссария (карточки/очередь) и API stepik_grader.glossary |
glossary.md | web-current.md (там — продуктовый контекст, не формат хранения) |
| Архитектура: модули, слои, граф зависимостей, «что умеет» | architecture.md | README, CLAUDE.md (там — инварианты, не дублирующее описание) |
| Контракт результата проверки (поля case/solution/run, вердикты, стабильность) | result-contract.md | web-current.md (там — ViewModel-надстройки), configuration.md (там — таблица вердиктов) |
| Дизайн server mode (Runner/SandboxRunner, API удалённого исполнения, sandbox-требования) | server-mode.md | SECURITY.md (там — короткая политика), ADR-0001 (там — решение, не спецификация), api.md (там — текущие эндпоинты, не дизайн) |
| Диагностический режим, лог-файл, редакция секретов | logging.md | SECURITY.md, configuration.md |
| Архитектурные решения (контекст/решение/альтернативы/последствия) | adr/README.md | docs/* (дизайн-доки описывают «как», ADR — «почему») |
| Дерево файлов проекта | project-structure.md | README |
| Сравнение версий, отличия от оригинала | versions.md | README |
| История релизов (детальный changelog) | ../CHANGELOG.md | versions.md (там — только качественные скачки) |
| Политика версионирования (схема тег=MINOR+1, release vs dev) | ../CONTRIBUTING.md § Версионирование | README, CLAUDE.md, versions.md, history.md |
| Инварианты ядра, правила для агентов | ../CLAUDE.md | docs/* |
| История спринтов/roadmap, подробные примечания к issue (архив) | history.md | CLAUDE.md (там — только действующие инварианты) |
| Постановки будущих реализаций для Claude (scope/non-goals) | claude-handoff.md | CLAUDE.md (там — короткие указатели); канон продукта — web-current.md/web-design.md |
Версия проекта — без ручного source of truth в доках. Актуальный номер берётся из git-тега /
importlib.metadata(бейдж релиза в README тянетgithub/v/release), а схема нумерации канонически описана в CONTRIBUTING.md. Не вписывайversion-X.Y.Zвручную в README как единственный источник истины.