`vibe.toml` is the one file you write to describe a project or a package: its name, what it depends on, where packages come from, and what it delivers. This page lists every table and field with its meaning.
Every 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.
Unknown keys are rejected, not ignored: a [manifest](../glossary/index.xml#manifest) written for a newer vibe than the one reading it fails to parse with the offending key named.
| Field | Meaning |
| `name` | the package name, kebab-case, unique within its group |
| `group` | the publisher's namespace, a reversed domain such as `org.vibevm.world`; mandatory; `(group, name)` is the identity |
| `kind` | one of the eight kinds; metadata, not identity |
| `version` | semantic version of this package |
| `epoch`, `format` | the package's manifest epoch and its content form (`simple` by default, `normal` for the contract-and-source layout) |
| `authors`, `license`, `description`, `homepage`, `keywords` | the card every registry shows |
| `title`, `abstract` | the human-readable name and the four-question summary shown on documentation shelves; required for `doc` packages, optional otherwise |
| `authorship` | who wrote the prose of a `doc` package: `human`, `ai` or `mixed`; a reader's filter, not the commits' attribution |
| `describes` | the Package URL of an upstream library this package documents or wraps, for version-matched discovery |
| `publish` | the publishing posture of a workspace member |
`[project]` carries the same descriptive fields for a consumer, without a version line or a kind.
| Table | Meaning |
| `[requires.packages]` | one key per required coordinate, the value a constraint string or an inline table with `version`, a `git` or `path` source, `link` for the boot inclusion type, and the visibility marks `access`, `friend` and `exclude` |
| `[visibility]` | `friends`, `unfriend`, `allow-friends` and `ignore-concept-warnings` for the package as a whole; see [Dependency visibility](../model/dependency-visibility.xml) |
| `[override]` (table) | rewrites the visibility marks of edges you do not own, keyed `"a -> b"`, or a provider's `allow-friends`, keyed by its coordinate |
| `[requires] capabilities` | abstract abilities any provider may satisfy, `namespace:name@constraint` |
| `[[requires_any]]` | a disjunction: exactly one of `one_of` must be satisfied |
| `[provides] capabilities` | the abilities this package offers |
| `[obsoletes]`, `[conflicts]` | packages this one supersedes, and packages that cannot coexist with it |
| `[features]` | optional, additive content sets with a `default` list; features may depend on features |
| `[compatibility]` | `min_vibe_version` and `requires_kinds` |
A [feature](../glossary/index.xml#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.
| Table | Meaning |
| `[[registry]]` | an ordered list of package sources: `name`, `url` (the organisation root), `naming`, `auth`, optional `index_url` and `token_env` |
| `[[mirror]]` | an alternative address for one registry or for any, tried by `priority` and verified by fingerprint |
| `[[override]]` | a replacement source for one coordinate, short-circuiting the registries |
| `[boot]` | workspace-wide loading settings; today a default `link` |
| `[i18n]` | `preferred` and `fallback` languages in a project; `canonical` and `available` in a package |
| `[workspace] members` | the member paths of a workspace, globs allowed |
A 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.
| Table | Meaning | Legal in |
| `[boot_snippet]` | `source`, the snippet file inside the package, and `category` for its place in the boot order; optional `when` and a suggested `link` | every kind but `doc` |
| `[[skill]]` | `name`, `path`, `description`, optional target `agents`: a [skill](../glossary/index.xml#skill) an agent may install | every kind |
| `[[binary]]` | `name` and `crate`: a tool vibe builds on install and runs through `vibe bin exec` | code-bearing kinds; not `doc` |
| `[[mcp_server]]` | `name`, `binary`, `args`: a server registered into agents | `mcp` only |
| `[hooks]` | `pre-install` and `post-install` script base paths | packages |
| `[[extension]]` | `id`, `point`, `handler`, optional selector and config: a contribution to the lifecycle | packages and projects |
| `[[embedded_source]]` | an immutable external source a package refers to without vendoring it | bridge packages |
A [skill](../glossary/index.xml#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.
| Table | Meaning | Legal in |
| `[[documents]]` | `package` and a `version` constraint: a [subject](../glossary/index.xml#subject) this documentation describes; required, repeatable | `doc` |
| `[documentation]` | `primary` (at most one coordinate) and `official` (any number): the documentation a package names as its own | every kind |
| `[translates]` | `package` and `version` of the documentation this translation mirrors | `doc` |
| `[navigation]` | `pinned`, the document paths listed first, and `[[navigation.section]]` rows with `id` and `title` for the folders of the page tree | `doc` |
| `[media]` | `icon`, `banner`, `preview`: source image files within the card limits | every kind |
The manifest of this manual, generated from the package itself, shows a `doc` package with a card, a [subject](../glossary/index.xml#subject) and a [skill](../glossary/index.xml#skill).