Glossary

The source language is English. org.vibevm.core/vibevm-docs carries [i18n].canonical = "en". Every other language, Russian included, is an adaptation published as its own package (§5): a mirror block for block, free sentence for sentence, with its own jokes and its own glossary of terms. Machine translation may produce a draft and never the text.

Anchors are immutable; a rename is a tombstone — for published documentation pages as for specs, and for translations, which must match their source.

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.

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.

[boot_snippet] (package-role) drops the filename field (the NN- target name) and gains category (§2.5); source — the path to the boot file inside the package — is retained. It may carry an optional suggested link default, and an optional when activation condition — the declaration site for §2.3's dynamic-entry when, closing the gap Phase 4 flagged. For v1 the only when is an operating-system match, the wire string "os:<name>" with <name> one of windows / macos / linux; a snippet carrying a when is dynamic (§2.4). The package author owns this declaration: whether a boot snippet is OS-specific is the author's knowledge, not the consumer's.

Decision. A package's identity is the tuple (kind, name, version, content_hash). The content_hash is a digest over the deterministically-ordered concatenation of (rel_path_bytes || 0x00 || file_bytes || 0x00) for every file in the package directory, and the value names the recipe that produced it (PROP-044 §4.7): sha256-tree/1:<hex> is recipe 1, whose exclusion list, path normalisation and traversal order are carried as data in formats/hash_recipes/1.toml; the bare sha256:<hex> is recipe 0, the pre-recipe form, frozen verbatim in code — not configurable, because a frozen recipe that can be edited is not frozen — so that values written before recipes were named stay readable. Two hashes are comparable only at the same recipe; comparing across recipes answers a question nobody asked, and is never done silently. PROP-024 §2.2 re-scopes this to the package's shippable tree — its source, minus build output (.git/, .vibe/, target/, node_modules/, .vibeignore globs) — so a code-bearing package's identity is its source, not its build state; that exclusion lands with the code that implements it. The URL used to fetch the content is informational — recorded in the lockfile for debuggability, not for identity.

Official documentation is the one whose edges converge: the subject named the package and the package declared the subject. Community documentation has only the edge from the documentation. An edge from the subject alone reads «not published or an error», and the site shows a warning.

<family>-docs — the documentation companion (kind = "doc", PROP-057 §3): the official-by-default documentation of the family's subject, in the subject's group. Unlike the three code roles it is a companion, not a member: it is never pinned by the aggregator, it does not take part in the family's unison (§2.2), it keeps its own version line, and it states compatibility with its subject through the version constraint of its [[documents]] table. Its translations follow the same companion form, one package per language, named <family>-docs-<lang> with a lower-case BCP-47 tag (rust-ai-native-docs-ru). Amended 2026-09-11.

A contribution binds a handler to a point. It is declared as an [[extension]] table — in a package manifest (the package ships and offers the behaviour) or in the project manifest (the host adds its own). The shape is one grammar for every family:

Decision. Package identity becomes (group, name, version, content_hash). kind leaves the identity tuple.

Deploy profiles select ordered targets; plan is read-only. The engine owns provider selection, collision locks, intent/checkpoints, receipts, three-digest recovery, inverse sequencing and exact resource ownership. vibe-bin plus isolated Claude/Codex/OpenCode skill/plugin adapters implement plan/apply/verify/recover/remove without touching foreign neighbours. Evidence: 0a42456e, 45d88e80, ae36ac48.

Version resolution operates on E(R) only: private edges of non-root packages contribute no constraints, fetch nothing, and cannot conflict. vibe.lock records E(R) — the lock of a consumer no longer contains other packages' dev-world entries. Version unification (one node per (group, name), PROP-003/017) is unchanged within the effective set. A welcome simplification vs code ecosystems: the Cargo-RFC-1977 problem («may private deps duplicate at different versions?») does not arise — an invisible package has no copies at all.

This PROP makes the in-tree packages/ of a source-installed vibe an ambient default registry — resolved automatically, with zero configuration in the consuming project.

