Манифест: vibe.toml

Один файл, три роли

02У каждого узла, будь то проект-потребитель, публикуемый пакет или корень рабочего пространства, есть файл с именем vibe.toml. Присутствующие таблицы решают роль: [project] помечает потребителя, который никогда не публикуется, [package] — публикуемый пакет, [workspace] — координатора участников; первые две исключают друг друга, третья сочетается с любой из них или ни с одной.

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

05Неизвестные ключи отвергаются, а не игнорируются: манифест, написанный для более нового vibe, чем тот, что его читает, не разбирается, и ошибка называет виновный ключ.

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] несёт те же описательные поля для потребителя, без строки версии и без вида.

[requires] и его соседи

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.

22Фича добавляет содержимое и никогда ничего не убирает и не противоречит; default перечисляет фичи, активные, когда ничего не сказано, а --no-default-features их опускает. Когда два пакета требуют один пакет с разными фичами, резолвер материализует его один раз с объединением. В командной строке активацией управляют vibe install <coordinate> --features a,b, --no-default-features и --all-features.

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

Откуда берутся пакеты

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

31Локализованный файл лежит рядом с каноническим, с тегом языка перед расширением, README.ru.md рядом с README.md. Каждый пакет поставляет каноническую форму каждого файла, который перечисляет, а переводы только добавляют к ней, так что проект без перевода на предпочитаемый язык ставится без ошибки. vibe install --language ru задаёт предпочтение на один запуск.

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.

Что доставляет пакет

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:

38Навык — секция манифеста, а не отдельный вид. include сужает, какие файлы из path проецируются в папку навыков агента, а его отсутствие проецирует всё дерево. Навык может взять своё тело из объявленного [[embedded_source]] и добавить ресурсы под папкой references/, с тем же отбором include и теми же проверками обхода.

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:

Документация и её предметы

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.

Полный пример

# 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-ru"
group = "org.vibevm.core"
version = "1.0.0"
kind = "doc"
title = "Руководство VibeVM"
abstract = "Что покрывает: что такое VibeVM и как он даёт агенту-кодеру нужный текст для чтения; установку vibe; создание проекта; пакеты, реестры, лок-файл и машинный store; установку, обновление, публикацию и работу без сети; навык vibevm для агента и работу через него; жизненный цикл от проверки до выкладки; полный справочник команд, манифеста, лок-файла и настроек; написание пакетов всех видов, включая документацию и её адаптации.\nДля кого: для тех, кто запускает vibe в своих проектах, для тех, кто пишет пакеты, и для агентов, которые читают за них.\nЧто считает известным: как пользоваться терминалом и текстовым редактором, что такое агент-кодер и что делает менеджер пакетов для языка программирования.\nЧего не покрывает: сами нормативные спецификации (руководство их цитирует, а не пересказывает), внутреннее устройство отдельных агентов и историю проектирования vibe."
description = "Руководство VibeVM по-русски: установить vibe, понять пакеты и стартовую полосу, работать с агентом, писать и публиковать пакеты."
authorship = "ai"
authors = ["Oleg Chirukhin"]

[i18n]
canonical = "ru"

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

[translates]
package = "org.vibevm.core/vibevm-docs"
version = "^1.0"

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

[[navigation.section]]
id = "start"
title = "Старт"

[[navigation.section]]
id = "model"
title = "Модель"

[[navigation.section]]
id = "howto"
title = "Как сделать"

[[navigation.section]]
id = "agent"
title = "Агент"

[[navigation.section]]
id = "lifecycle"
title = "Жизненный цикл"

[[navigation.section]]
id = "authoring"
title = "Авторам"

[[navigation.section]]
id = "reference"
title = "Справочник"

[[navigation.section]]
id = "architecture"
title = "Архитектура"

[[navigation.section]]
id = "diagnostics"
title = "Диагностика"

[[navigation.section]]
id = "faq"
title = "Вопросы"

[[navigation.section]]
id = "glossary"
title = "Глоссарий"

54Манифест этого перевода, сгенерированный из самого пакета, показывает пакет doc с карточкой, предметом и таблицей [translates], которая называет источник.