@vibgrate/cli 2026.702.1 → 2026.703.1

package/DOCS.md

@@ -11,14 +11,34 @@ 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)
-  - [vibgrate init](#vibgrate-init)
-  - [vibgrate scan](#vibgrate-scan)
-  - [vibgrate baseline](#vibgrate-baseline)
-  - [vibgrate report](#vibgrate-report)
-  - [vibgrate sbom](#vibgrate-sbom)
-  - [vibgrate push](#vibgrate-push)
-  - [vibgrate dsn create](#vibgrate-dsn-create)
-  - [vibgrate update](#vibgrate-update)
+  - [vg init](#vg-init)
+  - [vg scan](#vg-scan)
+  - [Vulnerabilities and exposure attribution](#vulnerabilities-and-exposure-attribution)
+  - [vg why](#vg-why)
+  - [vg bisect](#vg-bisect)
+  - [vg baseline](#vg-baseline)
+  - [vg report](#vg-report)
+  - [vg sbom](#vg-sbom)
+  - [vg push](#vg-push)
+  - [vg dsn create](#vg-dsn-create)
+  - [vg update](#vg-update)
+- [Code Graph Commands](#code-graph-commands)
+  - [vg build](#vg-build)
+  - [vg show](#vg-show)
+  - [vg ask](#vg-ask)
+  - [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 lib](#vg-lib)
+  - [vg serve](#vg-serve)
+  - [vg install](#vg-install)
+  - [vg share](#vg-share)
+  - [vg status](#vg-status)
+  - [vg facts](#vg-facts)
+  - [vg tests](#vg-tests)
+  - [vg embed](#vg-embed)
+  - [vg export](#vg-export)
 - [Upgrade Drift Score](#upgrade-drift-score)
 - [Drift Baselines & Fitness Functions](#drift-baselines--fitness-functions)
   - [How the Score Is Calculated](#how-the-score-is-calculated)
@@ -44,6 +64,7 @@ For a quick overview, see the [README](./README.md). This document covers everyt
   - [Breaking Change Exposure](#breaking-change-exposure)
   - [File Hotspots](#file-hotspots)
   - [Security Posture](#security-posture)
+  - [Security Scanners](#security-scanners)
   - [Service Dependencies](#service-dependencies)
   - [Architecture Layers](#architecture-layers)
   - [Code Quality Metrics](#code-quality-metrics)
@@ -59,13 +80,12 @@ For a quick overview, see the [README](./README.md). This document covers everyt
 - [Privacy & Security](#privacy--security)
 - [Exit Codes](#exit-codes)
 - [Programmatic API](#programmatic-api)
-- [HCS Extract Runtime Prerequisites](#hcs-extract-runtime-prerequisites)
 
 ---
 
 ## How It Works
 
-Vibgrate recursively scans your repository for `package.json` (Node/TypeScript), `.sln`/`.csproj`/`.vbproj` (.NET), Python manifests, and Java build manifests. For each project it discovers, it:
+Vibgrate recursively scans your repository for `package.json` (Node/TypeScript), `.sln`/`.csproj` (.NET), Python manifests, and Java build manifests. For each project it discovers, it:
 
 1. **Detects** the runtime version, target framework, and all dependencies
 2. **Queries** the npm/NuGet registry for latest stable versions (with built-in caching and concurrency control)
@@ -73,7 +93,7 @@ Vibgrate recursively scans your repository for `package.json` (Node/TypeScript),
 4. **Generates** a deterministic Upgrade Drift Score (0–100)
 5. **Produces** findings, a full JSON artifact, and optional SARIF output
 
-Core drift analysis does not execute source code. Vibgrate Cloud upload remains optional.
+Core drift analysis does not execute source code. Optional security scanners can run lightweight secret heuristics and local toolchain checks. Vibgrate Cloud upload remains optional.
 
 ---
 
@@ -99,13 +119,15 @@ This section summarizes what the CLI supports today and how to use each capabili
 
 ### Supported project ecosystems
 
-Vibgrate currently discovers and evaluates projects in:
+Vibgrate evaluates **upgrade drift** in depth for:
 
 - **Node.js / TypeScript** (`package.json`, lockfiles)
-- **.NET** (`.sln`, `.csproj`, `.vbproj`)
+- **.NET** (`.sln`, `.csproj`)
 - **Python** (`requirements.txt`, `pyproject.toml`-style manifests)
 - **Java** (`pom.xml`, Gradle-style manifests)
 
+**Known-vulnerability detection** (`--vulns`) and **dependency attribution** (`vg why`, exposure windows) additionally cover npm / pnpm / yarn, pip / poetry / pipenv, cargo, composer, bundler, go, pub, hex, NuGet, and Maven/Gradle — read from each project's lockfile.
+
 ### End-to-end workflow (recommended)
 
 1. Run an initial scan.
@@ -117,16 +139,16 @@ Example:
 
 ```bash
 # Step 1: first scan
-vibgrate scan
+vg scan
 
 # Step 2: baseline
-vibgrate baseline
+vg baseline
 
 # Step 3: policy in CI
-vibgrate scan --baseline .vibgrate/baseline.json --drift-budget 40 --drift-worsening 5 --fail-on error
+vg scan --baseline .vibgrate/baseline.json --drift-budget 40 --drift-worsening 5 --fail-on error
 
 # Step 4: produce report
-vibgrate report --in .vibgrate/scan_result.json --format md
+vg report --in .vibgrate/scan_result.json --format md
 ```
 
 Expected results:
@@ -137,12 +159,12 @@ Expected results:
 
 ## Commands Reference
 
-### vibgrate init
+### vg init
 
 Initialise Vibgrate in a project.
 
 ```bash
-vibgrate init [path] [--baseline] [--yes]
+vg init [path] [--baseline] [--yes]
 ```
 
 | Flag         | Description                                 |
@@ -157,22 +179,23 @@ Creates:
 
 ---
 
-### vibgrate scan
+### vg scan
 
 The primary command. Scans your project for upgrade drift.
 
 ```bash
-vibgrate scan [path] [--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] [--exclude <glob>...] [--concurrency <n>]
+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>]
 ```
 
 | 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 |
-| `-e, --exclude <glob>` | — | Exclude paths matching a glob pattern. Repeatable, and a single value may list several patterns separated by commas or semicolons. Merged with `exclude` from the config file |
 | `--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 |
@@ -185,101 +208,110 @@ vibgrate scan [path] [--format text|json|sarif|md] [--out <file>] [--fail-on war
 | `--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 |
-| `--emit-facts` | — | Emit the schema-validated HCS fact payload (an in-toto attestation predicate) to stdout instead of a scan report. Runs offline and writes nothing to the scanned tree |
 
 By default, the scan writes `.vibgrate/scan_result.json`. Use `--no-local-artifacts` or `--max-privacy` to suppress local JSON artifact files.
 
-#### Emitting a fact payload for attestation (`--emit-facts`)
+For offline drift scoring, pass `--package-manifest <file>` with a downloaded manifest bundle such as `https://github.com/vibgrate/manifests/latest-packages.zip`.
 
-`--emit-facts` turns a scan into machine-readable evidence: it runs offline,
-writes only a single JSON document to stdout (no source code — drift facts and
-counts), and is deterministic for a given commit so re-runs are byte-stable. The
-document is the predicate body for the `https://vibgrate.com/attestations/hcs/v0.5`
-in-toto attestation, ready to bind to a published artifact:
+Examples:
 
 ```bash
-vibgrate scan --emit-facts > vibgrate-facts.json
-cosign attest --yes \
-  --type https://vibgrate.com/attestations/hcs/v0.5 \
-  --predicate vibgrate-facts.json "$IMAGE_REF"
+# 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
 ```
 
-See [`docs/SIGNING-AND-PROVENANCE.md`](../../docs/SIGNING-AND-PROVENANCE.md) for the
-full signing & provenance pipeline.
+Expected results:
 
-For offline drift scoring, pass `--package-manifest <file>` with a downloaded manifest bundle such as `https://github.com/vibgrate/manifests/latest-packages.zip`.
+- 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.
+
+---
 
-#### Excluding paths from a scan
+### Vulnerabilities and exposure attribution
 
-Use `--exclude` (alias `-e`) to skip directories or files from the scan. Values are [glob patterns](#exclude-glob-syntax) matched against repository-relative, forward-slash paths. The flag is **repeatable**, and a single value may carry **several patterns separated by commas or semicolons** — use whichever reads best:
+`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
-# Repeat the flag
-vibgrate scan --exclude "legacy/**" --exclude "vendor/**"
+# Online detection against OSV
+vg scan --vulns
 
-# Or list multiple patterns in one flag (comma- or semicolon-separated)
-vibgrate scan --exclude "legacy/**,vendor/**;**/fixtures/**"
-```
+# Air-gapped: advisories supplied in the manifest bundle
+vg scan --vulns --offline --package-manifest ./package-versions.zip
 
-CLI excludes are **additive**: they are merged (and de-duplicated) with any `exclude` patterns from your [config file](#configuration), so command-line excludes never replace your committed defaults.
+# Everything in one run: drift + vulnerabilities + a banned-dependency report
+vg scan --full
+```
 
-<a id="exclude-glob-syntax"></a>
-Supported glob syntax:
+---
 
-| Pattern | Matches |
-|---------|---------|
-| `*` | Any run of characters within a single path segment (no `/`) |
-| `**` | Any number of path segments, including `/` (recursive) |
-| `?` | Exactly one non-separator character |
-| `{a,b}` | Alternation — either `a` or `b` |
-| `[abc]` | A single character from the set |
-| `legacy` | A bare name is treated as a directory prefix — equivalent to `legacy/**` |
+### vg why
 
-Examples:
+Explain a dependency from git history: who added it, every version since, and any open vulnerabilities it carries.
 
 ```bash
-# Standard text scan
-vibgrate scan
+vg why <package>
+```
 
-# JSON output for automation
-vibgrate scan --format json --out scan.json
+`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`.
 
-# Skip vendored and generated code
-vibgrate scan --exclude "vendor/**,**/*.generated.ts;dist/**"
+---
 
-# CI gate with baseline regression protection
-vibgrate scan --baseline .vibgrate/baseline.json --drift-budget 40 --drift-worsening 5 --fail-on error
+### vg bisect
 
-# Upload result in the same command
-vibgrate scan --push --strict
+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 bisect <package> <constraint>
 ```
 
-Expected results:
+`<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.
 
-- 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.
+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
+```
+
+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.
 
 ---
 
-### vibgrate baseline
+### vg baseline
 
 Create a drift baseline snapshot for delta comparison.
 
 ```bash
-vibgrate baseline [path]
+vg baseline [path]
 ```
 
 Runs a full scan and saves the result to `.vibgrate/baseline.json`. Use this as the starting point for tracking drift over time.
 
 ---
 
-### vibgrate report
+### vg report
 
 Generate a human-readable report from a scan artifact.
 
 ```bash
-vibgrate report [--in <file>] [--format md|text|json]
+vg report [--in <file>] [--format md|text|json]
 ```
 
 | Flag       | Default                      | Description                            |
@@ -289,62 +321,34 @@ vibgrate report [--in <file>] [--format md|text|json]
 
 ---
 
-### vibgrate sbom
+### vg sbom
 
 Export SBOMs from an existing scan artifact or compare two artifacts.
 
-The `sbom` command family covers supply-chain evidence — SBOM export/delta and
-OpenVEX generation.
-
 ```bash
-vibgrate sbom export [--in <file>] [--format cyclonedx|spdx] [--out <file>]
-vibgrate sbom delta --from <file> --to <file> [--out <file>]
-vibgrate sbom vex [--from <file>] [--statement <json>...] [--product <ref>] [--out <file>]
+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>]
 ```
 
 | Command | Description |
 |---------|-------------|
-| `vibgrate sbom export` | Emit CycloneDX or SPDX JSON from a scan artifact |
-| `vibgrate sbom delta` | Compare dependencies between two artifacts (added/removed/changed + drift delta) |
-| `vibgrate sbom vex` | Emit a spec-compliant OpenVEX document (exploitability statements) |
+| `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.
 
-#### vibgrate sbom vex
-
-Generate a spec-compliant **OpenVEX** document (exploitability statements) for
-attestation, consistent with the rest of the `sbom` family. The generator is
-input-agnostic — it assembles a complete document from statements you supply, so
-it works regardless of which scanner flagged the components. A zero-statement
-document is valid and honest: it asserts no known affected components.
-
-| Flag | Description |
-|------|-------------|
-| `--from <file>` | Read statements from a JSON file (an array, or an object with a `statements` array) |
-| `--statement <json>` | Add a statement as inline JSON. Repeatable |
-| `--product <ref>` | Default product applied to statements without their own (e.g. an image digest) |
-| `--author <name>` | Document author (default `Vibgrate`) |
-| `--timestamp <iso>` / `--id <uri>` | Pin for reproducible output |
-| `--out <file>` | Write to a file (default: stdout) |
-
-```bash
-# Attest exploitability alongside the image
-vibgrate sbom vex --product "$IMAGE_REF" \
-  --statement '{"vulnerability":"CVE-2024-1","status":"not_affected","justification":"vulnerable_code_not_present"}' \
-  > openvex.json
-cosign attest --yes --type openvex --predicate openvex.json "$IMAGE_REF"
-```
-
-See [`docs/SIGNING-AND-PROVENANCE.md`](../../docs/SIGNING-AND-PROVENANCE.md).
+`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.
 
 ---
 
-### vibgrate push
+### vg push
 
 Upload scan results to the Vibgrate Cloud API.
 
 ```bash
-vibgrate push [--dsn <dsn>] [--file <file>] [--region <region>] [--strict]
+vg push [--dsn <dsn>] [--file <file>] [--region <region>] [--strict]
 ```
 
 | Flag       | Default                      | Description                                 |
@@ -358,12 +362,12 @@ Upload is always optional. Best-effort by default — use `--strict` in CI if yo
 
 ---
 
-### vibgrate dsn create
+### vg dsn create
 
 Generate an HMAC-signed DSN token for API authentication.
 
 ```bash
-vibgrate dsn create --workspace <id|new> [--region <region>] [--ingest <url>] [--write <path>]
+vg dsn create --workspace <id|new> [--region <region>] [--ingest <url>] [--write <path>]
 ```
 
 | Flag          | Default    | Description                                                                 |
@@ -378,12 +382,12 @@ with the Vibgrate API. Rate limited to 1 new DSN per 5 minutes per IP address.
 
 ---
 
-### vibgrate update
+### vg update
 
 Check for and install updates.
 
 ```bash
-vibgrate update [--check] [--pm <manager>]
+vg update [--check] [--pm <manager>]
 ```
 
 | Flag      | Description                                            |
@@ -393,27 +397,382 @@ vibgrate update [--check] [--pm <manager>]
 
 ---
 
+---
+
+## 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 |
+|------|-------------|
+| `--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 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 show
+
+Explain a single node: what it is, what it calls, what calls it.
+
+```bash
+vg show <name>
+```
+
+| 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 ask
+
+Ask the code map a question using hybrid lexical + structural + semantic search.
+
+```bash
+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`.
+
+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 |
+|------|---------|-------------|
+| `<question...>` | — | Your question |
+| `-b, --budget <n>` | `2000` | Approx token budget for returned context |
+| `--no-semantic` | — | Lexical only; skip the local embedding pass |
+| `--no-refresh` | — | Answer from the map as built; skip the auto-rebuild when files changed |
+
+---
+
+### vg impact
+
+What breaks if you change it — deterministic structural blast radius.
+
+```bash
+vg impact <name>
+```
+
+Reverse reachability with decay confidence. With `--tests`, returns exactly the tests to run before shipping.
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `<name>` | — | Node to assess |
+| `--depth <n>` | `4` | Max traversal depth |
+| `--tests` | — | Also surface the tests covering the affected set |
+| `--fail-on-untested` | — | Exit 2 if any affected node is untested (CI gate) |
+| `--pick <n>` | — | Pick the nth candidate when ambiguous |
+
+---
+
+### 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 tree
+
+The call tree rooted at a node.
+
+```bash
+vg tree <name>
+```
+
+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 |
+
+---
+
+### vg map / vg hubs / vg areas / vg oddities
+
+Map-level insights — read-only views over the committed graph.
+
+```bash
+vg map      # Overview: areas, hubs, untested hotspots
+vg hubs     # Most-depended-on code (centrality outliers)
+vg areas    # Natural groupings (communities), each labelled and sized
+vg oddities # Surprising cross-area links (architectural smells)
+```
+
+| Command | Flag | Default | Description |
+|---------|------|---------|-------------|
+| `vg hubs` | `-n, --limit <n>` | `20` | How many hubs to show |
+| `vg areas` | `-n, --limit <n>` | `30` | How many areas to show |
+| `vg oddities` | `-n, --limit <n>` | `20` | How many oddities to show |
+
+---
+
+### vg lib
+
+Version-correct library docs — from the hosted catalog or local ingestion.
+
+```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
+```
+
+| 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`) |
+
+---
+
+### vg serve
+
+Start Vibgrate AI Context — a local-first MCP serving your code map, drift, and version-correct docs to your AI assistant (fully offline under `--local`).
+
+```bash
+vg serve
+```
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--http` | — | Serve over streamable HTTP instead of stdio |
+| `--port <n>` | `7437` | Port for `--http` |
+| `--host <h>` | `127.0.0.1` | Host for `--http` |
+| `--savings` | — | Record local, counts-only usage savings (opt-in) |
+| `--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.
+
+**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:
+
+- `query_graph`, `get_node`, `find_path`, `impact_of`, `tests_for` — navigate and reason about the code map.
+- `check_drift` — offline dependency inventory; pass `attribute: true` to add git "who added this / who set the version" attribution.
+- `list_vulnerabilities`, `vuln_attribution` — known vulnerabilities and their exposure attribution from the last `vg scan --vulns`.
+- `upgrade_impact` — what an upgrade will cost: version distance, how many files import the package, the vulnerabilities it fixes, and — with `changelog: true` — online breaking-change notes between your version and the latest.
+- `resolve_library`, `library_docs` — version-correct, drift-annotated library docs.
+
+All tools are read-only. The server is local-first: it always answers from your machine when it can, and its only network touches are the embedder's one-time model fetch, `upgrade_impact`'s `changelog`, and `library_docs`' fall-through to the hosted catalog when the local docs for a library are thin or missing. `--local` is the hard airgap — it disables all three.
+
+---
+
+### 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.
+
+```bash
+vg share
+```
+
+Installs a pre-commit hook, deterministic merge driver, and `.gitignore` so the map stays fresh without any manual steps.
+
+| Flag | Description |
+|------|-------------|
+| `--undo` | Reverse what `vg share` installed |
+| `--reports` | Also commit `graph.html` / `GRAPH_REPORT.md` (default: gitignored) |
+
+---
+
+### vg status
+
+Graph freshness, counts, and staleness — compared against the working tree.
+
+```bash
+vg status
+```
+
+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.
+
+---
+
+### 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 tests
+
+Which tests cover a node (call/coverage linkage).
+
+```bash
+vg tests <name>
+```
+
+`--missing` flips to show untested nodes nearby. `--run` prints (or `--exec` runs) the minimal command to exercise exactly those tests.
+
+| Flag | Description |
+|------|-------------|
+| `<name>` | Node to inspect |
+| `--missing` | Show untested nodes nearby instead |
+| `--run` | Print the command to run exactly these tests |
+| `--exec` | Run that command |
+| `--pick <n>` | Pick the nth candidate when ambiguous |
+
+---
+
+### 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 |
+
+---
+
 ## Drift Baselines & Fitness Functions
 
 Vibgrate stores scan state under `.vibgrate/`:
 
 - `.vibgrate/scan_result.json`: latest scan artifact
-- `.vibgrate/baseline.json`: explicit baseline snapshot (`vibgrate baseline`)
+- `.vibgrate/baseline.json`: explicit baseline snapshot (`vg baseline`)
 - `<project>/.vibgrate/project_score.json`: per-project score snapshots
 
 Recommended workflow:
 
 1. Create baseline once on main branch:
    ```bash
-   vibgrate baseline
+   vg baseline
    ```
 2. In CI, run scan with comparison and gates:
    ```bash
-   vibgrate scan --baseline .vibgrate/baseline.json --drift-budget 40 --drift-worsening 5
+   vg scan --baseline .vibgrate/baseline.json --drift-budget 40 --drift-worsening 5
    ```
 3. When planned upgrades land, refresh baseline:
    ```bash
-   vibgrate baseline
+   vg baseline
    ```
 
 This makes drift a formal quality gate (fitness function), not just reporting.
@@ -476,7 +835,7 @@ A clean Markdown report suitable for PRs, wikis, or documentation.
 
 ### vibgrate.config.ts
 
-Run `vibgrate init` to generate the config file, or create one manually:
+Run `vg init` to generate the config file, or create one manually:
 
 ```typescript
 import type { VibgrateConfig } from "@vibgrate/cli";
@@ -514,18 +873,6 @@ export default config;
 
 Also supports `vibgrate.config.js` and `vibgrate.config.json`.
 
-### Exclude patterns
-
-`exclude` accepts an array of glob patterns describing paths the scan should skip (relative to the repository root, forward-slash separated). See [exclude glob syntax](#exclude-glob-syntax) for the supported patterns.
-
-```typescript
-const config: VibgrateConfig = {
-  exclude: ["legacy/**", "vendor/**", "**/*.generated.ts"],
-};
-```
-
-The same patterns can be supplied per-run on the command line with [`--exclude`](#excluding-paths-from-a-scan). CLI excludes are merged with (not a replacement for) the config `exclude` list, so committed defaults always apply and ad-hoc excludes are additive.
-
 ### Thresholds
 
 Control when findings are raised and when the CLI should fail.
@@ -589,12 +936,12 @@ Vibgrate artifacts include dependency graph and package inventory data that can
 - Phantom dependency evidence (`phantomDependencies` + details)
 - Inventory metadata that pairs well with internal SBOM pipelines
 
-Vibgrate supports both direct SBOM export (`vibgrate sbom export`) and raw inventory consumption from `scan_result.json`, so teams can choose either built-in output or custom SBOM pipelines.
+Vibgrate supports both direct SBOM export (`vg sbom export`) and raw inventory consumption from `scan_result.json`, so teams can choose either built-in output or custom SBOM pipelines.
 
 Example:
 
 ```bash
-vibgrate sbom export --in .vibgrate/scan_result.json --format spdx --out sbom.spdx.json
+vg sbom export --in .vibgrate/scan_result.json --format spdx --out sbom.spdx.json
 ```
 
 Expected result:
@@ -662,6 +1009,17 @@ Structural security hygiene indicators (not a secret scanner):
 - `.env` files tracked outside `.gitignore`
 - Audit severity counts (via `npm audit --json`)
 
+### Security Scanners
+
+Security scanner orchestration and readiness analysis for local policy and secret-scanning workflows:
+
+- Scanner engine discovery (installed vs missing)
+- Version freshness checks to flag stale scanner engines/signatures
+- Local config discovery for scanner policy files
+- Cache-backed heuristic secret signals to add value even when binaries are unavailable
+
+> This scanner does not guarantee full secret detection or rule coverage by itself; it reports toolchain status and lightweight in-repo indicators so teams can decide how to harden CI enforcement.
+
 ### Service Dependencies
 
 Maps external service and platform dependencies by detecting SDK packages:
@@ -694,6 +1052,15 @@ Fast AST-based quality checks to identify upgrade friction hotspots:
 - Circular dependencies and dead-code estimate
 - "God file" detection for oversized high-complexity modules
 
+### OWASP Category Mapping
+
+Maps security findings into OWASP Top 10 categories for security triage inside existing drift reports:
+
+- Supports `fast` and `cache-input` modes
+- Categorizes findings with severity and CWE metadata
+- Emits per-category counts in JSON output
+- Designed for CI visibility without requiring a separate report format
+
 ---
 
 ## CI Integration
@@ -704,6 +1071,7 @@ Use the maintained templates in this package for copy-paste setup:
 
 - `examples/github-actions/driftscore-ci.yml` (JSON artifact + drift gate)
 - `examples/github-actions/driftscore-sarif.yml` (SARIF upload to code scanning)
+- `examples/github-actions/vulnerabilities-sarif.yml` (vulnerability gate + SARIF upload)
 - `docs/ci/github-actions.md` (integration notes)
 
 ```yaml
@@ -723,6 +1091,23 @@ steps:
     run: npx @vibgrate/cli push --file .vibgrate/scan_result.json
 ```
 
+To gate pull requests on **known vulnerabilities** and surface them in the
+Security tab, the maintained `vibgrate/cli` Action does the scan, gate, and SARIF
+upload in one step (needs `permissions: security-events: write`):
+
+```yaml
+steps:
+  - uses: actions/checkout@v4
+    with:
+      fetch-depth: 0          # full history → exposure attribution + remediation MTTR
+  - uses: vibgrate/cli@v1
+    with:
+      vulns: true
+      fail-on: error          # critical/high block the merge
+      upload-sarif: true
+      category: vibgrate-vulns
+```
+
 ### Azure DevOps
 
 ```yaml
@@ -798,7 +1183,7 @@ Vibgrate is built with a privacy-first architecture. Here's what it **never** do
 
 What it **does** collect:
 
-- Package names and version numbers (from `package.json`, `.csproj`/`.vbproj`, lockfiles)
+- Package names and version numbers (from `package.json`, `.csproj`, lockfiles)
 - Config structure flags (e.g. `strict: true` from `tsconfig.json`)
 - File names and sizes (paths and metadata, never contents)
 - Public npm/NuGet registry metadata (latest versions, deprecation flags)
@@ -833,7 +1218,7 @@ import type {
 
 ## Requirements
 
-- **Node.js** >= 20.0.0
+- **Node.js** >= 22.0.0
 - Works on macOS, Linux, and Windows
 
 ---
@@ -846,13 +1231,3 @@ import type {
 ---
 
 Copyright © 2026 Vibgrate. All rights reserved. See [LICENSE](https://vibgrate.com/license) for terms.
-
-## HCS Extract Runtime Prerequisites
-
-When using `vibgrate extract`, language workers run as subprocesses.
-
-- Swift currently uses the Node worker (text extraction), so no Swift/Xcode install is required for HCS extract at this time.
-- Go/Python/Java/.NET may require local runtimes (`go`, `python3`, `java`, `dotnet`) when platform-native workers are not bundled.
-- The CLI now emits install hints when these commands are missing on PATH.
-
-For OS-specific setup and packaging strategy, see [`HCS-RUNTIME-SETUP.md`](./HCS-RUNTIME-SETUP.md).