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

Источник: https://docs.novapoker.ru/dev/how-to-maintain/
Дорожка: разработка
Сверено с кодом: Mon Aug 24
Код: repos/poker-docs/scripts/agent-bundle.mjs, docs/superpowers/specs/2026-08-24-docs-site-design.md

---

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

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

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

```yaml
---
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` — это день, когда статью **читали рядом с кодом**, а не день, когда
правили текст. Опечатку можно исправить не открывая репозиторий, и это не делает
статью верной.

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

Все даты видны на [карте документации](https://docs.novapoker.ru/map.md).

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

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

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

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

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

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

```bash
pnpm build && pnpm test
```

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

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

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

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

## Что рядом

- [Ландшафт и границы](https://docs.novapoker.ru/dev.md) — с чего начать чтение.
- [Карта документации](https://docs.novapoker.ru/map.md) — что давно не сверяли.