A manual for a package is itself a package: it names what it documents, carries a title and a summary, and is read rather than installed. This page writes one, with examples that are run and rules quoted from the source they come from.
The agent creates the package with the `doc` kind, fills the card, names the subject, and writes the first page in the XML dialect with the documentation vocabulary. `vibe doc check --citations` resolves every `rule` address against the subject's [specification](../glossary/index.xml#specification) and fails on any that does not exist. The manual is published like any package; the site finds it through the `[[documents]]` edge and, because the subject's group published it under the `-docs` name, shows it as the subject's [official documentation](../glossary/index.xml#official).
A `doc` package must name at least one subject and carry a `title` and an `abstract`; it may declare a [skill](../glossary/index.xml#skill), images and, for a translation, the documentation it adapts. It may not declare a [boot snippet](../glossary/index.xml#boot-snippet), a binary or a server: documentation is read, never executed, and never enters a session's reading list.
The `abstract` answers four questions in three to six sentences: what the manual covers, for whom, what it assumes known, what it leaves out. The `title` is the display name on every shelf; the [coordinate](../glossary/index.xml#coordinate) stays the identity, and the publisher is shown beside it. Images are optional source files in the package tree; when absent, the site draws a placeholder from the coordinate.
A documentation package may also declare a skill, a `[translates]` table and `[media]`. Its pages live under `vibevm/vibespecs/` like the specs of any package, and only there is the documentation vocabulary open. The default name of a subject's documentation is the subject's name with `-docs`, in the same group.
Two more declarations are for the reader rather than the site. `authorship` in `[package]` says who wrote the prose, `human`, `ai` or `mixed`; it is a property of the document a shelf can filter by, never an attribution of the commits, whose law is the repository's own. `[navigation]` pins the pages a newcomer should see first and names the sections of the page tree; every other page keeps the order the package declares.
Pages are written in the project's XML dialect, extended for documentation with a small vocabulary that ordinary specifications do not have. Each element is checked by a tool, which is the point of having it.
| Element | What it does | What checks it |
| `example` with `run` and `expect` | a command and its expected output, run in a fixture | the runner: exact match after declared normalisation |
| `rule ref="spec://…#ANCHOR"` | quotes a rule from a specification, live, in the specification's language | the [anchor](../glossary/index.xml#anchor) exists |
| `derived kind="cli-help | jtd-schema | manifest-field"` | inserts a generated reference block | regenerated at build; a divergence is red |
| `note kind="note | tip | warning"` | a call-out | the schema |
| `figure src alt` with `caption` | an image from the package tree | the file exists and passes the media rules |
| `prompt` with `needs`, `outcome`, `assert` | the request a user gives an agent to do the task, and the commands that prove it was done | an agent runs it in a clean fixture, then the asserts |
| `when="os:…"` on any block | a platform variant | the condition vocabulary |
A page that quotes a normative value, a flag, a path, a field name, does so through `rule`; it never restates the value in prose, because a restated value is a second copy that drifts.
A concept page has a noun as its title and opens with a paragraph that uses no term of the glossary. It shows an example before it explains, explains as a ladder where each step uses only the steps before it, and ends with edge cases and questions. A task page has an imperative title, opens the same way, and then gives the request for an agent before anything else: what to ask, what the agent needs, what you will see, and the commands that prove it worked. Manual steps follow only when they are worth walking. No page ends with a conclusion.
The full writing rules, including the banned words and the limits on sentence length in technical passages, ship with this manual as `AUTHORING.md`; `vibe doc check --style` enforces the mechanical part.
`vibe doc check --examples --citations --derived --media --style` runs every check; the examples run against the real binary in a sandbox copied from the fixture the page names, and a page is committed only when the checks are green. Publishing is `vibe registry publish` like any package; a reader gets the manual with `vibe cache add`, and the site renders it when the [index](../glossary/index.xml#index-registry) announces it.
Every `rule` is a live citation without a pin: the page shows the [fact](../glossary/index.xml#fact)'s current text at every render, and the citation check asks one thing, whether the [anchor](../glossary/index.xml#anchor) still exists. Facts a specification marks as obligations for an audience must be cited by a page for that audience, and `vibe doc check --coverage` is that gate.
Any group may document any package; the site shows such a manual on the community shelf with its publisher, and the subject's own group can promote it to official by naming it in `[documentation]`.
Examples in a README of an ordinary package are not run: the vocabulary opens only in packages of kind `doc`.
A manual describes a version range of its subject through `[[documents]] version`, and the site shows, for each subject version, the newest manual whose range admits it.
A package with no documentation at all is still shown: the site renders any published version from its own bytes, the [manifest](../glossary/index.xml#manifest) as a reference page, the README, the boot snippet, the specs with their anchors, and the declared skills, binaries and servers.
Such a rendering says so in its manifest, so a shelf marks it as generated, and the page of a bridge keeps the maintainer of the bridge apart from the author of what it wraps.