@vibgrate/cli 2026.722.2 → 2026.727.2

package/DOCS.md

@@ -14,30 +14,31 @@ For a quick overview, see the [README](./README.md). This document covers everyt
   - [vg baseline](#vg-baseline)
   - [vg bisect](#vg-bisect)
   - [vg drift](#vg-drift)
-  - [vg dsn create](#vg-dsn-create)
   - [vg evidence](#vg-evidence)
   - [vg fix](#vg-fix)
   - [vg init](#vg-init)
-  - [vg login](#vg-login)
-  - [vg logout](#vg-logout)
-  - [vg push](#vg-push)
   - [vg report](#vg-report)
   - [vg sbom](#vg-sbom)
   - [vg scan](#vg-scan)
     - [Vulnerabilities and exposure attribution](#vulnerabilities-and-exposure-attribution)
   - [vg update](#vg-update)
   - [vg why](#vg-why)
+- [Workspace auth & cloud upload](#workspace-auth--cloud-upload)
+  - [vg dsn create](#vg-dsn-create)
+  - [vg login](#vg-login)
+  - [vg logout](#vg-logout)
+  - [vg push](#vg-push)
 - [Code Graph Commands](#code-graph-commands)
   - [vg ask](#vg-ask)
-  - [vg benchmark](#vg-benchmark)
   - [vg build](#vg-build)
   - [vg bundle](#vg-bundle)
+  - [vg code](#vg-code)
   - [vg embed](#vg-embed)
   - [vg export](#vg-export)
   - [vg facts](#vg-facts)
   - [vg guide](#vg-guide)
   - [vg impact](#vg-impact)
-  - [vg install](#vg-install)
+  - [vg install / vg uninstall](#vg-install)
   - [vg lib](#vg-lib)
   - [vg map / vg hubs / vg areas / vg oddities](#vg-map--vg-hubs--vg-areas--vg-oddities)
   - [vg models](#vg-models)
@@ -50,6 +51,11 @@ For a quick overview, see the [README](./README.md). This document covers everyt
   - [vg tests](#vg-tests)
   - [vg tree](#vg-tree)
   - [vg unknowns](#vg-unknowns)
+- [Diagnostics, IDE & runtime](#diagnostics-ide--runtime)
+  - [vg daemon](#vg-daemon)
+  - [vg doctor](#vg-doctor)
+  - [vg lsp](#vg-lsp)
+  - [vg policy](#vg-policy)
 - [DriftScore](#driftscore)
 - [Drift Baselines & Fitness Functions](#drift-baselines--fitness-functions)
   - [How the Score Is Calculated](#how-the-score-is-calculated)
@@ -171,6 +177,10 @@ Expected results:
 
 ## Commands Reference
 
+Drift scoring, baselines, reports, supply-chain evidence, and related local tooling.
+
+**Typical path:** `vg init` → `vg scan` → `vg baseline` → `vg report` → `vg fix`
+
 ### vg baseline
 
 Create a drift baseline snapshot for delta comparison.
@@ -183,6 +193,7 @@ Runs a full scan and saves the result to `.vibgrate/baseline.json`. Use this as
 
 ---
 
+
 ### vg bisect
 
 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.
@@ -205,6 +216,7 @@ Exit codes: `0` when the query resolves, `2` when `--assert` finds the constrain
 
 ---
 
+
 ### vg drift
 
 What is outdated across your dependencies — a fast, offline currency check.
@@ -224,25 +236,6 @@ Add `--json` for machine-readable output.
 
 ---
 
-### vg dsn create
-
-Generate an HMAC-signed DSN token for API authentication.
-
-```bash
-vg dsn create --workspace <id|new> [--region <region>] [--ingest <url>] [--write <path>]
-```
-
-| Flag          | Default    | Description                                                                 |
-| ------------- | ---------- | --------------------------------------------------------------------------- |
-| `--workspace` | _required_ | Your workspace ID, or `new` to auto-generate a workspace                    |
-| `--region`    | `us`       | Data residency region (`us`, `eu`)                                          |
-| `--ingest`    | —          | Custom ingest API URL (overrides `--region`)                                |
-| `--write`     | —          | Write DSN to a file (add to `.gitignore`!)                                  |
-
-When using `--workspace new`, the CLI auto-generates a workspace ID and provisions the DSN
-with the Vibgrate API. Rate limited to 1 new DSN per 5 minutes per IP address.
-
----
 
 ### vg evidence
 
@@ -293,6 +286,7 @@ No language model touches any figure in the evidence path, and every determinati
 
 ---
 
+
 ### vg fix
 
 Turn a drift scan into ranked, risk-tiered upgrade plans and **apply** the one
@@ -378,6 +372,7 @@ advisory at or above the threshold or an apply step fails.
 
 ---
 
+
 ### vg init
 
 Initialise Vibgrate in a project.
@@ -398,50 +393,6 @@ Creates:
 
 ---
 
-### vg login
-
-Authenticate the CLI with your Vibgrate workspace through the browser. Credentials are stored locally so `vg fix` and `vg push` can reach the hosted planner and Vibgrate Cloud.
-
-```bash
-vg login
-```
-
-| Flag | Default | Description |
-|------|---------|-------------|
-| `--region <region>` | `us` | Data-residency region (`us`, `eu`) |
-| `--ingest <url>` | — | Custom ingest API URL (overrides `--region`) |
-| `--no-browser` | — | Print the URL to open instead of launching a browser (headless / SSH) |
-
----
-
-### vg logout
-
-Clear stored Vibgrate login credentials from this machine.
-
-```bash
-vg logout
-```
-
----
-
-### vg push
-
-Upload scan results to the Vibgrate Cloud API.
-
-```bash
-vg push [--dsn <dsn>] [--file <file>] [--region <region>] [--strict]
-```
-
-| Flag       | Default                      | Description                                 |
-| ---------- | ---------------------------- | ------------------------------------------- |
-| `--dsn`    | `VIBGRATE_DSN` env           | DSN token for authentication                |
-| `--file`   | `.vibgrate/scan_result.json` | Scan artifact to upload                     |
-| `--region` | —                            | Override data residency region (`us`, `eu`) |
-| `--strict` | —                            | Fail hard on upload errors                  |
-
-Upload is always optional. Best-effort by default — use `--strict` in CI if you want the pipeline to fail on upload errors.
-
----
 
 ### vg report
 
@@ -458,6 +409,7 @@ vg report [--in <file>] [--format md|text|json]
 
 ---
 
+
 ### vg sbom
 
 Export [SBOMs](https://vibgrate.com/glossary/sbom) from an existing scan artifact or compare two artifacts.
@@ -480,6 +432,7 @@ Use this to treat SBOMs as operational intelligence instead of static compliance
 
 ---
 
+
 ### vg scan
 
 The primary command. Scans your project for upgrade drift.
@@ -561,6 +514,7 @@ vg scan --full
 
 ---
 
+
 ### vg update
 
 Check for and install updates.
@@ -576,6 +530,7 @@ vg update [--check] [--pm <manager>]
 
 ---
 
+
 ### vg why
 
 Explain a dependency from git history: who added it, every version since, and any open vulnerabilities it carries.
@@ -588,25 +543,88 @@ vg why <package>
 
 ---
 
-## 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.
+## Workspace auth & cloud upload
 
-**Global options available on every graph command:**
+Sign in to Vibgrate Cloud, manage DSN tokens for CI, and push scan results. Local drift scoring does not require this — nothing leaves your machine until you push.
 
-| 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 |
-| `--client <name>` | Identify the AI client (e.g. `claude`) so navigation calls are counted in `vg savings` |
-| `--deep` | Enable deep derivation (for `vg facts`, `vg build`) |
-| `--no-cache` | Skip and clear cached data |
+**Typical path:** `vg login` → `vg dsn create` → `vg push` → `vg logout`
+
+### vg dsn create
+
+Generate an HMAC-signed DSN token for API authentication.
+
+```bash
+vg dsn create --workspace <id|new> [--region <region>] [--ingest <url>] [--write <path>]
+```
+
+| Flag          | Default    | Description                                                                 |
+| ------------- | ---------- | --------------------------------------------------------------------------- |
+| `--workspace` | _required_ | Your workspace ID, or `new` to auto-generate a workspace                    |
+| `--region`    | `us`       | Data residency region (`us`, `eu`)                                          |
+| `--ingest`    | —          | Custom ingest API URL (overrides `--region`)                                |
+| `--write`     | —          | Write DSN to a file (add to `.gitignore`!)                                  |
+
+When using `--workspace new`, the CLI auto-generates a workspace ID and provisions the DSN
+with the Vibgrate API. Rate limited to 1 new DSN per 5 minutes per IP address.
 
 ---
 
+
+### vg login
+
+Authenticate the CLI with your Vibgrate workspace through the browser. Credentials are stored locally so `vg fix` and `vg push` can reach the hosted planner and Vibgrate Cloud.
+
+```bash
+vg login
+```
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--region <region>` | `us` | Data-residency region (`us`, `eu`) |
+| `--ingest <url>` | — | Custom ingest API URL (overrides `--region`) |
+| `--no-browser` | — | Print the URL to open instead of launching a browser (headless / SSH) |
+
+---
+
+
+### vg logout
+
+Clear stored Vibgrate login credentials from this machine.
+
+```bash
+vg logout
+```
+
+---
+
+
+### vg push
+
+Upload scan results to the Vibgrate Cloud API.
+
+```bash
+vg push [--dsn <dsn>] [--file <file>] [--region <region>] [--strict]
+```
+
+| Flag       | Default                      | Description                                 |
+| ---------- | ---------------------------- | ------------------------------------------- |
+| `--dsn`    | `VIBGRATE_DSN` env           | DSN token for authentication                |
+| `--file`   | `.vibgrate/scan_result.json` | Scan artifact to upload                     |
+| `--region` | —                            | Override data residency region (`us`, `eu`) |
+| `--strict` | —                            | Fail hard on upload errors                  |
+
+Upload is always optional. Best-effort by default — use `--strict` in CI if you want the pipeline to fail on upload errors.
+
+---
+
+
+## Code Graph Commands
+
+Build and query the deterministic code map.
+
+**Typical path:** `vg build` → `vg status` → `vg ask` → `vg impact` → `vg share`
+
 ### vg ask
 
 Ask the code map a question using hybrid lexical + structural + semantic search.
@@ -630,22 +648,6 @@ Before answering, `ask` checks whether files changed since the map was last buil
 
 ---
 
-### vg benchmark
-
-A reproducible build + memory + token-reduction benchmark for this repository — honest, self-measured estimates you can re-run.
-
-```bash
-vg benchmark
-```
-
-| Flag | Default | Description |
-|------|---------|-------------|
-| `--budget <n>` | `2000` | Approx token budget used when estimating context savings |
-
-Add `--json` for machine-readable output.
-
----
-
 ### vg build
 
 Build or update the code map incrementally.
@@ -692,6 +694,129 @@ Add `--json` for machine-readable output.
 
 ---
 
+### vg code
+
+Propose a code edit for a plain-language instruction, grounded in the deterministic code graph. `vg code` is **dry-run by default**: it prints the proposed diff and writes nothing.
+
+```bash
+vg code "add a --timeout flag to the scan command"
+```
+
+**Agentic sessions.** With a real model, `vg code` is a coding *agent*, not just a one-shot editor: the model is given tools and works in steps — **search the code graph**, read files, check a symbol's blast radius, edit, create/delete files, and run your tests or build — until the task is done. Every mutating step (an edit or a command) is **governed**: you approve it, or run autonomously with `--auto`. Read-only steps (search/read/list/impact) run without prompting. `--single` forces the old one-shot diff; `--max-steps <n>` caps the loop.
+
+**Guided mode.** Run `vg code` with no instruction at an interactive terminal and it walks you through everything: it builds the code map, then asks where the model should run — a local model, or one of the current top providers (Claude, GPT, Grok, Gemini, …) surfaced live from the catalog — and which model, with an "enter a slug myself" option at every step. Before pulling any local model it runs a memory pre-flight (estimated footprint vs free RAM/VRAM and already-loaded models) and won't pull a model your machine can't run; then it drops into an agent session where you describe tasks and approve each change. For scripts and CI, pass an instruction with `--auto` (or `--mock`) — the agent only prompts at a TTY, so automation never blocks.
+
+While a session is active, Vibgrate Graph (`vg serve`) runs as a separate process for the life of the session and is stopped when you exit. Every graph-backed call is attributed to VG Code and the model in use, so `vg savings` reports token/$ savings **per model**.
+
+**A full local session (no cloud):**
+
+```bash
+# one-time: a local coding model (or: vg models install)
+vg models pull qwen2.5-coder:7b
+
+# start a guided agent session — pick "Local model" → qwen2.5-coder:7b
+vg code
+```
+
+```text
+  VG Code  · graph-grounded coding · v2026.x
+
+  ✔ Code map built
+  ✔ Model catalog loaded
+  ? Where should the model run?
+  ❯ Local model (on your machine)   1 found
+    Anthropic (Claude)              via OpenRouter
+    …
+  ✔ qwen2.5-coder:7b
+  ◆ Ready — ollama/qwen2.5-coder:7b · graph 48213. Describe a task; empty line to exit.
+
+  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
+    → read_file(path: src/commands/scan.ts)
+      src/commands/scan.ts (40 lines): …
+    → graph_impact(symbol: runScan)
+      3 symbol(s) depend on runScan: …
+  I'll add the option and thread it through.
+    → edit_file(path: src/commands/scan.ts, …)
+--- a/src/commands/scan.ts
++++ b/src/commands/scan.ts
+@@ …
++  .option('--timeout <ms>', 'abort the scan after <ms> milliseconds')
+  ? 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
+    → finish(summary: added a --timeout flag to scan and covered it with tests)
+
+  ✔ added a --timeout flag to scan and covered it with tests
+    +6 -1 across 1 file(s) · via ollama/qwen2.5-coder:7b
+```
+
+Run it non-interactively with `vg code "add a --timeout flag to scan" --provider ollama --model qwen2.5-coder:7b --auto`, or against a hosted model with `--provider openrouter --model anthropic/claude-3.5-sonnet` (set `OPENROUTER_API_KEY`).
+
+**In a session** you can type slash-commands: `/undo` reverts the last change, `/diff` shows it, `/model` switches model, `/cost` shows the running token/$ cost, `/help` lists them, `/exit` quits.
+
+**More session controls:**
+
+- `--stream` streams the model's output live as it's generated.
+- `--verify [command]` runs your tests after the agent finishes and, if they fail, feeds the failures back so it fixes them (uses the `testCommand` from config if you don't name one).
+- `--continue` resumes your most recent session — it recaps what was already done for the model and restores `/undo`.
+- A live **token/$ meter** shows after each task and via `/cost` (cost is shown when the model's price is known; local models are free).
+- **External MCP tools:** list servers under `mcpServers` in `.vibgrate/code.json` and the agent can call their tools (namespaced `mcp__<server>__<tool>`); read-only tools run freely, anything else is approved like a built-in mutating tool. VG Code also **adopts the standard MCP config files** already in your repo — `.mcp.json` (Claude Code), `.cursor/mcp.json` (Cursor), and `.vscode/mcp.json` (VS Code) — and merges them with your `.vibgrate/code.json` (which wins on any name clash), so servers you've already configured for another tool work here with no extra setup. Both local (`command`) and remote (`url`) servers are supported.
+
+**Tools the agent has:** searching is the code graph (`search_code`) — not a grep — plus `read_file`, `list_files`, `graph_impact` (blast radius), **`library_docs`** (version-correct docs for a dependency you actually have installed, so the model uses the right API for your version), `edit_file`, `create_file`, `delete_file`, and `run_command`.
+
+**Safety.** The agent never sends a secrets file (`.env`, keys, credentials) to the model, and redacts stray credential shapes from any file it reads. Under `--auto`, a denylist blocks catastrophic commands (filesystem wipes, `curl … | sh`, force-push, …); interactively you see and approve each command yourself.
+
+**Configure once** in `.vibgrate/code.json` so you can then just run `vg code` (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"] }
+  }
+}
+```
+
+It assembles a small, high-signal context from the map (the relevant symbols, their relations, the blast radius of changing them, and any hard constraints), asks the model you choose for a minimal edit, and applies that edit through a deterministic merge so the change lands exactly where it was meant to.
+
+Writing is opt-in and confirmed. `--apply` walks the full inspect → assess → dry-run → approve → execute → verify → log lifecycle, and still requires your explicit `--yes` (or an interactive confirmation) — there is no write-without-consent path.
+
+```bash
+vg code "rename readCfg to readConfig everywhere it is called" --apply --yes
+```
+
+Pick a backend with `--provider` and `--model`. No model is bundled, and nothing is installed until you first use a backend that needs it:
+
+- **Local** — `--provider ollama` or `--provider lmstudio` (or `--local` to force on-device only, no network).
+- **Hosted** — any OpenAI-compatible endpoint: `--provider openrouter` / `litellm` / `openai` / `together`. API keys are read from the environment only (e.g. `OPENROUTER_API_KEY`), never passed as flags.
+
+With no `--provider`, `vg code` chooses from what you have already configured (a hosted key, or a locally-pulled model) and never dials a cloud endpoint you didn't set up.
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `<instruction>` | — | What to change, in plain language |
+| `--provider <id>` | auto | `ollama`, `lmstudio`, `openrouter`, `litellm`, `openai`, `together`, `llama-cpp` |
+| `--model <id>` | — | Model id (or set `VG_CODE_MODEL`) |
+| `--file <path>` | — | Restrict the edit surface to this file (repeatable) |
+| `--budget <n>` | `3000` | Approx context token budget |
+| `--apply` | — | Write the change (still requires `--yes` or a confirmation) |
+| `--yes` | — | Consent to write, or to a first-use package install, non-interactively |
+| `--local` | — | On-device backends only; never touch the network |
+
+Add `--json` for the full machine-readable result (proposed changes, diffs, and the verification summary), or `--out <file>` to write it for CI. Requires a map — run `vg` first if you have not built one.
+
+---
+
 ### vg embed
 
 Precompute the semantic index so the next `vg ask` is instant.
@@ -791,17 +916,24 @@ Add Vibgrate AI Context to your AI assistant(s) — skill, MCP wiring, and advis
 
 ```bash
 vg install [tools...]
+vg install --all
+vg install --detect
+vg install --list
 vg uninstall <tools...>
+vg uninstall cursor --purge
 ```
 
 Idempotent and repo-local (changes can be committed and shared with your team).
 
-**Supported assistants:** `claude`, `cursor`, `windsurf`, `vscode`, `codex`, `gemini`
+**Supported assistant ids:** `claude`, `cursor`, `windsurf`, `vscode`, `codex`, `gemini`, `grok`, `opencode`, `kilo`, `aider`, `factory`, `trae`, `kiro`, `amp`, `kimi`, `codebuddy`, `copilot-cli`, `pi`, `devin`, `hermes`, `openclaw`, `agents`
+
+Run `vg install --list` for the live support matrix (ids can grow over time).
 
 | Flag | Description |
 |------|-------------|
 | `[tools...]` | Assistant ids to install for |
 | `--all` | Install for every supported assistant |
+| `--detect` | Detect assistants in use (repo footprint, home config, PATH) and install for those; with `--list`, only report what was detected |
 | `--list` | Show the support matrix and exit |
 | `--no-hook` | Skip the advisory nudge |
 
@@ -812,6 +944,8 @@ Idempotent and repo-local (changes can be committed and shared with your team).
 | `<tools...>` | Assistant ids to remove (required) |
 | `--purge` | Also delete the skill file |
 
+`vg uninstall` only removes AI-assistant wiring. To remove the CLI package from the machine, use your package manager (`npm uninstall -g @vibgrate/cli`, etc.).
+
 ---
 
 ### vg lib
@@ -859,150 +993,101 @@ vg oddities # Surprising cross-area links (architectural smells)
 
 ---
 
-### vg models
-
-The local model fleet — Ollama, LM Studio, and on-disk `gguf` models — discovered entirely offline.
-
-```bash
-vg models
-```
-
-Lists the local inference backends and models Vibgrate can see, so you know what is available without any network calls. Add `--json` for machine-readable output.
+### vg llm-host
 
-To fetch a model through your Ollama runtime, use the `pull` subcommand. **No model is ever downloaded by default** — the download only happens when you pass `--yes`; without it, `pull` just prints the plan.
+Thin **enterprise inference process** (ADR-005). Code Modes and install stay on `vg models`; this host only loads weights and decodes over a local socket when isolation is `process`.
 
 ```bash
-vg models pull qwen2.5-coder:7b --yes
+vg llm-host status
+vg llm-host serve                 # listen on the default runtime socket
+vg llm-host serve --socket /tmp/vg-llm.sock --yes
 ```
 
-| Flag | Default | Description |
-|------|---------|-------------|
-| `<name>` | — | Model to pull, e.g. `qwen2.5-coder:7b` |
-| `--runtime <id>` | `ollama` | Runtime to pull with |
-| `--yes` | — | Actually download (without this it only prints the plan) |
+Default isolation is **embedded** (same process as the agent). Set `VIBGRATE_INFERENCE_ISOLATION=process` to use the host. Management never moves into the host process.
 
----
-
-### vg code
+**First-party weights.** For catalogued GGUF refs (e.g. Spark’s llama.cpp fallback), `vg models install` can download into the Vibgrate weight store under the cache directory (HTTPS hosts allowlisted, including Hugging Face LFS/Xet CDNs). Catalog entries carry **sha256 pins**; a download that does not match is rejected. Ollama remains the default pull channel for Code Mode packs that list `ollama` as primary.
 
-Propose a code edit for a plain-language instruction, grounded in the deterministic code graph. `vg code` is **dry-run by default**: it prints the proposed diff and writes nothing.
+**Foundry Local.** On Windows (or any host running Microsoft Foundry Local), use `--provider foundry-local --model <id>` with the OpenAI-compatible server (default `http://127.0.0.1:5272/v1`, override with `FOUNDRY_LOCAL_BASE_URL`). `vg models status` lists models when the server responds.
 
-```bash
-vg code "add a --timeout flag to the scan command"
-```
+**Warm local inference (Approach B default).** Code Mode packs (channel 2026.07.3) install first-party GGUF weights when fit allows; Ollama is the fallback adapter. When a GGUF is on disk (weight store or `~/models`), `vg code` prefers embedded llama.cpp automatically. Set `VG_PREFER_OLLAMA=1` to force Ollama first. Spark constrained decoding is **fail-closed**: if the binding cannot attach a PatchIR grammar, generation errors instead of free-text (opt-in raw string GBNF only via `VG_ALLOW_GRAMMAR_STRING_FALLBACK=1`).
 
-**Agentic sessions.** With a real model, `vg code` is a coding *agent*, not just a one-shot editor: the model is given tools and works in steps — **search the code graph**, read files, check a symbol's blast radius, edit, create/delete files, and run your tests or build — until the task is done. Every mutating step (an edit or a command) is **governed**: you approve it, or run autonomously with `--auto`. Read-only steps (search/read/list/impact) run without prompting. `--single` forces the old one-shot diff; `--max-steps <n>` caps the loop.
+**Identifier enforce (before apply).** Edits and `apply_patch` that invent identifiers not present in the code graph are **blocked** (not merely annotated). Identifiers already in the target file (locals, params, existing helpers) and tokens only in comments/strings are allowed. After an approved edit, the session trie updates so new symbols become legal.
 
-**Guided mode.** Run `vg code` with no instruction at an interactive terminal and it walks you through everything: it builds the code map, then asks where the model should run — a local model, or one of the current top providers (Claude, GPT, Grok, Gemini, …) surfaced live from the catalog — and which model, with an "enter a slug myself" option at every step. Before pulling any local model it runs a memory pre-flight (estimated footprint vs free RAM/VRAM and already-loaded models) and won't pull a model your machine can't run; then it drops into an agent session where you describe tasks and approve each change. For scripts and CI, pass an instruction with `--auto` (or `--mock`) — the agent only prompts at a TTY, so automation never blocks.
+**Native logit mask (P1).** When node-llama-cpp exposes `TokenBias`, the warm host **boosts** tokens for graph identifiers and can **suppress** vocabulary tokens that are complete identifiers absent from the graph. Bias is cached per session/trie. Without `TokenBias`, generation still runs (post-scan annotation + enforce-before-apply remain).
 
-While a session is active, Vibgrate Graph (`vg serve`) runs as a separate process for the life of the session and is stopped when you exit. Every graph-backed call is attributed to VG Code and the model in use, so `vg savings` reports token/$ savings **per model**.
+**Dynamic open-identifier sampler (P2).** When enabled (`VG_LLM_ON_TOKEN=1` or `VG_LLM_CUSTOM_SAMPLER=1`, or a binding that declares the hook), the host tracks whether generation is inside a code identifier and rejects tokens that invent graph-unknown names mid-decode. Composed with grammar + TokenBias on the same `prompt()` call.
 
-**A full local session (no cloud):**
+**Warm KV prefix reuse (P1/P2).** Prompt segments are content-hashed; after the first turn, stable system/capsule blocks are warm. A multi-turn **cursor** skips already-evaluated leading blocks and only re-evaluates the delta when the binding supports evaluate-without-generate, so multi-turn TTFT does not re-prefill the full capsule every step.
 
-```bash
-# one-time: a local coding model (nothing is downloaded by default)
-vg models pull qwen2.5-coder:7b --yes
+**Speculative drafts (P2).** Graph-verbatim draft candidates are **ranked** against the user ask; the host tries accept in score order (evaluate-without-generate when available).
 
-# start a guided agent session — pick "Local model" → qwen2.5-coder:7b
-vg code
-```
+**Shared host in vgd.** The daemon protocol includes `host-status`, `host-load`, `host-unload`, and `host-generate` so a long-lived process can keep a warm model for CLI and IDE clients (same session pool as embedded). Clients may pass a **client id** on load so unload is **refcounted** — CLI and VS Code can share one warm model without the first exit killing the session.
 
-```text
-  VG Code  · graph-grounded coding · v2026.x
+**Hardware default mode.** `vg models mode --apply-recommend` pins the Code Mode recommended from free RAM/VRAM and repo size when no default is set. `vg doctor` surfaces the same recommendation under `localInference`.
 
-  ✔ Code map built
-  ✔ Model catalog loaded
-  ? Where should the model run?
-  ❯ Local model (on your machine)   1 found
-    Anthropic (Claude)              via OpenRouter
-    …
-  ✔ qwen2.5-coder:7b
-  ◆ Ready — ollama/qwen2.5-coder:7b · graph 48213. Describe a task; empty line to exit.
+**Coding metrics (release).** `vg models coding-metrics` builds a `coding-metrics/0` report: host-bench arms + gates + offline Fusion FCS/ZNS trajectory pack. Default host mode is **simulate** (no GPU). CI runs simulate+gate on PRs; CLI publish opens a website data PR under `data/benchmarks-coding/` (human review before public claims), same pattern as CLI release benchmarks.
 
-  code › add a --timeout flag to the scan command and use it
+**Host bench (P3).** `vg models host-bench` runs Approach B measurement arms (Ollama baseline, embedded warm, grammar, identifier enforce, TokenBias, dynamic sampler, KV delta). Default **simulate** exercises the warm host without a GPU; `--mock` is registry shells only; `--live --model-path <gguf>` is operator hardware. Add `--gate` to evaluate release gates (exit code **2** on hard failure). Use `--json` for CI artifacts.
 
-    → search_code(query: --timeout flag scan command)
-      scanCommand (function) src/commands/scan.ts:12
-    → read_file(path: src/commands/scan.ts)
-      src/commands/scan.ts (40 lines): …
-    → graph_impact(symbol: runScan)
-      3 symbol(s) depend on runScan: …
-  I'll add the option and thread it through.
-    → edit_file(path: src/commands/scan.ts, …)
---- a/src/commands/scan.ts
-+++ b/src/commands/scan.ts
-@@ …
-+  .option('--timeout <ms>', 'abort the scan after <ms> milliseconds')
-  ? 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
-    → finish(summary: added a --timeout flag to scan and covered it with tests)
-
-  ✔ added a --timeout flag to scan and covered it with tests
-    +6 -1 across 1 file(s) · via ollama/qwen2.5-coder:7b
-```
-
-Run it non-interactively with `vg code "add a --timeout flag to scan" --provider ollama --model qwen2.5-coder:7b --auto`, or against a hosted model with `--provider openrouter --model anthropic/claude-3.5-sonnet` (set `OPENROUTER_API_KEY`).
-
-**In a session** you can type slash-commands: `/undo` reverts the last change, `/diff` shows it, `/model` switches model, `/cost` shows the running token/$ cost, `/help` lists them, `/exit` quits.
-
-**More session controls:**
+---
 
-- `--stream` streams the model's output live as it's generated.
-- `--verify [command]` runs your tests after the agent finishes and, if they fail, feeds the failures back so it fixes them (uses the `testCommand` from config if you don't name one).
-- `--continue` resumes your most recent session — it recaps what was already done for the model and restores `/undo`.
-- A live **token/$ meter** shows after each task and via `/cost` (cost is shown when the model's price is known; local models are free).
-- **External MCP tools:** list servers under `mcpServers` in `.vibgrate/code.json` and the agent can call their tools (namespaced `mcp__<server>__<tool>`); read-only tools run freely, anything else is approved like a built-in mutating tool. VG Code also **adopts the standard MCP config files** already in your repo — `.mcp.json` (Claude Code), `.cursor/mcp.json` (Cursor), and `.vscode/mcp.json` (VS Code) — and merges them with your `.vibgrate/code.json` (which wins on any name clash), so servers you've already configured for another tool work here with no extra setup. Both local (`command`) and remote (`url`) servers are supported.
+### vg models
 
-**Tools the agent has:** searching is the code graph (`search_code`) — not a grep — plus `read_file`, `list_files`, `graph_impact` (blast radius), **`library_docs`** (version-correct docs for a dependency you actually have installed, so the model uses the right API for your version), `edit_file`, `create_file`, `delete_file`, and `run_command`.
+**Code Modes** (Spark / Flow / Forge) for VG Code, plus the **local model fleet** (Ollama, LM Studio, and on-disk `gguf` files). The default view is outcome-oriented: which mode fits this machine and repo, which pack backs it, and whether it is ready.
 
-**Safety.** The agent never sends a secrets file (`.env`, keys, credentials) to the model, and redacts stray credential shapes from any file it reads. Under `--auto`, a denylist blocks catastrophic commands (filesystem wipes, `curl … | sh`, force-push, …); interactively you see and approve each command yourself.
+**Named install commands run by default** (same polarity as the rest of `vg`: the command does what it says). Pass `--dry-run` to print the plan only. Status/resolve never download. Destructive `rm` confirms on a TTY; non-interactive remove needs `--yes`.
 
-**Configure once** in `.vibgrate/code.json` so you can then just run `vg code` (flags still override):
+`install` / `pull` install the **full provider dependency closure** for the pack (e.g. runtime npm deps for llama-cpp, then weight download for Ollama). Third-party apps such as Ollama itself are never auto-installed — install them separately if the plan lists them as blocked.
 
-```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"] }
-  }
-}
+```bash
+vg models                 # Code Modes status + fleet summary
+vg models --raw           # local models only
+vg models status
+vg models mode [spark|flow|forge]
+vg models resolve [mode]  # pack + model + fit (no download)
+vg models install [mode]  # install the pack (add --dry-run to preview)
+vg models pin <packId>
+vg models unpin <mode>
+vg models packs
+vg models pull <name>     # download (add --dry-run to preview)
+vg models uninstall <name> # uninstall (TTY confirm; --yes for CI; --dry-run to preview)
+vg models host-bench      # Approach B measurement arms (default: simulate, no GPU)
+vg models coding-metrics  # host-bench + Fusion FCS/ZNS report (coding-metrics/0)
+vg models catalog
 ```
 
-It assembles a small, high-signal context from the map (the relevant symbols, their relations, the blast radius of changing them, and any hard constraints), asks the model you choose for a minimal edit, and applies that edit through a deterministic merge so the change lands exactly where it was meant to.
-
-Writing is opt-in and confirmed. `--apply` walks the full inspect → assess → dry-run → approve → execute → verify → log lifecycle, and still requires your explicit `--yes` (or an interactive confirmation) — there is no write-without-consent path.
+| 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 |
+
+| Subcommand / flag | Description |
+|-------------------|-------------|
+| `--raw` | Skip Code Modes; list discovered local models only |
+| `mode [spark\|flow\|forge]` | Show or set the default Code Mode (`--auto` clears a fixed default) |
+| `resolve [mode]` | Resolve pack + underlying model + fit without downloading |
+| `install [mode]` | Resolve and install the pack (`--dry-run` for plan only) |
+| `pin <packId>` / `unpin <mode>` | Pin or clear a reproducible pack (e.g. `flow@2026.07.1`) |
+| `packs` | List qualified Code Mode packs |
+| `pull <name>` | Download via local runtime (default Ollama; `--dry-run` for plan only) |
+| `uninstall <name>` | Uninstall a local model (`--dry-run` plan; TTY confirm or `--yes`) |
+| `host-bench` | Approach B measurement arms (`--simulate` default, `--mock`, `--live --model-path`, `--gate`) |
+| `coding-metrics` | Unified host-bench + Fusion FCS/ZNS report (`--out`, `--gate`, `--version`); publish path for release |
+| `catalog` | Live hosted model catalog (cached; not used under `--local`) |
+| `--json` | Machine-readable JSON on stdout |
 
 ```bash
-vg code "rename readCfg to readConfig everywhere it is called" --apply --yes
+vg models pull qwen2.5-coder:7b
+vg models pull qwen2.5-coder:7b --dry-run   # plan only
 ```
 
-Pick a backend with `--provider` and `--model`. No model is bundled, and nothing is installed until you first use a backend that needs it:
-
-- **Local** — `--provider ollama` or `--provider lmstudio` (or `--local` to force on-device only, no network).
-- **Hosted** — any OpenAI-compatible endpoint: `--provider openrouter` / `litellm` / `openai` / `together`. API keys are read from the environment only (e.g. `OPENROUTER_API_KEY`), never passed as flags.
-
-With no `--provider`, `vg code` chooses from what you have already configured (a hosted key, or a locally-pulled model) and never dials a cloud endpoint you didn't set up.
-
 | Flag | Default | Description |
 |------|---------|-------------|
-| `<instruction>` | — | What to change, in plain language |
-| `--provider <id>` | auto | `ollama`, `lmstudio`, `openrouter`, `litellm`, `openai`, `together`, `llama-cpp` |
-| `--model <id>` | — | Model id (or set `VG_CODE_MODEL`) |
-| `--file <path>` | — | Restrict the edit surface to this file (repeatable) |
-| `--budget <n>` | `3000` | Approx context token budget |
-| `--apply` | — | Write the change (still requires `--yes` or a confirmation) |
-| `--yes` | — | Consent to write, or to a first-use package install, non-interactively |
-| `--local` | — | On-device backends only; never touch the network |
-
-Add `--json` for the full machine-readable result (proposed changes, diffs, and the verification summary), or `--out <file>` to write it for CI. Requires a map — run `vg` first if you have not built one.
+| `<name>` | — | Model to pull, e.g. `qwen2.5-coder:7b` |
+| `--runtime <id>` | `ollama` | Runtime to pull with |
+| `--dry-run` | — | Print the plan only; do not download or uninstall |
+| `--yes` | — | Skip interactive confirms (required for non-interactive `uninstall`) |
 
 ---
 
@@ -1068,7 +1153,7 @@ Via stdio (default), your AI assistant spawns the server. Via `--http`, it runs
 
 **Attributing CLI calls.** The MCP path detects the calling client automatically from the connection handshake. For CLI calls, pass `--client=<ai>` (e.g. `vg "how does auth work" --client=claude`) so the call is attributed in `vg savings` and any shared stats — this is what `vg install` writes into each assistant's skill. Without `--client`, a bare `vg ask` records nothing.
 
-**The map stays fresh while you (or your AI) edit code.** Each tool call runs a cheap stat-only freshness check against the last build; when files really changed, the server rebuilds the map incrementally in-process — only changed files re-parse — and answers from the updated graph. Probes are debounced with a self-tuning cadence (2s floor, scaling with measured probe cost so probing never exceeds a few percent of serve time even on very large repos), rebuilds are single-flight and cross-process locked, and touch-only changes (a `git checkout`, a re-save with identical content) are recognized by content hash and never trigger a rebuild. There is no filesystem watcher and no daemon: freshness is checked exactly when it matters — at query time. The server also hot-reloads `graph.json` whenever it changes on disk, so an external `vg` build is picked up on the next call too.
+**The 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: freshness is checked exactly when it matters — at query time. (`vg daemon` is a separate optional process for multi-workspace IDE/agent sessions; `vg serve` does not require it.) 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:
 
@@ -1185,6 +1270,126 @@ Add `--json` for machine-readable output.
 
 ---
 
+## Diagnostics, IDE & runtime
+
+Setup health, IDE language server, local workspace daemon, and context-policy pins.
+
+**Typical path:** `vg doctor` → `vg lsp` → `vg daemon`
+
+### vg daemon
+
+Local workspace daemon for multi-root graph sessions used by IDE extensions and coding agents. Tracks registered repository roots, can load a built map into an in-memory active graph, and answers structural queries and impact over a local socket. Does not rewrite your source tree.
+
+Most developers never need this directly — Vibgrate for VS Code and `vg code` attach when needed. Use the CLI for explicit control, multi-root federation, or scripting.
+
+```bash
+vg daemon status
+vg daemon ensure
+vg daemon start
+vg daemon register
+vg daemon list
+vg daemon federation
+vg daemon publish
+vg daemon query "<text>"
+vg daemon impact <symbol>
+vg daemon graphs
+```
+
+| Subcommand | Description |
+|------------|-------------|
+| `status` | Whether the daemon is running and how many workspaces it tracks |
+| `start` | Run in the foreground (Ctrl-C to stop) |
+| `ensure` | Start in the background if not already running (idempotent; for hosts and agents) |
+| `register [root]` | Register the current (or given) repository with a running daemon |
+| `list` | List registered workspaces |
+| `federation [root]` | Register a multi-root federation from `.vibgrate/federation.json` (or primary cwd) |
+| `publish [root]` | Load the workspace code map into the daemon active graph (run `vg build` first) |
+| `query <query...>` | Lexical/structural query against the active graph |
+| `impact <symbol>` | Blast radius for a symbol in the active graph |
+| `graphs` | List multi-branch graph slots currently resident |
+
+| Flag | Description |
+|------|-------------|
+| `--socket <path>` | Override the local socket path |
+| `--repository-id <id>` | On `query` / `impact` / `graphs`: target a workspace id from `vg daemon list` |
+| `--git-ref <ref>` | On `publish` / `query` / `impact`: branch or SHA |
+| `--limit <n>` | On `query`: max matches (default 12) |
+| `--depth <n>` | On `impact`: max dependency depth (default 4) |
+| `--json` | Machine-readable JSON on stdout |
+
+Typical host flow:
+
+```bash
+vg build
+vg daemon ensure
+vg daemon publish
+vg daemon query "payment service"
+```
+
+---
+
+### vg doctor
+
+One read-only diagnostic pass over setup: which config file won, which credential source won (secrets never printed), whether a code map exists and how fresh it is, hosted catalog reachability, what `vg install` would register as the MCP launch, telemetry opt-outs, and **local inference** (Code Mode recommendation from free RAM/VRAM, weight catalog pin status, warm host pool size, isolation / sampler env). Prints state; changes nothing.
+
+```bash
+vg doctor
+vg doctor --json
+vg doctor --local
+```
+
+| Flag | Description |
+|------|-------------|
+| `--json` | Machine-readable JSON on stdout |
+| `--local` | Skip the hosted reachability probe |
+| `-C, --cwd <dir>` | Run as if started in that directory |
+
+---
+
+### vg lsp
+
+Start the Vibgrate language server over **stdio** — the shared engine behind **Vibgrate for VS Code** and other thin IDE clients. Editors spawn this; humans rarely run it by hand.
+
+```bash
+vg lsp
+vg lsp --diagnostics
+vg lsp --no-graph
+vg lsp --no-semantic
+vg lsp --local
+```
+
+| Flag | Description |
+|------|-------------|
+| `--diagnostics` | Also publish Problems-panel diagnostics (EOL runtime, unmaintained packages, license change). **Off by default** — drift is not a defect, and the Problems panel is not filled by default. |
+| `--no-graph` | Skip the local code graph entirely: no background build; graph queries report it as turned off |
+| `--no-semantic` | Never use semantic search for graph queries (lexical only; embedding model is not downloaded) |
+| `--local` | Never touch the network (air-gapped editor sessions) |
+
+The process owns stdin/stdout until the client sends `shutdown` + `exit`. Speaks standard LSP plus a custom `vibgrate/score` notification carrying the DriftScore and its **band** (never a colour) so clients can theme correctly.
+
+---
+
+### vg policy
+
+Show the production **context-policy** pin used by VG Code ranking, and verify a signed `context-policy-patch/0` JSON file before any release that would bump it. Learning never mutates production policy from a single task.
+
+This is not the hosted workspace policy UI in Vibgrate Cloud (banned packages, drift budgets). For dependency bans in CI, use `vg drift --fail-on standards` with a committed standards file.
+
+```bash
+vg policy
+vg policy --json
+vg policy verify ./context-policy-patch.json
+```
+
+| Subcommand | Description |
+|------------|-------------|
+| *(default)* | Print production pin and ranking version |
+| `verify <file>` | Verify a `context-policy-patch/0` JSON file (hash + optional signature + production gate) |
+
+Exit non-zero from `verify` when the production gate is not ready (so CI can block a premature bump).
+
+---
+
 ## Drift Baselines & Fitness Functions
 
 Vibgrate stores scan state under `.vibgrate/`: