The text in a package is only useful to an agent if every rule in it has an address. This page shows the shape of such text: named sections, one idea per unit, a status on each, and an address that never changes once published.
A person and an agent share one repository and nothing else: no hallway, no shared memory, no tone of voice. The [specification](../glossary/index.xml#specification) tree is the only channel between them, and a channel works when a message can be pointed at. «Fix the retry count» sends the agent guessing; «fix `spec://org.acme/notes-flow/flows/notes/PROTOCOL#RETRY-COUNT`» sends it to one line. The second costs about twenty tokens; the first costs hundreds and may land on the wrong rule.
`spec://<group>/<name>[@<version>]/<path>/<document>#<anchor>`: the package [coordinate](../glossary/index.xml#coordinate), an optional version, the document's path inside `vibevm/vibespecs/` without its extension, and an [anchor](../glossary/index.xml#anchor). The version is a feature, never an obligation: absent, the address resolves against the freshest installed version. Anchors are section ids and [fact](../glossary/index.xml#fact) ids in one address space, so a rule is cited the same way whether it is a section or one sentence.
A unit is one anchored heading and the text under it, up to the next heading; it carries one decision or one rule, makes sense on its own, and fits on a page. If a unit needs «and also», it is two units. Contract statements use MUST, SHOULD and MAY; a reader must never guess whether a sentence binds. Checkable claims stand outside code fences, because a fence carries no anchor and an instruction inside one is unverified by construction.
A specification is written in Markdown or in the project's XML dialect, and both parse into one document model. In XML a section is an element named after its anchor, `<retry-policy title="3. Retries">`. A rule is an element named after its id, with the attribute `fact="true"` and a status. In Markdown the same rule is a paragraph opening with `@fact:RETRY-COUNT` and closing with `@status:spec/done`. A tool that knows nothing of your vocabulary still finds every rule by one attribute test, and a converter turns one form into the other, reporting anything a round trip would not preserve.
The status on each unit says where it stands: `spec/done` for a settled rule, `impl/done` once code implements it, `spec/work` for a draft. Two id registers carry the signal at no cost: an upper-case id marks a rule with binding weight, a lower-case one a lead-in or a note.
`vibe refactor convert-source --to xml` or `--to markdown` converts files or whole folders, skipping the dependency tree and generated files. It writes the sibling form and deletes the original in one act, so the tree never holds both forms of one document. Before writing, it converts the result back and compares: a byte-identical round trip converts silently, and a loss of comments or layout is refused with a per-file description unless you confirm, or pass `--force`. A change of meaning is always refused, because that is a defect of the converter, not of your file. `--dry-run` reports every file and writes nothing.
A spec may pull another by address. `#use spec://…` pulls the whole top-level section that contains the addressed node, and not its siblings; `#embed` splices exactly the addressed node, no more. The default merge is `:add`, so interface text need not be repeated to appear in the result. Every file a directive names must be declared in the package's [manifest](../glossary/index.xml#manifest). Cycles are legal in the contract layer and forbidden among source bodies, which is what guarantees that a build always ends.
In prose an agent reads, `@spec://…` with the at-sign is mandatory: the agent reads it in place, once, on first encounter, and the compiler never splices it. A bare `spec://…` is at the agent's discretion.
Once published, an anchor is immutable. Renaming a section or a rule leaves a tombstone at the old anchor pointing at the new one, so a citation written last year still lands. Moving files does not change addresses either: the address is logical, the path is physics.
A generated file is never a citation target: cite the source document, not the compiled [boot lane](../glossary/index.xml#boot-lane).
`vibe facts check` validates the markup of a package's specifications; `vibe check` validates the package as a whole; both run before publishing.
Code may cite specifications too, with an attribute on the item that implements a rule, and a map then answers which code implements which rule in both directions; the architecture pages of this manual explain that map.