# The newcomer's route {#root} @status:doc/work @audience:user [p01] You have a coding agent and a project. VibeVM gives that agent the right text to read before it starts working, and keeps that text in step with what your team decided. This page walks you from an empty folder to a project your agent understands, one short step at a time. ## Step 1: understand what you are installing {#step-1} [p02] Read [What VibeVM is](what-vibevm-is.xml) first. It takes five minutes and gives you the one idea everything else rests on: instruction text for an agent is a dependency, and dependencies are installed, versioned and shared like libraries. The rule to remember is that installing never edits what you wrote. > [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`. > > ## Step 2: install vibe {#step-2} [p04] Follow [Install vibe](install-vibe.xml). On Windows it is an archive and a script; elsewhere it is a clone and a script. You are done when a new terminal answers `vibe --version`. Everything vibe owns lives under one folder in your home directory, and you can move that folder with one environment variable. > [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. > > ## Step 3: create a project and install one package {#step-3} [p06] Follow [Create your first project](first-project.xml). Give the prompt to your agent, or run the four commands by hand. The package you install is a way of working; the agent reads it at every session start from then on. Note the plan vibe shows before it writes anything: nothing is installed until you say yes. > [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:` is recipe 1, whose exclusion list, path normalisation and traversal order are carried as data in `formats/hash_recipes/1.toml`; the bare `sha256:` 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. > > ## Step 4: look at what appeared {#step-4} [p08] Read [What a project contains](what-a-project-contains.xml) with the new folder open beside it. Two files are yours, one tree is yours, one tree is vibe's, and the generated files carry the reading list. Knowing who writes what is the difference between a project that stays consistent and one that fights its own tool. > [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/`**. > > ## Step 5: see how the agent reads it {#step-5} [p10] Read [The boot lane](../model/boot-lane.xml). The agent opens the instruction file, reads one generated file in full, and follows a list for the rest. It never runs vibe to start. When you later add packages, remove them or update them, the lane is regenerated and the agent's next session reads the new one. > [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. > > ## After the route {#after} [p12] From here the manual branches. To work day to day, the pages under *How to* cover [installing](../howto/install-a-package.xml), [updating](../howto/update-packages.xml), [removing](../howto/remove-a-package.xml), [working offline](../howto/work-offline.xml) and [publishing](../howto/publish-a-package.xml). To understand the machinery, the pages under *Model* explain [packages and kinds](../model/packages-and-kinds.xml), [registries](../model/registries.xml), the [lock file](../glossary/index.xml#lock-file) and the machine [store](../glossary/index.xml#store), and [versions](../model/versions.xml). To let your agent do the work, [Give your agent the vibevm skill](../agent/give-your-agent-the-skill.xml) comes next. And whenever a command refuses, [From an error message to the rule](../diagnostics/errors.xml) names the rule it enforced.