Read documentation locally

What happens

03The agent runs vibe cache add org.vibevm.core/vibevm-docs. A documentation package is never installed into a project; it is warmed into the machine store together with the packages it documents, so that every rule it cites can be resolved offline. Then the agent runs vibe doc serve: vibe starts a small web server that listens on your own machine only, renders each page from the store on request, and prints the address. Nothing is fetched from the internet while you read, and no page leaves the machine.

04 vibe install MUST refuse a doc package with a hint naming the warm-up command; documentation is warmed into the machine store with vibe cache add (§11), and the local reader and vibe explain read the store.

05 vibe doc serve starts an HTTP server on 127.0.0.1 only, serves the shell and, on every request, glues in the island rendered from the machine store, the current project's lock file or a private registry. The language preference comes from the project's [i18n].preferred when present. The mode is fully autonomous: no request to vibevm.org, no external CDN or fonts, everything in the bundle. The server serves files only from known roots (the store, the shell), without path traversal and without directory listing, with a content security policy naming no external source.

By hand

061. Warm the store. Inside a project, its registries are the source; outside one, the machine-wide registries:

vibe cache add org.vibevm.core/vibevm-docs

082. Start the reader and open the printed address in a browser. Stop it with Ctrl+C:

vibe doc serve --help

103. Pick a language with the selector on any page. Where a page has no translation, the reader shows the manual's own language and says so.

Private packages

11The same reader shows the documentation of packages that live in a private registry or only on your machine: whatever the store holds, the reader renders. This is the intended path for proprietary documentation, and it is why the reader never contacts the public site.

12 The local reader listens on 127.0.0.1 only, serves only known roots, loads nothing external, and contacts the network only for a shell download the user explicitly confirmed.

The reader's shell

13A released vibe carries the reader's interface inside the binary. A vibe you built from source carries a plain fallback; vibe doc shell install fetches the full interface for its version from the release assets, verified by size and digest, into ~/.vibe/opt/, and only when you ask. The reader works, plainly, without it, and vibe doc serve --print-shell says which of the two it holds.

14 When the instance's shell pin names a shell that is not in the shell store and there is no network, the reader falls back to the bare shell and warns; it never contacts the network without consent (§12).

Edge cases and rules

15Warming a documentation package warms its subjects too, so the rules a page quotes resolve without a network.

16 Warming a doc package with vibe cache add warms its subjects too, so that spec:// citations resolve offline.

17Inside a project whose local registry holds the package in-tree, vibe cache add --offline warms it without a network. The reader's language comes from the project's [i18n].preferred or from a flag at launch.

18 The store is warmed with vibe cache add <coordinate> from a registry, or vibe cache add --offline <coordinate> from a project root whose project-local registry holds the package in-tree; the sources of vibe-doc are the store (lookup, list_all), the lock file (Lockfile::read, slot_abs_path), a registry (resolve_and_fetch) and a checkout (LocalRegistry).

19 The local reader serves the same from the store; the preference comes from the project's [i18n].preferred or a launch flag.

20On the site the same page lives under /doc/, with the language as the next path segment and no prefix for the source language. An address with a version number shows the current content of that version, because a version may be published again and the registry keeps no past publications.

21 The site is mounted under the path /doc of the main domain. The language is the path segment after /doc/; the source language of a documentation carries no prefix. The address map is deterministic and needs no index:

22 An address with a version number always shows the current content of that version in the registry: one number may be published ten times a day, and the site shows the last publication. There are no permanent links to past publications — they do not exist in the registry either (§14).

23The reader can be embedded by an editor plugin through an iframe; then the plugin passes its own origin at launch and the reader accepts frames from that origin alone.

24 The policy is sent as a header, not a <meta>: default-src 'self'; script-src 'self'; style-src 'self'; img-src 'self' data:; font-src 'self'; connect-src 'self'; media-src 'self'; object-src 'none'; base-uri 'none'; form-action 'none'; frame-ancestors <origin>, where frame-ancestors names only the origin of the host that launched the reader — the launch parameter vibe doc serve --frame-ancestor <origin>, because a webview's origin changes from window to window — and is 'none' without the parameter. The reader has no CORS layer at all and sends x-content-type-options: nosniff. The public site is not embeddable in frames.

25An agent reads the same store: vibe explain "spec://org.vibevm.core/vibevm-docs/start/what-vibevm-is" prints a page or a block as text.