The manifest: vibe.toml

One file, three roles

02Every node, whether a consumer project, a publishable package or a workspace root, has a file named vibe.toml. The tables present decide the role: [project] marks a consumer that is never published, [package] a publishable package, [workspace] a coordinator of members; the first two exclude each other, the third composes with either or with neither.

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

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

05Unknown keys are rejected, not ignored: a manifest written for a newer vibe than the one reading it fails to parse with the offending key named.

06 deny_unknown_fields everywhere — vibevm never silently drops unfamiliar manifest keys; we'd rather fail loud and add the section to the schema than corrupt provenance.

[package]

08 Decision. [package] gains a mandatory group field:

09 Grammar (owner ruling 2026-08-13 — «настоящие домены»): dot-separated segments, each an LDH hostname label — [a-z0-9-]+, ASCII lowercase, hyphen never at a label edge; _ is forbidden (it is not legal in a domain). Interior doubled hyphens stay legal, as DNS itself allows (xn--… punycode). A group is therefore grammatically a valid reversed FQDN even though semantically it is a claim, not a credential (§2.10). Enforced by Group::parse. Considered and rejected: keeping _ (groups would not even be formally domains, and the flat <group>.<name> carrier §2.5 would lose its unambiguous split); recording "FQDN-like, not FQDN-valid" as a deliberate looseness (the ruling chose real domain rules). Revisit: a real-world group needing _ appears — it cannot, if groups track domains.

10 The package manifest gains card fields; for kind doc title and abstract are REQUIRED, for the other kinds optional, and [media] is optional for all:

11 A doc package MAY declare authorship in [package]: human, ai or mixed — who wrote the prose the package carries. It is metadata of the document, kept for the reader who filters a shelf by it; it is never an attribution of the commits or of the repository, whose authorship law is spec://org.vibevm.core/vibevm/common/PROP-000#commits. Absent means unknown: the site shows no badge and a filter by authorship leaves the package out of both named groups.

12[project] carries the same descriptive fields for a consumer, without a version line or a kind.

[requires] and its neighbours

14 [requires.packages] inline-table entries accept an optional link field (§2.4): "static" | "dynamic", default dynamic. Valid on registry-, path-, and git-source dependencies.

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

16 [requires].packages = ["kind:name@<constraint>", …] — concrete pkgref requirements.

17 [requires].capabilities = ["<namespace>:<name>[@<constraint>]", …] — satisfied by any package that provides that capability.

18 [[requires_any]] one_of = [ pkgrefs… ] — disjunction; exactly one must be satisfied. Repeatable table for multiple independent disjunctions.

19 [provides].capabilities = ["<namespace>:<name>[@<semver>]", …] — abstract capabilities the package advertises.

20 [obsoletes].packages = [ pkgrefs… ] — the package supersedes these; the solver flags them for removal on upgrade.

21 [conflicts].packages = [ pkgrefs… ] — mutually exclusive installs.

22A feature adds content and never removes or contradicts any; default lists the features active when nothing is said, and --no-default-features omits them. When two packages require one package with different features, the resolver materialises it once with the union. On the command line vibe install <coordinate> --features a,b, --no-default-features and --all-features control activation.

23 Additive only. Enabling a feature can introduce additional content; never remove or contradict existing content. (Cargo enforces this informally; vibevm enforces it via vibe check since spec content collisions are easier to detect than code-level ones.)

24 Default features. default = [...] lists features active when no override is given. --no-default-features on the install / update CLI omits them.

25 Feature unification across the dep graph. If pkg-A and pkg-B both depend on pkg-C and request different features, the solver unifies — pkg-C is built/materialised once with the union of requested features.

26 vibe install <pkgref> [--features <a,b,c>] [--no-default-features] [--all-features] — control feature activation (cargo-shape).

Where packages come from

28 Decision. vibe.toml carries an array of registries:

29 Decision. [[mirror]] entries are parallel alternative URLs for a specific registry (or * for any). During fetch:

30 Decision. Adopt a sidecar file naming pattern with BCP-47 language tags as suffixes, plus first-class language-preference declarations at three levels (CLI flag, project manifest, package manifest).

31A localised file sits beside the canonical one with a language tag before the extension, README.ru.md next to README.md. Every package ships the canonical form of every file it lists, and translations only add to it, so a project with no translation in its preferred language installs without an error. vibe install --language ru sets the preference for one run.

32 A localised file is the canonical filename with a .<lang> segment inserted before the extension. <lang> is a BCP-47 language tag — en, ru, ja, zh-Hans, pt-BR. We also accept short ISO-639-1 codes alone (ru, ja) as a convenience; they map to the BCP-47 tag with no region.

