A version is a promise about behaviour, not a snapshot of files. Your project asks for a range, vibe records the one number it chose, and an update moves that number on purpose. vibe itself follows the same rule: one number stands for one contract, however often the binary behind it is rebuilt.
Package versions follow semantic versioning: three numbers, where the first changes when a package breaks compatibility. In the [manifest](../glossary/index.xml#manifest) you name a constraint, not a version: `^1.0` means any 1.x from 1.0 up, `=1.2.0` means exactly that one, and a bare [coordinate](../glossary/index.xml#coordinate) means the newest stable release. The resolver picks one version per package that satisfies every constraint in the graph, and the [lock file](../glossary/index.xml#lock-file) records the choice.
A [family](../glossary/index.xml#family) of packages that must move together pins its members exactly, so that a language guide and the server that serves its tools always resolve to one version set. You will meet these pins in the manifests of bundles; they are deliberate.
`vibe outdated` reads the lock file and the [registry](../glossary/index.xml#registry) and lists the packages with a newer version available; it changes nothing. `vibe update` re-resolves and moves the pins, preferring to keep every package you did not name at its current version, so that updating one package does not silently drag the others along.
After an update the dependency tree and the boot files are regenerated, and the diff of the lock file is the change log of what your agent will now read.
A version number is a contract: version 1 does what version 1 is documented to do. Inside a version the files behind it may be rebuilt, corrected or re-published, and a reader of the documentation does not see that kitchen. This is also how vibe treats its own releases. The binary you get from `vibe self install latest` is whatever the main branch holds today, under one version number. The manual describes the contract of that number rather than the files of one build.
A package version is a snapshot by default, in the sense the word has in Maven: its content may change under the same number, and `vibe update` brings the fresh content. A frozen version is the exception a publisher declares. Before the first public release, breaking changes ship without migration notes; the switch that ends that regime is the owner's alone.
The program manages its own versions with `vibe self`: `self install` builds a version from source or installs a verified bundle, `self ls` lists what the machine holds, `self use` switches the active one, and `self rollback` returns to the previous one. The selector `latest` means the tip of the main branch, `stable` the newest tagged release, and a plain `X.Y.Z` that tag.
Switching versions never overwrites a running binary and never requires a new terminal: the active version is a pointer the shim follows on the next call.
The manager looks after the program on the machine, not a project's dependencies, and its launcher folder goes on `PATH` once. `self use` repoints the active version; `--eval` prints a shell line for a one-terminal switch instead. `self update` follows where the running copy came from: a source checkout rebuilds at the tip, an installed binary moves to the newest published release. The same number is fetched again only when its release was rebuilt underneath it; `self reinstall` fetches the running version again without changing which one it is. `self rollback` swaps to the previous version and back again. The active version needs `--force` to be removed, and the copy that is running cannot be removed at all. Every prompt has a flag, so the whole thing works from a script or an agent, and `vibe vars` prints the variables the installation reads, without the publish token.
Two packages with the same coordinate and version but different bytes are two different things, and the second is refused. If a maintainer needs to re-publish, the version number changes.
A branch used as a [git source](../glossary/index.xml#git-source) is the one exception to pinning by number: its lock entry records the commit that was installed, and an update walks the branch again.