Руководство для пакета — само по себе пакет: оно называет, что документирует, несёт заголовок и краткое описание, и его читают, а не устанавливают. Эта страница пишет такое руководство, с примерами, которые выполняются, и правилами, процитированными из источника, откуда они взяты.
Агент создаёт пакет вида `doc`, заполняет карточку, называет [предмет](../glossary/index.xml#subject) и пишет первую страницу на XML-диалекте со словарём документации. `vibe doc check --citations` разрешает каждый адрес `rule` по [спецификации](../glossary/index.xml#specification) предмета и падает на любом, которого нет. Руководство публикуется как любой пакет; сайт находит его по ребру `[[documents]]` и, поскольку группа предмета опубликовала его под именем с `-docs`, показывает как [официальную документацию](../glossary/index.xml#official) предмета.
Пакет `doc` обязан назвать хотя бы один предмет и нести `title` и `abstract`; он может объявить [навык](../glossary/index.xml#skill), изображения и, для перевода, документацию, которую адаптирует. Он не может объявить [стартовый фрагмент](../glossary/index.xml#boot-snippet), бинарник или сервер: документацию читают, никогда не выполняют, и она никогда не попадает в список чтения сессии.
`abstract` отвечает на четыре вопроса в трёх–шести предложениях: что руководство охватывает, для кого, что считает известным, что оставляет за скобками. `title` — отображаемое имя на каждой полке; [координата](../glossary/index.xml#coordinate) остаётся идентичностью, а издатель показывается рядом. Изображения — необязательные исходные файлы в дереве пакета; когда их нет, сайт рисует заглушку из координаты.
Пакет документации может также объявить навык, таблицу `[translates]` и `[media]`. Его страницы живут под `vibevm/vibespecs/`, как спецификации любого пакета, и только там открыт словарь документации. Имя документации предмета по умолчанию — имя предмета с `-docs`, в той же группе.
Ещё два объявления адресованы читателю, а не сайту. `authorship` в `[package]` говорит, кто написал прозу: `human`, `ai` или `mixed`; это свойство документа, по которому полка умеет фильтровать, и никогда не атрибуция коммитов, закон которой у репозитория свой. `[navigation]` припиняет страницы, которые новичок должен увидеть первыми, и называет разделы дерева страниц; остальные страницы сохраняют порядок, объявленный пакетом.
Страницы пишутся на XML-диалекте проекта, расширенном для документации небольшим словарём, которого у обычных спецификаций нет. Каждый элемент проверяется инструментом, и в этом весь смысл его существования.
| Элемент | Что делает | Что проверяет |
| `example` с `run` и `expect` | команда и её ожидаемый вывод, выполняемые в фикстуре | раннер: точное совпадение после объявленной нормализации |
| `rule ref="spec://…#ANCHOR"` | цитирует правило из спецификации, вживую, на языке спецификации | [якорь](../glossary/index.xml#anchor) существует |
| `derived kind="cli-help | jtd-schema | manifest-field"` | вставляет сгенерированный справочный блок | перегенерируется при сборке; расхождение горит красным |
| `note kind="note | tip | warning"` | врезка | схема |
| `figure src alt` с `caption` | изображение из дерева пакета | файл существует и проходит правила для медиа |
| `prompt` с `needs`, `outcome`, `assert` | просьба, которую пользователь даёт агенту для задачи, и команды, доказывающие, что она сделана | агент выполняет её в чистой фикстуре, затем строки assert |
| `when="os:…"` на любом блоке | вариант для платформы | словарь условий |
Страница, которая цитирует нормативное значение, флаг, путь, имя поля, делает это через `rule`; она никогда не пересказывает значение прозой, потому что пересказанное значение — вторая копия, которая расходится.
У страницы-понятия заголовок — существительное, и открывается она абзацем, в котором нет ни одного термина глоссария. Она показывает пример прежде, чем объясняет, объясняет лестницей, где каждая ступень пользуется только предыдущими, и заканчивается особыми случаями и вопросами. У страницы-задачи заголовок в повелительном наклонении, открывается она так же, а затем прежде всего даёт просьбу для агента: что попросить, что агенту нужно, что вы увидите и какие команды докажут, что получилось. Ручные шаги следуют, только когда их стоит пройти. Ни одна страница не заканчивается заключением.
Полные правила письма, включая запрещённые слова и пределы длины предложений в технических местах, поставляются с этим руководством как `AUTHORING.md`; `vibe doc check --style` применяет их механическую часть.
`vibe doc check --examples --citations --derived --media --style` запускает все проверки; примеры выполняются настоящим бинарником в песочнице, скопированной из фикстуры, которую называет страница, и страница коммитится, только когда проверки зелёные. Публикация — `vibe registry publish`, как у любого пакета; читатель получает руководство через `vibe cache add`, а сайт отрисовывает его, когда [индекс](../glossary/index.xml#index-registry) о нём объявит.
Каждый `rule` — живая цитата без пина: страница показывает текущий текст [факта](../glossary/index.xml#fact) при каждой отрисовке, а проверка цитат спрашивает одно: существует ли ещё [якорь](../glossary/index.xml#anchor). Факты, которые спецификация помечает как обязательства перед аудиторией, должна цитировать страница для этой аудитории, и `vibe doc check --coverage` — эти ворота.
Любая группа может документировать любой пакет; сайт показывает такое руководство на полке сообщества с его издателем, а собственная группа предмета может повысить его до официального, назвав в `[documentation]`.
Примеры в README обычного пакета не выполняются: словарь открыт только в пакетах вида `doc`.
Руководство описывает диапазон версий своего предмета через `[[documents]] version`, и сайт показывает для каждой версии предмета новейшее руководство, чей диапазон её допускает.
Пакет вообще без документации всё равно показывается: сайт отрисовывает любую опубликованную версию из её собственных байтов: [манифест](../glossary/index.xml#manifest) как справочную страницу, README, стартовый фрагмент, спецификации с их якорями и объявленные навыки, бинарники и серверы.
Такая отрисовка говорит об этом в своём манифесте, так что полка помечает её как сгенерированную, а страница моста держит сопровождающего моста отдельно от автора того, что он оборачивает.