docs: document vg lib lockfile pin and failure modes

DOCS.md

@@ -54,6 +54,8 @@ For a quick overview, see the [README](./README.md). This document covers everyt
   - [vg impact](#vg-impact)
   - [vg install / vg uninstall](#vg-install)
   - [vg lib](#vg-lib)
+    - [Lockfile pin](#lockfile-pin)
+    - [When a lookup fails](#when-a-lookup-fails)
   - [vg locale](#vg-locale)
   - [vg map / vg hubs / vg areas / vg oddities](#vg-map--vg-hubs--vg-areas--vg-oddities)
   - [vg llm-host](#vg-llm-host)
@@ -3545,15 +3547,19 @@ Run `vg install --list` for the live support matrix (ids can grow over time) —
 
 ### vg lib
 
-Version-correct library docs — from the hosted catalog or local ingestion.
+`vg lib <pkg>` prints usage docs for one library. When a lockfile in the project root lists that package, the version label is that pin.
 
 ```bash
-vg lib                  # List the catalog
-vg lib <name>           # Show docs for a library (pinned to your lockfile version)
+vg lib react
+```
+
+```bash
+vg lib                  # List the local catalog
+vg lib <name>           # Docs for one library
 vg lib add <source>     # Ingest docs from a local source
 vg lib publish <name>   # Upload private library docs to the hosted catalog
 vg lib resolve <name>   # Resolve name → catalog id + version
-vg lib refresh          # Re-ingest all local sources
+vg lib refresh          # Re-ingest local sources
 ```
 
 | Flag | Default | Description |
@@ -3566,6 +3572,65 @@ vg lib refresh          # Re-ingest all local sources
 | `--language <lang>` | — | Primary language (for `publish`) |
 | `--region <region>` | `us` | Data-residency region for the hosted catalog |
 | `--ingest <url>` | — | Hosted catalog URL override (wins over `--region`) |
+| `-C, --cwd <dir>` | `.` | Directory whose lockfiles and manifests are read |
+| `--json` | — | Machine-readable JSON, including `source` and `version_mismatch` |
+| `--offline` | off | Skip the hosted catalog |
+| `--local` | off | On-device only; implies `--offline`, so the hosted catalog is skipped |
+
+#### Lockfile pin
+
+A pin is looked up when the name is a declared dependency. For npm that is `dependencies` and `devDependencies` in `package.json`. A name that exists only inside a lockfile has no pin from this command.
+
+The label uses the first version it can read:
+
+1. The lockfile pin, from the files in the table below.
+2. The installed copy, when those files have no entry.
+3. The range written in the manifest, when there is no pin and no installed copy.
+
+`--json` reports that choice as `source`: `lockfile`, `installed`, `declared`, or `unknown`.
+
+Readers open these filenames in the directory you run from (`-C` changes it). A lockfile that lives only in a subdirectory is left unread. For npm, the first file that contains the name wins.
+
+| Ecosystem | File | What is read |
+|-----------|------|----------------|
+| npm | `package-lock.json` | v2/v3: `packages["node_modules/<name>"].version`. v1: `dependencies.<name>.version`. |
+| npm | `pnpm-lock.yaml` | The importer entry's `version`. A peer suffix such as `(zod@4.0.0)` is removed. |
+| npm | `yarn.lock` | The `version` line in the block whose header names the package. |
+| Python | `poetry.lock`, then `uv.lock` | `version` on the `[[package]]` table with that name. Matching ignores case and treats `-`, `_`, and `.` as the same character. |
+| Python | `Pipfile.lock` | `version` under `default` or `develop`, with a leading `==` removed. Same name matching as Poetry. |
+| Rust | `Cargo.lock` | `version` on the `[[package]]` table. Crate names are matched case-insensitively. |
+| Ruby | `Gemfile.lock` | The concrete version in the specs block (`name (1.2.3)`). |
+| PHP | `composer.lock` | `version` in `packages` or `packages-dev`, with a leading `v` removed. |
+| .NET | `packages.lock.json` | `resolved` under `dependencies.<framework>.<id>`. Ids are matched case-insensitively. |
+| Swift | `Package.resolved` | `state.version` for a matching `identity` (v1 `object.pins`, or v2/v3 `pins`). |
+| Dart | `pubspec.lock` | The `version` field on that package. |
+| Java | `gradle.lockfile` | The version in a `group:artifact:version=` line. Pass the name as `group:artifact`. |
+
+The pin lookup skips `go.sum` (Go keeps the version declared in `go.mod`), `pdm.lock`, `npm-shrinkwrap.json`, `bun.lock`, and Maven lockfiles. A Java dependency declared only in `pom.xml` uses that declared version.
+
+The text is chosen separately from the label:
+
+- A catalog entry from `vg lib add` is printed with the version stored on that entry.
+- Otherwise, for an npm package, the command reads the installed package: `llms.txt`, then a README, then markdown under `docs/`, then the `description` in `package.json`. The label stays the lockfile pin when one exists, so the words can be the installed copy while the heading shows the pin.
+- When that text is missing or too thin, and the run may use the network, the hosted catalog is asked by library name. The heading then shows the version the catalog returned. When the catalog omits a version, the heading keeps the lockfile label.
+
+#### When a lookup fails
+
+**Missing lockfile entry.** The lockfile is absent, or it has no row for that name. The label moves to the installed version, then to the declared range. `--json` sets `source` to `installed`, `declared`, or `unknown`.
+
+**Lockfile and install disagree.** When both a pin and an installed version are readable and they differ, the label stays the pin. The command prints a warning that names both versions: the lockfile pins one version and the installed tree has the other. Reinstall from the lockfile, or commit the lockfile that matches what is installed. The warning is omitted when the two versions agree. `--json` puts the same pair on `version_mismatch` (`lockfile`, `installed`, `note`), or `null` when they agree. The installed copy is `node_modules/<name>/package.json` for npm, a `.dist-info` directory under `.venv`, `venv`, `env`, or `.tox` for Python, and `vendor/composer/installed.json` for PHP. Other ecosystems can show a pin without this comparison.
+
+**Offline or `--local`.** `--local` and `--offline` both skip the hosted catalog. A catalog entry and installed npm docs still print. When neither exists, the command exits 3:
+
+```text
+no library docs for "<name>" — add with `vg lib add <path|url> --name <name>` or install the package (or retry with --online for the hosted catalog)
+```
+
+The error text mentions `--online`. Remove `--local` or `--offline` and run the command again; those two flags are what keep the hosted catalog off. The network is on unless you pass one of them.
+
+**Network fetch fails.** A timeout, a connection error, a non-success response, or an empty body counts as no hosted answer. The message leaves out the response body and any credential. A failed attempt is not saved. A successful answer can be reused for about a day, so a later outage can still show that earlier text. When local text exists, it is printed, with a note that the local docs look thin and the hosted catalog had nothing better. When no local text exists either, the command exits 3 with the not-found message above, without the `--online` hint.
+
+**Unreadable lockfile.** A lockfile that is present but truncated, invalid, or unreadable stops the command and exits 1. The message names the file and tells you to restore or regenerate it with your package manager. File contents stay out of the message.
 
 ---
 

README.md

@@ -595,11 +595,10 @@ Copy-paste CI templates live in `examples/github-actions/`. When the job fails,
 
 ## Version-correct library docs
 
-`vg lib` fetches usage docs pinned to the **exact version in your lockfile** — never a newer API your code can't call yet:
+`vg lib <pkg>` prints usage docs for one library. When a lockfile in the project root lists that package, the version label is that pin. Which files are read, and what happens when the pin is missing, the install disagrees, or the catalog fetch fails: [DOCS.md](./DOCS.md#lockfile-pin).
 
 ```bash
-vg lib react                    # React docs at your installed version
-vg lib express --fn middleware  # specific function reference
+vg lib react
 ```
 
 AI assistants connected via MCP use `vg lib` automatically when answering questions about library APIs in your project.