@vibgrate/cli 2026.702.2 → 2026.703.3

package/dist/index.js

@@ -1 +1,42 @@
-export{Z as runScan}from'./chunk-GGDB72YE.js';export{i as computeDriftScore,v as formatMarkdown,u as formatSarif,t as formatText,j as generateFindings}from'./chunk-OQSVJXWJ.js';import'./chunk-MKDRULJ6.js';import'./chunk-XTHPCEME.js';import'./chunk-EK7ODJWE.js';
+export { ASSISTANTS, FREE_PACK, GraphIndex, GraphSource, SCHEMA_VERSION, SKIP_DIRS, TOOLS, UsageError, addLibrary, analyze, applyCoverage, applyStaticTestLinkage, assistantById, buildFacts, buildGraph, buildModuleResolver, cosine, coveringTests, createServer, decodeScipIndex, defaultGraphPath, inventory as dependencyInventory, detectRunner, discover, discoverModels, driftCount, driftFor, enrichOnline, exportGraph, findNodes, formatForExt, getNodeEmbeddings, groundGraph, hasDrift, identifierParts, impactOf, installAssistant, isTestFile, libId, loadCatalog, loadCoverage, loadEmbedder, loadGraph, loadSnapshot, nodeById, nodeEmbedText, parseGraph, parseJsonc, probeFreshness, queryGraph, queryGraphSemantic, readDoc, readSavings, recordSaving, refreshIfStale, relativeResolver, renderHtml, renderReport, resolveLib, resolveOne, saveCatalog, savingsRecorded, scipEdges, serializeGraph, serveStdio, shortestPath, stableStringify, testsToRun, uninstallAssistant, verifyDeterminism, vibgrateDir, writeArtifacts, writeSnapshot } from './chunk-J4DFLN2Q.js';
+export { LANGUAGES, allLanguageIds, grammarsSourceDir, langById, langForExtension, parseSource } from './chunk-X5YT263H.js';
+export { VERSION } from './chunk-2PJRXVUW.js';
+import { redactUrlCredentials, redactSecrets } from './chunk-RXP66R2E.js';
+import './chunk-4M2MUQRO.js';
+import { execFileSync } from 'child_process';
+
+function buildEnvelope(root, graph, scanIngestId) {
+  const sha = git(root, ["rev-parse", "HEAD"]) ?? "0000000000000000000000000000000000000000";
+  const branch = git(root, ["rev-parse", "--abbrev-ref", "HEAD"]) ?? "HEAD";
+  const remoteUrl = git(root, ["config", "--get", "remote.origin.url"]) ?? void 0;
+  return {
+    schemaVersion: "vg-graph/1.0",
+    artifactType: "graph",
+    scanIngestId,
+    vcs: { sha, shortSha: sha.slice(0, 12), branch },
+    repository: remoteUrl ? { remoteUrl: redactUrlCredentials(remoteUrl) } : void 0,
+    generatedAt: graph.generatedAt,
+    graph: redactGraph(graph)
+  };
+}
+function redactGraph(graph) {
+  return {
+    ...graph,
+    nodes: graph.nodes.map((n) => {
+      const signature = n.signature ? redactSecrets(n.signature) : n.signature;
+      const doc = n.doc ? redactSecrets(n.doc) : n.doc;
+      return signature !== n.signature || doc !== n.doc ? { ...n, signature, doc } : n;
+    })
+  };
+}
+function git(root, args) {
+  try {
+    return execFileSync("git", args, { cwd: root, encoding: "utf8" }).trim() || null;
+  } catch {
+    return null;
+  }
+}
+
+export { buildEnvelope, redactGraph };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/engine/push.ts"],"names":[],"mappings":";;;;;;;AAsBO,SAAS,aAAA,CAAc,IAAA,EAAc,KAAA,EAAgB,YAAA,EAA4C;AACtG,EAAA,MAAM,MAAM,GAAA,CAAI,IAAA,EAAM,CAAC,WAAA,EAAa,MAAM,CAAC,CAAA,IAAK,0CAAA;AAChD,EAAA,MAAM,MAAA,GAAS,IAAI,IAAA,EAAM,CAAC,aAAa,cAAA,EAAgB,MAAM,CAAC,CAAA,IAAK,MAAA;AACnE,EAAA,MAAM,SAAA,GAAY,IAAI,IAAA,EAAM,CAAC,UAAU,OAAA,EAAS,mBAAmB,CAAC,CAAA,IAAK,MAAA;AACzE,EAAA,OAAO;AAAA,IACL,aAAA,EAAe,cAAA;AAAA,IACf,YAAA,EAAc,OAAA;AAAA,IACd,YAAA;AAAA,IACA,GAAA,EAAK,EAAE,GAAA,EAAK,QAAA,EAAU,IAAI,KAAA,CAAM,CAAA,EAAG,EAAE,CAAA,EAAG,MAAA,EAAO;AAAA,IAC/C,YAAY,SAAA,GAAY,EAAE,WAAW,oBAAA,CAAqB,SAAS,GAAE,GAAI,MAAA;AAAA,IACzE,aAAa,KAAA,CAAM,WAAA;AAAA,IACnB,KAAA,EAAO,YAAY,KAAK;AAAA,GAC1B;AACF;AAOO,SAAS,YAAY,KAAA,EAAyB;AACnD,EAAA,OAAO;AAAA,IACL,GAAG,KAAA;AAAA,IACH,KAAA,EAAO,KAAA,CAAM,KAAA,CAAM,GAAA,CAAI,CAAC,CAAA,KAAM;AAC5B,MAAA,MAAM,YAAY,CAAA,CAAE,SAAA,GAAY,cAAc,CAAA,CAAE,SAAS,IAAI,CAAA,CAAE,SAAA;AAC/D,MAAA,MAAM,MAAM,CAAA,CAAE,GAAA,GAAM,cAAc,CAAA,CAAE,GAAG,IAAI,CAAA,CAAE,GAAA;AAC7C,MAAA,OAAO,SAAA,KAAc,CAAA,CAAE,SAAA,IAAa,GAAA,KAAQ,CAAA,CAAE,GAAA,GAAM,EAAE,GAAG,CAAA,EAAG,SAAA,EAAW,GAAA,EAAI,GAAI,CAAA;AAAA,IACjF,CAAC;AAAA,GACH;AACF;AAEA,SAAS,GAAA,CAAI,MAAc,IAAA,EAA+B;AACxD,EAAA,IAAI;AACF,IAAA,OAAO,YAAA,CAAa,KAAA,EAAO,IAAA,EAAM,EAAE,GAAA,EAAK,IAAA,EAAM,QAAA,EAAU,MAAA,EAAQ,CAAA,CAAE,IAAA,EAAK,IAAK,IAAA;AAAA,EAC9E,CAAA,CAAA,MAAQ;AACN,IAAA,OAAO,IAAA;AAAA,EACT;AACF","file":"index.js","sourcesContent":["import { execFileSync } from 'node:child_process';\nimport { redactSecrets, redactUrlCredentials } from '../core-open/utils/redact.js';\nimport type { VgGraph } from '../schema.js';\n\n/**\n * The deferred, decoupled push envelope (VG-PACKAGE-AND-SCHEMA §7). In the open\n * CLI `vg push` is **specified but not built**: it assembles and redacts the\n * envelope and prints a notice, but performs **no network upload**. Nothing in\n * the free path depends on it. Drift-over-time/governance is the separate\n * commercial product.\n */\n\nexport interface GraphUploadEnvelope {\n  schemaVersion: 'vg-graph/1.0';\n  artifactType: 'graph';\n  scanIngestId?: string;\n  vcs: { sha: string; shortSha: string; branch: string };\n  repository?: { name?: string; remoteUrl?: string };\n  generatedAt: string;\n  graph: VgGraph;\n}\n\nexport function buildEnvelope(root: string, graph: VgGraph, scanIngestId?: string): GraphUploadEnvelope {\n  const sha = git(root, ['rev-parse', 'HEAD']) ?? '0000000000000000000000000000000000000000';\n  const branch = git(root, ['rev-parse', '--abbrev-ref', 'HEAD']) ?? 'HEAD';\n  const remoteUrl = git(root, ['config', '--get', 'remote.origin.url']) ?? undefined;\n  return {\n    schemaVersion: 'vg-graph/1.0',\n    artifactType: 'graph',\n    scanIngestId,\n    vcs: { sha, shortSha: sha.slice(0, 12), branch },\n    repository: remoteUrl ? { remoteUrl: redactUrlCredentials(remoteUrl) } : undefined,\n    generatedAt: graph.generatedAt,\n    graph: redactGraph(graph),\n  };\n}\n\n/**\n * Redaction pass (GUARDRAILS §1: redact before storage). The graph is structure,\n * not content, but we defensively scrub any signature/name that matches a\n * credential-shaped pattern, and strip credentials from the remote URL.\n */\nexport function redactGraph(graph: VgGraph): VgGraph {\n  return {\n    ...graph,\n    nodes: graph.nodes.map((n) => {\n      const signature = n.signature ? redactSecrets(n.signature) : n.signature;\n      const doc = n.doc ? redactSecrets(n.doc) : n.doc;\n      return signature !== n.signature || doc !== n.doc ? { ...n, signature, doc } : n;\n    }),\n  };\n}\n\nfunction git(root: string, args: string[]): string | null {\n  try {\n    return execFileSync('git', args, { cwd: root, encoding: 'utf8' }).trim() || null;\n  } catch {\n    return null;\n  }\n}\n"]}

