<?xml version="1.0" encoding="UTF-8"?>
<spec xmlns="https://vibevm.org/spec/1">
  <title id="root">Read documentation locally</title>
  <status stage="doc" state="work" audience="user"/>
  <p p="1">Documentation of the packages you use, including private ones, can be read on your own machine with nothing sent anywhere. This page fetches the manual onto your machine and opens the reader in a browser.</p>
  <prompt id="read-docs-locally" p="2">
    Fetch the VibeVM manual, the package org.vibevm.core/vibevm-docs, into the machine store, open the local documentation reader, and tell me the address to open in my browser.
    <needs>the vibevm skill installed for your agent; network access to the registry once, or the package already in the store</needs>
    <outcome>`vibe cache list` shows `org.vibevm.core/vibevm-docs`; `vibe doc serve` is running and prints an address on `127.0.0.1`; the browser shows the manual's first page</outcome>
    <assert>vibe cache list --quiet</assert>
  </prompt>
  <section id="what-happens" title="What happens">
    <p p="3">The 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](../glossary/index.xml#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.</p>
    <rule ref="spec://org.vibevm.core/vibevm/common/PROP-057#KIND-DOC-NOT-INSTALLED" p="4"/>
    <rule ref="spec://org.vibevm.core/vibevm/common/PROP-057#LOCAL-SERVE" p="5"/>
  </section>
  <section id="by-hand" title="By hand">
    <p p="6">1. Warm the store. Inside a project, its [registries](../glossary/index.xml#registry) are the source; outside one, the machine-wide registries:</p>
    <example id="cache-add-docs" fixture="empty" p="7">
      <run>vibe cache add org.vibevm.core/vibevm-docs</run>
      <expect></expect>
    </example>
    <p p="8">2. Start the reader and open the printed address in a browser. Stop it with Ctrl+C:</p>
    <example id="doc-serve" fixture="docs-store" p="9">
      <run>vibe doc serve --help</run>
      <expect></expect>
    </example>
    <p p="10">3. 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.</p>
  </section>
  <section id="private-packages" title="Private packages">
    <p p="11">The 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.</p>
    <rule ref="spec://org.vibevm.core/vibevm/common/PROP-057#INV-LOCAL-IS-OFFLINE" p="12"/>
  </section>
  <section id="the-shell" title="The reader&apos;s shell">
    <p p="13">A 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.</p>
    <rule ref="spec://org.vibevm.core/vibevm/common/PROP-057#LOCAL-OFFLINE-SHELL" p="14"/>
  </section>
  <section id="edge-cases" title="Edge cases and rules">
    <p p="15">Warming a documentation package warms its [subjects](../glossary/index.xml#subject) too, so the rules a page quotes resolve without a network.</p>
    <rule ref="spec://org.vibevm.core/vibevm/common/PROP-057#REL-WARMUP-CLOSURE" p="16"/>
    <p p="17">Inside 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.</p>
    <rule ref="spec://org.vibevm.core/vibevm/common/PROP-057#LOCAL-WARMUP" p="18"/>
    <rule ref="spec://org.vibevm.core/vibevm/common/PROP-057#LOC-LOCAL" p="19"/>
    <p p="20">On 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.</p>
    <rule ref="spec://org.vibevm.core/vibevm/common/PROP-057#SITE-MOUNT" p="21"/>
    <rule ref="spec://org.vibevm.core/vibevm/common/PROP-057#SITE-VERSION-SHOWS-CURRENT" p="22"/>
    <p p="23">The 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.</p>
    <rule ref="spec://org.vibevm.core/vibevm/common/PROP-057#LOCAL-CSP" p="24"/>
    <p p="25">An 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.</p>
  </section>
</spec>
