@vibgrate/cli 2026.702.2 → 2026.703.3

package/README.md

@@ -1,290 +1,185 @@
+<p align="center">
+  <a href="https://vibgrate.com"><img src="https://vibgrate.com/img/vibgrate-logo-512.png" alt="Vibgrate" width="96" height="96" /></a>
+</p>
+
 <p align="center">
   <strong>@vibgrate/cli</strong>
   <br />
-  Continuous Upgrade Drift Intelligence for engineering teams
+  Local codebase intelligence for AI coding agents — graph, drift, and version-correct docs on your machine
 </p>
 
 <p align="center">
   <a href="https://www.npmjs.com/package/@vibgrate/cli"><img src="https://img.shields.io/npm/v/@vibgrate/cli?color=blue&label=npm" alt="npm version" /></a>
   <a href="https://www.npmjs.com/package/@vibgrate/cli"><img src="https://img.shields.io/npm/dm/@vibgrate/cli?color=green" alt="npm downloads" /></a>
-  <a href="https://vibgrate.com"><img src="https://img.shields.io/badge/website-vibgrate.com-blue" alt="website" /></a>
-  <img src="https://img.shields.io/node/v/@vibgrate/cli" alt="node version" />
+  <a href="https://vibgrate.com/cli"><img src="https://img.shields.io/badge/live%20demo-vibgrate.com%2Fcli-3FB0A4" alt="live demo" /></a>
+  <a href="https://vibgrate.com/mcp"><img src="https://img.shields.io/badge/Vibgrate%20MCP%20(hosted)-vibgrate.com%2Fmcp-8B5CF6" alt="Vibgrate MCP (hosted)" /></a>
+  <a href="./LICENSE"><img src="https://img.shields.io/badge/license-Apache%202.0-blue" alt="Apache 2.0" /></a>
+  <img src="https://img.shields.io/badge/node-%3E%3D22-brightgreen" alt="node 22+" />
 </p>
 
-Vibgrate gives you a clear answer to one question:
-**How far behind is this repo, and what should we upgrade first?**
-
-In one command, you get:
+`vg` answers two questions for any repo:
 
-- A deterministic **Upgrade Drift Score** (0–100)
-- A clear risk level (**Low / Moderate / High**)
-- Runtime + framework major-version lag
-- Dependency age distribution + EOL proximity
-- Priority actions for what to fix next
+1. **What is this codebase?** — A deterministic code graph: call trees, import paths, impact surfaces, dependency facts.
+2. **How far behind is it?** — A ranked **Upgrade Drift Score** (0–100) with runtime/framework lag, dependency age and EOL proximity, and a prioritised fix list.
 
-Supported ecosystems today: **Node.js/TypeScript, .NET, Python, and Java**.
+Everything runs **on your machine**. No API key, no network call, no data leaving your repo unless you explicitly push. The `vibgrate` command is an alias for `vg` — they are interchangeable.
 
 ---
 
-## Why teams adopt Vibgrate
-
-Most systems do not fail all at once. They accumulate upgrade debt silently until migrations become expensive.
-
-Vibgrate makes drift measurable and repeatable:
-
-- **Developers** run a one-off scan to understand current debt.
-- **CI pipelines** run every PR/build to stop regression.
-- **Engineering leaders** track trends over time in the dashboard (optional push).
+## See it run
 
----
-
-## One-off scan vs CI-integrated drift tracking
+<p align="center">
+  <a href="https://vibgrate.com/cli">
+    <img src="docs/demo/cli-demo.svg" alt="Animated terminal replay: npx @vibgrate/cli scan produces a 74/100 drift score, a score breakdown, and ranked upgrade priorities." width="620" />
+  </a>
+</p>
 
-| Mode                   | What you get                                                      | Best for                                     |
-| ---------------------- | ----------------------------------------------------------------- | -------------------------------------------- |
-| **One-off scan**       | Fast snapshot of score, lag, and findings                         | Audits, due diligence, migration planning    |
-| **CI-integrated scan** | Continuous drift signal, SARIF annotations, regression guardrails | Keeping upgrade debt under control long-term |
+<p align="center">
+  <sub>A real <code>vg scan</code> replay — drift score, breakdown, and ranked priorities in one command. Animation plays right here on GitHub; nothing runs in your browser.</sub>
+</p>
 
