Два дерева: что пишете вы и что пишет vibe
01Проект держит порознь два рода текста: правила, которые написала ваша команда, и копии общих правил, которые пришли с установленными пакетами. Установка пакета никогда не правит ваш текст. Удаление никогда не оставляет в нём следа.
Основное правило
03Вспомните, как программа на C++ пользуется библиотекой: вы пишете #include, заголовки библиотеки читаются при сборке, но никто не вклеивает исходники библиотеки в ваши файлы. vibe следует тому же правилу для текста. Ваши спецификации живут в vibevm/vibespecs/; пакеты, от которых вы зависите, копируются целиком и без изменений в vibevm/vibedeps/, по папке на пакет и версию. Два дерева никогда не смешиваются.
04 Decision. A node's authoredspec/and its materialised dependencies live in physically separate trees.vibe installnever writes into any node's authoredspec/.
05Следствие просто сформулировать и легко забыть: каждый файл под vibevm/vibedeps/ — копия чего-то, опубликованного в другом месте. Правка там ничего не меняет наверху и живёт только до следующей установки. Если хотите, чтобы пакет говорил иначе, измените пакет, опубликуйте новую версию и обновитесь.
Почему копии коммитятся
06Скопированное дерево коммитится в ваш репозиторий, и это удивляет тех, кто ждёт, что каталог в духе node_modules будет проигнорирован. Причина — читатель: агент, который клонирует репозиторий, должен начать читать сразу, без сети, без инструмента и не зная, что vibe существует. Закоммиченное дерево превращает весь список чтения в набор обычных файлов чекаута, а ревью кода видит ровно тот текст, который агент прочитает после смены зависимости.
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.
Что и когда пересобирается
08Три вещи в проекте выводятся из манифеста и лок-файла, и vibe пересобирает их по требованию: дерево зависимостей, сгенерированные стартовые файлы и управляемый блок в файлах инструкций для агентов. vibe reinstall пересобирает все три из лок-файла и машинного хранилища, не спрашивая ни один реестр; добавьте --force, чтобы скачать файлы пакетов заново из их источников.
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 идёт на шаг дальше и удаляет выведенное состояние целиком, сохраняя всё, что вы написали, лок-файл и машинное хранилище. Это команда для чистого старта перед сборкой, и она отказывается работать вне проекта, чтобы не вымести не ту папку.
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.
Особые случаи и правила
13Папка пакета в дереве зависимостей названа по его группе, имени и версии, так что две версии одного пакета могут лежать рядом во время обновления, и ничего не перезаписывается на месте.
14Если вы разрабатываете пакеты в том же репозитории, их исходники живут в третьем дереве, vibevm/vibepacks/, которое ваше и которое вы правите. Когда проект в этом репозитории требует один из них, vibe всё равно копирует его в дерево зависимостей, как любой другой пакет.
15Два файла в стартовой папке ваши по закону: vibevm/vibespecs/boot/00-core и 90-user, Markdown в проекте, который создаёт vibe init, и XML в проекте, написанном на диалекте. Ни установка, ни обновление, ни удаление их не пишут никогда.
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.
17Управляемый блок в файле инструкций остаётся там, куда вы его поставили: vibe переписывает текст между маркерами и никогда не двигает сами маркеры, так что всё, что вы написали до или после блока, сохраняет своё место.
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.