Two trees: what you write and what vibe writes
01A 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.
vibe list --path hello-vibeKIND NAME VERSION ROLE BOOT SNIPPET
flow wal 1.0.0 package —
1 package installed.The founding rule
03Think of how a C++ program uses a library: you write #include, and the library's headers are read at build time, but nobody pastes the library's source into your files. vibe follows the same rule for text. Your specifications live in vibevm/vibespecs/; the packages you depend on are copied, whole and unchanged, into vibevm/vibedeps/, one folder per package and version. The two trees never mix.
04 Decision. A node's authoredspec/and its materialised dependencies live in physically separate trees.vibe installnever writes into any node's authoredspec/.
05The consequence is simple to state and easy to forget: every file under vibevm/vibedeps/ is a copy of something published elsewhere. Editing it changes nothing upstream and survives only until the next install. If you want a package to say something else, change the package, publish a new version, and update.
Why the copies are committed
06The copied tree is committed to your repository, which surprises people who expect a node_modules-style directory to be ignored. The reason is the reader: an agent that clones the repository must be able to start reading at once, without a network, without a tool, and without knowing that vibe exists. A committed tree makes the whole reading list a set of ordinary files in the checkout, and a code review can see exactly what text an agent will read after a dependency change.
07vibedeps/is committed to the repository. A fresh clone is immediately bootable with novibe install; the dependency corpus is visible and diffable; this matches the spec-driven principle that the committed spec corpus is the product.
What regenerates, and when
08Three things in a project are derived from the manifest and the lock file, and vibe rebuilds them on demand: the dependency tree, the generated boot files, and the managed block in the agent instruction files. vibe reinstall rebuilds all three from the lock file and the machine store, without asking any registry; add --force to fetch the package files again from their sources.
09
Decision. vibe reinstall [<path>] [--force] reinstalls and regenerates the materialised state.
10
to re-materialise even though the slots are present — vibe reinstall --force (re-fetches from source and reconciles each materialiser-owned footprint; PROP-009 §2.10).
11vibe clean goes one step further and removes the derived state altogether, keeping everything you wrote, the lock file and the machine store. It is the command for a clean start before a build, and it refuses to run outside a project so it cannot sweep the wrong folder.
12 Never touched — the authored surface: every authored file undervibevm/vibespecs/(the boot snippets00-*/90-*included — vibe never writes them),vibevm/vibefacts/, the instruction files (CLAUDE.md/AGENTS.md/GEMINI.md, their<vibevm>blocks included — an install rewrites the block in place, so clean has nothing to reclaim there), and every project file outside the derived set. This is the prompt-work specificity of the mandate: ourtarget/equivalent holds materialised PROMPTS, and the boundary between authored prompt and derived copy is the layout itself.
Edge cases and rules
13A package's folder in the dependency tree is named by its group, its name and its version, so two versions of one package can sit side by side during an update and nothing is overwritten in place.
14If you develop packages inside the same repository, their sources live in a third tree, vibevm/vibepacks/, which is yours to edit. When a project in that repository requires one of them, vibe still copies it into the dependency tree like any other package.
15Two files in the boot folder are yours by law: vibevm/vibespecs/boot/00-core and 90-user, Markdown in a project vibe init creates and XML in a project written in the dialect. No install, update or removal ever writes them.
16 User-owned files are never written byvibe.vibevm/vibespecs/boot/00-core.xmlandvibevm/vibespecs/boot/90-user.xmlare off-limits to install/uninstall/update.
17The managed block in an instruction file stays where you put it: vibe rewrites the text between the markers and never moves the markers, so whatever you wrote before or after the block keeps its place.
18 From then on the position is the user's:viberewrites the content between the markers and never relocates the markers; whatever text precedes or follows the block stays exactly where it is, across everyvibeoperation.