@vibgrate/cli 2026.814.1 → 2026.817.1

package/README.md

@@ -13,15 +13,17 @@
   <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://dash.vibgrate.com/badges/driftscore/vibgrate/cli"><img src="https://badges.vibgrate.com/vibgrate/cli" alt="Vibgrate DriftScore" /></a>
   <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/vgcode"><img src="https://img.shields.io/badge/VG%20Code-local%20or%20hosted-F59E0B" alt="VG Code — a coding agent grounded in the code graph" /></a>
   <a href="https://vibgrate.com/mcp"><img src="https://img.shields.io/badge/Vibgrate%20Cloud%20MCP-vibgrate.com%2Fmcp-8B5CF6" alt="Vibgrate Cloud MCP" /></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>
 
-`vg` answers two questions for any repo:
+`vg` answers three questions for any repo:
 
 1. **What is this codebase?** — A deterministic [code graph](https://vibgrate.com/graph): call trees, import paths, impact surfaces, dependency facts.
-2. **How far behind is it?** — A ranked **[DriftScore](https://vibgrate.com/driftscore)** (0–100) with runtime/framework lag, dependency age and EOL proximity, and a prioritised fix list. Exposure is scored separately as a **[RiskScore](https://vibgrate.com/riskscore)**; the two together are the **[DriftRisk Index](https://vibgrate.com/driftrisk)**. The full methodology — formulas, sources, and limitations — is published as a [whitepaper](https://vibgrate.com/whitepapers/software-risk-and-drift-scoring-methodology) under CC BY 4.0 (DOI [10.5281/zenodo.21336304](https://doi.org/10.5281/zenodo.21336304)).
+2. **How far behind is it?** — A ranked **[DriftScore](https://vibgrate.com/driftscore)** (0–100) with runtime/framework lag, dependency age and EOL proximity, and a prioritized fix list. Exposure is scored separately as a **[RiskScore](https://vibgrate.com/riskscore)**; the two together are the **[DriftRisk Index](https://vibgrate.com/driftrisk)**. The full methodology — formulas, sources, and limitations — is published as a [whitepaper](https://vibgrate.com/whitepapers/software-risk-and-drift-scoring-methodology) under CC BY 4.0 (DOI [10.5281/zenodo.21336304](https://doi.org/10.5281/zenodo.21336304)).
+3. **Can we fix it here?** — [**VG Code**](#vg-code--write-the-change-not-just-the-report), a coding agent whose search tool is the code graph, not a grep — in your terminal as `vg code` and as the VG Code panel in [Vibgrate for VS Code](https://vibgrate.com/vscode) — plus `vg fix`, ranked upgrade plans it can apply.
 
 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.
 
@@ -54,6 +56,7 @@ No install, no signup:
 npx @vibgrate/cli scan          # drift score + upgrade priorities
 npx @vibgrate/cli build         # build the code graph
 npx @vibgrate/cli ask "what does AuthService do?"
+npx @vibgrate/cli code          # a coding agent — it asks before every edit
 ```
 
 Install for repeat runs:
@@ -141,6 +144,166 @@ vg serve                        # start Vibgrate AI Context (local-first MCP: co
 
 ---
 
+## VG Code — write the change, not just the report
+
+**VG Code** is the coding agent inside Vibgrate CLI. Its search tool is the deterministic code graph — **not a grep, not embeddings over chunks** — and it runs on a local model or a hosted one, your choice.
+
+```bash
+vg code                                            # guided: pick a model, then describe tasks
+vg code "add a --timeout flag to the scan command"
+```
+
+**Does it write to your disk?** Yes — through steps you approve, and only those. Read-only steps (search, read, list, impact) run without prompting; every edit and every command asks first. `--auto` runs the same loop with no prompts for CI. Without a terminal and without `--auto`, `vg code` refuses to start rather than writing unattended.
+
+**Two surfaces, one agent.** `vg code` is the terminal surface. The **VG Code panel** in [Vibgrate for VS Code](https://vibgrate.com/vscode) is the graphical one, and for most people it will be the one they live in: warm sessions between tasks, chat history, inline Approve / Reject cards with diffs, checkpoints, and @-mentions. The extension does not re-implement the agent — it runs the one shipped with this CLI over `--stream-json` and relays your decisions to it, so terminal, editor, and CI behave the same way.
+
+### Why an agent here, and not another chat window?
+
+- **Search is the graph.** `search_code` resolves symbols, callers, and callees from the map `vg build` produced — so the model gets the three functions that matter, not forty files that mention the word.
+- **Blast radius before the edit.** `graph_impact` tells the model what depends on a symbol *before* it changes it, and `vg tests` knows which tests to run after.
+- **Version-correct library docs.** `library_docs` pins to the version in your lockfile, so the model writes against the API you actually have.
+- **Invented identifiers are blocked, not flagged.** Before an edit is written, its replacement body is scanned against the graph's identifier trie. A symbol the graph does not know — and that is not already local to the target file — stops the write.
+- **Local models are first-class, hosted models are one flag away.** With a pulled model there is no account and no key, and Code Modes fit the model to the machine. When a task needs more, [Vibgrate Relay](https://vibgrate.com/relay) supplies hosted models on your Vibgrate account — no per-provider API keys — and falls back to your local model if it is unreachable.
+- **It adopts the MCP servers you already have.** `.mcp.json` (Claude Code), `.cursor/mcp.json`, and `.vscode/mcp.json` are read and merged with `.vibgrate/code.json`, which wins on a name clash.
+- **Cost is visible.** A token/$ meter after each task and on `/cost`; `vg savings` reports graph-backed calls per model.
+
+**Trade-off:** no model ships with the CLI, and VG Code is only as good as the model you point it at. A 7B local model is not a frontier model — it buys you privacy, offline inference, and no per-token cost. Relay buys you capacity at a per-token price. Pick the tier that matches the task; the graph grounding is the same either way.
+
+### A session, end to end
+
+```text
+  VG Code  · graph-grounded coding · v2026.x
+
+  ✔ Code map built
+  ✔ Model catalog loaded
+  ◆ Ready — ollama/qwen2.5-coder:7b · graph 48213. Describe a task, or /help.
+
+  code › add a --timeout flag to the scan command and use it
+
+    → search_code(query: --timeout flag scan command)
+      scanCommand (function) src/commands/scan.ts:12
+    → graph_impact(symbol: runScan)
+      3 symbol(s) depend on runScan: …
+    → edit_file(path: src/commands/scan.ts, …)
+  ? Apply edit to src/commands/scan.ts? [Y/n] y
+      ✔ edited src/commands/scan.ts
+    → run_command(command: npm test -- scan)
+  ? Run `npm test -- scan`? [y/N] y
+      ✔ exit 0  … 12 passing
+
+  ✔ added a --timeout flag to scan and covered it with tests
+    +6 -1 across 1 file(s) · via ollama/qwen2.5-coder:7b
+```
+
+What happened, step by step:
+
+1. The code map is built or refreshed incrementally — only changed files re-parse.
+2. The model catalog loads and you pick a local model or a hosted provider. Before pulling a local model, a memory pre-flight compares its estimated footprint against available RAM/VRAM and refuses a model this machine cannot run.
+3. Vibgrate Graph (`vg serve`) starts as a child process for the life of the session and stops when you exit. Every graph call is attributed to VG Code and the model in use.
+4. The agent loops: search → read → assess impact → edit → run.
+5. You approve each mutating step, or it runs unattended under `--auto`.
+6. Edits land through a deterministic merge, so the change goes exactly where it was meant to.
+
+### Approval modes
+
+| Mode | Behavior |
+| --- | --- |
+| **Interactive** (default) | Read-only steps run freely. Every edit and every command asks first. |
+| **`--auto`** | No prompts. A denylist blocks catastrophic commands — filesystem wipes, `curl … \| sh`, force-push, `sudo`. For CI and scripted runs. |
+| **`--single`** | One-shot: propose a diff and stop. No tool loop, no commands. Dry-run unless you pass `--apply --yes`. |
+
+`--max-steps <n>` caps the loop (default 24). `--worktree` runs the whole session in an isolated git worktree so nothing touches your main tree until you apply it.
+
+### Which model — local, or hosted through Relay
+
+**Code Modes** pick a local model that actually fits this machine, checked against your real RAM, VRAM, and disk before anything downloads:
+
+| Mode | Intent |
+| --- | --- |
+| **Spark** | Fast, small footprint — quick edits and tight memory |
+| **Flow** | Balanced default for day-to-day coding |
+| **Forge** | Heavier pack when you have headroom and want more capacity |
+
+```bash
+vg models                       # what's set, and what fits this machine
+vg models install flow          # install the pack (--dry-run to preview)
+vg models pull qwen2.5-coder:7b
+```
+
+**[Vibgrate Relay](https://vibgrate.com/relay)** is the hosted tier that supplements those local models when a task needs more capacity than the machine has. One Vibgrate account and endpoint, a curated catalog of hosted models, per-token metering against prepaid credit — and no per-provider API keys to manage:
+
+```bash
+export VIBGRATE_RELAY_TOKEN=…   # Relay is then preferred, with local fallback
+vg code --provider vibgrate-relay --model <slug>
+```
+
+You are not locked to it. `--provider` also takes `ollama`, `lmstudio`, `foundry-local`, `llama-cpp`, `openrouter`, `litellm`, `openai`, and `together`; those API keys are read from the environment only (`OPENROUTER_API_KEY` and friends), never passed as flags. With no `--provider`, `vg code` uses what you have already configured — Relay first if its token is set, then another hosted key, then a local model — and never dials an endpoint you did not set up. `--local` keeps it on-device.
+
+### Tools the agent has
+
+| Tool | What it does | Approval |
+| --- | --- | --- |
+| `search_code` | Search the code graph — symbols and relations, plus a literal sweep for exact phrases | free |
+| `read_file` / `list_files` | Read a file or line range; list files in the map | free |
+| `graph_impact` | Blast radius of changing a symbol | free |
+| `library_docs` | Version-correct docs for a dependency you actually have installed | free |
+| `edit_file` / `create_file` / `delete_file` / `apply_patch` | Change the working tree | **approved** |
+| `run_command` | Run tests, builds, anything else | **approved** |
+| `web_fetch` / `web_search` | Fetch or search the public web — untrusted, secret-redacted, size-capped | **approved** |
+| `browser_*` / `read_notebook` / `spawn_subagent` | Drive a browser, work in Jupyter notebooks, delegate a sub-task | **approved** |
+| `mcp__<server>__<tool>` | Tools from your configured MCP servers | free if read-only, else **approved** |
+
+### In-session commands
+
+| Command | What it does |
+| --- | --- |
+| `/undo` | Revert the files changed by the last task |
+| `/diff` | Show the last change |
+| `/model` | Switch model without leaving the session |
+| `/cost` | Running token and dollar cost (local models are free) |
+| `/compact` | Condense the session so far into one checkpoint recap |
+| `/help` / `/exit` | List commands / quit |
+
+### Where state lives
+
+| On disk | In the session |
+| --- | --- |
+| The code map (`.vibgrate/`), gitignored | Conversation and step history |
+| Your config (`.vibgrate/code.json`) | The `/undo` stack |
+| The edits themselves — local and git-reversible | The token/$ meter |
+| Session store, so `--continue` can resume | The `vg serve` child process |
+
+`--continue` resumes your most recent session: it recaps what was already done for the model and restores `/undo`.
+
+### Configure once
+
+`.vibgrate/code.json` — flags still override:
+
+```json
+{
+  "provider": "ollama",
+  "model": "qwen2.5-coder:7b",
+  "testCommand": "npm test",
+  "auto": false,
+  "denyCommands": ["deploy", "kubectl\\s+delete"],
+  "maxSteps": 24,
+  "mcpServers": {
+    "playwright": { "command": "npx", "args": ["-y", "@playwright/mcp"] }
+  }
+}
+```
+
+Full key reference — including `securityTier`, `capsule`, and `modelProfile` — is in [DOCS.md](./DOCS.md#vg-code).
+
+### Safety
+
+- Secrets files (`.env`, `.npmrc`, `.netrc`, key material) are never read into a prompt, and credential shapes are redacted from any file the agent does read.
+- Under `--auto`, a denylist blocks catastrophic commands. Interactively you see and approve every command yourself.
+- Every change is local and git-reversible. `/undo` reverts the last task; `--worktree` keeps the whole session off your main tree.
+- Web and browser results are treated as untrusted content, never as instructions.
+
+---
+
 ## Measure and manage upgrade drift
 
 ```bash
@@ -170,7 +333,9 @@ vg scan --vulns                 # drift score + known vulnerabilities
 vg scan --full                  # drift + vulnerabilities + a banned-dependency report
 ```
 
-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)](https://vibgrate.com/cra) — and feed [Vibgrate Evidence](https://vibgrate.com/evidence), which freezes shipped-release manifests so "which shipped products contain this vulnerability?" has a signed, offline-verifiable answer — per-severity time-exposed and SLA breaches — so "are we fixing things fast enough?" has a number.
+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 per-severity time-exposed and SLA-breach metrics, framed around the [EU Cyber Resilience Act (CRA)](https://vibgrate.com/cra) — so "are we fixing things fast enough?" has a number.
+
+That answers the question about *this checkout*. For the question a regulator asks — which **shipped** products contain it — see [Vibgrate Evidence](#vibgrate-evidence--answer-which-shipped-products-contain-this) below.
 
 ```bash
 vg why lodash                   # who added a dependency, every version since, and any open vulnerabilities
@@ -183,6 +348,59 @@ Your AI assistant sees this too: `vg serve` exposes `list_vulnerabilities`, `vul
 
 ---
 
+## Vibgrate Evidence — answer "which shipped products contain this?"
+
+A scanner tells you about the code in front of you. A regulator asks about the code you **shipped** — eighteen months ago, at version 3.2.1, into Germany and France, still in its support window. **[Vibgrate Evidence](https://vibgrate.com/evidence)** answers that question as a signed artifact a third party can verify offline, with no account and no network.
+
+It produces **evidence, not a verdict.** It will not tell you that you are compliant, and it is not legal advice. It gives you a defensible, reproducible answer and the audit trail behind it; the determination and the filing stay yours.
+
+```bash
+vg evidence init --regime cra                       # who files, and to which coordinator
+vg evidence product add "Acme Gateway" --markets DE,FR --in-scope
+vg evidence release acme-gateway 3.2.1 --from sbom.cdx.json --ship-date 2025-02-14
+vg evidence exposure CVE-2025-12345 --bundle ./ev   # signed answer, exit code for CI
+```
+
+### Why freeze a manifest instead of scanning again?
+
+- **Ships are immutable; your tree is not.** `exposure` matches against the manifest **frozen at ship time**, not `HEAD`. Re-scanning today tells you what you would ship now, which is not the question asked.
+- **It refuses to guess.** A product bound to a release with no frozen manifest comes back `undetermined` **with a reason**, never a confident-looking `not affected`. That distinction is the whole value of the artifact.
+- **Jurisdiction-neutral by design.** Reporting duties are modeled as **regimes**: the EU CRA (`--regime cra`, applies from **11 September 2026**) and DORA incident reporting (`--regime dora-incident`) ship today. A new jurisdiction is a regime profile, not a new command or a new tool.
+- **No model touches a figure.** Nothing in the evidence path is generated by a language model. Every number is computed from frozen manifests and advisory data.
+- **Offline end to end.** `--offline` with a local advisory file needs no network, and `vg evidence verify` works on a machine that has never heard of Vibgrate.
+
+**Trade-off:** the answer is only as good as the manifests you froze. Evidence cannot reconstruct what you shipped before you started recording it — a release you never froze is `undetermined`, permanently. The value compounds from the day you start, which is the argument for starting now rather than in September.
+
+### The lifecycle
+
+| Step | Command | What it does |
+| --- | --- | --- |
+| 1. Set up | `vg evidence init` | Org, coordinator CSIRT, and the person with filing authority |
+| 2. Register | `vg evidence product add` | A product with digital elements — markets, classification, scope rationale |
+| 3. Freeze | `vg evidence release` | Pin a shipped version to an immutable component manifest, from an SBOM or scan |
+| 4. Ask | `vg evidence exposure <vuln>` | Which shipped products contain it, at which versions, in which markets, still in support |
+| 5. Prove | `vg evidence verify <bundle>` | Re-check the signed answer offline, on any machine |
+
+Between those: `vg evidence readiness` is a deterministic gap report against the regime's obligations, `vg evidence regimes` lists the regimes and their clocks, `vg evidence drill` runs a timed rehearsal against a simulated advisory, `vg evidence watch` joins the CISA KEV catalog to your frozen manifests, `vg evidence pack` builds the submission pack a human pastes into the reporting platform, and `vg evidence export` writes an air-gapped bundle of everything.
+
+### What is in a bundle, and what "verified" means
+
+`--bundle <dir>` writes `result.json`, a DSSE/Ed25519 in-toto attestation over it (`evidence.intoto.jsonl`), a `VERIFY.md` a third party can follow, and — with `--tsa <url>` — an RFC 3161 trusted-timestamp token (`timestamp.tsr`).
+
+`vg evidence verify` reports one of three honest states, and the middle one matters:
+
+| State | Meaning |
+| --- | --- |
+| `verified` | Signature checks, the signer is pinned to a trust root you supplied with `--pub`, **and** the result digest still matches |
+| `unverified` | Cryptographically intact and unmodified, but the signer is not pinned — real, and not yet trusted by you |
+| `failed` | Bad signature, or a `result.json` that no longer matches what was signed |
+
+Exit codes make it a CI gate: **0** no exposure · **2** exposure found · **3** undetermined, needs manual review · **1** operational error.
+
+Evidence state lives in `.vibgrate/evidence/`. The Ed25519 signing key is minted on first use at `.vibgrate/attest-key.pem` (mode `0600`, with a `.pub` beside it) unless you point at your own with `VG_ATTEST_KEY` — back it up, and never commit it.
+
+---
+
 ## Track drift over time → create a free workspace
 
 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 [Vibgrate Cloud](https://vibgrate.com/cloud) workspace:
@@ -264,6 +482,9 @@ vg vex                          # generate an OpenVEX document for attestation
 - 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.
+- `vg code --local` keeps model inference on-device: a local model, the local graph, no hosted call and no model-catalog fetch. The agent's own web tools stay available and, like every network step, are approved by you before they run.
+- `vg code` never reads a secrets file into a prompt, and redacts credential shapes from files it does read.
+- `vg evidence` runs locally: `--offline` with a local advisory file needs no network, and `vg evidence verify` checks a bundle on a machine with no account and no connection. Nothing reaches Vibgrate Cloud until you run `vg evidence push`.
 
 ```bash
 vg scan --offline --package-manifest ./package-versions.zip --max-privacy --format json --out scan.json
@@ -305,7 +526,7 @@ Under each set, commands are listed A–Z. A short **typical path** (usual order
 | `vg ask "<question>"` | Query the map in natural language |
 | `vg build [path]` | Build / update the code map (incremental, deterministic) |
 | `vg bundle` | Build an air-gapped bundle (grammars + graph + library catalog) |
-| `vg code "<instruction>"` | Propose a graph-grounded code edit (dry-run by default; `--apply --yes` to write) |
+| `vg code ["<instruction>"]` | Graph-grounded coding agent — local or hosted model, every edit and command approved (`--auto` for CI, `--single` for a one-shot diff) |
 | `vg embed` | Precompute the semantic index for instant `vg ask` |
 | `vg export` | Export the map (json / ndjson / graphml / dot / cypher / md / html / SBOM) |
 | `vg facts <file>` | Deterministic facts for a node (contracts, invariants) |
@@ -315,6 +536,7 @@ Under each set, commands are listed A–Z. A short **typical path** (usual order
 | `vg lib <package>` | Version-correct, drift-annotated library docs |
 | `vg map` / `vg hubs` / `vg areas` / `vg oddities` | Map insights: overview, most-depended-on code, natural groupings, cross-area smells |
 | `vg models` | Code Modes (Spark / Flow / Forge) + local fleet (Ollama / LM Studio / gguf); `install` / `pull` by default (`--dry-run` to preview) |
+| `vg module` | Manage optional local modules (`relevance`, `hcs`): `status`, `install`, `remove` |
 | `vg path <from> <to>` | How A connects to B (shortest path) |
 | `vg savings` | Local report of tokens/$ saved vs a grep baseline (estimates) |
 | `vg watch` | Rebuild the map when files change |
@@ -326,6 +548,22 @@ Under each set, commands are listed A–Z. A short **typical path** (usual order
 | `vg tree <file>` | Call tree rooted at a node |
 | `vg unknowns` | What the graph cannot resolve, ranked by blast radius |
 
+### Holistic Code Specification (`vg hcs`)
+
+Deterministic code facts for **Rust, Ruby, PHP, Dart, Swift, Scala, C++, COBOL, and VB6** — one NDJSON line per fact, reproducible on any machine, so a fact stream is something you can commit, diff, and gate CI on. Extraction is incremental by default: re-running over an existing stream costs only the delta.
+
+All HCS computation runs in an optional, separately-licensed engine module that executes in a local WASM sandbox — no network calls, no process spawns. It is fetched on first use, or ahead of time with `vg module install hcs`. When it is unavailable, every `vg hcs` command exits `6` — never `2`, so a CI gate can't mistake "engine missing" for a verdict.
+
+**Typical path:** `vg hcs extract` → `vg hcs digest` / `vg hcs map` / `vg hcs gate`
+
+| Command | Description |
+| --- | --- |
+| `vg hcs extract [dir]` | Extract facts into an NDJSON stream (incremental by default; `--full` to re-extract) |
+| `vg hcs digest` | Render a fact stream as a readable specification (`md` / `json` / `html`) |
+| `vg hcs gate` | Governance gate: diff two streams, fail (exit `2`) on material structural regressions |
+| `vg hcs map` | Build the System Map from a fact stream (`json` / `md` / `mermaid`) |
+| `vg hcs validate <file>` | Validate a stream against the HCS spec (Appendix-I conformance code) |
+
 ### Diagnostics, IDE & runtime
 
 **Typical path:** `vg doctor` → `vg lsp` → `vg daemon`
@@ -334,6 +572,7 @@ Under each set, commands are listed A–Z. A short **typical path** (usual order
 | --- | --- |
 | `vg daemon` | Local workspace daemon for multi-root graph sessions (IDE / agents): `status`, `ensure`, `publish`, `query`, `impact`, … |
 | `vg doctor` | Read-only diagnosis: config, credentials (redacted), map freshness, hosted reachability, MCP launch |
+| `vg llm-host` | Isolated local inference host process (`serve`, `status`) for enterprise process isolation |
 | `vg lsp` | Language server (stdio) — engine behind Vibgrate for VS Code and other thin IDE clients |
 | `vg policy` | Show production context-policy pin; `vg policy verify <file>` for signed learning patches |
 
@@ -346,7 +585,7 @@ Under each set, commands are listed A–Z. A short **typical path** (usual order
 | `vg baseline [path]` | Create a drift baseline |
 | `vg bisect <package> <constraint>` | The commit where a dependency crossed a version line (`--assert` to gate CI) |
 | `vg drift` | What is outdated across dependencies (offline; `--online` for currency) |
-| `vg evidence` | Signed, reproducible regulatory evidence (regime-neutral; CRA first) |
+| `vg evidence` | Signed, reproducible regulatory evidence — jurisdiction-neutral regimes (EU CRA first, DORA incident reporting too): `init`, `product`, `release`, `exposure`, `readiness`, `drill`, `watch`, `pack`, `verify`, `push`, `export` |
 | `vg fix` | Ranked, risk-tiered upgrade plans from the hosted planner — then apply the one you choose |
 | `vg init [path]` | Initialise config and `.vibgrate/` |
 | `vg report` | Generate a report from a scan artifact |
@@ -376,7 +615,7 @@ vg scan [path] [--vulns] [--full] [--format text|json|sarif|md] [--out <file>] [
   [--drift-budget <score>] [--drift-worsening <percent>] [--baseline <file>]
 ```
 
-Full flag and configuration reference: **[DOCS.md](./DOCS.md)** · **[vibgrate.com/cli](https://vibgrate.com/cli)** · [help centre](https://vibgrate.com/help) · [glossary](https://vibgrate.com/glossary).
+Full flag and configuration reference: **[DOCS.md](./DOCS.md)** · **[vibgrate.com/cli](https://vibgrate.com/cli)** · [help center](https://vibgrate.com/help) · [glossary](https://vibgrate.com/glossary).
 
 ---
 
@@ -389,8 +628,25 @@ Most systems don't fail all at once — they accumulate upgrade debt and archite
 | **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 |
+| **VG Code** | A coding agent grounded in the graph — terminal or VS Code panel, local model or Relay, governed edit by edit | Making the change, not just planning it |
+
+Recommended rollout: `vg build` + `vg install` now, add `vg scan` to CI this week, try `vg code` on one small task.
 
-Recommended rollout: `vg build` + `vg install` now, add `vg scan` to CI this week.
+---
+
+## Known limits
+
+- **Drift and risk scores are estimates**, computed from manifests, lockfiles, and public advisory data. They are a prioritization signal, not a compliance determination or a certification.
+- **VG Code quality tracks the model you choose.** No model ships with the CLI. A small local model handles mechanical edits well and struggles with cross-cutting design changes; `vg models` tells you what fits this machine, not what will do the job. Reach for Relay or another hosted model when the task is bigger than the machine.
+- **Guided `vg code` needs a terminal.** In CI, pass an instruction plus `--auto` (or `--mock`) — the interactive picker never appears, and the agent refuses to run unattended without it.
+- **The map is the ceiling.** Anything the resolver could not tie to a definition is invisible to `search_code` and `graph_impact`. Run `vg unknowns` to see what the graph is missing, ranked by blast radius.
+- **`--auto` is a denylist, not a sandbox.** It blocks known-catastrophic commands; it does not confine the agent. Run untrusted instructions in a container, or under `--worktree` with `--security-tier L1`.
+- **`--verify` re-runs your tests; it does not prove correctness.** Failures are fed back for a repair attempt. Passing tests mean passing tests.
+- **Vulnerability data is only as current as its source.** `--vulns` reports what OSV knows at scan time; offline runs report what is in the bundle you supplied.
+- **Vibgrate Evidence produces evidence, not a compliance determination.** It supports your obligations under a regime; it does not decide that you meet them, does not certify anything, and is not legal advice. The filing is yours.
+- **Evidence cannot look backwards.** Exposure is answered from manifests frozen at ship time. A release you never froze stays `undetermined` — there is no way to reconstruct it after the fact.
+- **`vg evidence watch` surfaces a KEV listing, not a determination.** Whether a vulnerability is "actively exploited" for the purposes of a filing is your call, not the tool's.
+- **`vg evidence verify` does not re-verify the TSA certificate chain.** It confirms the RFC 3161 token's imprint binds to `result.json` and surfaces the trusted time. For the full chain, use `openssl ts -verify -in timestamp.tsr -data result.json -CAfile <tsa-ca.pem>`.
 
 ---
 
@@ -398,12 +654,13 @@ Recommended rollout: `vg build` + `vg install` now, add `vg scan` to CI this wee
 
 - Node.js **22+**
 - macOS, Linux, Windows
+- VG Code additionally needs a model: a local runtime (a Code Mode pack, Ollama, LM Studio, or a GGUF on disk), a [Vibgrate Relay](https://vibgrate.com/relay) token, or an API key for another hosted provider. Run `vg models` to see what fits this machine.
 
 ## 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:
+**`vibgrate` is an identical alias** — same binary, same flags, same behavior. If `vg` is taken on your system, use `vibgrate` everywhere instead:
 
 ```bash
 vibgrate scan          # same as: vg scan
@@ -420,22 +677,27 @@ When `@vibgrate/cli` is installed, it registers **both** bin entries uncondition
 | | |
 |---|---|
 | [**Vibgrate CLI**](https://vibgrate.com/cli) | This package — scan, score, and map any repository. [Live demo](https://vibgrate.com/cli) · [benchmarks](https://vibgrate.com/cli/benchmarks) · [token savings](https://vibgrate.com/cli/benchmarks/token-savings) |
-| [**Vibgrate for VS Code**](https://vibgrate.com/vscode) | The same score in your editor, plus VG Code. [Marketplace](https://marketplace.visualstudio.com/items?itemName=vibgrate.vibgrate-vscode) · [Open VSX](https://open-vsx.org/extension/vibgrate/vibgrate-vscode) |
+| [**Vibgrate for VS Code**](https://vibgrate.com/vscode) | The same score in your editor, plus the **[VG Code](https://vibgrate.com/vgcode)** panel — the graphical surface for `vg code`, running this same agent. [Marketplace](https://marketplace.visualstudio.com/items?itemName=vibgrate.vibgrate-vscode) · [Open VSX](https://open-vsx.org/extension/vibgrate/vibgrate-vscode) |
+| [**Vibgrate Relay**](https://vibgrate.com/relay) | Hosted models for VG Code on one Vibgrate account — no per-provider API keys, prepaid per-token credit, local models still the offline path |
 | [**Vibgrate Graph**](https://vibgrate.com/graph) | The deterministic local code map behind `vg map`, `vg impact` and `vg show` |
 | [**Vibgrate AI Context**](https://vibgrate.com/library) | `vg serve` — version-correct library docs, your code map, and offline drift, served to any assistant. [Supported assistants](https://vibgrate.com/skills) · [on mcp.so](https://mcp.so/servers/cli-a2b26f) |
 | [**Vibgrate Cloud MCP**](https://vibgrate.com/mcp) | The hosted MCP server over your workspace data (OAuth 2.1) |
 | [**Vibgrate Cloud**](https://vibgrate.com/cloud) | History, trends, and team rollups. [Create a workspace](https://dash.vibgrate.com) · [pricing](https://vibgrate.com/pricing) |
-| [**Vibgrate Evidence**](https://vibgrate.com/evidence) | Signed, reproducible release evidence — including for the [EU CRA](https://vibgrate.com/cra) |
+| [**Vibgrate Evidence**](https://vibgrate.com/evidence) | `vg evidence` — freeze shipped releases, then answer "which shipped products contain this vulnerability?" as signed, offline-verifiable evidence. Jurisdiction-neutral regimes, [EU CRA](https://vibgrate.com/cra) first |
 
 **How the scores work:** [DriftScore](https://vibgrate.com/driftscore) · [RiskScore](https://vibgrate.com/riskscore) · [DriftRisk Index](https://vibgrate.com/driftrisk) · [published methodology](https://vibgrate.com/whitepapers/software-risk-and-drift-scoring-methodology) · [public index of real scans](https://vibgrate.com/driftrisk/index) · [README badges](https://vibgrate.com/badges)
 
-**Reference:** [package registry](https://vibgrate.com/packages) · [integrations marketplace](https://vibgrate.com/marketplace) · [glossary](https://vibgrate.com/glossary) · [help centre](https://vibgrate.com/help) · [security](https://vibgrate.com/security) · [mission](https://vibgrate.com/mission)
+**Reference:** [package registry](https://vibgrate.com/packages) · [integrations marketplace](https://vibgrate.com/marketplace) · [glossary](https://vibgrate.com/glossary) · [help center](https://vibgrate.com/help) · [security](https://vibgrate.com/security) · [mission](https://vibgrate.com/mission)
 
 <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="https://vibgrate.com/vgcode">VG Code</a>
+  &nbsp;·&nbsp;
+  <a href="https://vibgrate.com/evidence">Evidence</a>
+  &nbsp;·&nbsp;
   <a href="./DOCS.md">Full docs</a>
 </p>
 

package/dist/agent-CUYQKC6S.js

@@ -0,0 +1,26 @@
+export { CONTEXT_POLICY_VERSION, DISCOVERY_TOOLS, MUTATION_TOOLS, compact, compactWithModel, runAgent } from './chunk-YL4OIUA5.js';
+import './chunk-543E6WDJ.js';
+import './chunk-ZSECAGSU.js';
+import './chunk-RQAKBRAV.js';
+import './chunk-RBIRXQR6.js';
+import './chunk-5HYCB55P.js';
+import './chunk-74UBGF4P.js';
+import './chunk-3HNPVXUK.js';
+import './chunk-VIWZ4QT7.js';
+import './chunk-NQUWC2IA.js';
+import './chunk-J7LKEB2R.js';
+export { summarizeCapsule } from './chunk-NKRWKCME.js';
+import './chunk-2TJ5EY4I.js';
+import './chunk-EZ7UC5Y5.js';
+import './chunk-6NOGNOE4.js';
+import './chunk-RXP66R2E.js';
+import './chunk-2GSMCOIC.js';
+import './chunk-QPXVTQ7O.js';
+import './chunk-ENFSSUNK.js';
+import './chunk-PV76EO4G.js';
+import './chunk-BWPBB45M.js';
+import './chunk-JFGYT6BI.js';
+import './chunk-BPF3YX2U.js';
+import './chunk-Z6ZWNWWR.js';
+//# sourceMappingURL=agent-CUYQKC6S.js.map
+//# sourceMappingURL=agent-CUYQKC6S.js.map

package/dist/{agent-2ZISYEQF.js.map → agent-CUYQKC6S.js.map}

@@ -1 +1 @@
-{"version":3,"sources":[],"names":[],"mappings":"","file":"agent-2ZISYEQF.js"}
+{"version":3,"sources":[],"names":[],"mappings":"","file":"agent-CUYQKC6S.js"}

package/dist/{approvals-DOZ5RWJP.js → approvals-IPMUDEDV.js}

@@ -1,9 +1,9 @@
-export { addApprovalRule, approvalsPath, findMatchingRule, globMatch, loadApprovalRules, normalizeCommandPrefix, removeApprovalRule, ruleForAction, ruleKey, ruleLabel, saveApprovalRules } from './chunk-A4F7ESUR.js';
-import './chunk-K7MONYIM.js';
-import './chunk-QIUQH2ND.js';
+export { addApprovalRule, approvalsPath, findMatchingRule, globMatch, loadApprovalRules, normalizeCommandPrefix, removeApprovalRule, ruleForAction, ruleKey, ruleLabel, saveApprovalRules } from './chunk-ZSECAGSU.js';
+import './chunk-ENFSSUNK.js';
+import './chunk-PV76EO4G.js';
 import './chunk-BWPBB45M.js';
 import './chunk-JFGYT6BI.js';
 import './chunk-BPF3YX2U.js';
 import './chunk-Z6ZWNWWR.js';
-//# sourceMappingURL=approvals-DOZ5RWJP.js.map
-//# sourceMappingURL=approvals-DOZ5RWJP.js.map
+//# sourceMappingURL=approvals-IPMUDEDV.js.map
+//# sourceMappingURL=approvals-IPMUDEDV.js.map

package/dist/{approvals-DOZ5RWJP.js.map → approvals-IPMUDEDV.js.map}

@@ -1 +1 @@
-{"version":3,"sources":[],"names":[],"mappings":"","file":"approvals-DOZ5RWJP.js"}
+{"version":3,"sources":[],"names":[],"mappings":"","file":"approvals-IPMUDEDV.js"}

package/dist/baseline-NZFGLMER.js

@@ -0,0 +1,9 @@
+export { baselineCommand, runBaseline } from './chunk-2BURPMYA.js';
+import './chunk-ANYL7SUI.js';
+import './chunk-DT4KIVRI.js';
+import './chunk-CRAMOEBE.js';
+import './chunk-RXP66R2E.js';
+import './chunk-PV76EO4G.js';
+import './chunk-Z6ZWNWWR.js';
+//# sourceMappingURL=baseline-NZFGLMER.js.map
+//# sourceMappingURL=baseline-NZFGLMER.js.map

package/dist/{baseline-AGX42TZM.js.map → baseline-NZFGLMER.js.map}

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

package/dist/{chunk-TFAXW7VM.js → chunk-2BURPMYA.js}

@@ -1,4 +1,4 @@
-import { runCoreScan, compactUiPurpose } from './chunk-N6ZMZ5AI.js';
+import { runCoreScan, compactUiPurpose } from './chunk-ANYL7SUI.js';
 import { findPackageJsonFiles, readJsonFile, findFiles, readTextFile, pathExists, isSkippedDirName } from './chunk-DT4KIVRI.js';
 import { writeJsonFile } from './chunk-CRAMOEBE.js';
 import * as path3 from 'path';
@@ -4664,5 +4664,5 @@ var baselineCommand = new Command("baseline").description("Create a drift baseli
 });
 
 export { baselineCommand, loadAdvancedScanHook, runBaseline };
-//# sourceMappingURL=chunk-TFAXW7VM.js.map
-//# sourceMappingURL=chunk-TFAXW7VM.js.map
+//# sourceMappingURL=chunk-2BURPMYA.js.map
+//# sourceMappingURL=chunk-2BURPMYA.js.map