Glossary

adaptation

02A version of documentation in another language: a separate package that mirrors the source block for block and is free sentence by sentence. This manual says «translation» and «adaptation» for the same thing. See translation.

03 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.

agent session

04One run of a coding agent in a project, from the moment it reads its instruction file to the moment it stops. The boot lane is what vibe prepares for the start of a session.

anchor

05The identifier of a section or a fact inside a specification, the part after # in an address. Once published, an anchor never changes; a rename leaves a tombstone.

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

block number

07The ordinal pNN every block of a documentation page receives at build time; the same in the web page, the Markdown and the XML, so a human and an agent cite one place. It names the current text and may shift after an edit, like a line number.

08 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.

boot lane

09The ordered reading list an agent follows at the start of a session: the managed block in the instruction file, then STATIC.md in full, then the entries of INDEX.md. Computed by vibe from the dependency graph, never written by hand.

10 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

11A package's contribution to the boot lane: one short text declared in [boot_snippet] with a category, read at every session start by every consumer. Documentation packages have none.

12 [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.

capability

13An abstract ability a package provides or requires, written namespace:name with an optional version constraint; the resolver matches requirers with providers at install time.

14 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.

community documentation

15Documentation of a package that declares its subject but is not named by the subject: shown on the site with its publisher, below the official shelf. See official documentation.

16 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.

companion

17A package tied to another by name for the default case of officiality and by nothing else: the documentation <name>-docs of a package, or the translation <docname>-<lang> of a documentation. A companion keeps its own version line and stays outside family unison.

18 <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.

contribution

19A binding of a handler to an extension point, declared as an [[extension]] table in a package or a project; the unit the lifecycle runs and reports.

20 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:

coordinate

21The name of a package: a group, a slash and a name, org.vibevm.world/wal, with @version when a version is meant. The kind is not part of it.

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

deploy profile

23A named, ordered list of targets and the providers that apply packaged artifacts to them; vibe deploy runs one profile, vibe undeploy reverses it.

24 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.

effective set

25The packages that the visibility marks admit from your root: what version resolution sees, what the lock file records and what the dependency tree holds. A private edge of a package that is not your root lies outside it.

26 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.

embedded registry

27The in-tree packages of a source-built vibe, consulted automatically as a registry: first for a developer's build, after the declared registries for a distributed one.

28 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.

extension point

29A named place in the lifecycle a contribution binds to: a phase, a slot inside a phase, or a position in the boot compiler, written family:name.

30 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).

fact

31One anchored unit of a specification with a status: a rule, a decision, a lead-in. In XML an element named after its id with fact="true"; in Markdown a paragraph opening with @fact:ID. The addressable atom an agent cites.

32 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.

family

33A set of packages sharing a name stem that move in unison: the bundle <family>, the language guide <family>-lang, the server <family>-mcp. A change to any member bumps every member to one version.

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

feature

35An optional, additive content set of a package, declared in [features] and activated at install; features may depend on features.

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

fingerprint

37The hash of a package's shippable tree, the identity half of a package version, recorded as content_hash in the lock file and verified on every fetch.

38 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.

freshness fingerprint

39The hash of a phase run's declared inputs, recorded under .vibe/; a phase whose freshness fingerprint did not change is skipped on the next run.

40 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.

friend closure

41The packages a project has befriended, directly with friend = true or a friends line, or through a chain of friends-only edges. A friends-only dependency reaches only the projects whose friend closure contains its provider.

42 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.

git source

43A dependency declared by a git repository and a tag, commit or branch instead of a registry; identity and fingerprint discipline are the same, and a branch is re-walked on update.

44 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.

handler

45What a contribution runs: a built-in, a script, a binary, a native library, or an agent prompt.

46 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).

hook

47A package's pre-install or post-install script, run in the package's slot; installing the package is the consent to run it, and its effects are not tracked.

48 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.

index (of a registry)

49A repository beside a registry's packages that records every published version's summary and fingerprint; a cache that speeds search and cold installs and is never the truth.

50 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

51What a package is for, one of eight: flow, feat, stack, tool, lang, mcp, doc, app. Metadata, not identity; the set grows only by amendment.

