Написать документацию для пакета

Что происходит

03Агент создаёт пакет вида doc, заполняет карточку, называет предмет и пишет первую страницу на XML-диалекте со словарём документации. vibe doc check --citations разрешает каждый адрес rule по спецификации предмета и падает на любом, которого нет. Руководство публикуется как любой пакет; сайт находит его по ребру [[documents]] и, поскольку группа предмета опубликовала его под именем с -docs, показывает как официальную документацию предмета.

04 Default convention: when the subject declares no [documentation], the package <name>-docs in the same group counts as official and primary. A declared [documentation] replaces the convention entirely.

Манифест

05Пакет doc обязан назвать хотя бы один предмет и нести title и abstract; он может объявить навык, изображения и, для перевода, документацию, которую адаптирует. Он не может объявить стартовый фрагмент, бинарник или сервер: документацию читают, никогда не выполняют, и она никогда не попадает в список чтения сессии.

06 A doc package MUST declare at least one subject in [[documents]] (§4) and MUST carry title and abstract (§7).

07 A doc package MUST NOT declare [boot_snippet], [[mcp_server]] or [[binary]]; vibe check rejects the manifest. Documentation never enters a boot lane (§14).

08abstract отвечает на четыре вопроса в трёх–шести предложениях: что руководство охватывает, для кого, что считает известным, что оставляет за скобками. title — отображаемое имя на каждой полке; координата остаётся идентичностью, а издатель показывается рядом. Изображения — необязательные исходные файлы в дереве пакета; когда их нет, сайт рисует заглушку из координаты.

09 description stays the one-line subtitle for lists and the page's meta description; abstract answers 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 through derived kind="manifest-field".

10 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 A doc package MAY declare [[skill]], [translates] (§5) and [media] (§7).

13 Its pages live under vibevm/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 The official-by-default documentation of a subject <group>/<name> is named <group>/<name>-docs, in the same group. The core documentation is org.vibevm.core/vibevm-docs, the companion of the host coordinate org.vibevm.core/vibevm.

15Ещё два объявления адресованы читателю, а не сайту. authorship в [package] говорит, кто написал прозу: human, ai или mixed; это свойство документа, по которому полка умеет фильтровать, и никогда не атрибуция коммитов, закон которой у репозитория свой. [navigation] припиняет страницы, которые новичок должен увидеть первыми, и называет разделы дерева страниц; остальные страницы сохраняют порядок, объявленный пакетом.

16 A doc package MAY declare authorship in [package]: human, ai or mixed — 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 is spec://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 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 of vibe check.

Словарь страницы

18Страницы пишутся на XML-диалекте проекта, расширенном для документации небольшим словарём, которого у обычных спецификаций нет. Каждый элемент проверяется инструментом, и в этом весь смысл его существования.

20 The vocabulary is a parameter of the reader, not of the document. Vocabulary::{Spec, Doc} (default Spec) 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 no PackageKind by the separability law. A document declares nothing about its vocabulary.

21Страница, которая цитирует нормативное значение, флаг, путь, имя поля, делает это через rule; она никогда не пересказывает значение прозой, потому что пересказанное значение — вторая копия, которая расходится.

22 Documentation cites an anchor and never restates a normative value — a number, a flag, a path, a field name. Where the prose must mention a value, the same sentence carries the source address.

Форма страницы

23У страницы-понятия заголовок — существительное, и открывается она абзацем, в котором нет ни одного термина глоссария. Она показывает пример прежде, чем объясняет, объясняет лестницей, где каждая ступень пользуется только предыдущими, и заканчивается особыми случаями и вопросами. У страницы-задачи заголовок в повелительном наклонении, открывается она так же, а затем прежде всего даёт просьбу для агента: что попросить, что агенту нужно, что вы увидите и какие команды докажут, что получилось. Ручные шаги следуют, только когда их стоит пройти. Ни одна страница не заканчивается заключением.

24 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 in llms.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); an example with its expect; the mechanism as a ladder; edge cases through rule; questions only if real. A task page: an imperative title; the first paragraph without terms; then the prompt (§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.

25 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 a prompt block: 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 the vibevm skill), at most sixty words; beside it needs (what the agent must have) and outcome (what the person sees when it worked), and at least one assert — 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 marked assert="none". vibe doc check --prompts runs 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 skill vibevm-docs takes a page's prompt as the task when the user asks for what the page describes.

26Полные правила письма, включая запрещённые слова и пределы длины предложений в технических местах, поставляются с этим руководством как AUTHORING.md; vibe doc check --style применяет их механическую часть.

27 The mechanical check vibe doc check --style gates 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.

Проверка и публикация

28vibe doc check --examples --citations --derived --media --style запускает все проверки; примеры выполняются настоящим бинарником в песочнице, скопированной из фикстуры, которую называет страница, и страница коммитится, только когда проверки зелёные. Публикация — vibe registry publish, как у любого пакета; читатель получает руководство через vibe cache add, а сайт отрисовывает его, когда индекс о нём объявит.

29 The example runner (vibe doc check --examples) runs every example against the built binary and compares exactly after the declared normalisation; there are no match templates — every non-deterministic line is closed by a named replace rule visible in review. A page carries run, expect (stdout) and an optional stderr; the attribute exit defaults to 0; an absent stderr asserts «stderr is empty». A fixture is a directory with a tree and an example.toml declaring the normalisation rules and the map «--json document → JTD schema» by the command field. 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 variable VIBE_SETTINGS in the native path spelling plus NO_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 ~/.vibe and 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 --json stream is parsed document by document and each is validated by the fixture's schema map with a JTD validator written in vibe-doc (none exists in vibe-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 local replace rules; 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.

30Каждый rule — живая цитата без пина: страница показывает текущий текст факта при каждой отрисовке, а проверка цитат спрашивает одно: существует ли ещё якорь. Факты, которые спецификация помечает как обязательства перед аудиторией, должна цитировать страница для этой аудитории, и vibe doc check --coverage — эти ворота.

31 Every rule yields a documents edge without a pin: the citation is live, and the page shows the fact's current text by address at every render. vibe doc check --citations checks 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.

32 The coverage gate. Spec facts marked actionstage="doc" with an audience are obligations; vibe doc check --coverage requires every obligation to be cited by a page for the same audience — this is the ratchet PROP-047 ##DOC-COVERAGE-RATCHET names, and vibe 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.

Особые случаи и правила

33Любая группа может документировать любой пакет; сайт показывает такое руководство на полке сообщества с его издателем, а собственная группа предмета может повысить его до официального, назвав в [documentation].

34 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.

35Примеры в README обычного пакета не выполняются: словарь открыт только в пакетах вида doc.

36 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.

37Руководство описывает диапазон версий своего предмета через [[documents]] version, и сайт показывает для каждой версии предмета новейшее руководство, чей диапазон её допускает.

38 For a subject version V the site shows the documentation versions whose [[documents]] constraint admits V, choosing the newest.

39Пакет вообще без документации всё равно показывается: сайт отрисовывает любую опубликованную версию из её собственных байтов: манифест как справочную страницу, README, стартовый фрагмент, спецификации с их якорями и объявленные навыки, бинарники и серверы.

40 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; latest is an alias.

41Такая отрисовка говорит об этом в своём манифесте, так что полка помечает её как сгенерированную, а страница моста держит сопровождающего моста отдельно от автора того, что он оборачивает.

42 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.