33 Critical invariant: every package must ship the canonical form of every file it lists in [content].files_written. Translations are additive. This is what makes step 3 always reachable; it also lets a project install a package that has zero translation coverage for the user's preferred language without seeing errors.

34 CLI flag: vibe install flow:wal --language ru overrides everything else for this invocation.

What a package delivers

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

37 The MVP section is an array-of-tables, matching the manifest's existing [[requires_any]] / [[registry]] / [[mirror]] shape:

38A skill is a manifest section, never a kind of its own. include narrows which files of path are projected into an agent's skill folder, and its absence projects the whole tree. A skill may take its body from a declared [[embedded_source]] and add resources below a references/ folder, under the same include selection and traversal checks.

39 Decision. A package declares which of its files are skills for agents in a dedicated manifest section — not by introducing a package kind of its own. The kind register (package_ref.rs, VIBEVM-SPEC.md §4.1) stays closed to skills.

40 When present, only matching files are projected into the agent's skill directory, preserving their relative structure; when absent or empty, the whole path tree is projected — the existing §2.6 behaviour, unchanged.

41 A reference-backed bridge MAY select its body from a declared external source, and any skill MAY add authenticated source resources below a dedicated subdirectory:

42 source and embedded_source name a manifest [[embedded_source]]. Absent source retains the package-root meaning. Resource targets are portable relative paths below references/; they cannot replace the local SKILL.md, scripts, or another resource. Include selection, case-fold collision checks and no-follow traversal apply before any agent directory is changed.

43 A code-bearing package declares each shipped tool in its vibe.toml:

44 The [[mcp_server]] table (§2.2) is legal only in this kind — the kind IS the taxonomy, enforced by Manifest::validate, not advisory.

45 Hooks live in a package-role [hooks] table in vibe.toml:

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

Documentation and its subjects

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

49 [documentation] in the subject names coordinates without versions; primary names at most one package, official any number.

50 A translation of documentation is a separate package of kind doc:

51 Images are source files in the package tree, in PNG, JPEG or WebP; SVG is forbidden in this wave because it can carry scripts and the local reader serves the images of proprietary packages as they are. vibe check and the publish gate verify existence, format signature, proportions and size — by signature and dimensions, never by file extension. The limits are small on purpose: packages of ordinary kinds are materialised and committed at consumers.

52 A documentation package MAY declare [navigation]: pinned, the document paths the site and the local reader list first, in the order given; and [[navigation.section]], one row per top-level folder of the page tree with the title the navigation shows for it. Pinning changes only where the named pages stand; every other page keeps the manifest's order. A pinned path that names no page is an error of vibe check.

A complete example

# Written by `vibe doc build-site`: the level-0 view of one published version
# (PROP-057 `##LEVEL-ZERO`). It is a render input and never a package.

[package]
name = "vibevm-docs"
group = "org.vibevm.core"
version = "1.0.0"
kind = "doc"
title = "VibeVM Manual"
abstract = "What it covers: what VibeVM is and how it gives a coding agent the right text to read; installing vibe; creating a project; packages, registries, the lock file and the machine store; installing, updating, publishing and working offline; giving an agent the vibevm skill and asking it to do the work; the lifecycle from validate to deploy; a full command, manifest, lock-file and settings reference; writing packages of every kind, including documentation and its translations.\nFor whom: people who run vibe in their projects, people who write packages, and the agents that read on their behalf.\nWhat it assumes known: how to use a terminal and a text editor, what a coding agent is, and what a package manager does for a programming language.\nWhat it leaves out: the normative specifications themselves (this manual quotes them, never restates them), the internals of any one agent product, and the design history of vibe."
description = "The VibeVM manual: install vibe, understand packages and the boot lane, work with an agent, author and publish packages."
authorship = "ai"
authors = ["Oleg Chirukhin"]

[i18n]
canonical = "en"

[[documents]]
package = "org.vibevm.core/vibevm"
version = "^1.0"

[navigation]
pinned = ["start/what-vibevm-is", "start/index"]

[[navigation.section]]
id = "start"
title = "Start"

[[navigation.section]]
id = "model"
title = "Model"

[[navigation.section]]
id = "howto"
title = "How to"

[[navigation.section]]
id = "agent"
title = "Agent"

[[navigation.section]]
id = "lifecycle"
title = "Lifecycle"

[[navigation.section]]
id = "authoring"
title = "Authoring"

[[navigation.section]]
id = "reference"
title = "Reference"

[[navigation.section]]
id = "architecture"
title = "Architecture"

[[navigation.section]]
id = "diagnostics"
title = "Diagnostics"

[[navigation.section]]
id = "faq"
title = "Questions"

[[navigation.section]]
id = "glossary"
title = "Glossary"

54The manifest of this manual, generated from the package itself, shows a doc package with a card, a subject and a skill.