-Recommended rollout: start with a one-off scan now, then add Vibgrate to CI this week.
+<p align="center">
+  <a href="https://vibgrate.com/cli"><strong>▶ Try the live, interactive CLI simulator →</strong></a><br />
+  <sub>Step through every command (<code>scan</code>, <code>build</code>, <code>ask</code>, <code>why</code>, …) against real sample repos.</sub>
+</p>
 
 ---
 
-## Quick start
+## Try it in 10 seconds
 
-Run instantly (no install):
+No install, no signup:
 
 ```bash
-npx @vibgrate/cli scan
+npx @vibgrate/cli scan          # drift score + upgrade priorities
+npx @vibgrate/cli build         # build the code graph
+npx @vibgrate/cli ask "what does AuthService do?"
 ```
 
-Or install locally:
+Install for repeat runs:
 
 ```bash
 npm install -D @vibgrate/cli
-npx vibgrate scan
+npx vg scan                     # vg is the primary command; vibgrate is an alias
 ```
 
-Add an npm script:
-
-```json
-{
-  "scripts": {
-    "drift": "vibgrate scan"
-  }
-}
-```
-
-> Local binaries are in `node_modules/.bin`, so use `npx` (or an npm script) unless you install globally.
+> Local binaries live in `node_modules/.bin` — use `npx vg` (or an npm script) unless you install globally.
 
 ---
 
-## Quick start with AI assistants
-
-Paste this prompt into your AI coding tool (GitHub Copilot, Cursor, Claude, etc.) to get started:
+## Use it with your AI assistant
 
-```
-Set up Vibgrate for upgrade drift tracking:
-1. Install: npm install -g @vibgrate/cli@latest
-2. Create DSN: npx vibgrate dsn create --workspace new
-3. Save DSN: echo 'export VIBGRATE_DSN="<dsn>"' >> ~/.zshrc && source ~/.zshrc
-4. Scan: npx vibgrate scan --push
-Then explain my drift score and top 3 upgrade priorities.
-```
+`vg serve` starts **Vibgrate AI Context** — a local-first MCP server that
+gives any MCP-compatible assistant (Claude, Cursor, Windsurf, Copilot, Gemini
+CLI, …) your code map, **offline drift**, local models, and **version-correct
+library docs**, all from your machine (no account, nothing uploaded; thin
+local docs fall through to the hosted catalog unless you pass `--local`). No
+context-window stuffing, no hallucinated APIs. The map **keeps itself fresh**:
+when files change — including edits the assistant itself just made — the next
+tool call rebuilds it incrementally before answering, with no watcher or
+daemon involved.
 
-See [docs/QUICKSTART-PROMPT.md](./docs/QUICKSTART-PROMPT.md) for the full onboarding prompt.
+Wire it up in one command:
 
----
-
-## What the report contains
-
-Every scan includes:
+```bash
+vg install                      # interactive: pick your assistant(s) and done
+vg install --all                # install for every detected assistant at once
+```
 
-- **Overall score** and risk level
-- **Score breakdown** (runtime, frameworks, dependencies, EOL)
-- **Per-project details** across Node, .NET, Python, and Java
-- **Actionable findings** (warnings/errors/notes)
-- **Top Priority Actions** ranked by likely impact
+This writes the MCP config for your chosen tool(s) and installs a skill that teaches the assistant how to query the graph. After reloading your assistant you get graph-aware answers: call trees, impact analysis, drift findings, version-correct library docs — all from local data.
 
