# Стартовая полоса: как агент читает проект {#root} @status:doc/work @audience:user,author,agent [p01] Когда агент стартует, он читает короткий упорядоченный список файлов, который vibe вычислил из всего, от чего зависит проект. В списке есть фиксированный первый файл, читаемый целиком, и перечень остальных. Одни записи читаются всегда, другие — только когда выполняется условие, и ничего в списке не написано руками. [p02] Example `tree` is copied from the source page at projection time. ## Порядок чтения {#the-order} [p03] [Сессия агента](../glossary/index.xml#agent-session) начинается с файла инструкций, который читает его производитель: `CLAUDE.md`, `AGENTS.md` или `GEMINI.md`. В конце этого файла стоит короткий блок, который поддерживает vibe, и блок говорит: сначала прочитай `vibevm/vibespecs/boot/STATIC.md` целиком, потом открой `vibevm/vibespecs/boot/INDEX.md` и прочитай каждый файл, который он называет, по порядку. Вот и весь старт: три шага, и все — чтение. > [p04] **Session-start order:** the `CLAUDE.md` / `AGENTS.md` / `GEMINI.md` redirect → `vibevm/vibespecs/boot/STATIC.xml` (if present) → `vibevm/vibespecs/boot/INDEX.md` and the entries it names, in order. > > [p05] `STATIC.md` — приоритетная полоса. В ней текст, который должен оказаться перед агентом раньше всего остального; он собран из пакетов, попросивших читать себя именно так, текст каждого пакета ровно один раз. Файл существует, только когда какой-то пакет об этом попросил; у проекта, все пакеты которого читаются по требованию, приоритетной полосы нет, и `vibe tree` печатает `STATIC.md: (none)`, как выше. Проект, который держит свои стартовые файлы в XML-диалекте, получает вместо него `STATIC.xml` с тем же содержимым. Он меняется, только когда меняется набор пакетов или их версии, и этим дёшев: хост агента может держать его в кэше между сессиями. > [p06] **What STATIC is (the owner's definition, refined): the > generated static boot lane is a CACHE-STABLE PREFIX in LLM-economy terms.** It > is loaded into an agent or subagent once, at the head of its context, and from > then on stays byte-for-byte identical across sessions and spawns — so the > provider's prompt cache serves it as a hit and the user never pays full price > for the prefix twice. It is compiled, anchor-qualified, self-contained > (resolution rules ride inside it), and deliberately front-loaded: the highest > priority content reads first precisely because first is where cache stability > lives. > > [p07] `INDEX.md` — [манифест](../glossary/index.xml#manifest), а не содержимое. Каждая запись называет файл и говорит, *статический* ли он, то есть читается напрямую, или *динамический* — включение, которое агент разрешает по ходу. Запись может нести условие; тогда агент читает её, только когда условие выполняется для текущей сессии, например для одной операционной системы. > [p08] **`INDEX.md`** — a generated **TOML manifest** of the rest of the sequence: a `schema` version, a `static` pointer (the path of `STATIC.md`, when one exists), and an ordered list of `[[entry]]` tables. Each entry carries `path`, `kind` (`"static"` — a resolved file the agent reads directly; `"dynamic"` — an INCLUDE the agent resolves at boot, §2.4), and, for dynamic entries, `when` (the activation condition, §2.4). The manifest is flat and machine-precise — `vibe` performed the graph walk once at generation time; the agent parses one TOML document and reads the listed files, with no recursion, discovery, or cycle-detection. > > ## Откуда берётся список {#where-it-comes-from} [p09] Каждый пакет может внести один [стартовый фрагмент](../glossary/index.xml#boot-snippet): короткий текст, который читается при каждом старте сессии. Пакет объявляет его в своём манифесте с категорией, а манифест проекта решает, как фрагмент связан: вкомпилирован в приоритетную полосу или перечислен в `INDEX.md` и читается по требованию. Выбор проекта сильнее предложения пакета. > [p10] **Decision.** Each dependency declares an **inclusion type**, set by the consumer in its `vibe.toml` on the `[requires.packages]` entry: > > [p11] `link = "dynamic"` — умолчание: [вклад](../glossary/index.xml#contribution) становится путём в `INDEX.md`, читается по требованию и ограничен условием `when`, если фрагмент его объявляет. `link = "static"` вкомпилирует текст в приоритетную полосу, читаемую первой и целиком; им пользуются скупо, потому что он дублирует текст на диске. > [p12] `link = "dynamic"` — **the default.** `vibe` resolves the contribution to a concrete path in `INDEX.md`; the agent reads it dynamically, on demand. An optional `when` condition gates the read: with a `when` it is a **conditional** INCLUDE (loaded only when the condition holds) — mechanically the subskill `lazy-pull` delivery mode; without one it is read unconditionally. The `when` draws on the subskill `[activation]` probe vocabulary (PROP-003 §2.5) — one probe grammar across both mechanisms. **v1 implements the `os:` probe end-to-end** — `when = "os:windows"` matches the session's operating system (`windows` / `macos` / `linux`); the remaining probes are reserved until PROP-003's activation engine is built. > > > [p13] `link = "static"` — the contribution's boot text is compiled into `STATIC.md` ahead of time (whole, anchor-qualified — §2.3). Read first, one read, maximum attention weight. The **emergency priority lane** — for top-level skills and critical disciplines whose priority must be guaranteed by position, not by trusting agent-side resolution. Used sparingly; it duplicates the text on disk. > > [p14] [Тип связи](../glossary/index.xml#link-type) принадлежит ребру: его объявляет потребитель, и он никогда не впечатан в пакет. Голый `static` — это `static-soft`: пакет, статически связанный несколькими потребителями, компилируется один раз в общее место, и каждый на него ссылается. `static-hard` вкомпилирует его в собственную полосу каждого потребителя. `static-transitive` делает статическими пакет и всё его поддерево, перекрывая динамические рёбра внутри. Каждый пакет в дереве зависимостей несёт собственные стартовые файлы: то, что в него вкомпилировано, и то, на что он ссылается динамически; корень проекта — один такой пакет среди многих. > [p15] **Decision.** `link` is a property of the **edge** (consumer-side, declared in the parent's manifest), never baked into the pulled package (as PROP-034 §2.1 already states). A unit `P` is compiled by walking its **own** direct edges `P→X`: > > > [p16] **`static-soft`** — **the default**, the meaning of a bare `link = "static"`. Hoisting dedup at **compile time**: a package statically linked by more than one consumer is **hoisted** to a shared location (§2.4) and linked **once**; each consumer references it. Deterministic; does not depend on read-time behaviour. > > > [p17] **`static-hard`** — explicit opt-in (`link = "static-hard"`). **Pure local** compilation: every consumer compiles the package into its own `STATIC.md` independently, with no hoisting. Duplication is deduplicated at **read time** by the read-set (§2.9). > > > [p18] **`static-transitive`** — `X` and its **entire** subtree are forced `static`, **ignoring** any `dynamic` edges inside — "rewrite the whole tree under `X`". This is the one mode that overrides nested breaks. > > > [p19] **Decision.** Every package materialised under `vibedeps/` carries its **own** boot artifacts — `vibedeps//spec/boot/STATIC.xml` (what is compiled **into** this unit, verbatim) and `.../INDEX.md` (this unit's **external dynamic** references, resolved when the unit loads) — not only entry-point workspace nodes. > > [p20] vibe вычисляет последовательность для каждого проекта из разрешённого графа зависимостей: основа, которую объявляет сам проект, затем его собственный стартовый текст, затем фрагменты его зависимостей, причём зависимость идёт раньше того, что от неё зависит. Авторы не нумеруют свои фрагменты, и два пакета не могут драться за позицию, потому что порядок выводится, а не объявляется. > [p21] Within the computed sequence the order is: `foundation` → the node's own → dependency boot (topologically — a dependency before its dependents) → `user-override`. `static` contributions are concatenated into `STATIC.md` in the same relative order. > > ## Почему она короткая {#cost} [p22] За каждое слово в полосе платят при каждом старте сессии, каждым агентом, который открывает проект. Поэтому полоса держит инструкции, а не объяснения: что делать, где правила, какие адреса цитировать. Всё, что агенту нужно лишь иногда, включая это руководство, остаётся вне полосы и берётся по адресу, когда возникает вопрос. Текст стартового фрагмента нарочно пишется под этот бюджет. > [p23] **Everything is layered by mutation frequency — the whole > loaded context is one monotone gradient (owner, 2026-08-23, near-verbatim: > «всё в приложении устроено слоями; на самой вершине — динамическая загрузка > быстрых изменений»).** Reading order equals stability order: the > rarest-changing text reads first, because a change at depth N re-prices every > byte after it — the earlier a layer sits, the more cache its mutation burns. > The concrete gradient: *(0)* the instruction files (`CLAUDE.md` / `AGENTS.md` > / `GEMINI.md`) — read first, so an edit there resets the ENTIRE cache; they > carry only what must hit every session (the four rules, the standing > directives) and change only for large causes, everything else living in specs > loaded later; *(1)* the generated STATIC lane — structural-events-only (§3), > and INTERNALLY sorted by the same law: contributions of rarer-changing > packages belong earlier in the tape; *(2)* the INDEX manifest and the > conditional dynamic lane — per-boot variability; *(3)* the live session tail — > task text, tool results, fast state, which lives in context and is never > compiled into any lane. This is a GLOBAL architectural idea for all of > VibeVM, not a spec of any one mechanism (owner, 2026-08-23): whenever a new > system is designed or an existing one changed, the design review checks it > against this layering — where does each byte it adds sit on the gradient, > and does anything fast-changing sneak ahead of anything slow. > > [p24] Один и тот же префикс служит каждому агенту: когда босс и его воркеры загружают одну побайтно одинаковую полосу, кэш, который прогрел один из них, служит всем остальным. Вот почему в неё не может попасть ничего посессионного или поагентного: ни имён, ни идентификаторов, ни меток времени. > [p25] **The multiplier: one prefix, every agent.** When > the boss and all its workers load the SAME byte-identical prefix, the cache > warmed by any one of them serves every later spawn — each subagent starts > cheap. This makes the stability requirement STRICTER than per-session > determinism: nothing per-session and nothing per-agent may enter the prefix — > no agent names, no session ids, no roles, no timestamps. Per-agent material > belongs after the prefix, in the variable tail. > > ## Особые случаи и правила {#edge-cases} [p26] Фрагмент, объявляющий условие, всегда остаётся динамической записью, какой бы [тип связи](../glossary/index.xml#link-type) ни просил проект: условие нельзя вычислить заранее, а значит, текст нельзя вкомпилировать в приоритетную полосу. > [p27] A `[boot_snippet]` that declares a `when` condition (§2.6) stays a conditional `dynamic` entry, irrespective of `link`: a condition cannot be honoured by the ahead-of-time `static` lane, so a `when` forces the gated INDEX form. It is a correctness constraint, not a preference — OS-specific content must never reach a session on the wrong OS. > > [p28] Цикл среди требований — жёсткая ошибка при генерации полосы, с указанием виновного пути; полоса никогда не записывается связанной наполовину. > [p29] **Reject cycles.** `requires` is expected acyclic; a cycle is a **hard error at generate time**, reported with the offending cycle path. The boot is never emitted half-linked. (This is the one place cycle detection lives; the agent-side read is a flat, recursion-free parse per PROP-009 §2.) > > [p30] Сгенерированная полоса никогда не бывает целью цитаты. Правила цитируют по адресу их исходного документа, никогда по их месту в `STATIC.md`, потому что полоса — вывод компилятора и меняется всякий раз, когда меняется набор зависимостей. > [p31] **A generated `STATIC.md` is not a citation target** — authored text never cites `spec://…/boot/STATIC#…`; the lane is compiler output, and source-of-truth is the package source under `vibedeps/` (PROP-035 §11's lint, B-011 §6.1). > > [p32] Документация в полосу не попадает никогда. У пакета документации по определению нет стартового фрагмента; агент добирается до этого руководства через [навык](../glossary/index.xml#skill) или по адресу, когда оно ему нужно. > [p33] **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. > >