# Что лежит в проекте {#root} @status:doc/work @audience:user [p01] После первой установки в проекте лежит горстка файлов, которые написали вы, и набор побольше, который vibe написал за вас. Эта страница называет каждый из них и говорит, кому можно его менять, чтобы ничего из вашего не было перезаписано и ничего из сгенерированного не правили руками. [p02] Example `tree` is copied from the source page at projection time. ## Файлы, один за другим {#the-files} [p03] Начните с двух файлов в корне, потому что всё остальное выводится из них. [p04] `vibe.toml` — это *[манифест](../glossary/index.xml#manifest)*. Его пишете вы, или `vibe init` пишет первую версию за вас. Он называет проект, перечисляет нужные пакеты с диапазоном версий для каждого и перечисляет [реестры](../glossary/index.xml#registry), откуда их брать. Это единственный файл, который нужен коллеге, чтобы воспроизвести вашу настройку, вместе с [лок-файлом](../glossary/index.xml#lock-file) рядом. [p05] `vibe.lock` — это *лок-файл*. Его пишет vibe, вы его коммитите и никогда не правите. Он записывает точную версию каждого установленного пакета, включая те, что притянули ваши пакеты, и [отпечаток](../glossary/index.xml#fingerprint) содержимого каждого. С ним свежий клон ставит те же байты на любой машине. [p06] Ниже лежит один каталог, `vibevm/`, с тремя детьми. Эта раскладка одинакова в каждом проекте и каждом пакете, и она не настраивается. > [p07] 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. > > [p08] `vibevm/vibespecs/` — *ваше* дерево: [спецификации](../glossary/index.xml#specification) и правила, которые пишет сам этот проект, в Markdown или в XML-диалекте проекта. vibe читает его и никогда в него не пишет, с одним исключением, описанным ниже. [p09] `vibevm/vibedeps/` — дерево *vibe*: по папке на установленный пакет и версию, с опубликованными файлами этого пакета как есть. Вы его коммитите, чтобы свежий клон читался без запуска чего бы то ни было, но никогда не правите. Правка там исчезает при следующей установке. > [p10] `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. > > [p11] В `vibevm/vibepacks/` лежат пакеты, которые этот репозиторий разрабатывает на месте: проект, который и сам публикует пакеты, держит их исходники здесь, и vibe считает этот каталог маленьким локальным реестром. У большинства проектов его нет. ## Стартовые файлы {#the-boot-files} [p12] Исключение в вашем дереве — `vibevm/vibespecs/boot/`. Два файла там ваши: `00-core` держит основы проекта, `90-user` — ваши личные переопределения, и vibe не трогает ни тот, ни другой. Два файла там сгенерированы: `INDEX.md`, манифест того, что читает агент, есть всегда, а `STATIC.md`, текст, который он читает первым и целиком, есть только когда какой-то пакет попросил читать себя именно так. Оба несут заголовок о том, что они сгенерированы; этот заголовок не украшение. > [p13] Both artifacts are generated, git-tracked, and marked "generated — do not edit". > > [p14] Агент находит стартовые файлы через короткий [управляемый блок](../glossary/index.xml#managed-block) в конце `CLAUDE.md`, `AGENTS.md` и `GEMINI.md`, между строками `` и ``. vibe переписывает то, что между двумя маркерами, и ничего больше в этих файлах; остальной файл ваш, и место блока, раз он появился, — тоже ваше. > [p15] `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. > > ## Кто что пишет {#who-writes-what} [p16] | Файл или каталог | Кто пишет | Коммитится | Правится руками | | --- | --- | --- | --- | | `vibe.toml` | вы (первую версию — `vibe init`) | да | да | | `vibe.lock` | vibe | да | никогда | | `vibevm/vibespecs/` | вы | да | да | | `vibevm/vibespecs/boot/00-core`, `90-user` | вы | да | да | | `vibevm/vibespecs/boot/INDEX.md`, `STATIC.md` | vibe | да | никогда | | `vibevm/vibedeps/` | vibe | да | никогда | | `vibevm/vibepacks/` | вы, когда репозиторий разрабатывает пакеты | да | да | | блок `` в файлах инструкций для агентов | vibe | да | только его место | | `.vibe/` | vibe | нет | никогда | [p17] Последняя строка — черновая область проекта: кэши и внутреннее состояние, которые git игнорирует и которые можно спокойно удалить. Машинное [хранилище](../glossary/index.xml#store) скачанных пакетов лежит в другом месте, в вашем домашнем каталоге, и его делят все проекты на машине. > [p18] The `.vibe/` cache directory is gitignored and per-project. > > [p19] Ещё одна папка появляется, когда проект начинает вести учёт, какие правила своих пакетов он принял: `vibefacts/`, коммитится, по маленькому TOML-файлу на пакет. Установка пакета не копирует туда ни одного статуса автора; принять их — осознанное действие, `vibe facts adopt`, а `vibe facts` — рычаг для всего остального: перечислить, задать статус по адресу, синхронизировать и отчитаться. Удаление пакета спрашивает, оставить ли его файл принятия или убрать; `vibe facts clean` удаляет файлы исчезнувших пакетов, а после обновления `vibe facts sync` сообщает о [якорях](../glossary/index.xml#anchor), которые пропали или переехали. > [p20] **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/..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. > > > [p21] **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 [--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). > > > [p22] **`vibe facts` — the explicit lever.** CRUD over the registry, search by attributes (package, status, stage, indeterminate-only), status transitions (`vibe facts set
`), `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). > > > [p23] **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. > > ## Особые случаи и правила {#edge-cases} [p24] Если вы удалите `vibevm/vibedeps/` или сгенерированные стартовые файлы, `vibe reinstall` восстановит их из лок-файла и хранилища, не трогая сеть. > [p25] Without `--force` it recomputes the materialisation and the boot artifacts from the existing `vibe.lock` and the local cache — no fresh resolution. > > [p26] Если проект из времён до нынешней раскладки несёт корневую папку `spec/`, vibe останавливается с рецептом миграции, а не гадает. Старые раскладки молча не читаются. > [p27] **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. > > [p28] Если вы случайно напишете в `vibevm/vibedeps/`, сразу ничего не сломается; следующая установка перезапишет правку, потому что папка пакета там — дословная копия опубликованного.