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.
Start with the two files at the root, because everything else is derived from them.
`vibe.toml` is the *[manifest](../glossary/index.xml#manifest)*. You write it, or `vibe init` writes the first version for you. It names the project, lists the packages it requires with a version range for each, and lists the [registries](../glossary/index.xml#registry) to fetch them from. It is the only file a teammate needs to reproduce your setup, together with the [lock file](../glossary/index.xml#lock-file) beside it.
`vibe.lock` is the *lock file*. vibe writes it, you commit it, and you never edit it. It records the exact version of every package that was installed, including the ones your packages pulled in, and a [fingerprint](../glossary/index.xml#fingerprint) of each package's content. With it, a fresh clone installs the same bytes on any machine.
Below them sits one directory, `vibevm/`, with three children. This layout is the same in every project and every package, and it is not configurable.
`vibevm/vibespecs/` is *your* tree: the [specifications](../glossary/index.xml#specification) and rules this project itself writes, in Markdown or in the project's XML dialect. vibe reads it and never writes into it, with one exception described below.
`vibevm/vibedeps/` is *vibe's* tree: one folder per installed package and version, holding that package's published files verbatim. You commit it, so a fresh clone is readable without running anything, but you never edit it. An edit there disappears at the next install.
`vibevm/vibepacks/` holds packages this repository develops in place: a project that also publishes packages keeps their sources here, and vibe treats the directory as a small local registry. Most projects do not have it.
The exception in your tree is `vibevm/vibespecs/boot/`. Two files there are yours: `00-core` holds the project's foundations, `90-user` holds your personal overrides, and vibe never touches either. Two files there are generated: `INDEX.md`, a manifest of what the agent reads, always present, and `STATIC.md`, the text it reads first and in full, present only when some package asked to be read that way. Both carry a header saying they are generated; the header is not decoration.
The agent finds the boot files through a short [managed block](../glossary/index.xml#managed-block) at the end of `CLAUDE.md`, `AGENTS.md` and `GEMINI.md`, between the lines `<vibevm>` and `</vibevm>`. vibe rewrites what is between the two markers and nothing else in those files; the rest of the file is yours, and so is the position of the block once it exists.
| File or directory | Written by | Committed | Edited by hand |
| `vibe.toml` | you (first version by `vibe init`) | yes | yes |
| `vibe.lock` | vibe | yes | never |
| `vibevm/vibespecs/` | you | yes | yes |
| `vibevm/vibespecs/boot/00-core`, `90-user` | you | yes | yes |
| `vibevm/vibespecs/boot/INDEX.md`, `STATIC.md` | vibe | yes | never |
| `vibevm/vibedeps/` | vibe | yes | never |
| `vibevm/vibepacks/` | you, when the repository develops packages | yes | yes |
| the `<vibevm>` block in agent instruction files | vibe | yes | only its position |
| `.vibe/` | vibe | no | never |
The last row is the project's scratch space: caches and internal state, ignored by git and safe to delete. The machine-wide [store](../glossary/index.xml#store) of fetched packages is elsewhere, in your home directory, and is shared by every project on the machine.
One more folder appears once a project starts keeping track of which rules of its packages it has adopted: `vibefacts/`, committed, one small TOML file per package. Installing a package copies none of the author's statuses into it; adopting them is a deliberate act, `vibe facts adopt`, and `vibe facts` is the lever for everything else, listing, setting a status by address, syncing and reporting. Removing a package asks whether to keep or clean its adoption file; `vibe facts clean` removes the files of packages that are gone, and after an upgrade `vibe facts sync` reports the [anchors](../glossary/index.xml#anchor) that disappeared or moved.
If you delete `vibevm/vibedeps/` or the generated boot files, `vibe reinstall` rebuilds them from the lock file and the store without touching the network.
If a project from before the current layout carries a root `spec/` folder, vibe stops with a migration recipe rather than guessing. Old layouts are not read silently.
If you write into `vibevm/vibedeps/` by accident, nothing breaks immediately; the next install overwrites the edit, because a package's folder there is a verbatim copy of what was published.