# Как агент читает это руководство {#root} @status:doc/work @audience:agent [p01] Это руководство публикуется для машин так же, как для людей. Агент может получить любую страницу простым текстом, спросить, где живёт правило, и загрузить весь корпус одним файлом, подобранным под его бюджет. ## Машинные файлы {#the-files} [p02] | Адрес | Что это | Когда читать | | --- | --- | --- | | `https://vibevm.org/doc/llms.txt` | индекс: по строке на страницу, первый абзац страницы | сначала, чтобы выбрать страницу | | `https://vibevm.org/doc///.md` | одна страница простым Markdown, с номерами блоков | чтобы ответить на один вопрос | | `https://vibevm.org/doc///.xml` | та же страница в исходной форме, со всеми адресами правил и примерами | чтобы процитировать правило или выполнить пример | | `https://vibevm.org/doc/llms-small.txt`, `llms-medium.txt`, `llms-full.txt` | корпус в трёх размерах, стабильный текст первым | только когда задача охватывает много страниц | | `https://vibevm.org/doc/manifest.json` | каждая страница с её языком, аудиториями, статусом и якорями | для программной навигации | | `https://vibevm.org/doc/resolve/?uri=spec://…` | резолвер: адрес на входе, страница и блок на выходе | когда сообщение или страница цитирует адрес | | `https://vibevm.org/doc/ru/…` | те же файлы для другого языка | когда пользователь читает на этом языке | > [p03] publish `llms.txt` (an index with one-line summaries) and `llms-full.txt` for the base corpus, plus `llms-small.txt` and `llms-medium.txt` under a token budget, all derived from the same manifest as the navigation, the full corpus ordered by the layer law (stable before mutable); the same files per language and per package; the registry `llms.txt` is a catalogue of documentations in the arXiv style — title, officiality star, publisher, language, audiences, abstract, link; > > > [p04] serve every page as clean Markdown at the address with the `.md` suffix and as raw XML at the `.xml` suffix; > > [p05] Сайт также отдаёт манифест: JSON-список всех страниц с их статусами, языками, аудиториями и якорями, по адресу `/doc/manifest.json` и разрешает адрес `spec://` по адресу `/doc/resolve/?uri=…`; `` — это группа и имя руководства, `org.vibevm.core/vibevm-docs`, а `` — номер или `latest`. > [p06] serve the JSON page manifest with officiality statuses, languages, audiences, genres, anchors and summaries (`/doc/manifest.json`), a resolver endpoint for `spec://` addresses (`/doc/resolve?uri=…`), and optionally an MCP server of the site; > > ## Без сети {#offline} [p07] Те же страницы живут в машинном [хранилище](../glossary/index.xml#store), как только выполнен `vibe cache add org.vibevm.core/vibevm-docs`. `vibe explain "spec://org.vibevm.core/vibevm-docs-ru/#"` печатает страницу или блок; `vibe doc manifest --llms small` печатает список страниц из хранилища. Ничто на этом пути не обращается к сети, и потому проприетарную документацию читают именно так. > [p08] The store is warmed with `vibe cache add ` from a registry, or `vibe cache add --offline ` from a project root whose project-local registry holds the package in-tree; the sources of `vibe-doc` are the store (`lookup`, `list_all`), the lock file (`Lockfile::read`, `slot_abs_path`), a registry (`resolve_and_fetch`) and a checkout (`LocalRegistry`). > > ## Как сослаться на место {#citing} [p09] Каждый блок на странице несёт номер, `p12` и так далее; он присваивается при сборке страницы и одинаков в веб-странице, в Markdown и в XML. Ссылка — это адрес страницы плюс этот номер: `spec://org.vibevm.core/vibevm-docs-ru/model/boot-lane#p7`. Заголовки сохраняют и именованные [якоря](../glossary/index.xml#anchor), и именованный якорь после публикации не меняется никогда; [номер блока](../glossary/index.xml#block-number) называет текущий текст и после правки может сдвинуться, как номер строки. > [p10] **Numbered blocks.** Every flow block of the pivot — paragraph, list, table, fence, quote, `example`, `rule`, `note`, `figure`, `prompt`; a heading keeps its own id and is not numbered (clarified 2026-09-12 at implementation, following `PIPE-NUMBERING`) — receives an ordinal number and the id `pNN` **at build time** in the Rust pipeline (§10), never by a client script. The number is the block's position in the **current** text of the page, counted before `when` filtering, so that `p12` names the same block in the build for any platform and agent and in every translation; gaps in the rendered output are accepted. The number appears in the HTML island, in the `.md` and `.xml` projections (as `[p12]` at the start of the block) and in `llms-full.txt`, so a human and an agent cite one place. After an edit an old `#p12` may point at a neighbouring block, as a link to a file line does after an edit; this is accepted and nothing tries to «remember» it. Headings keep their named anchors `{#id}` above the number; named anchors are immutable and renamed only by tombstone, positional `pNN` live by the current text. > > [p11] Правила на странице цитируются из [спецификации](../glossary/index.xml#specification) по адресу и показываются на языке самой спецификации. Когда вы говорите пользователю, что гласит правило, предпочитайте адрес спецификации адресу руководства; когда объясняете почему, предпочитайте страницу руководства. > [p12] Every `rule` yields a `documents` edge **without a pin**: the citation is live, and the page shows the fact's current text by address at every render. `vibe doc check --citations` checks one thing — that the anchor exists; a vanished anchor without a tombstone fails the build. There are no revisions, no text hashes and no «the spec moved ahead»: such checks would need a history the project does not keep by design. > > ## Процедура, которой учит навык {#procedure} [p13] 1. На ошибке прочитайте адрес, который называет сообщение, затем страницу, на которую его отображает страница диагностики. [p14] 2. На вопросе отвечайте с одной страницы: первый абзац — простой ответ, блоки правил несут точную формулировку. [p15] 3. На задаче возьмите блок просьбы со страницы как свою задачу и подставьте имена и пути пользователя. Выполните её, затем выполните строки assert. Задача сделана, когда каждая из них завершилась нулём. [p16] 4. Выбирая среди документаций одного пакета, предпочитайте помеченную как официальная и называйте издателя документации сообщества. [p17] 5. Никогда не загружайте весь корпус, когда отвечает одна страница. > [p18] The audience vocabulary of PROP-043 gains `agent`; `user`, `author` and `dev` stay. Text marked `audience="agent"` obeys the laws of agent text: a token budget, no narration, and **never in a boot prefix** — the site serves it in the «for agents» section and first in `llms.txt`. Audiences are not declared in the manifest; they are derived from the page markup. > > ## Инструменты сервера {#the-tools} [p19] `vibe mcp serve` предлагает те же операции как инструменты. `explain` смотрит на один узел карты по адресу; `query` находит узлы, и это два разных глагола намеренно. `select` принимает до семи предикатов, `uri:`, `symbol:`, `kind:`, `scope:`, `has:`, `lacks:` и `depth:`, через пробел, соединённых по И, без операторов. Неизвестный предикат, повторённый предикат или пустой запрос — ошибка, которая называет токен и перечисляет, что ожидалось. > [p20] **`query` finds nodes; `explain` > looks at one.** Until 2026-08-06 the map could only be asked about a target > already known by name, so *«which of these exist?»* was unanswerable — not in > the host, not in any language stack, not in the engine. `query` is that > question, and the two are deliberately separate verbs rather than one verb with > a mode: a point lookup and a set filter render differently, cap differently, and > fail differently. > > > [p21] **Seven predicates, whitespace > separated, joined by AND, and no operators at all:** `uri:`, `symbol:`, `kind:` > (the filter level's own), `scope:` (prefix of a spec address), `has:` / `lacks:` > (an edge verb), `depth:` (0..3). No disjunction, no parentheses, no precedence — > each of those is a permanent versioning liability, and a predicate can be added > without renumbering a language that has no operator layer to renumber. > > > [p22] **An unknown predicate, an unknown > verb, a repeated predicate, an out-of-range depth or an empty query is an ERROR > that names the offending token and lists what was expected** — never a silently > ignored clause. Same law as the markup's typed fences, for the same reason: a > grammar that ignores what it does not understand promises everything and checks > nothing, and whoever trusted the promise is the one who finds out. An empty query > is refused rather than read as «everything», because that answer already exists > one verb away. > > [p23] `query_package` возвращает полную запись установленного пакета из лока. `read_subskill` возвращает содержимое активного [поднавыка](../glossary/index.xml#subskill), где бы он ни жил: в дереве проекта или в машинном хранилище. `materialise_subskill` копирует лениво подтянутый поднавык в дерево проекта и отказывается перезаписывать без `force`; это единственный инструмент, который пишет. > [p24] **`query_package`** — the full lockfile entry for an installed package > (kind, version, `content_hash`, registry, source, `files_written`, > features, active subskills, `describes` PURL, language). Read-only. > > > [p25] **`read_subskill`** — the concatenated content of an active subskill's > files. `eager` / `lazy-push` subskills read from the project tree; > `lazy-pull` subskills read from the package cache (PROP-003 §2.5.0), so > the agent gets bytes regardless of delivery mode. Read-only. > > > [p26] **`materialise_subskill`** — copy a `lazy-pull` subskill's content into > the project tree. No-op for `eager` / `lazy-push` (already on disk); > refuses to overwrite without `force`. The one writing tool. > > [p27] Языковые пакеты вида `mcp` приносят собственные серверы с четырьмя инструментами, `tcg_validate`, `tcg_scope`, `tcg_complete` и `tcg_type`: тонкими адаптерами над операциями с теми же именами. Каждый принимает обязательный `language`, `typescript` или `rust`, и собственные параметры операции без изменений. Каждый отвечает обогащённым результатом как структурированным содержимым плюс коротким текстом, в котором находки идут первыми. > [p28] The tools now ship in the per-language > `mcp`-kind packages ([PROP-027](PROP-027-mcp-packages.xml): > `mcp:org.vibevm.ai-native/rust-ai-native-mcp`, `…/typescript-ai-native-mcp`), each > serving its own language over the vendored `mcp-core` transport. > > > [p29] `tcg_validate`, `tcg_scope`, `tcg_complete`, `tcg_type` — thin schema > adapters over the TCG-PROTOCOL ops of the same names, each with: > > > [p30] `language` (required; accepts `"typescript"` and — since the Rust > twin landed, exactly as this clause promised — `"rust"`; any other > value is a ToolError NAMING the supported set, so the next language > adds an enum value, not new tools); > > > [p31] the op's own params per TCG-PROTOCOL §2 (`file`, `position`, > `content`, …), passed through verbatim. > > > [p32] Responses return the ENRICHED protocol result (TCG-PROTOCOL §3) as > `structuredContent`, plus a compact human text rendering (findings > first). > > ## Особые случаи и правила {#edge-cases} [p33] Текст, написанный для агентов, никогда не входит в [стартовую полосу](../glossary/index.xml#boot-lane) проекта; это руководство берут, когда нужно, а не читают на каждом старте сессии. > [p34] **No documentation page enters `STATIC.xml`, `INDEX.md` or a boot snippet.** A `doc` package has no `[boot_snippet]`; agent-audience text is never in a boot prefix. > > [p35] Сама стартовая полоса — чистое чтение файлов: ничто в ней не выполняется, и руководства в ней нет. > [p36] Boot remains **pure file-reading** — the redirect never becomes "run `vibe`", preserving the zero-dependency cross-agent property of `VIBEVM-SPEC.md` §6.1. > > [p37] Страница, которая есть на языке источника, но не на языке, который вы запросили, отдаётся на языке источника по запрошенному адресу, с пометкой; не считайте её отсутствующей. > [p38] **Switching the language keeps the place.** The language selector leads to the same page in the other language **with the same fragment** (`#pNN` or `#id`), which the block-for-block mirror of §5 makes possible. When the page does not exist in the chosen language, the site serves the source language under the chosen language's address as a statically materialised fallback (`` of the source, `rel=canonical` to the source page, `noindex`), shows a bilingual notice «this page is only in … so far» once per session, and rewrites internal links so navigation stays in the chosen language. The chosen language is remembered in the cookie `lang` for 365 days — the same name the landing uses, so the domain root and `/doc/` remember one choice. > >