package/dist/parse-worker.d.ts

@@ -0,0 +1,23 @@
+import { F as FileParse } from './types-C6ZyQpa9.js';
+
+/**
+ * tinypool worker entry. Receives a chunk of files, reads and parses each, and
+ * returns the FileParse table. Each worker owns its own web-tree-sitter instance
+ * (initialized lazily inside parseSource/grammars). Results are plain data, so
+ * they serialize cleanly back to the main thread.
+ *
+ * The `--grammars <dir>` override is passed in the payload (env vars don't cross
+ * into worker threads in a controlled way) and applied per worker before parsing.
+ */
+interface ParseTask {
+    rel: string;
+    abs: string;
+    lang: string;
+}
+interface ParsePayload {
+    tasks: ParseTask[];
+    grammarsDir?: string;
+}
+declare function run(payload: ParsePayload): Promise<FileParse[]>;
+
+export { type ParsePayload, type ParseTask, run as default };

package/dist/parse-worker.js

@@ -0,0 +1,32 @@
+import { setGrammarsOverride, parseSource } from './chunk-X5YT263H.js';
+import './chunk-RXP66R2E.js';
+import * as fs from 'fs';
+
+async function run(payload) {
+  setGrammarsOverride(payload.grammarsDir);
+  const out = [];
+  for (const task of payload.tasks) {
+    try {
+      const source = fs.readFileSync(task.abs, "utf8");
+      out.push(await parseSource(task.rel, task.lang, source));
+    } catch (err) {
+      out.push({
+        rel: task.rel,
+        lang: task.lang,
+        hash: "",
+        bytes: 0,
+        defs: [],
+        calls: [],
+        imports: [],
+        heritage: [],
+        guards: [],
+        warnings: [`parse failed: ${err.message}`]
+      });
+    }
+  }
+  return out;
+}
+
+export { run as default };
+//# sourceMappingURL=parse-worker.js.map
+//# sourceMappingURL=parse-worker.js.map

