Как сопровождается это руководство

Это руководство — пакет, и оно расходится с продуктом, как любой код на следующий день после выпуска: продукт добавляет флаг, читатель задаёт вопрос, на который не отвечает ни одна страница, абзац, залатанный пять раз, перестаёт читаться. Само по себе это не останавливается, поэтому руководство держится на небольшом наборе петель с именованными триггерами, очереди, которая измеряет пробелы, и журнале, куда записывается, что нашла каждая петля. Эта страница говорит, что это за петли, что их запускает и что вы должны, когда меняете продукт.

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 <PATH> The documentation package. Defaults to the current directory [default: .] --format <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 <AGENT> 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": "<value>"`) 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 <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/<run-id>/` 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 <PERCENT> 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 <PATH> 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 <PATH> 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 <PATH> The `vibe` binary the examples run and the surface is read from. Defaults to the running one --sandbox <PATH> Where example sandboxes are built --timeout <SECONDS> Seconds one documented command may take before it is killed [default: 300] -h, --help Print help (see a summary with '-h')

Продукт выпускается много раз в день и вливает много пул-реквестов; руководство не может следовать за каждым, и это принято. Никакие ворота не держат выпуск продукта ради документации, и ни один шаг панели самопроверки не краснеет оттого, что продукт ушёл вперёд страницы. Панель красная, только когда руководство сломано изнутри: пример, чей вывод изменился, блок `derived`, который больше не собирается, цитата, чей [якорь](../glossary/index.xml#anchor) исчез.

Вместо замка есть мера. Команда очереди печатает пробелы числами: обязательства, о которых не говорит ни одна страница, примеры, которые больше не совпадают, цитаты, которые не разрешаются, страницы, которые никто не читал вслух, строки долга, счёт линтера. Она никогда не валит сборку и отличает «ничего не найдено» от «никто не смотрел»: секция, которая не запускалась, печатает `null`, а не ноль.

Изменение, которое видит пользователь, несёт свою страницу в том же коммите: новая или изменённая команда или флаг, поле [манифеста](../glossary/index.xml#manifest) или лок-файла, формат отчёта, сообщение об ошибке с адресом, [факт](../glossary/index.xml#fact) спецификации, помеченный для документации, новая [спецификация](../glossary/index.xml#specification). Руководства разработчика уже работают так, а шаблон пул-реквеста держит привычку одной галочкой: документация обновлена, долг записан или не нужна.

Когда страница не может прийти вместе с коммитом, коммит приносит вместо неё строку долга: строку в `BACKLOG.md` хоста с префиксом `docs:`, серьёзностью и адресом изменения. Строка без адреса не принимается. Месячная петля осушает список.

Перед любой правкой посмотрите `git status` и убедитесь, что никакая другая сессия не пишет в том же дереве. В дереве, разделённом с параллельными воркерами, коммитьте только с явными путями, чтобы ничьи проиндексированные файлы не уехали внутри вашего коммита.

Недельная петля занимает меньше часа. Дешёвая модель прогоняет очередь и проверки по всему пакету и складывает отчёт. Сопровождающий разбирает очередь: что занимает пять минут, чинится сейчас, не больше пяти правок за петлю; что больше, становится строкой долга; что спорно, становится однострочным вопросом владельцу. Одна страница читается вслух, следующая по ротации чтения, и каждая запинка становится правкой или строкой долга. Запись в журнале закрывает петлю.

Месячная петля занимает полдня с владельцем: восемь метрик с их трендом, аудит корпуса, осушенный список долга, списки линтера, пополненные тиками, которые проскочили мимо него, каждая запись журнала с её решением, три страницы, прочитанные вслух, и публикация под тем же номером с датированной записью в списке изменений, написанной руками.

Полная сверка — обещание, которое команда даёт себе, раз в квартал и перед крупной вехой: руководство сверяется с текущим бинарником выпуска, каждая страница перечитывается против продукта с открытыми рядом текстом справки и спецификацией, [адаптации](../glossary/index.xml#adaptation) перечитываются против своих источников, и пакет выпускает версию, совпадающую с выпуском. Единственные её ворота — её собственные: ноль пробелов и ни одной даты чтения старше сверки.

Смена версии начинается, только когда владелец поднимает версию продукта. Для новой версии записывается снимок поверхности продукта, разница двух снимков называет страницы для обновления с причиной для каждой, и трогаются только эти страницы. Читатели видят номер версии и список изменений, никогда не диф.

Пока владелец не скажет иначе, каждый номер, который публикует этот репозиторий, остаётся `1.0.0`, а изменение выходит под тем же номером на месте: сайт показывает текущее содержимое номера, список изменений ведётся по датам, а проект, закрепивший номер, хранит байты, которые записал его [лок-файл](../glossary/index.xml#lock-file).

`maintenance/reviews.toml` записывает, когда каждую страницу в последний раз читали вслух и кто. Он пишется руками, держит дату и читателя и ничего не знает о ревизиях или хешах: факт, который он хранит, в том, что кто-то сел со страницей в такой-то день. Страница без строки никогда не читалась вслух, и очередь так и говорит. Порядок строк — ротация чтения.

`JOURNAL.md` — журнал петель. Запись пишется в том атоме, где случилось событие, никогда в конце недели по памяти; она называет улику и правило, которое подтверждает, меняет или создаёт. Правило регламента, которого не породила ни одна запись, — гипотеза, пока петля его не подтвердит.

`CHANGELOG.md` говорит, что изменилось для читателя, по версиям, простым текстом. Чеклисты под `maintenance/` — это петли в виде списков: `weekly.md`, `monthly.md`, `release.md`, а после первой сверки `reconcile.md`, написанный по прожитому.

Очередь, проверки, снимки поверхности и генераторы — код, и кампания, которая их построила, оставила правила для всякого, кто их меняет. Два кусаются первыми: никогда не останавливайте процесс, который не вы запустили, даже чтобы освободить бинарник, нужный сборке, и никогда не снимайте измерения «до и после», пока другой пакет задач перегенерирует код в том же дереве.

Шаг, который читает вывод `vibe doc build`, прогоняется хотя бы раз по настоящему руководству, прежде чем его закоммитят, а число, записанное в задачу, — догадка, пока его не измерили на собранном выводе. Оба правила существуют потому, что фикстуры были зелёными, пока настоящий вывод терял две проекции из трёх, а политика ждала два встроенных скрипта там, где вывод нёс сорок семь.

Маленькая правка — один коммит с конкретным описанием; пятая маленькая правка страницы с тех пор, как её в последний раз читали вслух, отправляет страницу в начало ротации чтения. Маленькая правка, которая тянет за собой другие страницы, не маленькая и становится строкой долга с атомом.

Журнал поставляется с пакетом. Поэтому запись не называет ни приватной инфраструктуры, ни неподтверждённого дефекта соседнего продукта, ни пути на чьей-то машине; над ней работают те же ворота, что стерегут записи кампании.

Каденции, кто дежурит по недельной петле, выходят ли маленькие правки еженедельно или ежемесячно и может ли агент писать строку `docs-gap:` в бэклог проекта — открытые вопросы владельца; до его слова петли работают, как написано здесь, а [навык](../glossary/index.xml#skill) только предлагает.