Как поддерживать документацию

Сайт собирается из markdown в репозитории poker-docs. Правка — обычный коммит.

Как добавить статью

Положите файл в src/content/docs/product/ или src/content/docs/dev/ — дорожка определяется директорией. Фронтматтер:

---
title: Запись на турнир
description: Одна строка о том, что читатель узнает
track: product          # product или dev
verified: 2026-08-24    # дата сверки с кодом
sources:                # файлы, по которым сверяли
  - repos/poker-api/apps/server/src/registrations
sidebar:
  order: 20
---

sidebar.order задаёт порядок и в боковом меню, и в llms.txt — это один источник, второго списка нигде нет.

Шаблон продуктовой статьи: зачем → что видит пользователь → правила и пограничные случаи → статусы → что рядом. Шаблон инженерной: что это и где код → контракт → как работает внутри → ограничения и грабли → что рядом.

Раздел «что рядом» обязателен. Он заменяет дублирование: продуктовая статья кончается ссылкой на инженерную и наоборот.

Что значит «сверено»

verified — это день, когда статью читали рядом с кодом, а не день, когда правили текст. Опечатку можно исправить не открывая репозиторий, и это не делает статью верной.

Поэтому: поправили формулировку — дату не трогаем. Перечитали код и убедились, что написанное всё ещё правда — ставим сегодняшнюю.

Все даты видны на карте документации.

Правила, которые проверяются автоматически

Ссылки только корневые-абсолютные: /product/rating/, не ../rating/ и не rating.md. Относительная ссылка бесполезна для агента, скачавшего один файл, а битая — заметна тесту раньше, чем читателю.

Секретов быть не может. Сайт публичный, поэтому грепа по паттернам (postgres://, _SECRET, -----BEGIN и подобные) роняет сборку, а не предупреждает. Адреса стендов секретами не считаются: секрет — это то, чем можно воспользоваться.

Если статья обязана назвать паттерн дословно — как эта, — исключение заводится в content-allowlist.json: страница, список точных строк текста и обязательное поле why. Разрешается именно строка целиком, а не паттерн: добавьте на той же странице новую строку с настоящей строкой подключения — она не совпадёт с разрешённой и уронит сборку. Отредактировали разрешённую строку — разрешение перестало действовать, и её нужно пересмотреть заново. Это осознанно.

Фронтматтер валидируется схемой — неверный тип поля тоже роняет сборку.

Прогнать всё локально:

pnpm build && pnpm test

Что нельзя делать

Копировать спеки из docs/superpowers/specs/ целиком. Спека — датированный снимок замысла под конкретную задачу; после реализации она устаревает, но продолжает выглядеть как истина. Статья описывает сегодняшнее поведение и сверяется с кодом. Спека — сырьё, не источник.

Честное ограничение

Связать правку кода с правкой статьи автоматически нельзя: приложения живут в разных репозиториях, общего pull request нет. Единственная защита — поле verified и привычка заглядывать в карту. Изображать здесь процесс, которого нет, было бы хуже, чем признать дыру.

Что рядом

• Ландшафт и границы — с чего начать чтение.
• Карта документации — что давно не сверяли.