Написать документацию для пакета
01Руководство для пакета — само по себе пакет: оно называет, что документирует, несёт заголовок и краткое описание, и его читают, а не устанавливают. Эта страница пишет такое руководство, с примерами, которые выполняются, и правилами, процитированными из источника, откуда они взяты.
Создай пакет документации org.acme/notes-flow-docs в текущем проекте VibeVM, как пакет в дереве под vibevm/vibepacks/, документирующий пакет org.acme/notes-flow. Дай ему манифест с видом doc, заголовком и аннотацией и запись [[documents]] для предмета. Напиши одну страницу, объясняющую, что делает этот flow, с правилом, процитированным из протокола предмета по адресу. Запусти на нём vibe doc check.навык vibevm, установленный у вашего агента; проект с vibe.toml в корне и пакетом-предметом в нём
vibevm/vibepacks/org.acme/notes-flow-docs/v0.1.0/vibe.toml объявляет kind = "doc", title, abstract и [[documents]]; у страницы под vibevm/vibespecs/ первый абзац без терминов и блок rule, чей адрес разрешается; vibe doc check --citations не находит неразрешённых цитат
grep -q "kind = \"doc\"" vibevm/vibepacks/org.acme/notes-flow-docs/v0.1.0/vibe.tomlvibe doc check --citations --path vibevm/vibepacks/org.acme/notes-flow-docs/v0.1.0
Что происходит
03Агент создаёт пакет вида doc, заполняет карточку, называет предмет (subject) и пишет первую страницу на XML-диалекте со словарём документации. vibe doc check --citations разрешает каждый адрес rule по спецификации предмета и падает на любом, которого нет. Руководство публикуется как любой пакет; сайт находит его по ребру [[documents]] и, поскольку группа предмета опубликовала его под именем с -docs, показывает как официальную документацию предмета.
Манифест
05Пакет doc обязан назвать хотя бы один предмет и нести title и abstract; он может объявить навык (skill), изображения и, для перевода, документацию, которую адаптирует. Он не может объявить стартовый фрагмент (boot snippet), бинарник или сервер: документацию читают, никогда не выполняют, и она никогда не попадает в список чтения сессии.
06 spec: A doc package MUST declare…
Adocpackage MUST declare at least one subject in[[documents]](§4) and MUST carrytitleandabstract(§7).
07 spec: A doc package MUST NOT declare…
Adocpackage MUST NOT declare[boot_snippet],[[mcp_server]]or[[binary]];vibe checkrejects the manifest. Documentation never enters a boot lane (§14).
08abstract отвечает на четыре вопроса в трёх–шести предложениях: что руководство охватывает, для кого, что считает известным, что оставляет за скобками. title — отображаемое имя на каждой полке; координата остаётся идентичностью, а издатель показывается рядом. Изображения — необязательные исходные файлы в дереве пакета; когда их нет, сайт рисует заглушку из координаты.
09 spec: description stays the one-line subtitle…
descriptionstays the one-line subtitle for lists and the page's meta description;abstractanswers four questions — what it covers, for whom, what it assumes known, what it leaves out — and is bounded at about a thousand characters. The entry page does not restate the abstract; it inserts it throughderived kind="manifest-field".
10 spec: Placeholders are generated, never stored…
Placeholders are generated, never stored: a gradient or pattern for the banner and a glyph for the icon are computed from the hash of the coordinate, so a package looks the same on the site and in the local reader and different packages are distinguishable; the glyph depends on the kind — a book for doc, its own sign for every other kind; inline SVG at render time, no files, no network.
11Пакет документации может также объявить навык, таблицу [translates] и [media]. Его страницы живут под vibevm/vibespecs/, как спецификации любого пакета, и только там открыт словарь документации. Имя документации предмета по умолчанию — имя предмета с -docs, в той же группе.
12 spec: A doc package MAY declare [[skill]]…
Adocpackage MAY declare[[skill]],[translates](§5) and[media](§7).
13 spec: Its pages live under vibevm/vibespecs/…
Its pages live undervibevm/vibespecs/of its own tree like the specs of any package (PROP-052); a document belongs to the documentation genre by the kind of the package that contains it, and only there the documentation vocabulary of the dialect is open (PROP-045##DOC-VOCAB-BY-KIND).
14 spec: The official-by-default documentation of a subject…
The official-by-default documentation of a subject<group>/<name>is named<group>/<name>-docs, in the same group. The core documentation isorg.vibevm.core/vibevm-docs, the companion of the host coordinateorg.vibevm.core/vibevm.
15Ещё два объявления адресованы читателю, а не сайту. authorship в [package] говорит, кто написал прозу: human, ai или mixed; это свойство документа, по которому полка умеет фильтровать, и никогда не атрибуция коммитов, закон которой у репозитория свой. [navigation] закрепляет первыми страницы, которые новичок должен увидеть, и называет разделы дерева страниц.
16 spec: A doc package MAY declare authorship…
Adocpackage MAY declareauthorshipin[package]:human,aiormixed— who wrote the prose the package carries. It is metadata of the document, kept for the reader who filters a shelf by it; it is never an attribution of the commits or of the repository, whose authorship law isspec://org.vibevm.core/vibevm/common/PROP-000#commits. Absent means unknown: the site shows no badge and a filter by authorship leaves the package out of both named groups.
17 spec: A documentation package MAY declare [navigation]…
A documentation package MAY declare[navigation]:pinned, the document paths the site and the local reader list first, in the order given; and[[navigation.section]], one row per top-level folder of the page tree with the title the navigation shows for it. Pinning changes only where the named pages stand; every other page keeps the manifest's order. A pinned path that names no page is an error ofvibe check.
18Руководству, которое читают от начала до конца, нужен ещё и порядок изучения, и написать его может только автор. Строки [[navigation.chapter]] объявляют его как учебный путь (learning path): у каждой строки есть id, title и pages — страницы главы в порядке чтения. Строки в том порядке, в каком они записаны, ведут от первой страницы первой главы к последней странице последней. Главу справочных страниц пометьте appendix = true, и читалка покажет её без номера, как учебник показывает приложения. Путь не меняет никакого другого порядка: машины по-прежнему читают страницы в порядке, который для них вычисляет vibe.
19 spec: A documentation package MAY declare…
A documentation package MAY declare a learning path in[navigation]:[[navigation.chapter]]rows, each with anid, atitleandpages— the document paths the chapter holds, in reading order — and optionallyappendix = truefor a chapter of pages a reader looks things up in rather than reads through. The rows in their written order are the path: followed from the first page of the first chapter to the last page of the last, it meets every page of the package once. The path is written for people and moves no other order:pagesin the page manifest and thellmsfiles keep the layer law (spec://org.vibevm.core/vibevm/common/PROP-048#THE-LAYER-LAW), and the page manifest carries the path beside them asnavigation.chapters.
20Каждая страница пакета стоит ровно в одной главе. vibe check отказывает пути, который называет несуществующую страницу, называет страницу дважды или пропускает её, поэтому страница, добавленная позже, не выпадет из пути. vibe doc check ещё и перечисляет ссылки, которые ведут дальше по пути, чем читатель успел дойти. Этот список — подсказка о порядке, а не ошибка: обзорная страница нарочно смотрит вперёд.
21 spec: vibe check refuses a learning path…
vibe checkrefuses a learning path that names a page the package does not have, names one page twice, leaves a page of the package out of every chapter, or uses one chapteridtwice: a page added later must be given its place on the path.vibe doc checkreports, without failing, every link from a page to a page the path reaches later, links into an appendix chapter excepted — a measure of how well the path reads as a textbook, not a gate, because an orientation page points ahead on purpose.
22Перевод не повторяет путь. Он называет главы на своём языке строками с id и title, а порядок берёт у документации, которую адаптирует.
23 spec: A translation takes the learning path…
A translation takes the learning path of the documentation it adapts. It MAY declare[[navigation.chapter]]rows withidandtitleonly, to name the chapters in its own language; a chapter it does not name keeps the source's title. A translation row that listspagesis an error ofvibe check, and a row whoseidthe source does not declare is an error ofvibe doc check --translations.
24Руководство, которое определяет свои слова на одной странице, объявляет эту страницу глоссарием: [glossary] с page — путём страницы без расширения. Каждый раздел верхнего уровня этой страницы — одна статья. Id раздела — якорь, его title — слово, а первый абзац — определение. Из этого объявления проверки стиля узнают слова руководства, а читалка показывает определение рядом со ссылкой на него. У пакета без объявления нет ни того, ни другого.
25 spec: A documentation MAY declare its glossary
A documentation MAY declare its glossary (added 2026-09-26): a top-level table[glossary]withpage, the document path of the page that defines the package's terms. That page is the glossary. Each of its top-level sections is one entry: the section's id is the entry's anchor, itstitleis the term, and its first paragraph is the definition; more paragraphs and cited rules may follow. Everything the pipeline, the reader and the tools do with terms — the style checks of##STYLE-LINT, the cards of##READER-GLOSSARY-CARD— they do with the declared glossary, and a package that declares none has none; the pathglossary/index.xmlmeans nothing by itself.
26vibe check отказывает, если пакет объявил страницу глоссария, которой у него нет, или если у статьи нет title или первого абзаца.
27 spec: vibe check refuses a [glossary]…
vibe checkrefuses a[glossary]that names a page the package does not have, and a glossary entry without atitleor without a first paragraph.
28Перевод объявляет ту же страницу глоссария, что и документация, которую он адаптирует, а слова и их определения пишет на своём языке.
29 spec: A translation declares the same [glossary]…
A translation declares the same[glossary]as the documentation it adapts: its glossary is its own mirrored page at the same path, with the terms and definitions in its language.vibe doc check --translationsreports a translation whose[glossary]is missing while the source declares one, or names another page.
Словарь страницы
30Страницы пишутся на XML-диалекте проекта, расширенном для документации небольшим словарём, которого у обычных спецификаций нет. Каждый элемент проверяется инструментом, и в этом весь смысл его существования.
| Элемент | Что делает | Что проверяет |
|---|---|---|
example с run и expect |
команда и её ожидаемый вывод, выполняемые в фикстуре | раннер: точное совпадение после объявленной нормализации |
rule ref="spec://…#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:…" на любом блоке |
вариант для платформы | словарь условий |
32 spec: The vocabulary is a parameter…
The vocabulary is a parameter of the reader, not of the document.Vocabulary::{Spec, Doc}(defaultSpec) selects the accepted element set through additive entry points (from_xml_with,load_spec_text_with,project_spec_text_with); the mapping «package kind → vocabulary» is the caller's, because the pivot knows noPackageKindby the separability law. A document declares nothing about its vocabulary.
33Страница, которая цитирует нормативное значение, флаг, путь, имя поля, делает это через rule; она никогда не пересказывает значение прозой, потому что пересказанное значение — вторая копия, которая расходится.
Форма страницы
35У страницы-понятия заголовок — существительное, и открывается она абзацем, в котором нет ни одного термина глоссария. Она показывает пример прежде, чем объясняет, объясняет лестницей, где каждая ступень пользуется только предыдущими, и заканчивается особыми случаями и вопросами. У страницы-задачи заголовок в повелительном наклонении, открывается она так же, а затем прежде всего даёт просьбу для агента: что попросить, что агенту нужно, что вы увидите и какие команды докажут, что получилось. Ручные шаги следуют, только когда их стоит пройти. Ни одна страница не заканчивается заключением.
36 spec: The page skeleton
The page skeleton. A concept page: a noun-phrase title; a first paragraph saying what this is and when it is needed with no glossary term at all (it is also the page's line inllms.txt; clarified 2026-09-12 at the first corpus check: a glossary word used in its ordinary English sense — package, project, kind, feature, workspace, translation — does not count, a word that means something only in vibe — lock file, manifest, registry, store, index, anchor, skill, contribution, fingerprint, receipt — does); anexamplewith itsexpect; the mechanism as a ladder; edge cases throughrule; questions only if real. A task page: an imperative title; the first paragraph without terms; then theprompt(§16##STYLE-PROMPT-FIRST); «what happens» in three to six sentences as a corridor; «by hand» as numbered STE steps only where the manual road is worth walking; edge cases and questions. No page ends with a conclusion, a summary or a «next steps» box.
37 spec: Prompt first
Prompt first. Any action in VibeVM is done by an agent or by hand, and the agent is the main road. A scenario page opens with apromptblock: the plain request in the user's voice, self-contained (coordinates, paths and registry named, never implied), one prompt for one outcome, free of secrets, neutral to the agent (it works for any agent with thevibevmskill), at most sixty words; beside itneeds(what the agent must have) andoutcome(what the person sees when it worked), and at least oneassert— a shell command that must exit zero after the agent's work, because a prompt cannot be checked by its output the way a shell example can. A prompt without an assert on a scenario page is a style-linter error; an illustrative prompt on an explanation page is markedassert="none".vibe doc check --promptsruns every prompt through the configured agent runner ([doc.prompts] runner) in a clean temporary directory with the fixture and then runs the asserts; it is not part of the panel — it runs in the prose phase before acceptance, as a sample in the monthly loop, and in full at reconciliation. The skillvibevm-docstakes a page'spromptas the task when the user asks for what the page describes.
38Полные правила письма, включая запрещённые слова и пределы длины предложений в технических местах, поставляются с этим руководством как AUTHORING.md; vibe doc check --style применяет их механическую часть.
39 spec: The mechanical check
The mechanical checkvibe doc check --stylegates a page: banned words and phrases by the page's language; sentence and paragraph length by block kind (errors in procedures and warnings, warnings in corridors); a glossary term used before its introduction; more than two glossary terms in one narrative sentence; deferral phrases («see the specification», «as described in») without an explanation on the same page; forbidden headings; exclamation marks, emoji, bold in prose; a readability score per page reported and not gated. A false positive is fixed in the linter's rule with a BACKLOG entry, never worked around in the text. A page is committed only after the author's self-edit against the norm and a green--style.
Проверка и публикация
40vibe doc check --examples --citations --derived --media --style запускает все проверки; примеры выполняются настоящим бинарником в песочнице, скопированной из фикстуры, которую называет страница, и страница коммитится, только когда проверки зелёные. Публикация — vibe registry publish, как у любого пакета; читатель получает руководство через vibe cache add, а сайт отрисовывает его, когда индекс о нём объявит.
41 spec: The example runner
The example runner (vibe doc check --examples) runs everyexampleagainst the built binary and compares exactly after the declared normalisation; there are no match templates — every non-deterministic line is closed by a namedreplacerule visible in review. A page carriesrun,expect(stdout) and an optionalstderr; the attributeexitdefaults to0; an absentstderrasserts «stderr is empty». A fixture is a directory with a tree and anexample.tomldeclaring the normalisation rules and the map «--jsondocument → JTD schema» by thecommandfield. The command's working directory is a fresh sandbox with a copy of the fixture, never the source tree; the command names no paths; isolation is one variableVIBE_SETTINGSin the native path spelling plusNO_COLOR; the behavioural variables (VIBE_OFFLINE,VIBE_UNATTENDED,VIBE_INVOKED_BY,VIBETERM,VIBEFRAME) are cleared and the flags stand in the example itself; a tripwire checks that the real~/.vibeand the source tree stayed unchanged; stdout and stderr are captured separately; examples document the non-TTY branch of the product and interactive prompts are described in prose; a--jsonstream is parsed document by document and each is validated by the fixture's schema map with a JTD validator written invibe-doc(none exists invibe-wire, whose schemas are codegen input); a document without a schema is reported as unchecked, never as passed. Normalisation:<TMP>,<HOME>,<REPO>, slashes, CRLF in expected files,vibe <VERSION>(package versions untouched), ANSI, block sorting by a declared line form, the fixture's localreplacerules; the order is path replacements before slash unification and sorting after all replacements. Loosening a comparison to turn a check green is forbidden: the normalisation or the product is fixed.
42Каждый rule — живая цитата без пина: страница показывает текущий текст факта при каждой отрисовке, а проверка цитат спрашивает одно: существует ли ещё якорь. Факты, которые спецификация помечает как обязательства перед аудиторией, должна цитировать страница для этой аудитории, и vibe doc check --coverage — эти ворота.
43 spec: Every rule yields a documents edge…
Everyruleyields adocumentsedge without a pin: the citation is live, and the page shows the fact's current text by address at every render.vibe doc check --citationschecks one thing — that the anchor exists; a vanished anchor without a tombstone fails the build. There are no revisions, no text hashes and no «the spec moved ahead»: such checks would need a history the project does not keep by design.
44 spec: The coverage gate
The coverage gate. Spec facts markedactionstage="doc"with an audience are obligations;vibe doc check --coveragerequires every obligation to be cited by a page for the same audience — this is the ratchet PROP-047##DOC-COVERAGE-RATCHETnames, andvibe progress report --view doc --audience …is its listing of obligations, a source for the gate and not a navigation. Marking the obligations in the spec corpus is a campaign atom of its own. The site's navigation is derived from the page manifest, never from this report.
Особые случаи и правила
45Любая группа может документировать любой пакет; сайт показывает такое руководство на полке сообщества с его издателем, а собственная группа предмета может повысить его до официального, назвав в [documentation].
46 spec: Official: documentation is the one whose…
Official documentation is the one whose edges converge: the subject named the package and the package declared the subject. Community documentation has only the edge from the documentation. An edge from the subject alone reads «not published or an error», and the site shows a warning.
47Примеры в README обычного пакета не выполняются: словарь открыт только в пакетах вида doc.
48 spec: Known limit: the README and specs…
Known limit: the README and specs of packages of other kinds cannot carry verifiable examples — the vocabulary opens by package kind. Their fences render at level 0 as they are, unverified.
49Руководство описывает диапазон версий своего предмета через [[documents]] version, и сайт показывает для каждой версии предмета новейшее руководство, чей диапазон её допускает.
50 spec: For a subject version V…
For a subject version V the site shows the documentation versions whose [[documents]] constraint admits V, choosing the newest.
51Пакет вообще без документации всё равно показывается: сайт отрисовывает любую опубликованную версию из её собственных байтов: манифест как справочную страницу, README, стартовый фрагмент, спецификации с их якорями и объявленные навыки, бинарники и серверы.
52 spec: Level 0
Level 0. The site renders any published version of any package from its own bytes: the manifest as a reference page, the README, the boot snippet marked «read by the session», the specs with anchors and fact highlighting by address, the declared skills, binaries and MCP servers, the dependants, «explained in», «translated into», and the images of[media]. Versions sit in the side navigation;latestis an alias.
53Такая отрисовка говорит об этом в своём манифесте, так что полка помечает её как сгенерированную, а страница моста держит сопровождающего моста отдельно от автора того, что он оборачивает.
54 spec: The manifest of a level-zero rendering…
The manifest of a level-zero rendering says so: projection = true, so a shelf can tell a page the site derived from a package's own bytes from a page an author wrote, and mark the first as generated. A bridge's rendering carries the two authorships the bridge keeps apart.