Что лежит в проекте

Файлы, один за другим

03Начните с двух файлов в корне, потому что всё остальное выводится из них.

04vibe.toml — это манифест. Его пишете вы, или vibe init пишет первую версию за вас. Он называет проект, перечисляет нужные пакеты с диапазоном версий для каждого и перечисляет реестры, откуда их брать. Это единственный файл, который нужен коллеге, чтобы воспроизвести вашу настройку, вместе с лок-файлом рядом.

05vibe.lock — это лок-файл. Его пишет vibe, вы его коммитите и никогда не правите. Он записывает точную версию каждого установленного пакета, включая те, что притянули ваши пакеты, и отпечаток содержимого каждого. С ним свежий клон ставит те же байты на любой машине.

06Ниже лежит один каталог, vibevm/, с тремя детьми. Эта раскладка одинакова в каждом проекте и каждом пакете, и она не настраивается.

07 The layout: every project and every package carries ONE distinctive root directory vibevm/, holding vibevm/vibespecs (was spec/), vibevm/vibepacks (was packages/), vibevm/vibedeps (was root vibedeps/) and vibevm/vibefacts (was root vibefacts/). Nothing else moves; vibe.toml stays at the project root.

08vibevm/vibespecs/ — ваше дерево: спецификации и правила, которые пишет сам этот проект, в Markdown или в XML-диалекте проекта. vibe читает его и никогда в него не пишет, с одним исключением, описанным ниже.

09vibevm/vibedeps/ — дерево vibe: по папке на установленный пакет и версию, с опубликованными файлами этого пакета как есть. Вы его коммитите, чтобы свежий клон читался без запуска чего бы то ни было, но никогда не правите. Правка там исчезает при следующей установке.

10 vibedeps/ is committed to the repository. A fresh clone is immediately bootable with no vibe install; the dependency corpus is visible and diffable; this matches the spec-driven principle that the committed spec corpus is the product.

11В vibevm/vibepacks/ лежат пакеты, которые этот репозиторий разрабатывает на месте: проект, который и сам публикует пакеты, держит их исходники здесь, и vibe считает этот каталог маленьким локальным реестром. У большинства проектов его нет.

Стартовые файлы

12Исключение в вашем дереве — vibevm/vibespecs/boot/. Два файла там ваши: 00-core держит основы проекта, 90-user — ваши личные переопределения, и vibe не трогает ни тот, ни другой. Два файла там сгенерированы: INDEX.md, манифест того, что читает агент, есть всегда, а STATIC.md, текст, который он читает первым и целиком, есть только когда какой-то пакет попросил читать себя именно так. Оба несут заголовок о том, что они сгенерированы; этот заголовок не украшение.

13 Both artifacts are generated, git-tracked, and marked "generated — do not edit".

14Агент находит стартовые файлы через короткий управляемый блок в конце CLAUDE.md, AGENTS.md и GEMINI.md, между строками <vibevm> и </vibevm>. vibe переписывает то, что между двумя маркерами, и ничего больше в этих файлах; остальной файл ваш, и место блока, раз он появился, — тоже ваше.

15 vibe reads and rewrites only the content between the markers; every byte outside the block is treated as another tenant's property and preserved verbatim across every vibe operation.

Кто что пишет

17Последняя строка — черновая область проекта: кэши и внутреннее состояние, которые git игнорирует и которые можно спокойно удалить. Машинное хранилище скачанных пакетов лежит в другом месте, в вашем домашнем каталоге, и его делят все проекты на машине.

18 The .vibe/ cache directory is gitignored and per-project.

19Ещё одна папка появляется, когда проект начинает вести учёт, какие правила своих пакетов он принял: vibefacts/, коммитится, по маленькому TOML-файлу на пакет. Установка пакета не копирует туда ни одного статуса автора; принять их — осознанное действие, vibe facts adopt, а vibe facts — рычаг для всего остального: перечислить, задать статус по адресу, синхронизировать и отчитаться. Удаление пакета спрашивает, оставить ли его файл принятия или убрать; vibe facts clean удаляет файлы исчезнувших пакетов, а после обновления vibe facts sync сообщает о якорях, которые пропали или переехали.

20 Home and format. vibefacts/ at the project root, tracked in git (it is project state a teammate must see), one TOML file per source: vibefacts/spec.toml for the host's own spec/ tree, vibefacts/<group>.<name>.toml per installed package (the vibedeps slot-naming convention). Grep-friendly, small diffs, per-package lifecycle: removing a package's overlay is removing one file. Landed in W1.

21 L1 — consumer sovereignty: imported statuses are ignored. On package import the authored statuses in the package source are NOT copied into the registry — the package may use them for its own internal purposes, and the consumer's adoption state starts indeterminate. Acceptance of authored statuses is a deliberate act, never a default: vibe facts adopt --package <X> [--from-source] [filter] bulk-copies the author's statuses into the overlay in one auditable gesture (the escape hatch for implementation-shipping packages whose facts are done-by-construction). Landed: import never touches the registry by construction (W1); adopt fills absent entries only and reports added/kept (W2).

22 vibe facts — the explicit lever. CRUD over the registry, search by attributes (package, status, stage, indeterminate-only), status transitions (vibe facts set <address> <status>), adopt (L1), sync (L2), clean (L5), and the adoption report (vibe facts report [--package X] — «12/40 adopted»). An agent flips a fact through the tool — an auditable command — never by editing derived files. Landed across W1–W3: list/get/set/rm/sync (W1), adopt with point re-derivation (W2), clean and the per-package report with ? for unavailable denominators (W3).

23 L5 — lifecycle: removal keeps, cleaning reports. Removing a package does not silently erase its overlay; vibe uninstall (the CLI verb; built out if found unimplemented) asks whether to clean or keep the package's facts file. vibe facts clean is the revision pass that removes orphaned overlays of vanished packages; on dependency UPGRADE, vibe facts sync reports anchors that disappeared or moved (orphaned entries with candidates) rather than dropping them — the tombstone discipline, applied to overlays. Landed in W3: lockfile-driven clean with dry-run and named removals, the attended-only uninstall dialog (automation flags never imply consent to delete adoption data), spec.toml never an orphan.

Особые случаи и правила

24Если вы удалите vibevm/vibedeps/ или сгенерированные стартовые файлы, vibe reinstall восстановит их из лок-файла и хранилища, не трогая сеть.

25 Without --force it recomputes the materialisation and the boot artifacts from the existing vibe.lock and the local cache — no fresh resolution.

26Если проект из времён до нынешней раскладки несёт корневую папку spec/, vibe останавливается с рецептом миграции, а не гадает. Старые раскладки молча не читаются.

27 L3 — no legacy reading. The old layout is not read and not migrated silently: a project carrying root spec/ beside vibe.toml (or root vibedeps//vibefacts/) fails loudly with the migration recipe. The owner's ground: no project in the world carries a root vibevm/ today, so the new root is unambiguous and the old one is retired whole.

28Если вы случайно напишете в vibevm/vibedeps/, сразу ничего не сломается; следующая установка перезапишет правку, потому что папка пакета там — дословная копия опубликованного.