package/dist/parse-worker.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/engine/parse-worker.ts"],"names":[],"mappings":";;;;AA0BA,eAAO,IAA2B,OAAA,EAA6C;AAC7E,EAAA,mBAAA,CAAoB,QAAQ,WAAW,CAAA;AACvC,EAAA,MAAM,MAAmB,EAAC;AAC1B,EAAA,KAAA,MAAW,IAAA,IAAQ,QAAQ,KAAA,EAAO;AAChC,IAAA,IAAI;AACF,MAAA,MAAM,MAAA,GAAY,EAAA,CAAA,YAAA,CAAa,IAAA,CAAK,GAAA,EAAK,MAAM,CAAA;AAC/C,MAAA,GAAA,CAAI,IAAA,CAAK,MAAM,WAAA,CAAY,IAAA,CAAK,KAAK,IAAA,CAAK,IAAA,EAAM,MAAM,CAAC,CAAA;AAAA,IACzD,SAAS,GAAA,EAAK;AACZ,MAAA,GAAA,CAAI,IAAA,CAAK;AAAA,QACP,KAAK,IAAA,CAAK,GAAA;AAAA,QACV,MAAM,IAAA,CAAK,IAAA;AAAA,QACX,IAAA,EAAM,EAAA;AAAA,QACN,KAAA,EAAO,CAAA;AAAA,QACP,MAAM,EAAC;AAAA,QACP,OAAO,EAAC;AAAA,QACR,SAAS,EAAC;AAAA,QACV,UAAU,EAAC;AAAA,QACX,QAAQ,EAAC;AAAA,QACT,QAAA,EAAU,CAAC,CAAA,cAAA,EAAkB,GAAA,CAAc,OAAO,CAAA,CAAE;AAAA,OACrD,CAAA;AAAA,IACH;AAAA,EACF;AACA,EAAA,OAAO,GAAA;AACT","file":"parse-worker.js","sourcesContent":["import * as fs from 'node:fs';\nimport { parseSource } from './parse.js';\nimport { setGrammarsOverride } from './grammars.js';\nimport type { FileParse } from './types.js';\n\n/**\n * tinypool worker entry. Receives a chunk of files, reads and parses each, and\n * returns the FileParse table. Each worker owns its own web-tree-sitter instance\n * (initialized lazily inside parseSource/grammars). Results are plain data, so\n * they serialize cleanly back to the main thread.\n *\n * The `--grammars <dir>` override is passed in the payload (env vars don't cross\n * into worker threads in a controlled way) and applied per worker before parsing.\n */\n\nexport interface ParseTask {\n  rel: string;\n  abs: string;\n  lang: string;\n}\n\nexport interface ParsePayload {\n  tasks: ParseTask[];\n  grammarsDir?: string;\n}\n\nexport default async function run(payload: ParsePayload): Promise<FileParse[]> {\n  setGrammarsOverride(payload.grammarsDir);\n  const out: FileParse[] = [];\n  for (const task of payload.tasks) {\n    try {\n      const source = fs.readFileSync(task.abs, 'utf8');\n      out.push(await parseSource(task.rel, task.lang, source));\n    } catch (err) {\n      out.push({\n        rel: task.rel,\n        lang: task.lang,\n        hash: '',\n        bytes: 0,\n        defs: [],\n        calls: [],\n        imports: [],\n        heritage: [],\n        guards: [],\n        warnings: [`parse failed: ${(err as Error).message}`],\n      });\n    }\n  }\n  return out;\n}\n"]}

