@vibgrate/cli 2026.708.3 → 2026.709.2

package/DOCS.md

@@ -11,35 +11,44 @@ For a quick overview, see the [README](./README.md). This document covers everyt
 - [How It Works](#how-it-works)
 - [Choosing a rollout model: one-off vs CI](#choosing-a-rollout-model-one-off-vs-ci)
 - [Commands Reference](#commands-reference)
-  - [vg init](#vg-init)
-  - [vg scan](#vg-scan)
-  - [Vulnerabilities and exposure attribution](#vulnerabilities-and-exposure-attribution)
-  - [vg why](#vg-why)
+  - [vg baseline](#vg-baseline)
   - [vg bisect](#vg-bisect)
+  - [vg drift](#vg-drift)
+  - [vg dsn create](#vg-dsn-create)
   - [vg fix](#vg-fix)
-  - [vg baseline](#vg-baseline)
+  - [vg init](#vg-init)
+  - [vg login](#vg-login)
+  - [vg logout](#vg-logout)
+  - [vg push](#vg-push)
   - [vg report](#vg-report)
   - [vg sbom](#vg-sbom)
-  - [vg push](#vg-push)
-  - [vg dsn create](#vg-dsn-create)
+  - [vg scan](#vg-scan)
+    - [Vulnerabilities and exposure attribution](#vulnerabilities-and-exposure-attribution)
   - [vg update](#vg-update)
+  - [vg why](#vg-why)
 - [Code Graph Commands](#code-graph-commands)
-  - [vg build](#vg-build)
-  - [vg show](#vg-show)
   - [vg ask](#vg-ask)
+  - [vg benchmark](#vg-benchmark)
+  - [vg build](#vg-build)
+  - [vg bundle](#vg-bundle)
+  - [vg embed](#vg-embed)
+  - [vg export](#vg-export)
+  - [vg facts](#vg-facts)
+  - [vg guide](#vg-guide)
   - [vg impact](#vg-impact)
-  - [vg path](#vg-path)
-  - [vg tree](#vg-tree)
-  - [vg map / vg hubs / vg areas / vg oddities](#vg-map--vg-hubs--vg-areas--vg-oddities)
+  - [vg install](#vg-install)
   - [vg lib](#vg-lib)
+  - [vg map / vg hubs / vg areas / vg oddities](#vg-map--vg-hubs--vg-areas--vg-oddities)
+  - [vg models](#vg-models)
+  - [vg path](#vg-path)
+  - [vg savings](#vg-savings)
   - [vg serve](#vg-serve)
-  - [vg install](#vg-install)
   - [vg share](#vg-share)
+  - [vg show](#vg-show)
   - [vg status](#vg-status)
-  - [vg facts](#vg-facts)
   - [vg tests](#vg-tests)
-  - [vg embed](#vg-embed)
-  - [vg export](#vg-export)
+  - [vg tree](#vg-tree)
+  - [vg unknowns](#vg-unknowns)
 - [DriftScore](#driftscore)
 - [Drift Baselines & Fitness Functions](#drift-baselines--fitness-functions)
   - [How the Score Is Calculated](#how-the-score-is-calculated)
@@ -160,138 +169,76 @@ Expected results:
 
 ## Commands Reference
 
-### vg init
+### vg baseline
 
-Initialise Vibgrate in a project.
+Create a drift baseline snapshot for delta comparison.
 
 ```bash
-vg init [path] [--baseline] [--yes]
+vg baseline [path]
 ```
 
-| Flag         | Description                                 |
-| ------------ | ------------------------------------------- |
-| `--baseline` | Create an initial drift baseline after init |
-| `--yes`      | Skip confirmation prompts                   |
-
-Creates:
-
-- `.vibgrate/` directory
-- `vibgrate.config.ts` with sensible defaults
+Runs a full scan and saves the result to `.vibgrate/baseline.json`. Use this as the starting point for tracking drift over time.
 
 ---
 
-### vg scan
+### vg bisect
 
-The primary command. Scans your project for upgrade drift.
+Pinpoint the commit where a dependency crossed a version line. Where `vg why` narrates every version change, `vg bisect` answers one targeted question: *when did we cross this line?* — for example, when a vulnerable dependency was finally patched past the fixed version, or when a major was adopted.
 
 ```bash
-vg scan [path] [--vulns] [--full] [--format text|json|sarif|md] [--out <file>] [--fail-on warn|error] [--offline] [--package-manifest <file>] [--no-local-artifacts] [--max-privacy] [--baseline <file>] [--drift-budget <score>] [--drift-worsening <percent>] [--changed-only] [--concurrency <n>]
+vg bisect <package> <constraint>
 ```
 
-| Flag | Default | Description |
-|------|---------|-------------|
-| `--vulns` | — | Also detect known vulnerabilities (OSV online; offline via `--package-manifest` advisories) |
-| `--full` | — | Comprehensive scan: enables `--vulns` and reports banned dependencies when a standards policy exists |
-| `--format` | `text` | Output format: `text`, `json`, `sarif`, or `md` |
-| `--out <file>` | — | Write output to a file |
-| `--fail-on <level>` | — | Exit with code 2 if findings at this level exist |
-| `--baseline <file>` | — | Compare against a previous baseline |
-| `--changed-only` | — | Only scan changed files |
-| `--concurrency <n>` | `8` | Max concurrent npm registry calls |
-| `--drift-budget <score>` | — | Fitness gate: fail if drift score is above this budget |
-| `--drift-worsening <percent>` | — | Fitness gate: fail if drift worsens by more than % vs baseline |
-| `--push` | — | Upload scan artifact to Vibgrate Cloud after a successful scan |
-| `--dsn <dsn>` | `VIBGRATE_DSN` env | DSN used for `--push` authentication |
-| `--region <region>` | — | Override data residency (`us`, `eu`) during push |
-| `--strict` | — | Fail scan command if push fails |
-| `--ui-purpose` | — | Enable optional UI-purpose evidence extraction |
-| `--offline` | — | Disable network calls and disable upload/push behavior |
-| `--package-manifest <file>` | — | JSON or ZIP package-version manifest used for offline/latest lookups (latest bundle: `https://github.com/vibgrate/manifests/latest-packages.zip`) |
-| `--no-local-artifacts` | — | Do not write `.vibgrate/*.json` scan artifacts to disk |
-| `--max-privacy` | — | Hardened privacy mode with minimal scanners and no local artifacts |
-
-By default, the scan writes `.vibgrate/scan_result.json`. Use `--no-local-artifacts` or `--max-privacy` to suppress local JSON artifact files.
+`<constraint>` is a version or a semver range. A bare version means "reached or surpassed" — `vg bisect lodash 4.17.21` is the same as `vg bisect lodash '>=4.17.21'`. It reads the same lockfile history `vg why` uses (npm / pnpm / yarn, pip / poetry, cargo, composer, bundler, go, pub, hex, NuGet, and Maven/Gradle), offline and without checking out any commit.
 
-For offline drift scoring, pass `--package-manifest <file>` with a downloaded manifest bundle such as `https://github.com/vibgrate/manifests/latest-packages.zip`.
+It reports the commit that first reached the constraint — author, date, and the version before and after — or tells you the line was never crossed and shows the latest version in history (so an unadopted fix is obvious). Later flips, such as a downgrade that re-introduced the old version, are listed too.
 
-Examples:
+Add `--assert` to turn it into a CI gate: the command exits non-zero when the current version does not satisfy the constraint, so a pipeline step can block a merge until the fix is adopted.
 
 ```bash
-# Standard text scan
-vg scan
-
-# JSON output for automation
-vg scan --format json --out scan.json
-
-# CI gate with baseline regression protection
-vg scan --baseline .vibgrate/baseline.json --drift-budget 40 --drift-worsening 5 --fail-on error
-
-# Upload result in the same command
-vg scan --push --strict
+vg bisect lodash 4.17.21 --assert    # fails the build until lodash is patched to >= 4.17.21
 ```
 
-Expected results:
-
-- Clear score/risk output in terminal (or JSON/SARIF when selected).
-- Exit code `2` when configured quality gates are exceeded.
-- When `--push` is enabled, artifact upload is attempted after scan completion.
+Exit codes: `0` when the query resolves, `2` when `--assert` finds the constraint unsatisfied, `3` when the package has no version history, `5` for an invalid version or range.
 
 ---
 
-### Vulnerabilities and exposure attribution
-
-`vg scan --vulns` matches your installed dependencies against the public OSV database and records each known vulnerability — advisory id and CVE, severity, CVSS, and the fixing version — in the scan artifact, as findings, and in SARIF. Supply advisories in a `--package-manifest` bundle to run it offline.
-
-In a git repository the scan also attributes each finding: the commit, author, and date that introduced the vulnerable version, and how long you have been exposed. These exposure windows aggregate into remediation metrics framed around the EU Cyber Resilience Act (CRA): open counts by severity, mean and maximum time exposed, and per-severity SLA breaches (defaults: critical 7 days, high 30, moderate 90, low 180). The metrics are descriptive — they show whether remediation keeps pace; they are not a compliance certification.
-
-The scan also reconstructs **closed** exposure windows from history — a vulnerable version that was later bumped out of the affected range or removed from the lockfile entirely — and reports real remediation time (MTTR) from them: measured, not estimated. Offline, a package-version manifest extends this to advisories that are fully fixed today, so a dependency that is clean now but was once vulnerable still counts toward your remediation record.
+### vg drift
 
-Detection and attribution read each project's lockfile, so they cover npm / pnpm / yarn, pip / poetry / pipenv, cargo, composer, bundler, go, pub, hex, NuGet, and Maven/Gradle.
+What is outdated across your dependencies — a fast, offline currency check.
 
 ```bash
-# Online detection against OSV
-vg scan --vulns
-
-# Air-gapped: advisories supplied in the manifest bundle
-vg scan --vulns --offline --package-manifest ./package-versions.zip
-
-# Everything in one run: drift + vulnerabilities + a banned-dependency report
-vg scan --full
+vg drift
 ```
 
----
-
-### vg why
-
-Explain a dependency from git history: who added it, every version since, and any open vulnerabilities it carries.
+Reads each project's lockfile and reports which dependencies have drifted behind their latest known version. Offline by default (uses the last-known catalog); add `--online` to check live registries for current latest versions.
 
-```bash
-vg why <package>
-```
+| Flag | Description |
+|------|-------------|
+| `--online` | Check live registries for the latest versions instead of the offline catalog |
+| `--fail-on <level>` | CI gate: exit non-zero when drift is found at this level (`major`, `minor`, or `standards`) |
 
-`vg why` reads your lockfile's history, so it works across npm / pnpm / yarn, pip / poetry, cargo, composer, bundler, go, pub, hex, NuGet, and Maven/Gradle projects. For Maven/Gradle the history comes from a resolved `gradle.lockfile`, or a `pom.xml`'s pinned direct-dependency versions (versions managed by a BOM/`dependencyManagement` aren't resolved). Open vulnerabilities and their introduction attribution come from your most recent `vg scan --vulns`.
+Add `--json` for machine-readable output.
 
 ---
 
-### vg bisect
+### vg dsn create
 
-Pinpoint the commit where a dependency crossed a version line. Where `vg why` narrates every version change, `vg bisect` answers one targeted question: *when did we cross this line?* — for example, when a vulnerable dependency was finally patched past the fixed version, or when a major was adopted.
+Generate an HMAC-signed DSN token for API authentication.
 
 ```bash
-vg bisect <package> <constraint>
+vg dsn create --workspace <id|new> [--region <region>] [--ingest <url>] [--write <path>]
 ```
 
-`<constraint>` is a version or a semver range. A bare version means "reached or surpassed" — `vg bisect lodash 4.17.21` is the same as `vg bisect lodash '>=4.17.21'`. It reads the same lockfile history `vg why` uses (npm / pnpm / yarn, pip / poetry, cargo, composer, bundler, go, pub, hex, NuGet, and Maven/Gradle), offline and without checking out any commit.
-
-It reports the commit that first reached the constraint — author, date, and the version before and after — or tells you the line was never crossed and shows the latest version in history (so an unadopted fix is obvious). Later flips, such as a downgrade that re-introduced the old version, are listed too.
-
-Add `--assert` to turn it into a CI gate: the command exits non-zero when the current version does not satisfy the constraint, so a pipeline step can block a merge until the fix is adopted.
-
-```bash
-vg bisect lodash 4.17.21 --assert    # fails the build until lodash is patched to >= 4.17.21
-```
+| Flag          | Default    | Description                                                                 |
+| ------------- | ---------- | --------------------------------------------------------------------------- |
+| `--workspace` | _required_ | Your workspace ID, or `new` to auto-generate a workspace                    |
+| `--region`    | `us`       | Data residency region (`us`, `eu`)                                          |
+| `--ingest`    | —          | Custom ingest API URL (overrides `--region`)                                |
+| `--write`     | —          | Write DSN to a file (add to `.gitignore`!)                                  |
 
-Exit codes: `0` when the query resolves, `2` when `--assert` finds the constraint unsatisfied, `3` when the package has no version history, `5` for an invalid version or range.
+When using `--workspace new`, the CLI auto-generates a workspace ID and provisions the DSN
+with the Vibgrate API. Rate limited to 1 new DSN per 5 minutes per IP address.
 
 ---
 
@@ -380,53 +327,50 @@ advisory at or above the threshold or an apply step fails.
 
 ---
 
-### vg baseline
+### vg init
 
-Create a drift baseline snapshot for delta comparison.
+Initialise Vibgrate in a project.
 
 ```bash
-vg baseline [path]
+vg init [path] [--baseline] [--yes]
 ```
 
-Runs a full scan and saves the result to `.vibgrate/baseline.json`. Use this as the starting point for tracking drift over time.
+| Flag         | Description                                 |
+| ------------ | ------------------------------------------- |
+| `--baseline` | Create an initial drift baseline after init |
+| `--yes`      | Skip confirmation prompts                   |
+
+Creates:
+
+- `.vibgrate/` directory
+- `vibgrate.config.ts` with sensible defaults
 
 ---
 
-### vg report
+### vg login
 
-Generate a human-readable report from a scan artifact.
+Authenticate the CLI with your Vibgrate workspace through the browser. Credentials are stored locally so `vg fix` and `vg push` can reach the hosted planner and Vibgrate Cloud.
 
 ```bash
-vg report [--in <file>] [--format md|text|json]
+vg login
 ```
 
-| Flag       | Default                      | Description                            |
-| ---------- | ---------------------------- | -------------------------------------- |
-| `--in`     | `.vibgrate/scan_result.json` | Input artifact file                    |
-| `--format` | `text`                       | Output format: `md`, `text`, or `json` |
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--region <region>` | `us` | Data-residency region (`us`, `eu`) |
+| `--ingest <url>` | — | Custom ingest API URL (overrides `--region`) |
+| `--no-browser` | — | Print the URL to open instead of launching a browser (headless / SSH) |
 
 ---
 
-### vg sbom
+### vg logout
 
-Export SBOMs from an existing scan artifact or compare two artifacts.
+Clear stored Vibgrate login credentials from this machine.
 
 ```bash
-vg sbom export [--in <file>] [--format cyclonedx|spdx] [--out <file>]
-vg sbom delta --from <file> --to <file> [--out <file>]
-vg sbom vex [--from <file>] [--statement <json>...] [--product <ref>] [--out <file>]
+vg logout
 ```
 
-| Command | Description |
-|---------|-------------|
-| `vg sbom export` | Emit CycloneDX or SPDX JSON from a scan artifact |
-| `vg sbom delta` | Compare dependencies between two artifacts (added/removed/changed + drift delta) |
-| `vg sbom vex` | Emit a spec-compliant OpenVEX document (exploitability statements) for attestation |
-
-Use this to treat SBOMs as operational intelligence instead of static compliance output.
-
-`vg sbom vex` is input-agnostic: it assembles a complete OpenVEX document from the statements you supply (`--from <file>` and/or repeatable `--statement`), so it works regardless of which scanner flagged the components. A zero-statement document is valid and honest — it asserts no known affected components.
-
 ---
 
 ### vg push
@@ -448,102 +392,167 @@ Upload is always optional. Best-effort by default — use `--strict` in CI if yo
 
 ---
 
-### vg dsn create
+### vg report
 
-Generate an HMAC-signed DSN token for API authentication.
+Generate a human-readable report from a scan artifact.
 
 ```bash
-vg dsn create --workspace <id|new> [--region <region>] [--ingest <url>] [--write <path>]
+vg report [--in <file>] [--format md|text|json]
 ```
 
-| Flag          | Default    | Description                                                                 |
-| ------------- | ---------- | --------------------------------------------------------------------------- |
-| `--workspace` | _required_ | Your workspace ID, or `new` to auto-generate a workspace                    |
-| `--region`    | `us`       | Data residency region (`us`, `eu`)                                          |
-| `--ingest`    | —          | Custom ingest API URL (overrides `--region`)                                |
-| `--write`     | —          | Write DSN to a file (add to `.gitignore`!)                                  |
-
-When using `--workspace new`, the CLI auto-generates a workspace ID and provisions the DSN
-with the Vibgrate API. Rate limited to 1 new DSN per 5 minutes per IP address.
+| Flag       | Default                      | Description                            |
+| ---------- | ---------------------------- | -------------------------------------- |
+| `--in`     | `.vibgrate/scan_result.json` | Input artifact file                    |
+| `--format` | `text`                       | Output format: `md`, `text`, or `json` |
 
 ---
 
-### vg update
+### vg sbom
 
-Check for and install updates.
+Export SBOMs from an existing scan artifact or compare two artifacts.
 
 ```bash
-vg update [--check] [--pm <manager>]
+vg sbom export [--in <file>] [--format cyclonedx|spdx] [--out <file>]
+vg sbom delta --from <file> --to <file> [--out <file>]
+vg sbom vex [--from <file>] [--statement <json>...] [--product <ref>] [--out <file>]
 ```
 
-| Flag      | Description                                            |
-| --------- | ------------------------------------------------------ |
-| `--check` | Only check for updates, don't install                  |
-| `--pm`    | Force a package manager (`npm`, `pnpm`, `yarn`, `bun`) |
-
----
-
----
-
-## Code Graph Commands
-
-Vibgrate includes a full code graph engine — call trees, impact surfaces, semantic search, and AI Context serving. All graph commands read from (or write to) a local graph artifact at `.vibgrate/graph.json`. Build the map once with `vg build`, then query it offline indefinitely.
+| Command | Description |
+|---------|-------------|
+| `vg sbom export` | Emit CycloneDX or SPDX JSON from a scan artifact |
+| `vg sbom delta` | Compare dependencies between two artifacts (added/removed/changed + drift delta) |
+| `vg sbom vex` | Emit a spec-compliant OpenVEX document (exploitability statements) for attestation |
 
-**Global options available on every graph command:**
+Use this to treat SBOMs as operational intelligence instead of static compliance output.
 
-| Flag | Description |
-|------|-------------|
-| `--cwd <dir>` | Working directory (default: current) |
-| `--graph <file>` | Path to graph file (default: `.vibgrate/graph.json`) |
-| `--json` | Machine-readable JSON output |
-| `--quiet` | Suppress non-error output |
-| `--local` | Offline mode — no network calls or downloads |
-| `--deep` | Enable deep derivation (for `vg facts`, `vg build`) |
-| `--no-cache` | Skip and clear cached data |
+`vg sbom vex` is input-agnostic: it assembles a complete OpenVEX document from the statements you supply (`--from <file>` and/or repeatable `--statement`), so it works regardless of which scanner flagged the components. A zero-statement document is valid and honest — it asserts no known affected components.
 
 ---
 
-### vg build
+### vg scan
 
-Build or update the code map incrementally.
+The primary command. Scans your project for upgrade drift.
 
 ```bash
-vg build [paths...]
+vg scan [path] [--vulns] [--full] [--format text|json|sarif|md] [--out <file>] [--fail-on warn|error] [--offline] [--package-manifest <file>] [--no-local-artifacts] [--max-privacy] [--baseline <file>] [--drift-budget <score>] [--drift-worsening <percent>] [--changed-only] [--concurrency <n>]
 ```
 
-Maps source code into a graph artifact, enabling all downstream queries (`vg show`, `vg ask`, `vg impact`, etc.).
-
 | Flag | Default | Description |
 |------|---------|-------------|
-| `[paths...]` | `.` | Folders or files to map |
-| `--only <langs>` | — | Restrict to languages (e.g. `ts,py,go`) |
-| `--exclude <glob>` | — | Extra ignore glob (repeatable) |
-| `--jobs <n>` | auto | Worker count (`1` = single-threaded) |
-| `--scip <file>` | auto-detect | Ingest a SCIP index for precise resolution |
-| `--no-scip` | — | Ignore any SCIP index |
-| `--no-tsc` | — | Skip the TypeScript resolver (heuristic floor only) |
-| `--no-html` | — | Do not write `graph.html` |
-| `--no-report` | — | Do not write `GRAPH_REPORT.md` |
-| `--no-warm` | — | Do not warm the semantic index after building |
-| `--grammars <dir>` | — | Grammar `.wasm` directory for offline/air-gapped use |
-| `-o, --export <file>` | — | Also write the map to a file (format from extension) |
+| `--vulns` | — | Also detect known vulnerabilities (OSV online; offline via `--package-manifest` advisories) |
+| `--full` | — | Comprehensive scan: enables `--vulns` and reports banned dependencies when a standards policy exists |
+| `--format` | `text` | Output format: `text`, `json`, `sarif`, or `md` |
+| `--out <file>` | — | Write output to a file |
+| `--fail-on <level>` | — | Exit with code 2 if findings at this level exist |
+| `--baseline <file>` | — | Compare against a previous baseline |
+| `--changed-only` | — | Only scan changed files |
+| `--concurrency <n>` | `8` | Max concurrent npm registry calls |
+| `--drift-budget <score>` | — | Fitness gate: fail if drift score is above this budget |
+| `--drift-worsening <percent>` | — | Fitness gate: fail if drift worsens by more than % vs baseline |
+| `--push` | — | Upload scan artifact to Vibgrate Cloud after a successful scan |
+| `--dsn <dsn>` | `VIBGRATE_DSN` env | DSN used for `--push` authentication |
+| `--region <region>` | — | Override data residency (`us`, `eu`) during push |
+| `--strict` | — | Fail scan command if push fails |
+| `--ui-purpose` | — | Enable optional UI-purpose evidence extraction |
+| `--offline` | — | Disable network calls and disable upload/push behavior |
+| `--package-manifest <file>` | — | JSON or ZIP package-version manifest used for offline/latest lookups (latest bundle: `https://github.com/vibgrate/manifests/latest-packages.zip`) |
+| `--no-local-artifacts` | — | Do not write `.vibgrate/*.json` scan artifacts to disk |
+| `--max-privacy` | — | Hardened privacy mode with minimal scanners and no local artifacts |
+
+By default, the scan writes `.vibgrate/scan_result.json`. Use `--no-local-artifacts` or `--max-privacy` to suppress local JSON artifact files.
+
+For offline drift scoring, pass `--package-manifest <file>` with a downloaded manifest bundle such as `https://github.com/vibgrate/manifests/latest-packages.zip`.
+
+Examples:
+
+```bash
+# Standard text scan
+vg scan
+
+# JSON output for automation
+vg scan --format json --out scan.json
+
+# CI gate with baseline regression protection
+vg scan --baseline .vibgrate/baseline.json --drift-budget 40 --drift-worsening 5 --fail-on error
+
+# Upload result in the same command
+vg scan --push --strict
+```
+
+Expected results:
+
+- Clear score/risk output in terminal (or JSON/SARIF when selected).
+- Exit code `2` when configured quality gates are exceeded.
+- When `--push` is enabled, artifact upload is attempted after scan completion.
 
 ---
 
-### vg show
+### Vulnerabilities and exposure attribution
 
-Explain a single node: what it is, what it calls, what calls it.
+`vg scan --vulns` matches your installed dependencies against the public OSV database and records each known vulnerability — advisory id and CVE, severity, CVSS, and the fixing version — in the scan artifact, as findings, and in SARIF. Supply advisories in a `--package-manifest` bundle to run it offline.
+
+In a git repository the scan also attributes each finding: the commit, author, and date that introduced the vulnerable version, and how long you have been exposed. These exposure windows aggregate into remediation metrics framed around the EU Cyber Resilience Act (CRA): open counts by severity, mean and maximum time exposed, and per-severity SLA breaches (defaults: critical 7 days, high 30, moderate 90, low 180). The metrics are descriptive — they show whether remediation keeps pace; they are not a compliance certification.
+
+The scan also reconstructs **closed** exposure windows from history — a vulnerable version that was later bumped out of the affected range or removed from the lockfile entirely — and reports real remediation time (MTTR) from them: measured, not estimated. Offline, a package-version manifest extends this to advisories that are fully fixed today, so a dependency that is clean now but was once vulnerable still counts toward your remediation record.
+
+Detection and attribution read each project's lockfile, so they cover npm / pnpm / yarn, pip / poetry / pipenv, cargo, composer, bundler, go, pub, hex, NuGet, and Maven/Gradle.
 
 ```bash
-vg show <name>
+# Online detection against OSV
+vg scan --vulns
+
+# Air-gapped: advisories supplied in the manifest bundle
+vg scan --vulns --offline --package-manifest ./package-versions.zip
+
+# Everything in one run: drift + vulnerabilities + a banned-dependency report
+vg scan --full
 ```
 
+---
+
+### vg update
+
+Check for and install updates.
+
+```bash
+vg update [--check] [--pm <manager>]
+```
+
+| Flag      | Description                                            |
+| --------- | ------------------------------------------------------ |
+| `--check` | Only check for updates, don't install                  |
+| `--pm`    | Force a package manager (`npm`, `pnpm`, `yarn`, `bun`) |
+
+---
+
+### vg why
+
+Explain a dependency from git history: who added it, every version since, and any open vulnerabilities it carries.
+
+```bash
+vg why <package>
+```
+
+`vg why` reads your lockfile's history, so it works across npm / pnpm / yarn, pip / poetry, cargo, composer, bundler, go, pub, hex, NuGet, and Maven/Gradle projects. For Maven/Gradle the history comes from a resolved `gradle.lockfile`, or a `pom.xml`'s pinned direct-dependency versions (versions managed by a BOM/`dependencyManagement` aren't resolved). Open vulnerabilities and their introduction attribution come from your most recent `vg scan --vulns`.
+
+---
+
+## Code Graph Commands
+
+Vibgrate includes a full code graph engine — call trees, impact surfaces, semantic search, and AI Context serving. All graph commands read from (or write to) a local graph artifact at `.vibgrate/graph.json`. Build the map once with `vg build`, then query it offline indefinitely.
+
+**Global options available on every graph command:**
+
 | Flag | Description |
 |------|-------------|
-| `<name>` | Qualified name, short name, `file:line`, glob, or id |
-| `--pick <n>` | Pick the nth candidate when ambiguous |
-
-Outputs the qualified name, kind, file location, signature, importance score, area, extends relationships, callees, and callers.
+| `--cwd <dir>` | Working directory (default: current) |
+| `--graph <file>` | Path to graph file (default: `.vibgrate/graph.json`) |
+| `--json` | Machine-readable JSON output |
+| `--quiet` | Suppress non-error output |
+| `--local` | Offline mode — no network calls or downloads |
+| `--client <name>` | Identify the AI client (e.g. `claude`) so navigation calls are counted in `vg savings` |
+| `--deep` | Enable deep derivation (for `vg facts`, `vg build`) |
+| `--no-cache` | Skip and clear cached data |
 
 ---
 
@@ -557,6 +566,8 @@ vg ask "<question>"
 
 A local ONNX embedding model is downloaded once on first use, then cached and fully offline. Degrades gracefully to lexical-only under `--local` or `--no-semantic`.
 
+> **Semantic search is opt-in.** The embedding backend (`fastembed`, which pulls a native ONNX runtime) is declared as an **optional dependency**: package managers install it by default, but if it's absent — e.g. you installed with `--omit=optional`, or it failed to build on your platform — `vg ask` and `vg embed` transparently fall back to lexical + structural search. Nothing else in the CLI needs it, so `vg build`, `vg show`, `vg impact`, drift reporting, and MCP serving all run without it. If you never use semantic `ask`, you can install lean: `npm i @vibgrate/cli --omit=optional`.
+
 Before answering, `ask` checks whether files changed since the map was last built and, if so, rebuilds it incrementally first (only the changed files re-parse) — so answers always reflect the code as it is now. The check is stat-based and costs almost nothing when nothing changed; `--no-refresh` opts out.
 
 | Flag | Default | Description |
@@ -568,6 +579,139 @@ Before answering, `ask` checks whether files changed since the map was last buil
 
 ---
 
+### vg benchmark
+
+A reproducible build + memory + token-reduction benchmark for this repository — honest, self-measured estimates you can re-run.
+
+```bash
+vg benchmark
+```
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--budget <n>` | `2000` | Approx token budget used when estimating context savings |
+
+Add `--json` for machine-readable output.
+
+---
+
+### vg build
+
+Build or update the code map incrementally.
+
+```bash
+vg build [paths...]
+```
+
+Maps source code into a graph artifact, enabling all downstream queries (`vg show`, `vg ask`, `vg impact`, etc.).
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `[paths...]` | `.` | Folders or files to map |
+| `--only <langs>` | — | Restrict to languages (e.g. `ts,py,go`) |
+| `--exclude <glob>` | — | Extra ignore glob (repeatable) |
+| `--jobs <n>` | auto | Worker count (`1` = single-threaded) |
+| `--scip <file>` | auto-detect | Ingest a SCIP index for precise resolution |
+| `--no-scip` | — | Ignore any SCIP index |
+| `--no-tsc` | — | Skip the TypeScript resolver (heuristic floor only) |
+| `--no-html` | — | Do not write `graph.html` |
+| `--no-report` | — | Do not write `GRAPH_REPORT.md` |
+| `--no-warm` | — | Do not warm the semantic index after building |
+| `--grammars <dir>` | — | Grammar `.wasm` directory for offline/air-gapped use |
+| `-o, --export <file>` | — | Also write the map to a file (format from extension) |
+
+---
+
+### vg bundle
+
+Build an air-gapped bundle — grammars, the code graph, and the library catalog — for use on a machine with no network.
+
+```bash
+vg bundle
+```
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--offline` | — | Build using only locally-available assets |
+| `-o, --out <dir>` | `vg-bundle` | Output directory for the bundle |
+
+Add `--json` for machine-readable output.
+
+---
+
+### vg embed
+
+Precompute the semantic index so the next `vg ask` is instant.
+
+```bash
+vg embed
+```
+
+Local ONNX model downloaded once into a shared cache (`~/.cache/vibgrate/models`). Per-repo vectors stored in `.vibgrate/cache/`.
+
+| Flag | Description |
+|------|-------------|
+| `--where` | Show where the model is cached and its size |
+| `--clear` | Remove the downloaded model from shared cache |
+
+---
+
+### vg export
+
+Export the code map in various formats.
+
+```bash
+vg export [file]
+```
+
+Format is inferred from the file extension. Use `-` for stdout.
+
+| Extension | Format |
+|-----------|--------|
+| `.json` | JSON |
+| `.ndjson` | Newline-delimited JSON |
+| `.graphml` | GraphML |
+| `.dot` | Graphviz DOT |
+| `.cypher` | Neo4j Cypher |
+| `.md` | Markdown |
+| `.html` | HTML visualization |
+| `.cdx.json` | CycloneDX SBOM / AI-BOM |
+| `.spdx.json` | SPDX |
+
+---
+
+### vg facts
+
+Deterministic open facts for a node (contract, invariant, characterization).
+
+```bash
+vg facts <name>
+```
+
+Epistemic-typed: declared/static → observed/derived. Requires `--deep` for derived facts beyond basic declarations.
+
+| Flag | Description |
+|------|-------------|
+| `<name>` | Node to inspect |
+| `--pick <n>` | Pick the nth candidate when ambiguous |
+
+---
+
+### vg guide
+
+Cited, relevant standards and practices for a node — the free standards pack.
+
+```bash
+vg guide <name>
+```
+
+| Flag | Description |
+|------|-------------|
+| `<name>` | Node to inspect |
+| `--pick <n>` | Pick the nth candidate when ambiguous |
+
+---
+
 ### vg impact
 
 What breaks if you change it — deterministic structural blast radius.
@@ -588,39 +732,58 @@ Reverse reachability with decay confidence. With `--tests`, returns exactly the
 
 ---
 
-### vg path
+### vg install
 
-Show how A connects to B — shortest path in the call graph.
+Add Vibgrate AI Context to your AI assistant(s) — skill, MCP wiring, and advisory nudge.
 
 ```bash
-vg path <a> <b>
+vg install [tools...]
+vg uninstall <tools...>
 ```
 
+Idempotent and repo-local (changes can be committed and shared with your team).
+
+**Supported assistants:** `claude`, `cursor`, `windsurf`, `vscode`, `codex`, `gemini`
+
 | Flag | Description |
 |------|-------------|
-| `<a>` | Source node |
-| `<b>` | Target node |
-| `--pick-a <n>` | Pick the nth candidate for A |
-| `--pick-b <n>` | Pick the nth candidate for B |
+| `[tools...]` | Assistant ids to install for |
+| `--all` | Install for every supported assistant |
+| `--list` | Show the support matrix and exit |
+| `--no-hook` | Skip the advisory nudge |
+
+**`vg uninstall` flags:**
+
+| Flag | Description |
+|------|-------------|
+| `<tools...>` | Assistant ids to remove (required) |
+| `--purge` | Also delete the skill file |
 
 ---
 
-### vg tree
+### vg lib
 
-The call tree rooted at a node.
+Version-correct library docs — from the hosted catalog or local ingestion.
 
 ```bash
-vg tree <name>
+vg lib                  # List the catalog
+vg lib <name>           # Show docs for a library (pinned to your lockfile version)
+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
 ```
 
-Callees by default; `--callers` to invert. Depth-bounded and cycle-safe.
-
 | Flag | Default | Description |
 |------|---------|-------------|
-| `<name>` | — | Root node |
-| `--callers` | — | Show callers instead of callees |
-| `--depth <n>` | `3` | Max depth |
-| `--pick <n>` | — | Pick the nth candidate when ambiguous |
+| `--name <name>` | — | Library name (for `add`) |
+| `--version <v>` | — | Pin the doc version (for `add`/`publish`) |
+| `-b, --budget <n>` | — | Trim docs to ~N tokens |
+| `--readme <path>` | `./README.md` | README path (for `publish`) |
+| `--dts <path>` | — | TypeScript declaration path (for `publish`) |
+| `--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`) |
 
 ---
 
@@ -643,29 +806,50 @@ vg oddities # Surprising cross-area links (architectural smells)
 
 ---
 
-### vg lib
+### vg models
 
-Version-correct library docs — from the hosted catalog or local ingestion.
+The local model fleet — Ollama, LM Studio, and on-disk `gguf` models — discovered entirely offline.
 
 ```bash
-vg lib                  # List the catalog
-vg lib <name>           # Show docs for a library (pinned to your lockfile version)
-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 models
+```
+
+Lists the local inference backends and models Vibgrate can see, so you know what is available without any network calls. Add `--json` for machine-readable output.
+
+---
+
+### vg path
+
+Show how A connects to B — shortest path in the call graph.
+
+```bash
+vg path <a> <b>
 ```
 
+| Flag | Description |
+|------|-------------|
+| `<a>` | Source node |
+| `<b>` | Target node |
+| `--pick-a <n>` | Pick the nth candidate for A |
+| `--pick-b <n>` | Pick the nth candidate for B |
+
+---
+
+### vg savings
+
+A local, privacy-safe report of the tokens and dollars saved by querying the map instead of grepping and reading whole files.
+
+```bash
+vg savings
+```
+
+Reads the counts-only usage ledger recorded when you run `vg serve --savings` (or pass `--client` on CLI navigation calls). Nothing leaves your machine — the figures are estimates.
+
 | Flag | Default | Description |
 |------|---------|-------------|
-| `--name <name>` | — | Library name (for `add`) |
-| `--version <v>` | — | Pin the doc version (for `add`/`publish`) |
-| `-b, --budget <n>` | — | Trim docs to ~N tokens |
-| `--readme <path>` | `./README.md` | README path (for `publish`) |
-| `--dts <path>` | — | TypeScript declaration path (for `publish`) |
-| `--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`) |
+| `--days <n>` | `30` | Reporting window in days |
+
+Add `--json` for machine-readable output.
 
 ---
 
@@ -683,11 +867,16 @@ vg serve
 | `--port <n>` | `7437` | Port for `--http` |
 | `--host <h>` | `127.0.0.1` | Host for `--http` |
 | `--savings` | — | Record local, counts-only usage savings (opt-in) |
+| `--share-stats` | — | Also upload the counts-only usage ledger to Vibgrate to improve the local MCP (opt-in; off by default; implies `--savings`; disabled under `--local`) |
 | `--dedup` | — | Collapse a node's heavy relation lists on repeat reads within a session, to save tokens (opt-in) |
 | `--no-refresh` | — | Serve the map as built; skip the auto-rebuild when files change |
 
 Via stdio (default), your AI assistant spawns the server. Via `--http`, it runs as a local HTTP endpoint for browser or shared access.
 
+**Usage stats — local by default, sharing is opt-in.** `--savings` records a *counts-only* ledger under `.vibgrate/` — per navigation call: which tool, how it resolved (complete/partial/miss), the vg-vs-grep token figures, whether it came over the MCP (`mcp`) or the `vg` CLI (`cli`), and a coarse client label (which AI). `vg savings` reports it locally; nothing leaves your machine. `--share-stats` additionally uploads that same counts-only ledger to Vibgrate periodically, so we can see how the local MCP is used and improve it. It **never** sends code, file paths, question text, repo identity, or any credential — only counts, outcomes, token figures, the vg version, your OS/arch, and a random per-install id. It's off unless you pass the flag, is disabled entirely under `--local`, and the endpoint can be overridden with `VIBGRATE_STATS_ENDPOINT`.
+
+**Attributing CLI calls.** The MCP path detects the calling client automatically from the connection handshake. For CLI calls, pass `--client=<ai>` (e.g. `vg "how does auth work" --client=claude`) so the call is attributed in `vg savings` and any shared stats — this is what `vg install` writes into each assistant's skill. Without `--client`, a bare `vg ask` records nothing.
+
 **The map stays fresh while you (or your AI) edit code.** Each tool call runs a cheap stat-only freshness check against the last build; when files really changed, the server rebuilds the map incrementally in-process — only changed files re-parse — and answers from the updated graph. Probes are debounced with a self-tuning cadence (2s floor, scaling with measured probe cost so probing never exceeds a few percent of serve time even on very large repos), rebuilds are single-flight and cross-process locked, and touch-only changes (a `git checkout`, a re-save with identical content) are recognized by content hash and never trigger a rebuild. There is no filesystem watcher and no daemon: freshness is checked exactly when it matters — at query time. The server also hot-reloads `graph.json` whenever it changes on disk, so an external `vg` build is picked up on the next call too.
 
 The server exposes read-only tools your assistant can call over the code map and dependency data, including:
@@ -702,35 +891,6 @@ All tools are read-only. The server is local-first: it always answers from your
 
 ---
 
-### vg install
-
-Add Vibgrate AI Context to your AI assistant(s) — skill, MCP wiring, and advisory nudge.
-
-```bash
-vg install [tools...]
-vg uninstall <tools...>
-```
-
-Idempotent and repo-local (changes can be committed and shared with your team).
-
-**Supported assistants:** `claude`, `cursor`, `windsurf`, `vscode`, `codex`, `gemini`
-
-| Flag | Description |
-|------|-------------|
-| `[tools...]` | Assistant ids to install for |
-| `--all` | Install for every supported assistant |
-| `--list` | Show the support matrix and exit |
-| `--no-hook` | Skip the advisory nudge |
-
-**`vg uninstall` flags:**
-
-| Flag | Description |
-|------|-------------|
-| `<tools...>` | Assistant ids to remove (required) |
-| `--purge` | Also delete the skill file |
-
----
-
 ### vg share
 
 Make the code map committable and auto-updating for your team.
@@ -748,32 +908,32 @@ Installs a pre-commit hook, deterministic merge driver, and `.gitignore` so the
 
 ---
 
-### vg status
+### vg show
 
-Graph freshness, counts, and staleness — compared against the working tree.
+Explain a single node: what it is, what it calls, what calls it.
 
 ```bash
-vg status
+vg show <name>
 ```
 
-Outputs: map path, generation timestamp, node/edge/area counts, languages, cluster method, resolver rungs used, cache status, and stale file count. When a build has run on this machine, staleness is exact (per-file stat + content hash against the last build's snapshot — edits, adds, and removes); otherwise it falls back to comparing the file set.
+| Flag | Description |
+|------|-------------|
+| `<name>` | Qualified name, short name, `file:line`, glob, or id |
+| `--pick <n>` | Pick the nth candidate when ambiguous |
+
+Outputs the qualified name, kind, file location, signature, importance score, area, extends relationships, callees, and callers.
 
 ---
 
-### vg facts
+### vg status
 
-Deterministic open facts for a node (contract, invariant, characterization).
+Graph freshness, counts, and staleness — compared against the working tree.
 
 ```bash
-vg facts <name>
+vg status
 ```
 
-Epistemic-typed: declared/static → observed/derived. Requires `--deep` for derived facts beyond basic declarations.
-
-| Flag | Description |
-|------|-------------|
-| `<name>` | Node to inspect |
-| `--pick <n>` | Pick the nth candidate when ambiguous |
+Outputs: map path, generation timestamp, node/edge/area counts, languages, cluster method, resolver rungs used, cache status, and stale file count. When a build has run on this machine, staleness is exact (per-file stat + content hash against the last build's snapshot — edits, adds, and removes); otherwise it falls back to comparing the file set.
 
 ---
 
@@ -797,44 +957,40 @@ vg tests <name>
 
 ---
 
-### vg embed
+### vg tree
 
-Precompute the semantic index so the next `vg ask` is instant.
+The call tree rooted at a node.
 
 ```bash
-vg embed
+vg tree <name>
 ```
 
-Local ONNX model downloaded once into a shared cache (`~/.cache/vibgrate/models`). Per-repo vectors stored in `.vibgrate/cache/`.
+Callees by default; `--callers` to invert. Depth-bounded and cycle-safe.
 
-| Flag | Description |
-|------|-------------|
-| `--where` | Show where the model is cached and its size |
-| `--clear` | Remove the downloaded model from shared cache |
+| Flag | Default | Description |
+|------|---------|-------------|
+| `<name>` | — | Root node |
+| `--callers` | — | Show callers instead of callees |
+| `--depth <n>` | `3` | Max depth |
+| `--pick <n>` | — | Pick the nth candidate when ambiguous |
 
 ---
 
-### vg export
+### vg unknowns
 
-Export the code map in various formats.
+What the graph cannot resolve, ranked by blast radius — the unresolved references most worth teaching the map about.
 
 ```bash
-vg export [file]
+vg unknowns
 ```
 
-Format is inferred from the file extension. Use `-` for stdout.
+Surfaces the symbols and imports the resolver could not tie to a definition, ordered by how much depends on them, so you can see where a SCIP index or a targeted `--only` language pass would most improve resolution.
 
-| Extension | Format |
-|-----------|--------|
-| `.json` | JSON |
-| `.ndjson` | Newline-delimited JSON |
-| `.graphml` | GraphML |
-| `.dot` | Graphviz DOT |
-| `.cypher` | Neo4j Cypher |
-| `.md` | Markdown |
-| `.html` | HTML visualization |
-| `.cdx.json` | CycloneDX SBOM / AI-BOM |
-| `.spdx.json` | SPDX |
+| Flag | Default | Description |
+|------|---------|-------------|
+| `-n, --limit <n>` | `20` | How many to show |
+
+Add `--json` for machine-readable output.
 
 ---
 
@@ -1326,7 +1482,7 @@ import type {
 
 ## Requirements
 
-- **Node.js** >= 22.0.0
+- **Node.js** >= 20.0.0
 - Works on macOS, Linux, and Windows
 
 ---