<?xml version="1.0" encoding="UTF-8"?>
<spec xmlns="https://vibevm.org/spec/1">
  <title id="root">Two trees: what you write and what vibe writes</title>
  <status stage="doc" state="work" audience="user"/>
  <p p="1">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.</p>
  <example id="list" fixture="hello-vibe" p="2">
    <run>vibe list --path hello-vibe</run>
    <expect>KIND  NAME  VERSION  ROLE     BOOT SNIPPET
flow  wal  1.0.0    package  —

1 package installed.</expect>
  </example>
  <section id="the-rule" title="The founding rule">
    <p p="3">Think 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](../glossary/index.xml#specification) 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.</p>
    <rule ref="spec://org.vibevm.core/vibevm/modules/vibe-workspace/PROP-009#TWO-TREES" p="4"/>
    <p p="5">The 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.</p>
  </section>
  <section id="why-commit" title="Why the copies are committed">
    <p p="6">The 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.</p>
    <rule ref="spec://org.vibevm.core/vibevm/modules/vibe-workspace/PROP-009#VIBEDEPS-COMMITTED" p="7"/>
  </section>
  <section id="what-regenerates" title="What regenerates, and when">
    <p p="8">Three things in a project are derived from the [manifest](../glossary/index.xml#manifest) and the [lock file](../glossary/index.xml#lock-file), and vibe rebuilds them on demand: the dependency tree, the generated boot files, and the [managed block](../glossary/index.xml#managed-block) in the agent instruction files. `vibe reinstall` rebuilds all three from the lock file and the machine [store](../glossary/index.xml#store), without asking any [registry](../glossary/index.xml#registry); add `--force` to fetch the package files again from their sources.</p>
    <rule ref="spec://org.vibevm.core/vibevm/modules/vibe-workspace/PROP-009#REINSTALL" p="9"/>
    <rule ref="spec://org.vibevm.core/vibevm/modules/vibe-workspace/PROP-011#BYPASS-REINSTALL" p="10"/>
    <p p="11">`vibe 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.</p>
    <rule ref="spec://org.vibevm.core/vibevm/modules/vibe-workspace/PROP-053#CLEAN-KEEPS-AUTHORED" p="12"/>
  </section>
  <section id="edge-cases" title="Edge cases and rules">
    <p p="13">A 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.</p>
    <p p="14">If 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.</p>
    <p p="15">Two 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.</p>
    <rule ref="spec://org.vibevm.core/vibevm/common/PROP-000#INV-USER-FILES" p="16"/>
    <p p="17">The 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.</p>
    <rule ref="spec://org.vibevm.core/vibevm/modules/vibe-workspace/PROP-012#POSITION-USERS" p="18"/>
  </section>
</spec>