package/dist/types-C6ZyQpa9.d.ts

@@ -0,0 +1,168 @@
+/**
+ * The `vg-graph/1.0` on-disk schema.
+ *
+ * This is vg's own open schema (VG-PACKAGE-AND-SCHEMA.md §4) — informed by good
+ * ideas (content-hashed ids, epistemic typing of facts) but standalone and
+ * self-contained. Every collection is deterministically serialized
+ * (sorted keys, stable element order). These TypeScript shapes are normative.
+ */
+declare const SCHEMA_VERSION: "vg-graph/1.0";
+type ResolverKind = 'scip' | 'stackgraph' | 'tsc' | 'heuristic';
+interface Provenance {
+    tool: 'vg';
+    version: string;
+    grammars: Record<string, string>;
+    resolver: ResolverKind[];
+    deep: boolean;
+    semanticModel?: string;
+    corpusHash: string;
+}
+interface GraphMeta {
+    root: string;
+    languages: string[];
+    counts: {
+        nodes: number;
+        edges: number;
+        areas: number;
+        tests: number;
+        untested: number;
+    };
+    cluster: 'leiden' | 'louvain' | 'none';
+    edgeKinds: EdgeKind[];
+}
+type NodeKind = 'file' | 'module' | 'package' | 'class' | 'interface' | 'function' | 'method' | 'property' | 'test' | 'route' | 'component' | 'external';
+interface Span {
+    start: number;
+    end: number;
+}
+interface Centrality {
+    degree: number;
+    pagerank: number;
+    betweenness: number;
+    eigenvector: number;
+}
+interface GraphNode {
+    id: string;
+    kind: NodeKind;
+    name: string;
+    qualifiedName: string;
+    file: string;
+    span: Span;
+    lang: string;
+    visibility?: 'public' | 'private' | 'protected' | 'internal';
+    signature?: string;
+    doc?: string;
+    importance: number;
+    centrality: Centrality;
+    area: number;
+    isHub: boolean;
+    tested: boolean | null;
+    coverage?: number;
+    changeCoupling?: string[];
+}
+type EdgeKind = 'call' | 'import' | 'contains' | 'extends' | 'implements' | 'references' | 'test' | 'coverage';
+interface GraphEdge {
+    id: string;
+    kind: EdgeKind;
+    src: string;
+    dst: string;
+    resolution: ResolverKind;
+    confidence: number;
+    surprise?: number;
+    count?: number;
+}
+interface Area {
+    id: number;
+    label: string;
+    size: number;
+    members: string[];
+    cohesion: number;
+    externalEdges: number;
+}
+type FactKind = 'contract' | 'invariant' | 'characterization';
+type DerivedBy = 'declared' | 'static';
+type FactConfidence = 'Observed' | 'Derived';
+interface Fact {
+    id: string;
+    kind: FactKind;
+    subjectIds: string[];
+    predicate: unknown;
+    derivedBy: DerivedBy;
+    confidence: FactConfidence;
+    evidence: {
+        file: string;
+        span: Span;
+    }[];
+}
+type GroundingKind = 'should_follow' | 'smells_like' | 'relevant_to';
+interface GroundingEdge {
+    src: string;
+    packEntryId: string;
+    kind: GroundingKind;
+    confidence: number;
+    rationale: 'recommended' | 'conjectured';
+    citation: {
+        title: string;
+        url: string;
+    };
+}
+interface VgGraph {
+    schemaVersion: typeof SCHEMA_VERSION;
+    generatedAt: string;
+    provenance: Provenance;
+    meta: GraphMeta;
+    nodes: GraphNode[];
+    edges: GraphEdge[];
+    areas: Area[];
+    facts?: Fact[];
+    grounding?: GroundingEdge[];
+}
+
+/** A definition extracted from one file (pre-resolution, pre-id). */
+interface RawDef {
+    kind: NodeKind;
+    name: string;
+    qualifiedName: string;
+    startLine: number;
+    endLine: number;
+    startByte: number;
+    endByte: number;
+    signature?: string;
+    doc?: string;
+    visibility?: 'public' | 'private' | 'protected' | 'internal';
+}
+interface RawCall {
+    callee: string;
+    byte: number;
+    line: number;
+    /** True when the call site had a receiver/qualifier (`obj.foo()`, `pkg::foo()`); the receiver itself is not captured. */
+    qualified?: boolean;
+}
+interface RawImport {
+    source: string;
+}
+interface RawHeritage {
+    superName: string;
+    byte: number;
+    kind: 'extends' | 'implements';
+}
+interface RawGuard {
+    expr: string;
+    line: number;
+}
+/** The full result of parsing a single file. */
+interface FileParse {
+    rel: string;
+    lang: string;
+    hash: string;
+    bytes: number;
+    defs: RawDef[];
+    calls: RawCall[];
+    imports: RawImport[];
+    heritage: RawHeritage[];
+    guards: RawGuard[];
+    /** Non-fatal issues (e.g. a query that failed to compile for this grammar). */
+    warnings?: string[];
+}
+
+export { type Area as A, type Centrality as C, type DerivedBy as D, type EdgeKind as E, type FileParse as F, type GraphNode as G, type NodeKind as N, type Provenance as P, type ResolverKind as R, SCHEMA_VERSION as S, type VgGraph as V, type GraphEdge as a, type Fact as b, type GroundingKind as c, type GroundingEdge as d, type FactConfidence as e, type FactKind as f, type GraphMeta as g, type Span as h };

