# Как сопровождается это руководство {#root} @status:doc/work @audience:dev,author [p01] Это руководство — пакет, и оно расходится с продуктом, как любой код на следующий день после выпуска: продукт добавляет флаг, читатель задаёт вопрос, на который не отвечает ни одна страница, абзац, залатанный пять раз, перестаёт читаться. Само по себе это не останавливается, поэтому руководство держится на небольшом наборе петель с именованными триггерами, очереди, которая измеряет пробелы, и журнале, куда записывается, что нашла каждая петля. Эта страница говорит, что это за петли, что их запускает и что вы должны, когда меняете продукт. [p02] ```text The maintenance queue by the CURRENT state of the package and the product: obligations nobody tells, citations that no longer resolve, adaptations that do not mirror, pages owed a reading aloud, documentation debt and what the style linter found. It prints the numbers and returns success whatever they say — no technical gate binds a release of the product to its documentation, so this measures rather than stops Usage: vibe doc todo [OPTIONS] Options: --json Produce machine-readable JSON output --path The documentation package. Defaults to the current directory [default: .] --format How the queue is printed: the week's report for a person, or the month's eight numbers for a machine [default: md] [possible values: md, json] --quiet Reduce output to a single summary line (useful in scripts / CI) --examples Also run every documented example and fold the red ones in. Without it they are not measured, and the queue says so rather than reporting none: the runner builds a sandbox per fixture and costs minutes, which is not what a weekly reading should cost --invoked-by Identifier of the agent or harness invoking this command. Free-form string; conventional values are `claude-code`, `claude-desktop`, `cursor`, `opencode`, `codex`. When set, the value is stamped onto every JSON envelope vibe emits (`"invoked_by": ""`) so the caller's context is recoverable from logs and machine-readable output. Falls back to the `VIBE_INVOKED_BY` environment variable when the flag is absent; flag wins on conflict. The `vibevm` skill installed by `vibe mcp install --with-skill` instructs each agent to pass this flag automatically --agent-mode PROP-054 `##AGENT-HANDSHAKE`: how this invocation executes `agent` lifecycle contributions. `cli` calls the configured provider and pays for it (the R7.2 behaviour); `agent` never constructs a provider — each selected agent row is PARKED as a Markdown task under `.vibe/agentic/outbox//` for the hosting agent to perform, and the same command resumes the run once the declared outputs exist. The default, `auto`, resolves to `agent` exactly when the resolved `--invoked-by` / `VIBE_INVOKED_BY` value is present (something is hosting this process) and to `cli` otherwise. An explicit `cli`/`agent` always wins over `auto`'s inference Possible values: - auto: Infer from the resolved invoked-by value: present → `agent`, absent → `cli` - cli: Always call the configured provider, as R7.2 did - agent: Never construct a provider; park each agent row for the hosting agent [default: auto] --min The bar the coverage and style readings state. It changes what the report says the target is, never whether this command succeeds [default: 100] --backlog The debt file to count `docs:` lines in. Defaults to `BACKLOG.md` at the root of the checkout this runs in --unattended Run unattended — skip every confirmation prompt and refuse to open any interactive wizard. Equivalent to passing `--assume-yes` (`vibe install` / `vibe uninstall`) or `--yes` (`vibe mcp install` / `upgrade` / `uninstall`) to whichever subcommand needs it. Falls back to the `VIBE_UNATTENDED` environment variable (truthy values: `1`, `true`, `yes`, `on` — case-insensitive); flag wins on conflict. Stamps `"unattended": true` on every JSON envelope so log aggregators can tell scripted runs from interactive ones. Designed for first-time-user provisioning, CI, and other fully scripted environments --journal The journal to count entries owing a decision in. Defaults to `JOURNAL.md` in the documentation package --offline PROP-010 §2.5: forbid network access for the invocation. Under `--offline`, resolution and fetch must be satisfiable entirely from local sources (the cache, `file://` mirrors, the project's own `vibe.lock` + `vibedeps/`); anything not available locally is a hard error with an actionable message — never a silent degrade to a partial result. Falls back to the `VIBE_OFFLINE` environment variable (truthy values: `1`, `true`, `yes`, `on` — case-insensitive), then the user-config `[net].offline` key; the flag wins on conflict. Online remains the default and is unchanged. `vibe install --offline` (PROP-030 §3.1) stays and ORs into the same posture as one more input --binary The `vibe` binary the examples run and the surface is read from. Defaults to the running one --sandbox Where example sandboxes are built --timeout Seconds one documented command may take before it is killed [default: 300] -h, --help Print help (see a summary with '-h') ``` ## Нет замка между продуктом и руководством {#no-lock} [p03] Продукт выпускается много раз в день и вливает много пул-реквестов; руководство не может следовать за каждым, и это принято. Никакие ворота не держат выпуск продукта ради документации, и ни один шаг панели самопроверки не краснеет оттого, что продукт ушёл вперёд страницы. Панель красная, только когда руководство сломано изнутри: пример, чей вывод изменился, блок `derived`, который больше не собирается, цитата, чей [якорь](../glossary/index.xml#anchor) исчез. > [p04] 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). > > > [p05] 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. > > [p06] Вместо замка есть мера. Команда очереди печатает пробелы числами: обязательства, о которых не говорит ни одна страница, примеры, которые больше не совпадают, цитаты, которые не разрешаются, страницы, которые никто не читал вслух, строки долга, счёт линтера. Она никогда не валит сборку и отличает «ничего не найдено» от «никто не смотрел»: секция, которая не запускалась, печатает `null`, а не ноль. > [p07] `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} [p08] Изменение, которое видит пользователь, несёт свою страницу в том же коммите: новая или изменённая команда или флаг, поле [манифеста](../glossary/index.xml#manifest) или лок-файла, формат отчёта, сообщение об ошибке с адресом, [факт](../glossary/index.xml#fact) спецификации, помеченный для документации, новая [спецификация](../glossary/index.xml#specification). Руководства разработчика уже работают так, а шаблон пул-реквеста держит привычку одной галочкой: документация обновлена, долг записан или не нужна. > [p09] **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`). > > [p10] Когда страница не может прийти вместе с коммитом, коммит приносит вместо неё строку долга: строку в `BACKLOG.md` хоста с префиксом `docs:`, серьёзностью и адресом изменения. Строка без адреса не принимается. Месячная петля осушает список. > [p11] 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). > > [p12] Перед любой правкой посмотрите `git status` и убедитесь, что никакая другая сессия не пишет в том же дереве. В дереве, разделённом с параллельными воркерами, коммитьте только с явными путями, чтобы ничьи проиндексированные файлы не уехали внутри вашего коммита. > [p13] 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 … -- `, never a bare commit or `git add -A` (J-072, J-090). > > > [p14] 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} [p15] Недельная петля занимает меньше часа. Дешёвая модель прогоняет очередь и проверки по всему пакету и складывает отчёт. Сопровождающий разбирает очередь: что занимает пять минут, чинится сейчас, не больше пяти правок за петлю; что больше, становится строкой долга; что спорно, становится однострочным вопросом владельцу. Одна страница читается вслух, следующая по ротации чтения, и каждая запинка становится правкой или строкой долга. Запись в журнале закрывает петлю. > [p16] **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). > > [p17] Месячная петля занимает полдня с владельцем: восемь метрик с их трендом, аудит корпуса, осушенный список долга, списки линтера, пополненные тиками, которые проскочили мимо него, каждая запись журнала с её решением, три страницы, прочитанные вслух, и публикация под тем же номером с датированной записью в списке изменений, написанной руками. > [p18] **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). > > [p19] Полная сверка — обещание, которое команда даёт себе, раз в квартал и перед крупной вехой: руководство сверяется с текущим бинарником выпуска, каждая страница перечитывается против продукта с открытыми рядом текстом справки и спецификацией, [адаптации](../glossary/index.xml#adaptation) перечитываются против своих источников, и пакет выпускает версию, совпадающую с выпуском. Единственные её ворота — её собственные: ноль пробелов и ни одной даты чтения старше сверки. > [p20] **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). > > [p21] Смена версии начинается, только когда владелец поднимает версию продукта. Для новой версии записывается снимок поверхности продукта, разница двух снимков называет страницы для обновления с причиной для каждой, и трогаются только эти страницы. Читатели видят номер версии и список изменений, никогда не диф. > [p22] **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 `, 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 ` 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`). > > [p23] Пока владелец не скажет иначе, каждый номер, который публикует этот репозиторий, остаётся `1.0.0`, а изменение выходит под тем же номером на месте: сайт показывает текущее содержимое номера, список изменений ведётся по датам, а проект, закрепивший номер, хранит байты, которые записал его [лок-файл](../glossary/index.xml#lock-file). > [p24] 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-is-kept} [p25] `maintenance/reviews.toml` записывает, когда каждую страницу в последний раз читали вслух и кто. Он пишется руками, держит дату и читателя и ничего не знает о ревизиях или хешах: факт, который он хранит, в том, что кто-то сел со страницей в такой-то день. Страница без строки никогда не читалась вслух, и очередь так и говорит. Порядок строк — ротация чтения. > [p26] `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). > > [p27] `JOURNAL.md` — журнал петель. Запись пишется в том атоме, где случилось событие, никогда в конце недели по памяти; она называет улику и правило, которое подтверждает, меняет или создаёт. Правило регламента, которого не породила ни одна запись, — гипотеза, пока петля его не подтвердит. > [p28] **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). > > [p29] `CHANGELOG.md` говорит, что изменилось для читателя, по версиям, простым текстом. Чеклисты под `maintenance/` — это петли в виде списков: `weekly.md`, `monthly.md`, `release.md`, а после первой сверки `reconcile.md`, написанный по прожитому. > [p30] 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} [p31] Очередь, проверки, снимки поверхности и генераторы — код, и кампания, которая их построила, оставила правила для всякого, кто их меняет. Два кусаются первыми: никогда не останавливайте процесс, который не вы запустили, даже чтобы освободить бинарник, нужный сборке, и никогда не снимайте измерения «до и после», пока другой пакет задач перегенерирует код в том же дереве. > [p32] 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). > > > [p33] 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). > > [p34] Шаг, который читает вывод `vibe doc build`, прогоняется хотя бы раз по настоящему руководству, прежде чем его закоммитят, а число, записанное в задачу, — догадка, пока его не измерили на собранном выводе. Оба правила существуют потому, что фикстуры были зелёными, пока настоящий вывод терял две проекции из трёх, а политика ждала два встроенных скрипта там, где вывод нёс сорок семь. > [p35] 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). > > > [p36] 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} [p37] Маленькая правка — один коммит с конкретным описанием; пятая маленькая правка страницы с тех пор, как её в последний раз читали вслух, отправляет страницу в начало ротации чтения. Маленькая правка, которая тянет за собой другие страницы, не маленькая и становится строкой долга с атомом. > [p38] 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). > > > [p39] 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). > > [p40] Журнал поставляется с пакетом. Поэтому запись не называет ни приватной инфраструктуры, ни неподтверждённого дефекта соседнего продукта, ни пути на чьей-то машине; над ней работают те же ворота, что стерегут записи кампании. > [p41] 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). > > [p42] Каденции, кто дежурит по недельной петле, выходят ли маленькие правки еженедельно или ежемесячно и может ли агент писать строку `docs-gap:` в бэклог проекта — открытые вопросы владельца; до его слова петли работают, как написано здесь, а [навык](../glossary/index.xml#skill) только предлагает. > [p43] 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. > >