ADR-0012 · Публичный сайт документации play-api и граница «вики vs сайт»
Статус: принято · 2026-07-16 (issue: play-api#121). Дополняет ADR-0009/ADR-0010 (DX бот-платформы).
Контекст. У движка и analytics есть сайты документации (Astro + Starlight + GitHub Pages), у play-api — нет: публичный контракт Bot API живёт одним файлом docs/bot-api.md (читается как blob на GitHub), процедура верификации честности костей описана только по-русски в вики (06-Chestnost-kubikov-provabli-feyr-i-verifikatsiya), дизайн/ADR — здесь же в вики. При этом play-api — единственный сервис, чья документация обращена наружу: стратегия бот-платформы (ADR-0009/0010, фаза F плана 08) — это сторонние разработчики, подключающие ботов с минимальным трением; впереди публичные leaderboard API (D.2), webhook-контракт (F.1–F.2) и OpenAPI/SDK/темплейты (F.3), которым нужен дом.
Решение. Завести для play-api публичный англоязычный сайт документации по отработанному в экосистеме паттерну analytics (Astro + Starlight в docs/, CD с paths-filter на docs/** → GitHub Pages, mise run docs:dev) — и зафиксировать границу двух слоёв документации:
- Вики dicechess-docs (русский) — внутреннее: дизайн-документы, ADR, роадмап, планы выполнения.
- Сайт play-api (английский) — публичное: контракты (Bot API, ndjson-стрим, leaderboard, позже webhook/OpenAPI) и гайды, включая новую страницу верификации provably-fair костей на английском (сегодня такой публичной страницы не существует ни в одном виде).
Тайминг: не сейчас. Строить вместе с D.2 (play-api#103 — первый новый публичный API, который надо документировать) или первым шагом фазы F. Issue play-api#121 фиксирует скоуп MVP: скаффолд, переезд bot-api.md (со стабом-указателем на старом пути), страница верификации костей, Dependabot/Renovate с первого дня, правка доктрины в AGENTS.md.
Последствия.
- DX для сторонних разработчиков: навигация/поиск/стабильные URL вместо GitHub-blob; консистентность с движком и analytics (один паттерн на всю экосистему, копируется почти дословно).
- Закрывается дыра доверия: provably-fair работает, только если внешний человек может проверить процедуру — появится каноническая публичная страница (с учётом CRN-исключения: сид пары раскрывается после завершения обеих партий, play-api#115).
- Цена: ещё один
package.json, который гниёт, — свежий сигнал: Astro-сайт самой вики накопил 18 dependabot-advisories. Отсюда обязательные Dependabot/Renovate в скоупе MVP. - Правка доктрины play-api AGENTS.md («документация контрактов — file-head комментарии + вики»): добавляется третий слой, в update-trigger map — «изменение публичного API → страница сайта».
- Backend-CI не затрагивается (paths-filter), релизный цикл сайта независим.
Альтернативы (отклонены). Оставить bot-api.md как есть — работает для хакеров, но не масштабируется на D.2/F-контент и не даёт дома странице верификации; blob-ссылки — слабый онбординг для «платформы с минимальным трением». Публиковать англоязычные контракты из этой вики — смешивает аудитории и языки, ломает границу «внутреннее/внешнее», привязывает публичный продуктовый контент к личному Obsidian-потоку. Один общий сайт на всю экосистему — расходится с уже сложившимся паттерном «сайт при репозитории» у движка и analytics и создаёт кросс-репо связность на пустом месте.