An extension point is a string <family>:<name>. Three families: phase: — the default-lifecycle phases and clean (project-scoped moments: phase:build, phase:create, …); compile: — the compiler's two tiers: the §7.2 staged positions (compile:source, compile:document, compile:lane, compile:emitted) and the §7.4 pass tier's single point compile:pass, whose position inside the pipeline is carried by the contribution's pass = { … } declaration; slot: — the per-package materialisation moments that already exist as PROP-020 (slot:pre-install, slot:post-install), re-stated in this vocabulary without changing their semantics, timing, or manifest spelling ([[hooks]](../modules/vibe-workspace/PROP-020-install-hooks.xml#manifest) keeps working verbatim; it is now sugar for two slot: contributions).

Decision (ADR-part; owner ruling 2026-08-22, verbatim): «сконвертируй и факты тоже. Предлагаю такой формат <fact-name fact="true" ...>. Таким образом кастомный XML-парсер всегда может найти соответствующие элементы». A fact serialises with its ID as the element name, carrying the DISCRIMINATOR attribute — <THE-LAW fact="true" status="impl/done">body</THE-LAW> — so a reader that knows nothing of the vocabulary still finds every fact by one attribute test. The recognition law: an element IS a fact iff its name is fact (the generic form, which stays in the dialect) or it carries fact="true". The named form is emitted whenever the id passes the same elementability predicate sections use (fact-id grammar already forbids leading digits, so the fallback tail is vocabulary collisions only); the typed-fact fence binding stays by id and does not change. The owner's second clause binds the scanners: the progress machinery must work when a fact's SOURCE — not a materialised copy — is authored XML; the host lane holds by construction (XML sources enter progress through the canonical MD projection) and is PINNED by explicit tests (an observed .xml source scans unit-for-unit equal to its MD twin), while the specmap engine's native reader learns the named form mirror-wise. The converter recipe bumps again (specdoc/2 → specdoc/3); the host re-materialises once, after both shapes land. The owner's third clause (2026-08-22, same sitting) binds the boot lanes: «статические и динамические лоадеры должны хорошо работать с новым синтаксисом фактов» — pinned at the transition's landing by (a) the static-splice determinism test running over a NAMED-shape snippet whose projected facts survive into STATIC, (b) the vibe-spec normal-closure byte-equality test running over BOTH serialisations (generic and named) of one dependency, and (c) the polygon re-run at specdoc/3, whose control package auto-adopts the named shape through to_xml — INDEX targets, STATIC splice and every machine loader then exercise the final syntax end-to-end; the agent half of the dynamic router is §5a's measurement, deliberately run AFTER this transition so it measures the shape that ships. Landed: the recipe is specdoc/3, the host's 37 slots re-materialised once with named facts live (the redbook README golden pins 45), the recognition law holds in both readers with fact="false" a loud error, progress holds full ParsedDoc parity between an XML source and its hand-pinned MD twin across two scans, and pins (a)–(c) are in the tree — the splice snippet ships <BOOT-RULE fact="true">, the normal closure compiles three lanes byte-equal, the polygon re-ran 3/3. A live lesson worth its line: XML reserves every case-insensitive xml-prefixed name, so XMLBOOT cannot be an element — the predicate refuses it and the generic form carries such ids.

A package family is a set of packages sharing a <family> stem and delivering one coherent capability across three roles:

Decision. A package's vibe-package.toml gains a [features] table describing optional, conditionally-activated components:

content_hash is unchanged — computed over package file bytes per PROP-002 §2.1. group lives in vibe.toml, so it influences the hash only as ordinary file content; the tuple lists it explicitly so that changing group yields a different package.

Every phase execution owns a fingerprint — a hash over its declared inputs (for install: manifest+sources, already built; for build: the slot sources + project sources the preset names; for create: the prompt documents + their spec closure). A phase whose fingerprint matches the recorded one skips, reporting fresh per contribution — the Gradle up-to-date property grafted onto the Maven ritual. This is the design answer to «если vibe.toml не поменялся, инсталлировать пакеты не нужно», generalised to all nine phases because create (tokens) and build (native compile time) are even more expensive than install.

access = "friends-only" — Q seeps through P only into consumers whose friend closure contains P (§2.4): those who deliberately named P (directly or transitively) a friend. The curated middle.