package/package.json

@@ -1,9 +1,24 @@
 {
   "name": "@vibgrate/cli",
-  "version": "2026.702.2",
-  "description": "CLI for measuring upgrade drift across Node, .NET, Python & Java projects",
+  "version": "2026.703.3",
+  "description": "vg — local codebase intelligence CLI + MCP server for AI coding agents: deterministic code graph, drift reporting, and version-correct library docs (Apache-2.0)",
   "type": "module",
+  "license": "Apache-2.0",
+  "packageManager": "pnpm@9.0.0",
+  "author": "Vibgrate",
+  "homepage": "https://vibgrate.com",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/vibgrate/cli.git"
+  },
+  "bugs": {
+    "url": "https://github.com/vibgrate/cli/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
   "bin": {
+    "vg": "dist/cli.js",
     "vibgrate": "dist/cli.js"
   },
   "main": "./dist/index.js",
@@ -16,52 +31,72 @@
   },
   "files": [
     "dist",
-    "DOCS.md",
-    "HCS-RUNTIME-SETUP.md",
-    "LICENSE.md"
+    "grammars",
+    "skills",
+    "scripts/postinstall.mjs",
+    "LICENSE",
+    "NOTICE",
+    "README.md",
+    "DOCS.md"
   ],
   "scripts": {
-    "build": "pnpm run build:hcs && tsup && pnpm run bundle:hcs && pnpm test:solutions",
-    "build:only": "pnpm run build:hcs && tsup && pnpm run bundle:hcs",
-    "build:hcs": "pnpm --filter @vibgrate/hcs-node-worker build",
-    "bundle:hcs": "cp ../vibgrate-hcs/node/dist/main.js dist/hcs-worker.js && node scripts/bundle-hcs-wasm.mjs",
+    "build": "pnpm run bundle:grammars && tsup",
+    "bundle:grammars": "node scripts/bundle-grammars.mjs",
+    "stamp:pins": "node scripts/stamp-release-pins.mjs",
+    "check:pins": "node scripts/stamp-release-pins.mjs --check",
+    "demo:svg": "node scripts/gen-demo-svg.mjs",
+    "postinstall": "node scripts/postinstall.mjs",
     "dev": "tsx src/cli.ts",
     "lint": "eslint src",
     "typecheck": "tsc --noEmit",
-    "test": "vitest run",
-    "test:solutions": "tsx test-solutions/test-runner.ts",
-    "test:hcs": "tsx test-hcs/test-runner.ts",
-    "test:fixtures": "tsx test-fixtures/run-tests.ts test",
-    "test:all": "vitest run && pnpm test:solutions && pnpm test:hcs && pnpm test:fixtures"
+    "test": "vitest run"
   },
   "keywords": [
-    "upgrade",
+    "code-graph",
+    "codebase-intelligence",
+    "ast",
+    "tree-sitter",
+    "mcp",
+    "ai-agents",
     "drift",
-    "dependencies",
-    "cli",
-    "node",
-    "dotnet",
-    "sarif"
+    "deterministic",
+    "impact-analysis",
+    "cli"
   ],