-We keep output plain and operational: easy to convert into backlog items and CI policy.
+Browse all 21+ supported assistants and their skill descriptions at **[vibgrate.com/skills](https://vibgrate.com/skills)**.
 
 ---
 
-## New capabilities included in this release
-
-### 1) Multi-language workspace scanning
-
-Vibgrate recursively scans mixed repositories and supports:
-
-- Node.js / TypeScript (`package.json`)
-- .NET (`.sln`, `.csproj`, `.vbproj`)
-- Python (`requirements.txt`, `pyproject.toml` style ecosystems)
-- Java (`pom.xml`, Gradle-style manifest ecosystems)
-
-### 2) Extended scanner suite
-
-Beyond core drift scoring, Vibgrate can also detect:
-
-- Platform matrix and native-module risk
-- Dependency risk, graph duplication, and phantom dependencies
-- Full tooling inventory and build/deploy surface
-- TypeScript modernity and breaking-change exposure
-- File hotspots and structural security posture
-- Service dependency mapping (cloud, db, auth, messaging, etc.)
-- Architecture layer mapping
-- Code-quality metrics (complexity, nesting, cycles, god files)
-- OWASP category mapping from security findings
+## Understand any codebase
 
-### 3) SBOM Export & Delta
-
-Vibgrate now emits rich dependency inventory data in the JSON artifact, including lockfile-derived package graphs, duplicate-version hotspots, and phantom dependencies.
-
-This gives teams practical **SBOM-ready supply-chain visibility** for governance workflows while keeping the scan fast and CI-friendly.
-
-Use scan artifacts as operational SBOM intelligence in either CycloneDX or SPDX format:
+Build the graph once, query it continuously:
 
 ```bash
-npx vibgrate sbom export --format cyclonedx --out sbom.cdx.json
-npx vibgrate sbom export --format spdx --out sbom.spdx.json
+vg build                        # index the repo (incremental; re-run after changes)
+vg show src/auth/service.ts     # what this file does, calls, and is called by
+vg ask "where is rate limiting enforced?"
+vg impact src/db/connection.ts  # what breaks if this changes + tests to run
+vg path src/api/handler.ts src/db/query.ts   # shortest call path between two files
+vg tree src/server.ts           # call tree rooted at a node
+vg insights                     # overview: hubs, hotspots, untested paths
 ```
 
-Compare two scan artifacts to see dependency additions/removals/version changes between releases:
+The graph is byte-deterministic and reproducible — the same repo always produces the same graph on every machine.
 
 ```bash
-npx vibgrate sbom delta --from .vibgrate/baseline.json --to .vibgrate/scan_result.json --out sbom-delta.txt
+vg share                        # make the graph committable + auto-updating for the team
+vg serve                        # start Vibgrate AI Context (local-first MCP: code map + drift + version-correct docs)
 ```
 
-This keeps reports plain and actionable, so teams can go from scan output to backlog tasks quickly.
-
-### 4) Baseline, Drift Budgets & Fitness Gates
+---
 
-Take a baseline snapshot, then enforce dependency drift fitness functions in CI:
+## Measure and manage upgrade drift
 
 ```bash
-npx vibgrate baseline
-npx vibgrate scan --baseline .vibgrate/baseline.json --drift-worsening 5 --drift-budget 40
+vg scan                         # drift score + risk level + ranked priorities
+vg scan --push                  # same, and upload to Vibgrate Cloud for trend tracking
+vg baseline                     # snapshot current drift for regression gating
+vg report                       # generate a report from a saved scan artifact
 ```
 
-- `--drift-budget <score>` fails the build if absolute drift score exceeds your budget.
-- `--drift-worsening <percent>` fails the build if drift worsens by more than X% relative to baseline.
+One scan gives you:
 
-This turns drift scoring into a quality gate instead of passive reporting.
+- **Overall score** (0–100) and risk level (**Low / Moderate / High**)
+- **Score breakdown** — runtime, frameworks, dependencies, EOL
+- **Per-project detail** across Node.js/TypeScript, .NET, Python, and Java
+- **Actionable findings** ranked by likely impact
+- **SBOM export** (CycloneDX / SPDX)
+- **Known vulnerabilities** (opt in with `--vulns`) — severity, CVSS, the fixing version, and, in a git repo, who introduced them
 
 ---
 
+## Find known vulnerabilities and who introduced them
 
-## Privacy & offline-first workflows
-
-Vibgrate now supports explicit privacy controls:
-
-- `--no-local-artifacts` prevents writing `.vibgrate/*.json` files to disk.
-- `--max-privacy` enables a hardened profile (suppresses local artifact writes and disables high-context scanners such as UI-purpose evidence and architecture/code-quality enrichment).
-- Additional commercial scanner families are available and independently toggleable in `vibgrate.config.*`: `runtimeConfiguration`, `dataStores`, `apiSurface`, `operationalResilience`, `assetBranding`, and `ossGovernance` (see `docs/commercial-grade-scanners.md`).
-- `--offline` disables live registry/network lookups and never uploads scan results.
-- `--package-manifest <file>` accepts a local JSON or ZIP package-version manifest so drift can still be calculated offline. Download the latest bundle at `https://github.com/vibgrate/manifests/latest-packages.zip`.
-
-Example:
-
-```bash
-vibgrate scan --offline --package-manifest ./package-versions.zip --max-privacy --format json --out scan.json
-```
-
-When offline mode runs without a package manifest, package freshness is marked as unknown and drift scoring is necessarily partial.
-
-## Core commands
-
-```bash
-vibgrate scan [path] [--format text|json|sarif|md] [--out <file>] [--fail-on warn|error] [--exclude <glob>...] [--offline] [--package-manifest <file>] [--no-local-artifacts] [--max-privacy]
-vibgrate baseline [path]
-vibgrate report [--in <artifact.json>] [--format md|text|json]
-vibgrate push [--dsn <dsn>] [--file <artifact.json>] [--strict]
-vibgrate init [path] [--baseline] [--yes]
-vibgrate dsn create --workspace <id|new> [--region us|eu] [--write <path>]
-```
-
-### Command examples with expected results
+`vg scan --vulns` checks your installed dependencies against the public OSV database and reports each known vulnerability with its severity, CVSS score, and the version that fixes it — as text, JSON, or SARIF. Add `--package-manifest` to run it fully offline from a local advisory bundle.
 
 ```bash
-# 1) Scan current repo (text output)
-npx @vibgrate/cli scan
+vg scan --vulns                 # drift score + known vulnerabilities
+vg scan --full                  # drift + vulnerabilities + a banned-dependency report
 ```
 
-Expected result:
-
-- Prints overall score + risk level
-- Shows detected projects (Node/.NET/Python/Java)
-- Writes `.vibgrate/scan_result.json` unless disabled
+In a git repository, every finding is attributed from history: who introduced the vulnerable version, in which commit, and how long you have been exposed. Those exposure windows roll up into remediation metrics framed around the EU Cyber Resilience Act (CRA) — per-severity time-exposed and SLA breaches — so "are we fixing things fast enough?" has a number.
 
 ```bash
-# 2) Scan with CI gating
-npx @vibgrate/cli scan --fail-on error --drift-budget 40
+vg why lodash                   # who added a dependency, every version since, and any open vulnerabilities
+vg bisect lodash 4.17.21        # the commit where lodash crossed a version line (e.g. reached the fix)
 ```
 
-Expected result:
+Detection and attribution span the whole npm ecosystem (npm, pnpm, yarn) plus pip/poetry, cargo, composer, bundler, go, pub, hex, NuGet, and Maven/Gradle — read from each project's lockfile, so it works whatever you build in.
 
-- Exit code `0` when no error-level finding and score is within budget
-- Exit code `2` when the configured gate is exceeded
-
-```bash
-# 3) Scan while excluding vendored / generated paths
-#    --exclude is repeatable and accepts comma/semicolon-separated globs;
-#    patterns are merged with `exclude` from vibgrate.config.*
-npx @vibgrate/cli scan --exclude "legacy/**,vendor/**" --exclude "**/*.generated.ts"
-```
+Your AI assistant sees this too: `vg serve` exposes `list_vulnerabilities`, `vuln_attribution`, and an `upgrade_impact` tool that tells an agent what an upgrade will cost — version distance, how many files import the package, the vulnerabilities it fixes, and (online, opt in) the breaking-change notes between your version and the latest.
 
-Expected result:
-
-- Matching directories and files are skipped before scanning
-- Excludes from the config file still apply (CLI patterns are additive)
+---
 
-```bash
-# 4) Offline scan using local package-version bundle
-npx @vibgrate/cli scan --offline --package-manifest ./latest-packages.zip --format json --out scan.json
-```
+## Track drift over time → create a free workspace
 
-Expected result:
+The CLI is fully useful offline. When you want **trends across runs and repos** — so drift becomes a metric you manage, not a surprise you discover — push scans to a workspace:
 
-- No registry/network lookup
-- JSON artifact in `scan.json`
-- Package freshness may be marked unknown if manifest lacks entries
+1. **Create a workspace** at **[dash.vibgrate.com](https://dash.vibgrate.com)** and copy your DSN.
+2. **Connect and push:**
 
 ```bash
-# 5) Export SBOM and compare two runs
-npx @vibgrate/cli sbom export --format cyclonedx --out sbom.cdx.json
-npx @vibgrate/cli sbom delta --from .vibgrate/baseline.json --to .vibgrate/scan_result.json --out sbom-delta.txt
+VIBGRATE_DSN="vibgrate+https://<key_id>:<secret>@us.ingest.vibgrate.com/<workspace_id>" \
+  vg scan --push
 ```
 
-Expected result:
-
-- CycloneDX (or SPDX) JSON export file
-- Human-readable delta report with added/removed/changed dependencies
-
-Common usage:
+Upload is opt-in — nothing leaves your machine until you run `--push`. Store the DSN as a CI secret, never commit it.
 
-```bash
-# Standard scan
-npx @vibgrate/cli scan
-
-# CI-ready SARIF output
-npx @vibgrate/cli scan --format sarif --out vibgrate.sarif --fail-on error
-
-# Baseline and compare drift deltas over time
-npx @vibgrate/cli baseline
-npx @vibgrate/cli scan --baseline .vibgrate/baseline.json
-```
+**[→ Create your workspace](https://dash.vibgrate.com)**
 
 ---
 
-## CI integration (recommended)
+## CI integration
 
-### GitHub Actions
-
-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)
-- `docs/ci/github-actions.md` (integration notes)
+Drop `vg` into any pipeline to turn drift scoring into a quality gate:
 
 ```yaml
+# GitHub Actions — drift gate + SARIF upload
 - name: Vibgrate scan
   env:
     VIBGRATE_DSN: ${{ secrets.VIBGRATE_DSN }}
@@ -297,92 +192,179 @@ Use the maintained templates in this package for copy-paste setup:
     sarif_file: vibgrate.sarif
 ```
 
-### Azure DevOps
+Gate on drift budgets and regression relative to a baseline:
 
-```yaml
-- script: npx @vibgrate/cli scan --format sarif --out vibgrate.sarif --fail-on error
-  displayName: Vibgrate scan
+```bash
+vg baseline
+vg scan --baseline .vibgrate/baseline.json --drift-budget 40 --drift-worsening 5
 ```
 
-### GitLab CI
+- `--drift-budget <score>` fails the build if drift exceeds your budget.
+- `--drift-worsening <percent>` fails the build if drift worsens by more than X% vs baseline.
 
-```yaml
-vibgrate:
-  image: node:20
-  script:
-    - npx @vibgrate/cli scan --push --fail-on error
-```
+Copy-paste CI templates live in `examples/github-actions/`. Azure DevOps and GitLab CI snippets are in [DOCS.md](./DOCS.md#ci-integration).
 
 ---
 
-## Dashboard upload (optional)
+## 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:
+
+```bash
+vg lib react                    # React docs at your installed version
+vg lib express --fn middleware  # specific function reference
+```
+
+AI assistants connected via MCP use `vg lib` automatically when answering questions about library APIs in your project.
 
-The CLI is fully useful offline. Upload is opt-in.
+---
 
-If you want trend analysis across runs/repos, push scan artifacts with a DSN:
+## SBOM and OpenVEX
 
 ```bash
-VIBGRATE_DSN="vibgrate+https://<key_id>:<secret>@us.ingest.vibgrate.com/<workspace_id>" \
-  npx @vibgrate/cli scan --push
+vg sbom export --format cyclonedx --out sbom.cdx.json
+vg sbom export --format spdx     --out sbom.spdx.json
+vg sbom delta  --from .vibgrate/baseline.json --to .vibgrate/scan_result.json --out delta.txt
+vg vex                          # generate an OpenVEX document for attestation
 ```
 
-You can also upload an existing artifact:
+---
+
+## Privacy & offline-first
+
+- No data leaves your machine unless you run `--push` / `vg push`.
+- Core graph analysis and drift scoring read manifests and configs — **not your source code**.
+- Works without login and without any SaaS dependency.
+- `--offline` disables registry/network lookups; `--package-manifest <file>` feeds drift scoring a local version bundle.
+- `--max-privacy` suppresses local artifact writes and high-context scanners; `--no-local-artifacts` skips writing `.vibgrate/*.json` to disk.
 
 ```bash
-VIBGRATE_DSN="..." npx @vibgrate/cli push --file .vibgrate/scan_result.json
+vg scan --offline --package-manifest ./package-versions.zip --max-privacy --format json --out scan.json
 ```
 
-Get your DSN from [vibgrate.com](https://vibgrate.com). For CI, always store it as a secret (never commit it).
+Add `.vibgrate/` to your `.gitignore` — those are regenerated local outputs.
 
 ---
 
-## Privacy and safety
-
-- No data leaves your machine unless you run `--push` / `vibgrate push`
-- Core drift analysis is based on manifests/configs
-- Works without login and without SaaS dependencies
-- `.vibgrate/` artifacts are local outputs and may be gitignored
+## Quick start with AI assistants
 
-Add this to `.gitignore`:
+Paste this into your AI coding tool (Claude, Cursor, Copilot, Gemini CLI, …):
 
-```gitignore
-.vibgrate/
+```
+Set up Vibgrate for local codebase intelligence:
+1. Install: npm install -g @vibgrate/cli@latest
+2. Build the graph: vg build
+3. Wire your assistant: vg install
+4. Ask: vg ask "what are the main entry points?"
+Then explain the architecture and my top 3 upgrade priorities.
 ```
 
-The CLI writes per-project score files to `.vibgrate/` inside each detected project directory. These are regenerated on every scan and should not be copied between environments.
+See [docs/QUICKSTART-PROMPT.md](./docs/QUICKSTART-PROMPT.md) for the full prompt.
 
 ---
 
-## Commands
+## Command reference
+
+### Code graph
 
 | Command | Description |
-|---------|-------------|
-| `vibgrate scan [path]` | Scan for upgrade drift |
-| `vibgrate scan --push` | Scan and auto-push to dashboard |
-| `vibgrate baseline [path]` | Create a drift baseline |
-| `vibgrate report` | Generate a report from a scan artifact |
-| `vibgrate sbom export` | Export scan artifact as CycloneDX or SPDX SBOM |
-| `vibgrate sbom delta` | Compare two artifacts and report SBOM drift delta |
-| `vibgrate sbom vex` | Generate an OpenVEX document (exploitability statements) for attestation |
-| `vibgrate scan --emit-facts` | Emit the HCS fact payload (in-toto predicate) for artifact attestation |
-| `vibgrate init [path]` | Initialise config and `.vibgrate/` directory |
-| `vibgrate push` | Upload scan results to dashboard |
-| `vibgrate dsn create` | Generate a DSN token |
-| `vibgrate update` | Check for and install updates |
+| --- | --- |
+| `vg build [path]` | Build / update the code map (incremental, deterministic) |
+| `vg show <file>` | Explain a node: what it is, what it calls, what calls it |
+| `vg ask "<question>"` | Query the map in natural language |
+| `vg impact <file>` | What breaks if you change it — and the tests to run |
+| `vg path <from> <to>` | How A connects to B (shortest path) |
+| `vg tree <file>` | Call tree rooted at a node |
+| `vg insights` | Overview: hubs, hotspots, untested paths |
+| `vg lib <package>` | Version-correct, drift-annotated library docs |
+| `vg serve` | Start **Vibgrate AI Context** (local-first MCP: code map + drift + version-correct docs) |
+| `vg install` | Wire **Vibgrate AI Context** + skill into your AI assistant |
+| `vg share` | Make the graph committable + auto-updating for your team |
+| `vg status` | Cache/freshness, counts, staleness |
+| `vg facts <file>` | Deterministic facts for a node (contracts, invariants) |
+| `vg tests <file>` | Which tests cover a node |
+| `vg embed` | Precompute the semantic index for instant `vg ask` |
+| `vg export` | Export the map (json / ndjson / graphml / dot / cypher / md / html / SBOM) |
+
+### Drift reporting
+
+| Command | Description |
+| --- | --- |
+| `vg scan [path]` | Scan for upgrade drift |
+| `vg scan --vulns` | Also detect known vulnerabilities (OSV; offline via `--package-manifest`) |
+| `vg scan --full` | Comprehensive scan: drift + vulnerabilities + a banned-dependency report |
+| `vg why <package>` | Who introduced a dependency, its version history, and any open vulnerabilities |
+| `vg bisect <package> <constraint>` | The commit where a dependency crossed a version line (`--assert` to gate CI) |
+| `vg scan --push` | Scan and push results to Vibgrate Cloud |
+| `vg baseline [path]` | Create a drift baseline |
+| `vg report` | Generate a report from a scan artifact |
+| `vg sbom export` | Export CycloneDX or SPDX SBOM |
+| `vg sbom delta` | Compare two artifacts for SBOM drift |
+| `vg vex` | Generate an OpenVEX document for attestation |
+| `vg init [path]` | Initialise config and `.vibgrate/` |
+| `vg push` | Upload scan results to Vibgrate Cloud |
+| `vg dsn create` | Generate a DSN token |
+| `vg update` | Check for and install updates |
+
+```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] \
+  [--drift-budget <score>] [--drift-worsening <percent>] [--baseline <file>]
+```
+
+Full flag and configuration reference: **[DOCS.md](./DOCS.md)** · **[vibgrate.com/cli](https://vibgrate.com/cli)**.
+
+---
+
+## Why teams adopt Vibgrate
+
+Most systems don't fail all at once — they accumulate upgrade debt and architectural drift silently until migrations become expensive. `vg` makes that debt measurable and repeatable, and gives AI assistants the local context they need to be useful:
+
+| Mode | What you get | Best for |
+| --- | --- | --- |
+| **One-off scan** | Fast snapshot of drift score, lag, and findings | Audits, due diligence, migration planning |
+| **CI-integrated scan** | Continuous drift signal, SARIF annotations, regression guardrails | Keeping upgrade debt under control long-term |
+| **MCP + graph** | AI assistant with real-time, offline codebase context | Day-to-day development, code review, refactoring |
+
+Recommended rollout: `vg build` + `vg install` now, add `vg scan` to CI this week.
 
 ---
 
 ## Requirements
 
-- Node.js **20+**
+- Node.js **22+**
 - macOS, Linux, Windows
 
----
+## Command name conflicts
+
+`vg` is short and occasionally conflicts with other tools (`virtualgo`, `vugu`, the oh-my-zsh `git verify-commit` alias, custom shell aliases, etc.).
+
+**`vibgrate` is an identical alias** — same binary, same flags, same behaviour. If `vg` is taken on your system, use `vibgrate` everywhere instead:
 
-## Full docs
+```bash
+vibgrate scan          # same as: vg scan
+vibgrate build         # same as: vg build
+vibgrate serve         # same as: vg serve
+```
 
-For full command reference, configuration, scanner details, and advanced examples, see [CLI reference](https://vibgrate.com/cli).
+When `@vibgrate/cli` is installed, it registers **both** bin entries unconditionally. If it detects at install time that `vg` is already claimed by another tool, it prints a one-line notice pointing you to `vibgrate`.
 
 ---
 
-Copyright © 2026 Vibgrate. All rights reserved. See [Vibgrate CLI License](https://vibgrate.com/license) for terms.
+<p align="center">
+  <a href="https://dash.vibgrate.com"><strong>Create a free workspace →</strong></a>
+  &nbsp;·&nbsp;
+  <a href="https://vibgrate.com/cli">Try the live demo</a>
+  &nbsp;·&nbsp;
+  <a href="./DOCS.md">Vibgrate AI Context (local MCP)</a>
+  &nbsp;·&nbsp;
+  <a href="https://vibgrate.com/mcp">Vibgrate MCP (hosted)</a>
+  &nbsp;·&nbsp;
+  <a href="https://vibgrate.com/skills">AI agent skills</a>
+  &nbsp;·&nbsp;
+  <a href="./DOCS.md">Full docs</a>
+</p>
+
+<p align="center">
+  <sub>Apache-2.0 licensed · Copyright © 2026 Vibgrate</sub>
+</p>

package/dist/baseline-ZBXJONQ6.js

@@ -0,0 +1,6 @@
+export { baselineCommand, runBaseline } from './chunk-FPUNJNXD.js';
+import './chunk-2PJRXVUW.js';
+import './chunk-RXP66R2E.js';
+import './chunk-4M2MUQRO.js';
+//# sourceMappingURL=baseline-ZBXJONQ6.js.map
+//# sourceMappingURL=baseline-ZBXJONQ6.js.map

package/dist/baseline-ZBXJONQ6.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"baseline-ZBXJONQ6.js"}