# Маршрут новичка {#root}

@status:doc/work @audience:user

[p01] У вас есть агент-кодер и проект. VibeVM даёт этому агенту правильный текст для чтения перед началом работы и держит этот текст в согласии с тем, что решила ваша команда. Эта страница проводит от пустой папки до проекта, который агент понимает, короткими шагами.

## Шаг 1: понять, что вы ставите {#step-1}

[p02] Сначала прочитайте [Что такое VibeVM](what-vibevm-is.xml). Это пять минут, и они дают одну мысль, на которой держится всё остальное: инструкция для агента — это зависимость, а зависимости устанавливают, версионируют и разделяют, как библиотеки. Правило, которое стоит запомнить: установка никогда не правит написанное вами.

> [p03] The owner's hard constraint: **installing a dependency must never modify any node's authored spec** — the C++ rule that you do not paste a header's text into your `#include`.
>
> <spec://org.vibevm.core/vibevm/modules/vibe-workspace/PROP-009#INCLUDE-RULE>

## Шаг 2: установить vibe {#step-2}

[p04] Следуйте странице [Установить vibe](install-vibe.xml). На Windows это архив и скрипт, на остальных платформах — клон репозитория и скрипт. Готово, когда новый терминал отвечает на `vibe --version`. Всё, чем владеет vibe, лежит в одной папке вашего домашнего каталога, и эту папку можно перенести одной переменной окружения.

> [p05] **The settings home is `~/.vibe`** (owner, 2026-08-20). This document previously named `~/.config/vibe/config.toml`; the code has treated `~/.vibe` as canonical all along and the XDG path only as a legacy location an operator is invited to migrate out of. The correction is to this document, not to the tree.
>
> <spec://org.vibevm.core/vibevm/modules/vibe-registry/PROP-010#THE-SETTINGS-HOME-IS-DOT-VIBE-NOT-XDG>

## Шаг 3: создать проект и установить один пакет {#step-3}

[p06] Следуйте странице [Создать первый проект](first-project.xml). Отдайте промпт агенту или выполните четыре команды руками. Пакет, который вы ставите, — это способ работать; с этого момента агент читает его в начале каждой сессии. Обратите внимание на план, который vibe показывает перед тем, как что-то записать: пока вы не сказали «да», ничего не установлено.

> [p07] **Decision.** A package's identity is the tuple `(kind, name, version, content_hash)`. The `content_hash` is a digest over the deterministically-ordered concatenation of `(rel_path_bytes || 0x00 || file_bytes || 0x00)` for every file in the package directory, and **the value names the recipe that produced it** ([PROP-044 §4.7](../../common/PROP-044-change-native-formats.xml#machinery)): `sha256-tree/1:<hex>` is recipe 1, whose exclusion list, path normalisation and traversal order are carried as data in `formats/hash_recipes/1.toml`; the bare `sha256:<hex>` is recipe 0, the pre-recipe form, frozen verbatim in code — not configurable, because a frozen recipe that can be edited is not frozen — so that values written before recipes were named stay readable. Two hashes are comparable only **at the same recipe**; comparing across recipes answers a question nobody asked, and is never done silently. [PROP-024 §2.2](../../common/PROP-024-code-bearing-packages.xml#shippable-tree) re-scopes this to the package's **shippable tree** — its source, minus build output (`.git/`, `.vibe/`, `target/`, `node_modules/`, `.vibeignore` globs) — so a code-bearing package's identity is its source, not its build state; that exclusion lands with the code that implements it. The URL used to fetch the content is **informational** — recorded in the lockfile for debuggability, not for identity.
>
> <spec://org.vibevm.core/vibevm/modules/vibe-registry/PROP-002#IDENTITY-TUPLE>

## Шаг 4: посмотреть, что появилось {#step-4}

[p08] Прочитайте [Что лежит в проекте](what-a-project-contains.xml), держа новую папку открытой рядом. Два файла ваши, одно дерево ваше, одно дерево принадлежит vibe, а сгенерированные файлы несут список чтения. Знать, кто что пишет, — это разница между проектом, который остаётся согласованным, и проектом, который воюет с собственным инструментом.

> [p09] **Decision.** A node's authored `spec/` and its materialised dependencies live in physically separate trees. `vibe install` **never writes into any node's authored `spec/`**.
>
> <spec://org.vibevm.core/vibevm/modules/vibe-workspace/PROP-009#TWO-TREES>

## Шаг 5: увидеть, как агент это читает {#step-5}

[p10] Прочитайте [Стартовую полосу](../model/boot-lane.xml). Агент открывает файл с инструкциями, читает один сгенерированный файл целиком, а дальше идёт по списку. Чтобы начать, он никогда не запускает vibe. Когда вы позже добавите, удалите или обновите пакеты, полоса будет собрана заново, и агент в следующей сессии прочитает новую.

> [p11] **Session-start order:** the `CLAUDE.md` / `AGENTS.md` / `GEMINI.md` redirect → `vibevm/vibespecs/boot/STATIC.xml` (if present) → `vibevm/vibespecs/boot/INDEX.md` and the entries it names, in order.
>
> <spec://org.vibevm.core/vibevm/modules/vibe-workspace/PROP-009#SESSION-START-ORDER>

## После маршрута {#after}

[p12] Дальше руководство ветвится. Для ежедневной работы страницы раздела *Как сделать* рассказывают об [установке](../howto/install-a-package.xml), [обновлении](../howto/update-packages.xml), [удалении](../howto/remove-a-package.xml), [работе без сети](../howto/work-offline.xml) и [публикации](../howto/publish-a-package.xml). Чтобы понять механику, страницы раздела *Модель* объясняют [пакеты и виды](../model/packages-and-kinds.xml), [реестры](../model/registries.xml), [лок-файл](../glossary/index.xml#lock-file) и машинное [хранилище](../glossary/index.xml#store) и [версии](../model/versions.xml). Чтобы работу делал агент, следующая страница — [Дайте агенту навык vibevm](../agent/give-your-agent-the-skill.xml). А когда какая-нибудь команда отказывает, страница [От сообщения об ошибке к правилу](../diagnostics/errors.xml) называет правило, которое она применила.