Identity. Identical content-hash discipline as registry-resolved (§2.1): identity is (kind, name, version, content_hash); the URL is informational. Two projects that pull the same git-source from different mirrors and produce the same content_hash are bit-identical installs. Force-pushed tag rewrite caught as IntegrityError.

A contribution's handler.kind is one of five. Two wrap machinery that exists; three are new. All five are legal at every phase:/slot: point; the compile: family accepts builtin and native only (§8.5 explains why).

A package may declare pre-install / post-install scripts in its manifest. vibevm runs them at fixed points in the install pipeline, in the package's own materialised slot, choosing the right interpreter for the host OS.

Decision. Package repositories are the source of truth for content (manifests, files, tags). The index is a derived hot cache, regeneratable from the authoritative package state.

kind ∈ {flow, feat, stack, tool, mcp, lang, doc, app} — eight kinds; mcp shipped with PROP-027; doc and app admitted by PROP-057 through the VIBEVM-SPEC.md §4.1 amendment of 2026-09-12 (pending the owner's ratification at the merge of the docs-2026-09 branch; the code learns the two kinds in that campaign's phase 2). (§Invariants INV-VOCABULARY in this file carries the same list.)

A documentation package MAY declare a learning path in [navigation]: [[navigation.chapter]] rows, each with an id, a title and pages — the document paths the chapter holds, in reading order — and optionally appendix = true for a chapter of pages a reader looks things up in rather than reads through. The rows in their written order are the path: followed from the first page of the first chapter to the last page of the last, it meets every page of the package once. The path is written for people and moves no other order: pages in the page manifest and the llms files keep the layer law (spec://org.vibevm.core/vibevm/common/PROP-048#THE-LAYER-LAW), and the page manifest carries the path beside them as navigation.chapters.

vibe has two lifecycles. clean — one phase, exactly PROP-053. default — nine phases, in this fixed order:

Decision. Each dependency declares an inclusion type, set by the consumer in its vibe.toml on the [requires.packages] entry:

With the freshness check, vibe install becomes lockfile-respecting: unchanged [requires] ⇒ the locked versions are honoured verbatim.

Decision. vibe owns exactly one managed block inside each agent instruction file — a contiguous region bounded by an opening and a closing marker.

Decision. vibe-package.toml is retired as a distinct filename. Every node — project root, workspace member, published package — carries a single vibe.toml; the role is expressed by which sections are present. This is the cargo model: one Cargo.toml carries [package] and/or [workspace].

An mcp package is one whose primary deliverable is one or more Model Context Protocol servers.

A [[mirror]] is an availability copy of the same source — same naming, same identity, same content_hash. The mirror walk falls through on any availability failure (NetworkUnreachable, AuthFailed on the mirror, server error, content_hash mismatch). RepoNotFound from a mirror bubbles up to the registry-walk layer (same policy as if the canonical primary had said UnknownPackage), because absence-of-package is a registry-level fact, not a mirror-level one.

Officiality is never stored as a flag: it is computed from the convergence of edges at every render. A field official = true in a manifest or an index is a design error.

Decision. [[override]] bypasses the registry layer for a named pkgref:

Owner-ruled (2026-08-23): override is lawful in any manifest, not only the root («разрешён не только в корневом манифесте, а где угодно»). Any node N may carry an [override] table whose entries rewrite foreign edges — their access, friend, presence (exclude = true), or a target's allow-friends — and the rewrite acts wherever N stands on the chain: an aggregator repairs or reshapes a member's edge for all of its own consumers, exactly as it curates its delivery with exclude. The threat model follows the owner's earlier ruling: a deliberate break-in is not an attack (the developer can edit any file on disk anyway); this is the official verb that replaces reflection-style hacks — and it stays quiet (pull-based provenance only).

Decision. A package has the identical on-disk shape as a consumer project:

vibe <phase> executes every default-lifecycle phase up to and including the named one, in order — the Maven ritual verbatim. vibe clean <phase> runs the clean lifecycle first, then the default lifecycle up to <phase> (§4.4). A phase with no contributions and no built-in binding completes as a no-op — Maven's empty-phase law, which is what makes nine slots cost nothing for a prompt-only project (its deploy chain degenerates to validate+install).

[package] and [project] are mutually exclusive in one file — a node is either a publishable package or a plain project, not both. (Decision 7-α from the design session: keep the two sections distinct rather than folding [project] into a [package] with optional kind. Explicitness wins; kind stays strictly mandatory wherever [package] appears.)

A real installed package may displace a builtin deploy mechanism through an exact route/pin. The engine reuses ABI-1, R5 prebuilt/source record and immutable-image carriage, admits the generated mechanism manifest and exact operation, and invokes all six deploy operations while retaining plan/receipt/recovery ownership. Restart plan/recovery/undeploy re-resolve once at the command boundary and exact-compare the durable sidecar binding, existing record/image/digest/path without build, repair, publication or builtin fallback. Evidence: 854707a1, 9465291e, 24b1fe4a, 269bec0d, 370ea177, a24e4aff, d475963c.

Deploy profiles select ordered targets; plan is read-only. The engine owns provider selection, collision locks, intent/checkpoints, receipts, three-digest recovery, inverse sequencing and exact resource ownership. vibe-bin plus isolated Claude/Codex/OpenCode skill/plugin adapters implement plan/apply/verify/recover/remove without touching foreign neighbours. Evidence: 0a42456e, 45d88e80, ae36ac48.

Each package is its own git repository — no monorepo. Per-package maintainer permissions are hosting-native (a package repo's owner controls access); no central merge queue.

Decision. When a reasoning operation runs under the relay backend, it does not act. It writes an Intent — a markdown prompt with light frontmatter (id, source command, created-at, status) — to a single-slot mailbox, the project-local .vibe/agentic/command.md (§3), and returns a pointer telling the caller to drain it.

Scrape is the terminal cleaning operation defined here: it removes the selected VibeVM repository layer while preserving the native product. The command vocabulary deliberately reserves attach and detach for a future live-tool relationship such as connecting and disconnecting a debugger. Scrape is never an alias for that future runtime operation, and no detach spelling is accepted by this command.

Decision. Installing a skill into an agent is a projection: read the declared skill body from the package (in vibedeps/… once installed) or an external source authenticated by the package's matching lock record, and write it into each target agent's skill directory in that agent's own convention (.claude/skills/<name>/…, .opencode/skills/<name>/…, .agents/skills/<name>/… — the paths PROP-015 §2.6 already resolves).

spec://org.vibevm.world/addressable-specs/flows/addressable-specs/ADDRESSABLE-SPECS-PROTOCOL#THE-SPEC-TREE-IS-THE-ONLY-CHANNEL

Decision (override clause corrected 2026-08-20 to the later, more specific ruling). The package store is machine-global, not project-scoped — one store per machine at <settings-home>/cache, relocated only with the settings home ($VIBE_SETTINGS); no store-specific override exists — ##THE-STORE-IS-DOT-VIBE-CACHE is the governing ruling. (VIBE_REGISTRY_CACHE, which this decision originally named, governs the registry clone cache — a different layer that keeps its own job.)

[[documents]] is REQUIRED in a doc package, may list several subjects, and its version is a semver constraint.

Per §2.7 of PROP-004, Tessl's headline marketing claim — version-matched documentation — rides on the describes field at the tile level. vibevm goes one step further: the field is available on subskills as well as packages. A flow:wal package as a whole may not bind to any one library, but its subskills/stack/rust/ cut binds specifically to pkg:cargo/sqlx@0.8.0; another subskills/stack/rust-diesel/ cut binds to pkg:cargo/diesel@2.x. The two coexist in the same package, and the activation channel context.if_describes_match selects the right one for the consumer's actual library version.

spec://org.vibevm.ai-native/core-ai-native/mechanisms/PROP-014#FORCE-INVARIANTS-ARE-MACHINE-CHECKED

An official translation is one that declared translates on the source and is published by the same group as the source under the name <docname>-<lang>; everything else is a community translation (§6).

flow:wal@^0.3 → semver range.

Decision. A vibe.toml may carry a [workspace] table declaring member packages: