You wrote a package and want others to install it. This page publishes it to the place your projects install from, as its own repository, tags the version, and checks that a fresh project can install it.
The agent runs `vibe registry publish vibevm/vibepacks/org.acme/notes/v0.1.0 --dry-run` first and shows you what would happen: the [registry](../glossary/index.xml#registry), the repository name derived from the [coordinate](../glossary/index.xml#coordinate), the version tag. After your yes it runs the real command: vibe creates the repository in the registry organisation through the host's API if it does not exist, pushes the package's shippable tree, and tags the version. The package is then one more repository the registry's [index](../glossary/index.xml#index-registry) will pick up. To prove it, the agent creates a scratch project and installs the package by coordinate.
The publisher is a mechanical tool: it creates the repository, pushes the content and tags the version, and nothing more. The host of the registry's address picks the adapter that creates repositories; GitHub and GitVerse are known, and an unknown host is a clear error rather than a guess. In the repository the package content lies flat at the root, and the version is the tag `v` followed by the version number.
1. Put a publish token where vibe reads it. That is the environment variable `VIBEVM_PUBLISH_TOKEN`, or a file `~/.vibe/<host>.publish.token` such as `~/.vibe/github.publish.token`, readable by you alone. The token needs the right to create repositories in the organisation.
vibe looks for the token in a fixed order and takes the first it finds. First comes `VIBEVM_PUBLISH_TOKEN_<HOST>` for the registry's host, such as `VIBEVM_PUBLISH_TOKEN_GITHUB`. Then `VIBEVM_PUBLISH_TOKEN`, then the per-host file, then the older `~/.vibe/git.publish.token`. The token is a surface secret: never printed, never logged, never written to a file vibe writes. It leaves the process only in the request to the host, over an encrypted connection.
2. Rehearse:
3. Publish. `--registry` picks a registry by name; without it the first one in the [manifest](../glossary/index.xml#manifest) is used:
4. Install it from a fresh project to be sure: `vibe init scratch` and `vibe install <group>/notes --path scratch`.
Publishing a version that already exists replaces it: vibe appends a commit with the new content and moves the version tag to it. The version number changes only when you change it in the manifest. A consumer who already resolved that version keeps the exact bytes the [lock file](../glossary/index.xml#lock-file) recorded, and verifies the content [fingerprint](../glossary/index.xml#fingerprint) on every install, so the moved tag is noticed rather than silently accepted; a fresh install gets the new content. When the change matters to consumers, bump the version.
The publisher never rewrites the registry's history: every publish commit is a child of the head it observed, the tag moves only inside one atomic push guarded by the expected state of both refs, older tags are never touched, and the run stays inside the organisation the manifest names.
A repository that develops several packages publishes them with `vibe workspace publish`. It orders the members by their dependencies on each other and publishes each as its own repository. It stops at the first failure with a report of what was published and what remains. Each published copy carries an `[origin]` table naming the repository and the commit it came from, so a copy can always be traced to its source. `--member` restricts the run to one node; `--dry-run` shows the selection and the order without pushing.
`--repo-url` pushes straight to an existing git repository with your local git credentials and loads no publish token; use it for hosts without an API adapter.
The token is never sent to a package's install script and never printed, even in machine-readable output; if a command prints it, that is a bug to report.
A documentation package is published the same way; what differs is how it is consumed, by `vibe cache add` and the site rather than by `vibe install`.