Манифест: vibe.toml
01vibe.toml — единственный файл, который вы пишете, чтобы описать проект или пакет: его имя, от чего он зависит, откуда берутся пакеты и что он доставляет. Эта страница перечисляет каждую таблицу и поле с их смыслом.
Один файл, три роли
02У каждого узла, будь то проект-потребитель, публикуемый пакет или корень рабочего пространства, есть файл с именем vibe.toml. Присутствующие таблицы решают роль: [project] помечает потребителя, который никогда не публикуется, [package] — публикуемый пакет, [workspace] — координатора участников; первые две исключают друг друга, третья сочетается с любой из них или ни с одной.
03 spec: Decision: vibe-package.toml is retired…
Decision.vibe-package.tomlis retired as a distinct filename. Every node — project root, workspace member, published package — carries a singlevibe.toml; the role is expressed by which sections are present. This is the cargo model: oneCargo.tomlcarries[package]and/or[workspace].
04 spec: [package] and [project] are mutually exclusive…
[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 optionalkind. Explicitness wins;kindstays strictly mandatory wherever[package]appears.)
05Неизвестные ключи отвергаются, а не игнорируются: манифест, написанный для более нового vibe, чем тот, что его читает, не разбирается, и ошибка называет виновный ключ.
06 spec: deny_unknown_fields everywhere — vibevm never silently…
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]
| Поле | Смысл |
|---|---|
name |
имя пакета, kebab-case, уникальное внутри группы |
group |
пространство имён издателя, перевёрнутый домен вроде org.vibevm.world; обязательно; (group, name) — идентичность |
kind |
один из восьми видов; метаданные, а не идентичность |
version |
семантическая версия этого пакета |
epoch, format |
эпоха манифеста пакета и форма его содержимого (simple по умолчанию, normal для раскладки из contract и source) |
authors, license, description, homepage, keywords |
карточка, которую показывает каждый реестр |
title, abstract |
человекочитаемое имя и сводка из четырёх вопросов, показываемые на полках документации; обязательны для пакетов doc, иначе необязательны |
authorship |
кто написал прозу пакета doc: human, ai или mixed; фильтр читателя, а не атрибуция коммитов |
describes |
Package URL исходной библиотеки, которую этот пакет документирует или оборачивает, для поиска по совпадению версий |
publish |
позиция участника рабочего пространства при публикации |
08 цитата из спецификации
Decision.[package]gains a mandatorygroupfield:
09 spec: Grammar (owner ruling 2026-08-13 — «настоящие…
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 byGroup::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 spec: The package manifest gains card fields…
The package manifest gains card fields; for kinddoctitleandabstractare REQUIRED, for the other kinds optional, and[media]is optional for all:
11 spec: A doc package MAY declare authorship…
Adocpackage MAY declareauthorshipin[package]:human,aiormixed— 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 isspec://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] и его соседи
| Таблица | Смысл |
|---|---|
[requires.packages] |
по ключу на требуемую координату; значение — строка ограничения или инлайновая таблица с version, источником git или path, link для типа включения в старт и метками видимости access, friend и exclude |
[visibility] |
friends, unfriend, allow-friends и ignore-concept-warnings для пакета в целом; см. Видимость зависимостей |
[override] (таблица) |
переписывает метки видимости на рёбрах, которыми вы не владеете, ключом "a -> b", или allow-friends провайдера, ключом по его координате |
[requires] capabilities |
абстрактные умения, которые может удовлетворить любой провайдер, namespace:name@constraint |
[[requires_any]] |
дизъюнкция: ровно одно из one_of должно быть удовлетворено |
[provides] capabilities |
умения, которые предлагает этот пакет |
[obsoletes], [conflicts] |
пакеты, которые этот вытесняет, и пакеты, которые не могут сосуществовать с ним |
[features] |
необязательные, аддитивные наборы содержимого со списком default; фичи могут зависеть от фич |
[compatibility] |
min_vibe_version и requires_kinds |
14 spec: [requires.packages] inline-table entries accept an optional…
[requires.packages]inline-table entries accept an optionallinkfield (§2.4):"static" | "dynamic", defaultdynamic. Valid on registry-, path-, and git-source dependencies.
15 spec: Decision: A package's vibe-package.toml gains…
Decision. A package'svibe-package.tomlgains a[features]table describing optional, conditionally-activated components:
16 цитата из спецификации
[requires].packages = ["kind:name@<constraint>", …] — concrete pkgref requirements.
17 spec: [requires].capabilities = ["<namespace>:<name>[@<constraint>]", …] — satisfied…
[requires].capabilities = ["<namespace>:<name>[@<constraint>]", …] — satisfied by any package that provides that capability.
18 spec: [[requires_any]] one_of = [ pkgrefs… ]…
[[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 spec: [obsoletes].packages = [ pkgrefs… ] —…
[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 spec: Additive only
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 spec: Default features
Default features.default = [...]lists features active when no override is given.--no-default-featureson the install / update CLI omits them.
25 spec: Feature unification across the dep graph
Feature unification across the dep graph. Ifpkg-Aandpkg-Bboth depend onpkg-Cand request different features, the solver unifies —pkg-Cis built/materialised once with the union of requested features.
26 spec: vibe install <pkgref> [--features <a,b,c>] [--no-default-features]…
vibe install <pkgref> [--features <a,b,c>] [--no-default-features] [--all-features] — control feature activation (cargo-shape).
Откуда берутся пакеты
| Таблица | Смысл |
|---|---|
[[registry]] |
упорядоченный список источников пакетов: name, url (корень организации), naming, auth, необязательные index_url и token_env |
[[mirror]] |
альтернативный адрес для одного реестра или для любого, пробуется по priority и проверяется по отпечатку |
[[override]] |
замена источника для одной координаты, в обход реестров |
[boot] |
настройки загрузки для всего рабочего пространства; сегодня link по умолчанию |
[i18n] |
языки preferred и fallback в проекте; canonical и available в пакете |
[workspace] members |
пути участников рабочего пространства, глобы разрешены |
28 цитата из спецификации
Decision. vibe.toml carries an array of registries:
29 spec: Decision: [[mirror]] entries are parallel alternative…
Decision.[[mirror]]entries are parallel alternative URLs for a specific registry (or*for any). During fetch:
30 spec: Decision: Adopt a sidecar file naming…
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 spec: A localised file is the canonical…
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 spec: Critical invariant: every package must ship…
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.
Что доставляет пакет
| Таблица | Смысл | Где законна |
|---|---|---|
[boot_snippet] |
source, файл фрагмента внутри пакета, и category для его места в порядке старта; необязательные when и предлагаемый link |
все виды, кроме doc |
[[skill]] |
name, path, description, необязательные целевые agents: навык, который агент может установить |
все виды |
[[binary]] |
name и crate: инструмент, который vibe собирает при установке и запускает через vibe bin exec |
виды с кодом; не doc |
[[mcp_server]] |
name, binary, args: сервер, регистрируемый у агентов |
только mcp |
[hooks] |
базовые пути скриптов pre-install и post-install |
пакеты |
[[extension]] |
id, point, handler, необязательные селектор и config: вклад в жизненный цикл |
пакеты и проекты |
[[command]] |
id, необязательное описание и типизированный обработчик-скрипт: явная точка входа vibe run |
только проекты и корни workspace |
[[embedded_source]] |
неизменяемый внешний источник, на который пакет ссылается, не вендоря его | пакеты-мосты |
36 spec: [boot_snippet] (package-role) drops the filename field…
[boot_snippet](package-role) drops thefilenamefield (theNN-target name) and gainscategory(§2.5);source— the path to the boot file inside the package — is retained. It may carry an optional suggestedlinkdefault, and an optionalwhenactivation condition — the declaration site for §2.3's dynamic-entrywhen, closing the gap Phase 4 flagged. For v1 the onlywhenis an operating-system match, the wire string"os:<name>"with<name>one ofwindows/macos/linux; a snippet carrying awhenisdynamic(§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 spec: The MVP section is an array-of-tables…
The MVP section is an array-of-tables, matching the manifest's existing[[requires_any]]/[[registry]]/[[mirror]]shape:
38 spec: vibe run <id> -- <args…> dispatches…
vibe run <id> -- <args…>dispatches an explicit host-owned[[command]]from the selectedvibe.toml. The first handler is{ kind = "script", base = "…" }, using the same cross-platform.sh/.ps1selection as lifecycle scripts, a project-contained canonical path, exact argument forwarding, inherited operator environment,VIBE_PROJECT_ROOT, and the exactVIBE_EXECUTABLE; the child exit code passes through. A command is legal only on a project/workspace host, never in a publishable package, so installing a dependency cannot inject an npm-style ambient script. There is deliberately no shell-string form. This is the explicit typed-action posture of NEXT-A11/A14 and leaves the command id stable when a later implementation lowers its handler to the shared recorded-artifact plane.
39Навык (skill) — секция манифеста, а не отдельный вид. include сужает, какие файлы из path проецируются в папку навыков агента, а его отсутствие проецирует всё дерево. Навык может взять своё тело из объявленного [[embedded_source]] и добавить ресурсы под папкой references/, с тем же отбором include и теми же проверками обхода.
40 spec: Decision: A package declares…
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.
41 spec: When present, only matching files…
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.
42 spec: A reference-backed bridge MAY select…
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:
43 spec: source and embedded_source name a manifest…
sourceandembedded_sourcename a manifest[[embedded_source]]. Absentsourceretains the package-root meaning. Resource targets are portable relative paths belowreferences/; they cannot replace the localSKILL.md, scripts, or another resource. Include selection, case-fold collision checks and no-follow traversal apply before any agent directory is changed.
44 цитата из спецификации
A code-bearing package declares each shipped tool in its vibe.toml:
45 spec: The [[mcp_server]] table (§2.2) is legal…
The[[mcp_server]]table (§2.2) is legal only in this kind — the kind IS the taxonomy, enforced byManifest::validate, not advisory.
46 цитата из спецификации
Hooks live in a package-role[hooks]table invibe.toml:
Документация и её предметы
| Таблица | Смысл | Где законна |
|---|---|---|
[[documents]] |
package и ограничение version: предмет, который описывает эта документация; обязательно, повторяемо |
doc |
[documentation] |
primary (не больше одной координаты) и official (сколько угодно): документация, которую пакет называет своей |
все виды |
[translates] |
package и version документации, которую зеркалит этот перевод |
doc |
[navigation] |
pinned, пути документов, которые перечисляются первыми; строки [[navigation.section]] с id и title для папок дерева страниц; строки [[navigation.chapter]] с id, title, pages и необязательным appendix для учебного пути, которые перевод называет только через id и title |
doc |
[glossary] |
page: путь документа страницы, которая определяет слова пакета; каждый раздел верхнего уровня этой страницы — одна статья |
doc |
[media] |
icon, banner, preview: исходные файлы изображений в пределах ограничений карточки |
все виды |
49 spec: [[documents]] is REQUIRED in a doc…
[[documents]]is REQUIRED in adocpackage, may list several subjects, and itsversionis a semver constraint.
50 spec: [documentation] in the subject names coordinates…
[documentation]in the subject names coordinates without versions;primarynames at most one package,officialany number.
51 spec: A translation of documentation…
A translation of documentation is a separate package of kind doc:
52 spec: Images are source files…
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.
53 spec: A documentation package MAY declare [navigation]…
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 ofvibe check.
54 spec: A documentation package MAY declare…
A documentation package MAY declare a learning path in[navigation]:[[navigation.chapter]]rows, each with anid, atitleandpages— the document paths the chapter holds, in reading order — and optionallyappendix = truefor 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:pagesin the page manifest and thellmsfiles keep the layer law (spec://org.vibevm.core/vibevm/common/PROP-048#THE-LAYER-LAW), and the page manifest carries the path beside them asnavigation.chapters.
55 spec: A documentation MAY declare its glossary
A documentation MAY declare its glossary (added 2026-09-26): a top-level table[glossary]withpage, the document path of the page that defines the package's terms. That page is the glossary. Each of its top-level sections is one entry: the section's id is the entry's anchor, itstitleis the term, and its first paragraph is the definition; more paragraphs and cited rules may follow. Everything the pipeline, the reader and the tools do with terms — the style checks of##STYLE-LINT, the cards of##READER-GLOSSARY-CARD— they do with the declared glossary, and a package that declares none has none; the pathglossary/index.xmlmeans nothing by itself.
Полный пример
56
57Манифест этого перевода, сгенерированный из самого пакета, показывает пакет doc с карточкой, предметом (subject) и таблицей [translates], которая называет источник.