52 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.)

lifecycle

53The fixed order of build steps vibe runs: the one-phase clean lifecycle and the nine-phase default lifecycle from validate to deploy. See phase.

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

link type

55How a dependency's boot snippet enters a consumer's lane: static, compiled into STATIC.md, or dynamic, listed in INDEX.md and read on demand; set by the consumer, suggested by the package.

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

lock file

57vibe.lock: the recorded resolution, one per workspace, with every package's exact version, fingerprint and provenance. Written by vibe, committed by you.

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

managed block

59The region between the lines <vibevm> and </vibevm> at the end of CLAUDE.md, AGENTS.md and GEMINI.md, the only part of those files vibe writes; it points an agent at the boot lane.

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

manifest

61vibe.toml: the one file you write to describe a project, a package or a workspace; its tables decide the node's role.

62 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].

MCP server

63A program an agent talks to over the Model Context Protocol. vibe's own server exposes a project's packages; a package of kind mcp delivers servers of its own.

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

mirror

65An alternative address for the same registry, tried for availability and verified against the same fingerprints; never recorded in the lock file.

66 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.

official documentation

67Documentation whose edges converge: the subject names the package in [documentation] or by the -docs convention, and the package names the subject in [[documents]]. One may be primary. Computed at every render, stored nowhere as a flag.

68 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.

override

69A replacement source for one coordinate that short-circuits the registries; marked in the lock file so nobody mistakes it for a published version. The same word names the [override] table that rewrites the visibility marks of edges you do not own.

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

71 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).

package

72The unit vibe installs: a folder with a manifest and the text or tools it delivers, published as its own repository, identified by its coordinate, version and content hash. A package is a project made installable.

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

phase

74One step of a lifecycle: validate, install, generate, build, test, create, verify, package, deploy. Naming a phase runs every phase before it.

75 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).

project

76Any folder with a vibe.toml; a consumer of packages, marked by a [project] table, or a workspace of them.

77 [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.)

provider

78What answers how a mechanism runs: a built-in or a package-supplied implementation of a build, package or deploy step, or a model endpoint behind an agent handler. Selected by exact route or pin.

79 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.

receipt

80The record a deploy writes for every resource it created: what, where, under which generation, owned by which profile. The only authority for removal.

81 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.

registry

82A hosting organisation where packages are published, one repository per package; a project lists the registries it trusts in order.

83 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.

relay

84The mailbox under .vibe/agentic/ where vibe parks an instruction it cannot execute itself; the agent drains it with vibe command.

85 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

86The terminal removal of the vibe layer from a project, by contract, with a plan and a health proof; not to be confused with clean.

87 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.

skill

88A file a package declares in [[skill]] that teaches an agent something; vibe skill install projects it into the agents' skill folders.

89 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).

specification

90The normative text of a package or a project under vibevm/vibespecs/: addressable units with statuses, in Markdown or the XML dialect. What documentation quotes and never restates.

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

store

92The machine-wide cache of fetched package versions under ~/.vibe/cache/, keyed by identity, shared by every project, emptied only on request.

93 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.)

subject

94A package that a documentation package documents, named in its [[documents]] table with a version range.

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

subskill

96A selectable cut of a package's content, activated by the consumer's context, such as the library version a project uses.

97 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.

traceability map

98specmap.json: the generated graph of specification units, tagged code items and the edges between them, checked by the build and queried by vibe explain, vibe query and vibe select.

99 Invariants are machine-checked. Dangling references, uncovered requirements, orphan code, and — the load-bearing one — staleness: a spec unit carries a revision + content hash; when it changes, every edge pinned to the old revision flips to suspect until re-affirmed.

translation

100A separate documentation package in another language that names its source in [translates] and mirrors its tree; official when published by the source's group under <docname>-<lang>. See adaptation.

101 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).

version constraint

102What a manifest asks for: a range such as ^1.0, an exact =1.2.0, or nothing for the newest stable. The lock file records the one version the resolver chose within it.

103 flow:wal@^0.3 → semver range.

workspace

104A repository developing several packages together, declared by a [workspace] table listing member paths; one lock file at the root and one unified resolution across members.

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