How this manual is maintained

No lock between the product and the manual

03The product ships many times a day and merges many pull requests; the manual cannot follow every one of them, and that is accepted. No gate holds a product release for the documentation, and no step of the self-check panel turns red because the product moved ahead of a page. The panel is red only when the manual is broken on the inside: an example whose output changed, a derived block that no longer builds, a citation whose anchor vanished.

04 Only internal breakage of the documentation is red in the panel: a red example, a derived block that no longer builds, a vanished citation anchor, a page the pivot cannot read. Drift and debt are printed as numbers (PROP-057 ##OBS-NO-RELEASE-LOCK; J-074, J-088).

05 The owner set the frame on 2026-09-10 (J-013, J-014): the product ships up to ten times a day and merges up to a hundred pull requests, documentation drifts between checks and that risk is accepted; a version is a contract on behaviour, not a set of files; no technical lock binds a product release to the documentation. The regulation therefore measures drift, shows it to the reader and keeps a team promise to reconcile fully on a calendar.

06Instead of a lock there is a measure. The queue command prints the gaps as numbers: obligations no page tells, examples that no longer match, citations that do not resolve, pages nobody has read aloud, debt lines, the linter's count. It never fails a build, and it distinguishes «nothing found» from «nobody looked»: a section that did not run prints null, not zero.

07 vibe doc todo is the maintenance queue by the current state, with no «since» comparison: commands, fields and obligations without a page, red examples, unresolvable citations, structural divergences of adaptations, page age by reviews.toml, docs: debt lines from BACKLOG.md, and the linter's statistics; --format md for the weekly report, --format json for the metrics. It prints numbers and never fails a build; every section carries measured, and a metric the run could not take is null, never 0 — «no findings» and «nobody looked» must print differently (J-099). Examples run only with --examples, because a sandbox per fixture costs minutes and the weekly reading should not.

What you owe when you change the product

08A change a user can see carries its page in the same commit: a new or changed command or flag, a manifest or lock-file field, a report format, an error message with an address, a spec fact marked for documentation, a new specification. The developer guides already work this way, and the pull-request template keeps the habit with one checkbox: documentation updated, debt recorded, or not needed.

09 The commit loop. A product change a user can see — a new or changed command, flag, manifest or lock-file field, report format, error message with an address, a spec fact marked actionstage="doc", a new PROP — carries its documentation in the same commit, as DEV-GUIDE.md and RUNTIME-GUIDE.md already do; when that is impossible, the commit carries a debt line (§8). This is a habit kept by the pull-request checkbox «documentation: updated / debt recorded / not needed», never a lock (J-013; PROP-057 ##OBS-NO-RELEASE-LOCK).

10When the page cannot come with the commit, the commit brings a debt line instead: a row in the host's BACKLOG.md prefixed docs:, with a severity and the address of the change. A line without an address is not accepted. The monthly loop drains the list.

11 A debt line is a row of the host's BACKLOG.md prefixed docs:, with a severity P1–P3 and the address of the change it owes a page to; a line without an address is not accepted. The monthly loop drains the list; the full reconciliation takes what is left (J-064: «needs an author» was closed by a rule written into a script, not row by row).

12Before any edit, look at git status and make sure no other session is writing in the same tree. In a tree shared with parallel workers, commit only with explicit paths, so that nobody's staged files travel inside your commit.

13 The first action of any edit is git status and a check for a live conflicting writer; two central sessions in one tree stop (J-005). In a tree shared with parallel workers, commits name their paths explicitly — git commit -m … -- <paths>, never a bare commit or git add -A (J-072, J-090).

14 Parallel packets in one tree commit only with explicit paths and never stage a neighbour's files; packets that share an entry-point file — an export barrel, a build script — get it split in advance or run one after the other (J-072, J-090).

The loops

15The weekly loop takes under an hour. A cheap model runs the queue and the checks over the whole package and files the report. The maintainer sorts the queue: what takes five minutes is fixed now, at most five edits per loop; what is bigger becomes a debt line; what is disputable becomes a one-line question to the owner. One page is read aloud, the next one along the reading rota, and every stumble becomes an edit or a debt line. A journal entry closes the loop.

16 The weekly loop, 30–60 minutes, in this order: a cheap model runs vibe doc todo --format md and vibe doc check over the whole package and files the report; the central session sorts the queue — what is fixed in five minutes is fixed now, at most five edits per loop, what is bigger becomes a debt line with severity, what is disputable becomes a one-line question to the owner; the signals of the week (§6) each become an edit, a debt line or «observation without action: reason»; the page of the week — the next page along reviews.toml — is read aloud by the owner or the central session as the reader of the style law, every stumble becomes an edit or a debt line, and the reading date goes into reviews.toml; a journal entry closes the loop with what was done, deferred and surprising (J-112: rehearsed 2026-09-12 in 25 minutes).

17The monthly loop takes half a day with the owner: eight metrics with their trend, an audit of the corpus, the debt list drained, the linter's lists fed with the ticks that slipped past it, every journal entry given its decision, three pages read aloud, and a republication under the same number with a dated entry in the changelog, written by hand.

18 The monthly loop, half a day, with the owner: the eight metrics of §9 as a table with their trend; an audit of the corpus — every top-level command, manifest field and kind has a page, the glossary keeps one word to one meaning, terms are introduced where readers look for them, duplicates and dead pages, the llms tiers within their budgets, a sample of ten prompts run through an agent; the analytics of the site; the lag of adaptations; the drain of docs: debt — every line closed, given an atom or re-rated with a reason; the ticks that slipped past the linter go into its lists and false positives fix the rule; every journal entry of the month still owing a decision gets one, and the regulation is amended with a date and the entries; the owner reads three pages aloud — one new, one most visited, one oldest by reviews.toml; the documentation package is published again under the same number, with a dated entry in the changelog written by hand from the journal, for as long as PROP-057 ##VERSION-OVERWRITE-POLICY holds (hypothesis until the first monthly rehearsal, A6.3).

19The full reconciliation is a promise the team makes itself, once a quarter and before a major milestone: the manual is checked against the current release binary, every page is reread against the product with the help text and the specification open beside it, adaptations are reread against their sources, and the package ships a version that matches the release. Its only gate is its own: zero gaps and no reading date older than the reconciliation.

20 The full reconciliation, a day or two, once a quarter and before a major milestone — a promise the team makes itself, never a release condition: a cheap model builds the documentation against the current release binary, not a debug one (J-001), runs vibe doc todo and vibe doc check with every flag, all examples and all prompts through an agent, and files the report; the central session closes the gaps — new pages or debt with an atom, regenerated derived, updated golden examples, repaired citations; every page is reread against the current product with --help and the spec open beside it, in the order of reviews.toml from the least recently read, and each page reread gets the date; adaptations are reread against their sources; the package ships a version compatible with the current product release, the site shows it as latest, and after publication the root links of the domain to /doc/sitemap.xml and /doc/llms.txt are checked with curl (J-004); the report goes to the journal with the gaps before and after, the pages reread and rewritten, and the time. The only gate is the reconciliation's own: zero gaps and no reading date older than the reconciliation (hypothesis until the first reconciliation, A6.5).

21The version change starts only when the owner bumps the product version. A snapshot of the product's surface is recorded for the new version, the difference between two snapshots names the pages to update with a reason each, and only those pages are touched. Readers see a version number and a changelog, never the diff.

22 The version change, hours: the owner bumps the product version — no gate on that step; a cheap model records the surface snapshot of the new version against the current release binary, vibe doc surface --record <new>, beside the snapshot the last reconciliation or version change left — one snapshot while the number stands still, overwritten in place by vibe doc surface --record 1.0.0, for as long as PROP-057 ##VERSION-OVERWRITE-POLICY holds; vibe doc diff <old> <new> names the pages to update with a reason each — an empty list is also an answer; the central session updates only the pages named and writes new ones for what appeared without a page, the rest becomes docs: debt with an atom; a human changelog between versions is written from the diff by hand and the diff itself is never published; the package is published again under that same number, with a dated entry in the changelog and the new [[documents]] version, and the site shows it as latest; the journal records how many pages the diff named, how many were updated, and the time (J-017, J-099; PROP-057 ##OBS-SURFACE-SNAPSHOTS, ##OBS-NOTHING-LEAKS).

23Until the owner says otherwise, every number this repository publishes stays 1.0.0, and a change goes out under the same number in place: the site shows the current content of the number, the changelog records what changed by date, and a project that pinned the number keeps the bytes its lock file recorded.

24 Until the owner decides otherwise (ruling 2026-09-14), every package this repository publishes carries the number 1.0.0, and a change is published under the same number in place: the registry keeps no past publication, the site shows the current content of the number, and the changelog records what changed by date rather than by a new number. A consumer who pinned the number keeps the bytes the lock file recorded, and a fresh install gets the current ones (##SITE-VERSION-SHOWS-CURRENT, PROP-002 ##PUBLISH-MUTABLE-VERSIONS).

What the package keeps for this

25maintenance/reviews.toml records when each page was last read aloud and by whom. It is written by hand, holds a date and a reader, and knows nothing about revisions or hashes: the fact it keeps is that somebody sat down with a page on a day. A page without a row has never been read aloud, and the queue says so. The order of the rows is the reading rota.

26 maintenance/reviews.toml records when each page was last read aloud and by whom, and the date of the last full reconciliation; the order of its rows is the reading rota. It is authored data, never a generated record: a date and a reader, never a revision, a hash or «checked against». A page with no row has never been read aloud, and the queue says exactly that. The reader is named by a name people recognise or by a role such as «central session», never by the name of a model (J-112).

27JOURNAL.md is the journal of the loops. An entry is written in the atom where the event happened, never at the end of the week from memory; it names the evidence and the rule it confirms, changes or creates. A rule of the regulation that no entry produced is a hypothesis until a loop confirms it.

28 Law one. The entry is written in the same atom where the event happened — a red probe, a false positive of the linter, a refuted prediction, a workaround, a trick that worked — never «at the end of the week from memory» (J-046, J-063, J-066: three entries that would have been lost a day later).

29CHANGELOG.md says what changed for the reader, by version, in plain text. The checklists under maintenance/ are the loops as lists: weekly.md, monthly.md, release.md, and after the first reconciliation reconcile.md, written from what was lived.

30 The package carries the checklists the loops are run by — maintenance/weekly.md, maintenance/monthly.md, maintenance/release.md, and after the first reconciliation maintenance/reconcile.md written from what was lived; a checklist item without a rule here is a hypothesis.

Changing the tools

31The queue, the checks, the surface snapshots and the generators are code, and the campaign that built them left rules for anyone who changes them. Two of them bite first: never stop a process you did not start, even to free a binary the build needs, and never take before-and-after measurements while another packet regenerates code in the same tree.

32 A worker never stops a process it did not start; a busy binary is waited for or built into a private target directory, and a worker that flips the features of the shared binary returns it to the panel's state or says it could not (J-105, J-110).

33 Before/after measurements are taken one at a time and with no other packet's codegen in the tree; a test that reads generated code is not measured during parallel work (J-101).

34A step that reads the output of vibe doc build runs at least once over the real manual before it is committed, and a number written into a task is a guess until it is measured on the built output. Both rules exist because fixtures were green while the real output lost two projections of three and a policy expected two inline scripts where the output carried forty-seven.

35 A step over the output of vibe doc build runs at least once over the real manual before it is committed, and a builder runs once over the real registry: fixtures did not catch a copy step that lost two projections of three, a shelf that stayed empty, or a table that lost its first row (J-097, J-108).

36 A number in a packet is a hypothesis until measured on the built output — the content-security policy expected two inline scripts and the output carried forty-seven (J-096); a generator's zero exit code is not evidence, the page count is (J-040).

Edge cases and rules

37A small edit is one commit with a concrete description; the fifth small edit of a page since it was last read aloud sends the page to the front of the reading rota. A small edit that pulls other pages after it is not small and becomes a debt line with an atom.

38 One edit is one commit docs(vibevm-docs): … with a concrete description, so the reading rota and the rule of five can count them (J-112: five edits, five commits).

39 A small edit that pulls other pages after it is not small: it becomes a debt line with an atom (J-062: seven pages described a layout vibe init does not create, and the fix was an atom, not a patch).

40The journal ships with the package. An entry therefore names no private infrastructure, no unconfirmed defect of a neighbouring product and no path of somebody's machine; the same gate that guards the campaign records runs over it.

41 The journal ships with the package, so an entry names no private infrastructure, no unconfirmed defect of a neighbouring product, no user-local identifier and no temporary path; the campaign-side gate that checks those patterns runs over the package journal before every commit that touches it (J-046, J-111).

42The cadences, who is on duty for the weekly loop, whether small edits ship weekly or monthly, and whether an agent may write a docs-gap: line into a project's backlog are the owner's open questions; until his word the loops run as written here and the skill only proposes.

43 Open to the owner: the cadences — week and month as written, or two weeks and a quarter; who is on duty for the weekly loop — the owner with the central session, or the session alone with a report; whether small edits ship as a patch version weekly or accumulate to the monthly release.