# VibeVM Manual

> The VibeVM manual: install vibe, understand packages and the boot lane, work with an agent, author and publish packages.

★ The primary documentation of org.vibevm.core/vibevm, published by org.vibevm.core, in en.
Read it at /doc/org.vibevm.core/vibevm-docs/1.0.0/. Rendered 2026-09-14.

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.
For whom: people who run vibe in their projects, people who write packages, and the agents that read on their behalf.
What 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.
What 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.

## For agents

- [How an agent reads this manual](/doc/org.vibevm.core/vibevm-docs/1.0.0/agent/how-agents-read-this-manual/): This manual is published for machines as much as for people. An agent can fetch any page as plain text, ask where a rule lives, and load the whole corpus in one file sized to its budget. (4 min · agent)
- [Glossary](/doc/org.vibevm.core/vibevm-docs/1.0.0/glossary/index/): One definition per term, and the only place a term is defined. Every other page links here the first time it uses a word from this list. (7 min · user, author, dev, agent)
- [The dependency tree on screen](/doc/org.vibevm.core/vibevm-docs/1.0.0/reference/tree/): `vibe tree` draws the packages a project resolved as a tree, says for each one how its text reaches the agent, and explains why. On a terminal it opens an interactive screen; in a script it prints a plain tree or JSON. This page is that command, its screen, and the way an agent can look at the screen without a terminal. (4 min · user, author, agent)
- [The boot lane: how an agent reads a project](/doc/org.vibevm.core/vibevm-docs/1.0.0/model/boot-lane/): When an agent starts, it reads a short ordered list of files that vibe computed from everything the project depends on. The list has a fixed first file, read in full, and a list of the rest. Some entries are read always, some only when a condition holds, and nothing in the list is written by hand. (4 min · user, author, agent)
- [Write specs an agent can cite](/doc/org.vibevm.core/vibevm-docs/1.0.0/authoring/specs-agents-can-cite/): The text in a package is only useful to an agent if every rule in it has an address. This page shows the shape of such text: named sections, one idea per unit, a status on each, and an address that never changes once published. (4 min · author, agent)
- [Ask your agent to do the work](/doc/org.vibevm.core/vibevm-docs/1.0.0/agent/ask-your-agent/): Every page in this manual that describes a task starts with the plain request you type to your agent. This page explains what those requests assume, how the agent proves the work is done, and what happens when vibe hands a job back to the agent instead of doing it itself. (4 min · user, agent)
- [Machine formats and JSON reports](/doc/org.vibevm.core/vibevm-docs/1.0.0/reference/machine-formats/): Every command can answer in JSON for scripts and agents. This page lists the documents, their schemas and the envelope fields that every document carries. (3 min · user, author, agent)
- [Command reference](/doc/org.vibevm.core/vibevm-docs/1.0.0/reference/commands/): Every command vibe accepts, with its options, in the words the program itself prints. Nothing on this page is written by hand. (1 min · user, author, agent)

## Pages