-  "author": "Vibgrate",
-  "license": "SEE LICENSE IN LICENSE",
-  "homepage": "https://vibgrate.com",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.19.0",
+    "@noble/hashes": "^2.2.0",
+    "chalk": "^5.3.0",
+    "commander": "^15.0.0",
+    "fast-xml-parser": "^5.0.0",
+    "gpt-tokenizer": "^3.0.0",
+    "graphology": "^0.26.0",
+    "graphology-communities-louvain": "^2.0.2",
+    "graphology-metrics": "^2.4.0",
+    "graphology-shortest-path": "^2.1.0",
+    "graphology-traversal": "^0.3.1",
+    "ignore": "^7.0.0",
+    "semver": "^7.8.5",
+    "smol-toml": "^1.7.0",
+    "tinypool": "^2.1.0",
+    "tree-sitter-wasms": "^0.1.13",
+    "typescript": "^6.0.0",
+    "web-tree-sitter": "0.25.10",
+    "yaml": "^2.6.1"
+  },
+  "optionalDependencies": {
+    "fastembed": "^2.1.0"
+  },
   "devDependencies": {
     "@types/node": "^26.1.0",
     "@types/semver": "^7.5.0",
+    "@typescript-eslint/eslint-plugin": "^8.61.0",
+    "@typescript-eslint/parser": "^8.62.1",
     "eslint": "^10.6.0",
-    "fast-xml-parser": "^5.9.3",
-    "semver": "^7.8.5",
+    "graphology-types": "^0.24.8",
     "tsup": "^8.0.0",
     "tsx": "^4.22.4",
-    "vitest": "^2.0.0"
-  },
-  "dependencies": {
-    "chalk": "^5.3.0",
-    "commander": "^15.0.0",
-    "typescript": "^5.4.0",
-    "zod": "^4.4.3",
-    "yaml": "^2.6.1"
+    "vitest": "^4.0.0"
   },
   "engines": {
     "node": ">=20.0.0"

package/scripts/postinstall.mjs

@@ -0,0 +1,84 @@
+#!/usr/bin/env node
+// Checks whether `vg` is already occupied by another tool on PATH.
+// If it is, prints a one-time notice that `vibgrate` is an identical alias.
+// Exits 0 regardless — a conflict is not an install failure.
+
+import { execFileSync } from 'node:child_process';
+import { realpathSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import * as path from 'node:path';
+
+const isWindows = process.platform === 'win32';
+
+// Resolve the directory this package installed its own bin links into.
+// __filename → scripts/postinstall.mjs → ../../dist/cli.js (the actual binary)
+const pkgRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const ownBin = path.join(pkgRoot, 'dist', 'cli.js');
+
+function which(cmd) {
+  try {
+    const out = execFileSync(
+      isWindows ? 'where' : 'which',
+      [cmd],
+      { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] },
+    ).trim().split(/\r?\n/)[0];
+    return out || null;
+  } catch {
+    return null;
+  }
+}
+
+function realpath(p) {
+  try { return realpathSync(p); } catch { return p; }
+}
+
+const vgOnPath = which('vg');
+
+if (!vgOnPath) {
+  // `vg` not on PATH yet (e.g. local install, PATH not updated) — nothing to warn about.
+  process.exit(0);
+}
+
+// Resolve symlinks so we compare actual files, not wrapper scripts.
+const resolvedVg = realpath(vgOnPath);
+const resolvedOwn = realpath(ownBin);
+
+if (resolvedVg === resolvedOwn) {
+  // Our binary is the one that wins — no conflict.
+  process.exit(0);
+}
+
+// Not a symlink to us — but pnpm/bun/yarn (and every Windows install) generate
+// script *shims*, not symlinks. Treat a shim as ours when its resolved path
+// lives in our package directory or its first bytes reference the package;
+// otherwise every Windows/pnpm user gets a false "vg is taken" warning.
+if (/[\\/]@vibgrate[\\/]cli[\\/]/.test(resolvedVg)) process.exit(0);
+try {
+  const { readFileSync } = await import('node:fs');
+  const head = readFileSync(resolvedVg, 'utf8').slice(0, 2048);
+  if (head.includes('@vibgrate/cli')) process.exit(0);
+} catch {
+  // Unreadable → cannot verify; keep the (possibly false) warning below rather
+  // than staying silent about a real conflict.
+}
+
+// Something else owns `vg` on this machine.
+console.log('');
+console.log(
+  '\x1b[33m⚠\x1b[0m  \x1b[1m@vibgrate/cli:\x1b[0m \x1b[33mThe `vg` command is already used by another tool on this system.\x1b[0m',
+);
+console.log(
+  '   Use \x1b[1mvibgrate\x1b[0m instead — it is installed alongside `vg` and is identical in every way.',
+);
+console.log('');
+console.log('   Examples:');
+console.log('     vibgrate scan');
+console.log('     vibgrate build');
+console.log('     vibgrate serve');
+console.log('');
+console.log(
+  '   See https://vibgrate.com/cli for full documentation.',
+);
+console.log('');
+
+process.exit(0);

package/skills/README.md

@@ -0,0 +1,58 @@
+# Vibgrate CLI skills for AI agents
+
+A **skill** is a ready-made instruction file (plus local MCP wiring) that teaches
+an AI coding assistant to use the `vg` code graph instead of grepping or reading
+many files — cheaper, more relevant context.
+
+You don't write these by hand. One command installs them:
+
+```bash
+vg install --all          # every supported assistant
+vg install claude         # or one at a time
+vg install --list         # show the support matrix
+vg uninstall claude       # remove (add --purge to delete the skill file)
+```
+
+Each install is idempotent and repo-local (team-shareable). It writes:
+
+1. A **skill file** (`SKILL.md`) — see [`vg/SKILL.md`](./vg/SKILL.md) for the
+   canonical content.
+2. A **local MCP server** registration (`vg serve`) where the assistant supports
+   it — read-only, auto-approvable tools.
+3. An **advisory nudge** in the assistant's instructions file (opt-out, never
+   "mandatory").
+
+## Supported assistants
+
+| id | Assistant | Skill | MCP | Nudge |
+| --- | --- | :---: | :---: | :---: |
+| `claude` | Claude Code | ✓ | ✓ | ✓ |
+| `cursor` | Cursor | — | ✓ | ✓ |
+| `windsurf` | Windsurf | — | ✓ | ✓ |
+| `vscode` | VS Code (Copilot Chat) | — | ✓ | ✓ |
+| `codex` | Codex | ✓ | — | ✓ |
+| `gemini` | Gemini CLI | ✓ | — | ✓ |
+| `opencode` | OpenCode | ✓ | — | ✓ |
+| `kilo` | Kilo Code | ✓ | — | ✓ |
+| `aider` | Aider | ✓ | — | ✓ |
+| `factory` | Factory Droid | ✓ | — | ✓ |
+| `trae` | Trae | ✓ | — | ✓ |
+| `kiro` | Kiro | ✓ | — | ✓ |
+| `amp` | Amp | ✓ | — | ✓ |
+| `kimi` | Kimi Code | ✓ | — | ✓ |
+| `codebuddy` | CodeBuddy | ✓ | — | ✓ |
+| `copilot-cli` | GitHub Copilot CLI | ✓ | — | ✓ |
+| `pi` | Pi | ✓ | — | ✓ |
+| `devin` | Devin CLI | ✓ | — | ✓ |
+| `hermes` | Hermes | ✓ | — | ✓ |
+| `openclaw` | OpenClaw | ✓ | — | ✓ |
+| `agents` | Agent-Skills (generic) | ✓ | — | ✓ |
+
+MCP registration for the skill-only assistants is added as their formats
+stabilise; the skill + nudge work today. Run `vg install --list` for the live
+matrix.
+
+The canonical skill content is generated from
+[`src/install/content.ts`](../src/install/content.ts) so the published file and
+the installed file never drift. See also the
+[skills page](https://vibgrate.com/skills).

package/skills/vg/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: vg
+description: Query the local code graph (vg) for structure, impact, and navigation instead of grepping/reading many files.
+---
+
+# vg — the code map
+
+This repo has a deterministic code graph built by `vg`. Prefer it over reading or
+grepping many files — it is smaller, more relevant context, and free.
+
+## When to use it
+
+- **Understand code:** `vg "<question>"` returns a budget-bounded, fact-annotated
+  context block. Start here instead of opening files blindly.
+- **Find a symbol:** `vg show <name>` — what it is, what it calls, what calls it.
+- **Before changing something:** `vg impact <name>` — what breaks if you change it.
+- **Navigate:** `vg path <A> <B>`, `vg tree <name>`, `vg hubs`, `vg areas`.
+
+## Dependencies & library docs
+
+- **Upgrade drift:** `vg drift` lists what is outdated across dependencies
+  (offline; `--online` for currency). `vg scan` scores upgrade drift and
+  `vg report` renders it (text | json | sarif | md).
+- **Version-correct docs:** `vg lib <name>` returns drift-annotated, version-
+  specific usage docs for a library — inject these instead of guessing an API.
+
+## Via MCP
+
+If the `vg` MCP server is registered, call its read-only tools directly:
+`query_graph`, `get_node`, `impact_of`, `find_path`, `list_hubs`, `list_areas`,
+`get_graph_summary`. They are side-effect-free and auto-approvable.
+
+## Keep it fresh
+
+Run `vg` after pulling or making structural changes. The map lives at
+`.vibgrate/graph.json` and is deterministic (byte-identical across machines).
+
+---
+
+> This is the canonical reference copy. `vg install <assistant>` writes this skill
+> into each assistant's expected location and registers the local MCP server. The
+> source of truth is `src/install/content.ts`.