# Create your first project {#root} @status:doc/work @audience:user [p01] A project is a folder your agent works in. This page creates one, adds the first shared rule set to it, and shows what appeared on disk and why the agent will now read it. Ten minutes, no prior knowledge. [p02] ```prompt Create a VibeVM project named hello-vibe in the current folder, install the package org.vibevm.world/wal into it from the default registry, and show me the reading list the agent gets at session start. ``` - needs: the vibevm skill installed for your agent; network access to github.com/vibespecs, or the package already in the machine store outcome: a folder `hello-vibe` with `vibe.toml`, `vibe.lock`, a `vibevm/` directory, and `CLAUDE.md`, `AGENTS.md` and `GEMINI.md` ending with a `` block; `vibe check` reports no errors - assert: `test -f hello-vibe/vibe.toml` - assert: `test -f hello-vibe/vibe.lock` - assert: `grep -q "org.vibevm.world/wal" hello-vibe/vibe.lock` - assert: `vibe check --path hello-vibe --quiet` ## What happens {#what-happens} [p03] The agent runs `vibe init hello-vibe`, which creates the folder with a [manifest](../glossary/index.xml#manifest), an empty [lock file](../glossary/index.xml#lock-file), the two boot files that are yours to edit, and the three agent instruction files. It then runs `vibe install org.vibevm.world/wal --path hello-vibe`. vibe reads the manifest's [registries](../glossary/index.xml#registry), finds the package, resolves a version, fetches it into the machine [store](../glossary/index.xml#store), and shows a plan. On confirmation it copies the package into `hello-vibe/vibevm/vibedeps/`, writes the lock file, and generates the boot files the agent will read. Finally the agent runs `vibe tree` to show that reading list and `vibe check` to confirm the project is consistent. > [p04] **Decision.** For every entry-point node, `vibe install` generates two artifacts under the node's `vibevm/vibespecs/boot/`: > > ## By hand {#by-hand} [p05] 1. Create the project. The name becomes the folder: [p06] ```sh vibe init hello-vibe ``` ```output Initializing project `hello-vibe` in `hello-vibe` ✓ created vibevm/vibespecs/boot/00-core.md ✓ created vibevm/vibespecs/boot/90-user.md ✓ created vibe.toml ✓ created vibe.lock ✓ created .vibe/.gitignore ✓ created .gitignore ✓ created vibevm/vibespecs/boot/INDEX.md ✓ created CLAUDE.md ✓ created AGENTS.md ✓ created GEMINI.md Done. Project `hello-vibe`: 10 files created, 0 kept. Next: • edit vibevm/vibespecs/boot/00-core.md and vibevm/vibespecs/common as your project takes shape • install packages with `vibe install :` (e.g. flow:wal) ``` [p07] 2. Install a package. The install shows a plan and asks for confirmation; `--assume-yes` skips the question in a script: [p08] ```sh vibe install org.vibevm.world/wal --path hello-vibe --assume-yes ``` ```output Resolving 1 root package… Materialising 1 package into vibedeps/: org.vibevm.world/wal@1.0.0 closure diff: → + org.vibevm.world/wal@1.0.0 (root-edge) → lane vibevm/vibespecs/boot/INDEX.md: 737 -> 854 B Materialised 1 package into vibedeps/; regenerated boot artifacts for 1 node(s). ``` [p09] 3. Look at what is recorded: [p10] ```sh vibe list --path hello-vibe ``` ```output KIND NAME VERSION ROLE BOOT SNIPPET flow wal 1.0.0 package — 1 package installed. ``` [p11] 4. Look at the reading list the agent gets: [p12] ```sh vibe tree --plain --path hello-vibe ``` ```output project: /work/hello-vibe STATIC.md: (none) packages: 1 roots: 1 columns: load T=transitive C=condition S=in STATIC.md org.vibevm.world/wal dynamic . . . ``` [p13] 5. Check the project: [p14] ```sh vibe check --path hello-vibe ``` ```output vibe check: clean — every check passed against `/work/hello-vibe` ``` ## What appeared on disk {#what-appeared} [p15] Open `hello-vibe/vibe.toml`: it names the project and, after the install, lists `org.vibevm.world/wal` under its requirements with a version range. Open `hello-vibe/vibe.lock`: it pins the exact version and the content [fingerprint](../glossary/index.xml#fingerprint). Under `hello-vibe/vibevm/vibedeps/` sits the package's published tree, unchanged. Under `hello-vibe/vibevm/vibespecs/boot/` sit your two boot files and the generated `INDEX.md`; a generated `STATIC.md` appears beside it as soon as a package asks to be read first and in full, which `wal` does not. And at the end of `CLAUDE.md`, `AGENTS.md` and `GEMINI.md` stands the block that points an agent at them. > [p16] **Decision.** `vibe` owns exactly one **managed block** inside each agent instruction file — a contiguous region bounded by an opening and a closing marker. > > [p17] Open a new [agent session](../glossary/index.xml#agent-session) in `hello-vibe` and ask it what rules it follows: it will name the package you installed a moment ago, because it read the lane before answering. ## Edge cases and rules {#edge-cases} [p18] A repeated `vibe install` with no package names installs whatever the manifest requires; that is the command after cloning an existing project. [p19] If the folder already has a `CLAUDE.md`, vibe appends its block at the end and leaves your text alone. If it finds two blocks or a broken one, it stops with an error and changes nothing until you fix the file. > [p20] **Malformed** (§2.2) — `vibe` **aborts the whole operation** with an error naming the file and the exact defect, and changes nothing. It does not proceed until the user repairs the file by hand. vibevm **never guesses** which of two blocks is canonical and **never auto-deletes** a stray marker — a malformed managed block is always a human's call. > > [p21] Declining the install plan is not an error: nothing is written, and the store keeps what was fetched for next time.