- [How vibe is built](/doc/org.vibevm.core/vibevm-docs/1.0.0/architecture/how-vibe-is-built/): vibe is one binary built from a set of Rust libraries, each owning one concern: reading the description of a project, choosing versions, fetching from where packages are published, writing the tree on disk, talking to agents. This page maps the libraries, the seams between them, and the path an install takes through them. (4 min · dev)
- [What the lifecycle epic delivered](/doc/org.vibevm.core/vibevm-docs/1.0.0/architecture/what-the-lifecycle-epic-delivered/): Between July and September 2026 vibe grew from a package installer into a build system with an extension machine, a native ABI, a record of every deployment and a terminal export. This page tells that route as one system, what was decided on the way, and what was left for later. (4 min · dev)
- [Bridge a repository you do not own](/doc/org.vibevm.core/vibevm-docs/1.0.0/authoring/bridge-a-repository/): Some text you want your agent to read lives in a repository whose author has never heard of vibe. A bridge package makes it installable anyway: you steward someone else's repository and publish an ordinary package that wraps it, with the original's authorship and licence kept apart from yours. (3 min · user, author)
- [Translate documentation](/doc/org.vibevm.core/vibevm-docs/1.0.0/authoring/translate-documentation/): A translation is a separate package in the same shape as the original: same pages, same section names, same examples by reference, in another language. This page creates one and explains what makes it official. (3 min · author)
- [Write a feat or a stack](/doc/org.vibevm.core/vibevm-docs/1.0.0/authoring/write-a-feat-or-stack/): A feat says what to build without saying how; a stack says how a technology does it. This page writes one of each and connects them through the abilities one needs and the other provides. (3 min · author)
- [Write documentation for a package](/doc/org.vibevm.core/vibevm-docs/1.0.0/authoring/write-documentation/): A manual for a package is itself a package: it names what it documents, carries a title and a summary, and is read rather than installed. This page writes one, with examples that are run and rules quoted from the source they come from. (5 min · author)
- [From an error message to the rule](/doc/org.vibevm.core/vibevm-docs/1.0.0/diagnostics/errors/): vibe's error messages name the rule they enforce. This page lists the messages you are likely to meet, what each means, and the shortest way out, in the order they tend to appear. (4 min · user)
- [Questions](/doc/org.vibevm.core/vibevm-docs/1.0.0/faq/index/): Real questions people asked, each answered in a few sentences with a link to the page that explains the mechanism. (4 min · user)
- [Package manifest](/doc/org.vibevm.core/vibevm-docs/1.0.0/manifest/): What `org.vibevm.core/vibevm-docs@1.0.0` declares about itself. Everything on this page is the package's own manifest, read and shown — nothing here is an opinion about the package. (3 min · user, dev)
- [VibeVM Manual — README](/doc/org.vibevm.core/vibevm-docs/1.0.0/readme/): The README of `org.vibevm.core/vibevm-docs@1.0.0`, as the package ships it. (2 min · user, dev)
- [The lock file: vibe.lock](/doc/org.vibevm.core/vibevm-docs/1.0.0/reference/lock-file/): `vibe.lock` is the file vibe writes and you commit: the exact versions the project got. This page explains every field so you can read a diff of it in a pull request and know what changed. (3 min · user)
- [The newcomer's route](/doc/org.vibevm.core/vibevm-docs/1.0.0/start/index/): You have a coding agent and a project. VibeVM gives that agent the right text to read before it starts working, and keeps that text in step with what your team decided. This page walks you from an empty folder to a project your agent understands, one short step at a time. (2 min · user)
- [Registries and the index](/doc/org.vibevm.core/vibevm-docs/1.0.0/model/registries/): Packages are published to a place vibe knows how to read: by default a public organisation on GitHub, one repository per package. A project lists such places in the order it trusts them. A catalogue beside each one answers searches without cloning anything. (7 min · user)
- [The manifest: vibe.toml](/doc/org.vibevm.core/vibevm-docs/1.0.0/reference/manifest/): `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. (4 min · user, author)
- [Dependency visibility: public, private and friends](/doc/org.vibevm.core/vibevm-docs/1.0.0/model/dependency-visibility/): A package you depend on has dependencies of its own, and those can reach your project too. Whether they do is decided where each dependency is declared, one line at a time: everyone gets it, nobody gets it, or only the projects that have named the declaring package a friend. This page explains the three marks, the friendship that opens the middle one, what ends up in your tree as a result, and how to ask vibe why a package is there or missing. (6 min · user, author)
- [Packages and their kinds](/doc/org.vibevm.core/vibevm-docs/1.0.0/model/packages-and-kinds/): Everything vibe installs is a package: a folder with a small description file and the text or tools it delivers. Packages come in eight kinds, and the kind tells you what a package is for before you open it: a way of working, a feature, a technology, a tool, a language guide, an agent server, documentation, or an application. (5 min · user, author)
- [How this manual is maintained](/doc/org.vibevm.core/vibevm-docs/1.0.0/architecture/how-this-manual-is-maintained/): This manual is a package, and it drifts like any code the day after it ships: the product adds a flag, a reader asks a question no page answers, a paragraph patched five times stops reading well. Nothing stops that on its own, so the manual is kept by a small set of loops with named triggers, a queue that measures the gaps, and a journal that records what each loop found. This page says what the loops are, what runs them, and what you owe when you change the product. (5 min · author, dev)
- [Ship tools and MCP servers](/doc/org.vibevm.core/vibevm-docs/1.0.0/authoring/ship-tools-and-mcp-servers/): A package can deliver programs: command-line tools built on install, or a server your agent talks to. This page declares both, builds them in the package's own folder, and explains why a server pins the exact version of the tools it serves. (4 min · author)
- [Settings, paths and environment](/doc/org.vibevm.core/vibevm-docs/1.0.0/reference/settings-and-environment/): vibe keeps its own files in one folder in your home directory and reads a few environment variables. This page lists the folder's contents, every variable, and which wins when they disagree. (3 min · user)
- [Facts and their status markers](/doc/org.vibevm.core/vibevm-docs/1.0.0/authoring/facts-and-status-markers/): A spec is a list of promises, and each promise has a state: proposed, being built, done, abandoned. vibe reads that state from a small marker written next to the promise, in Markdown or in the XML form, and one command tells you when a marker is malformed or in the wrong place. This page is the grammar of those markers. (3 min · author)
- [Versions and updates](/doc/org.vibevm.core/vibevm-docs/1.0.0/model/versions/): A version is a promise about behaviour, not a snapshot of files. Your project asks for a range, vibe records the one number it chose, and an update moves that number on purpose. vibe itself follows the same rule: one number stands for one contract, however often the binary behind it is rebuilt. (3 min · user)
- [The lock file and the machine store](/doc/org.vibevm.core/vibevm-docs/1.0.0/model/lock-and-store/): One file in your project records exactly which package versions it got, down to a checksum of their content, so a teammate installs the same bytes. One folder on your machine keeps those bytes once per computer, so a second project or an offline day costs nothing extra. (3 min · user)
- [Use a private registry](/doc/org.vibevm.core/vibevm-docs/1.0.0/howto/use-a-private-registry/): A company can keep its packages in its own place and still use vibe unchanged. This page points a project or a whole machine at that place, with or without a search catalogue beside it, and keeps the public one as a fallback. (3 min · user)
- [What a project contains](/doc/org.vibevm.core/vibevm-docs/1.0.0/start/what-a-project-contains/): After the first install, a project holds a handful of files you wrote and a larger set that vibe wrote for you. This page names each of them and says who is allowed to change it, so nothing you edit gets overwritten and nothing vibe generates gets edited by hand. (4 min · user)
- [The lifecycle: from validate to deploy](/doc/org.vibevm.core/vibevm-docs/1.0.0/lifecycle/phases/): Building software has a fixed order of steps, and vibe names them: check the tree, produce generated sources, build, test, let an agent create what only an agent can, verify, assemble, deploy. Each step runs only when something it depends on changed. (3 min · user, author)
- [Write a lang package](/doc/org.vibevm.core/vibevm-docs/1.0.0/authoring/write-a-lang-package/): A lang package teaches an agent how to write in a language or a notation: the idioms, the constraints, the shape of a good file. This page writes one and explains how vibe recognises it as a language discipline. (3 min · author)
- [Extensions and providers](/doc/org.vibevm.core/vibevm-docs/1.0.0/lifecycle/extensions-and-providers/): A package can plug into the build: run a step, transform a stage, or hand a task to an agent. This page explains how such plug-ins are declared, how a project turns them on, and how to see which ones ran and why. (4 min · user, author)
- [Two trees: what you write and what vibe writes](/doc/org.vibevm.core/vibevm-docs/1.0.0/model/two-trees/): A project keeps two kinds of text apart: the rules your team wrote, and the copies of shared rules that arrived with the packages you installed. Installing a package never edits your own text. Removing one never leaves a trace in it. (3 min · user)
- [Publish a package](/doc/org.vibevm.core/vibevm-docs/1.0.0/howto/publish-a-package/): You wrote a package and want others to install it. This page publishes it to the place your projects install from, as its own repository, tags the version, and checks that a fresh project can install it. (4 min · user, author)
- [Install vibe](/doc/org.vibevm.core/vibevm-docs/1.0.0/start/install-vibe/): vibe is one program with no runtime to install. On Windows you download an archive and unpack it; on any platform with a Rust toolchain you build it from the source. When it is done, one command prints the version. (3 min · user)
- [What VibeVM is](/doc/org.vibevm.core/vibevm-docs/1.0.0/start/what-vibevm-is/): A coding agent starts every session knowing nothing about your project. VibeVM fixes that the way a package manager fixes missing libraries: you name what your project follows, and the agent gets the exact text to read at the start of each session. The text comes from packages, so a team, a company or a community can share it and improve it in one place. (3 min · user)
- [Write a flow package](/doc/org.vibevm.core/vibevm-docs/1.0.0/authoring/write-a-flow/): A flow tells an agent how a team works: how to commit, what to check before pushing, how to keep notes between sessions. This page writes one from scratch, including the short text the agent reads at every session start. (4 min · author)
- [Remove VibeVM from a project](/doc/org.vibevm.core/vibevm-docs/1.0.0/lifecycle/scrape/): When a project is finished and must leave without a trace of the tool that helped build it, one operation removes every vibe file and reference while keeping the product and its build intact. (4 min · user)
- [Read documentation locally](/doc/org.vibevm.core/vibevm-docs/1.0.0/howto/read-documentation-locally/): Documentation of the packages you use, including private ones, can be read on your own machine with nothing sent anywhere. This page fetches the manual onto your machine and opens the reader in a browser. (3 min · user)
- [Give your agent the vibevm skill](/doc/org.vibevm.core/vibevm-docs/1.0.0/agent/give-your-agent-the-skill/): Your agent works better when it knows what vibe is and how to call it. This page puts a short instruction file where the agent reads it, and, for agents that support it, starts a server the agent can query directly. (5 min · user)
- [Traceability: specs, code and the map](/doc/org.vibevm.core/vibevm-docs/1.0.0/architecture/traceability/): Every public piece of code in vibe points at the rule it implements, and a generated map lets you ask in either direction: which code implements this rule, which rule does this code answer to. (4 min · dev)
- [Set up a workspace](/doc/org.vibevm.core/vibevm-docs/1.0.0/howto/set-up-a-workspace/): Several packages developed together can live in one repository and share one record of the versions they use. This page turns a folder into such a workspace and shows how members refer to each other by path. (4 min · user, author)
- [Install a package](/doc/org.vibevm.core/vibevm-docs/1.0.0/howto/install-a-package/): You found a package your project should follow. This page adds it to the project, records the exact version, and shows how to check that your agent will now read it. (4 min · user)
- [Update packages](/doc/org.vibevm.core/vibevm-docs/1.0.0/howto/update-packages/): Packages change. This page shows which of yours have a newer version, moves one or all of them forward, and explains what vibe records during the move. (3 min · user)
- [Remove a package](/doc/org.vibevm.core/vibevm-docs/1.0.0/howto/remove-a-package/): Removing a package takes its text out of the project and out of the agent's reading list, and leaves everything you wrote untouched. (2 min · user)
- [Build, package and deploy a project](/doc/org.vibevm.core/vibevm-docs/1.0.0/lifecycle/build-package-deploy/): This page takes a project from source to a running deployment with three commands, shows what each leaves on disk, and how to take a deployment down again without guessing what it owned. (4 min · user, author)
- [Work offline](/doc/org.vibevm.core/vibevm-docs/1.0.0/howto/work-offline/): On a plane or behind a firewall, vibe keeps working from what the machine already holds. This page fetches what you will need before you leave and installs from it without a network. (3 min · user)
- [Create your first project](/doc/org.vibevm.core/vibevm-docs/1.0.0/start/first-project/): A project is a folder your agent works in. This page creates one, adds the first shared rule set to it, and shows what appeared on disk and why the agent will now read it. Ten minutes, no prior knowledge. (3 min · user)