@vibgrate/cli 2026.715.1 → 2026.718.2

package/dist/{chunk-D4BPWARI.js → chunk-H5M7CXE6.js}

@@ -1,5 +1,5 @@
 import { hashString, langById, shortId, canonicalize, grammarSetVersion, hashBytes, langForExtension, setGrammarsOverride, parseSource } from './chunk-VFO5UDAT.js';
-import { writeTextFile, pathExists, readJsonFile, loadConfig, computeUpgradeImpact, getChangelogSignals, gitHistoryAvailable, buildVersionTimelines, findPackageTimeline, severityRank, projectTypeToVulnEcosystem, VERSION } from './chunk-C5AVF7PT.js';
+import { writeTextFile, pathExists, readJsonFile, loadConfig, computeUpgradeImpact, getChangelogSignals, gitHistoryAvailable, buildVersionTimelines, findPackageTimeline, severityRank, projectTypeToVulnEcosystem, VERSION } from './chunk-RME7BFMU.js';
 import * as fs19 from 'fs';
 import { spawnSync, execFileSync } from 'child_process';
 import * as path19 from 'path';
@@ -11,8 +11,9 @@ import betweenness from 'graphology-metrics/centrality/betweenness.js';
 import eigenvector from 'graphology-metrics/centrality/eigenvector.js';
 import louvain from 'graphology-communities-louvain';
 import * as os from 'os';
-import { fileURLToPath } from 'url';
+import { pathToFileURL, fileURLToPath } from 'url';
 import ts from 'typescript';
+import { createRequire } from 'module';
 import { bidirectional } from 'graphology-shortest-path/unweighted.js';
 import * as crypto from 'crypto';
 import { createHash } from 'crypto';
@@ -2678,7 +2679,7 @@ async function loadEmbedder(options = {}) {
     options.onUnavailable?.(reason);
     return null;
   };
-  const mod = await import('fastembed').catch(() => null);
+  const mod = await importEmbedBackend();
   if (!mod?.FlagEmbedding) return fail("not-installed");
   const cache = modelCacheDir();
   try {
@@ -2718,6 +2719,19 @@ async function loadEmbedder(options = {}) {
     return fail(isPermissionError(e) ? "no-permission" : "download-failed");
   }
 }
+async function importEmbedBackend() {
+  const hostDir = process.env.VIBGRATE_EMBEDDER_PATH;
+  if (hostDir) {
+    try {
+      const req = createRequire(path19.join(hostDir, "package.json"));
+      const mod = await import(pathToFileURL(req.resolve("fastembed")).href);
+      const resolved = mod?.FlagEmbedding ? mod : mod?.default;
+      if (resolved?.FlagEmbedding) return resolved;
+    } catch {
+    }
+  }
+  return await import('fastembed').catch(() => null);
+}
 function embedInitTimeoutMs() {
   const n = Number(process.env.VG_EMBED_TIMEOUT_MS);
   return Number.isFinite(n) && n > 0 ? n : 6e4;
@@ -6582,11 +6596,14 @@ var TOOLS = [
   },
   {
     name: "resolve_library",
-    description: "Resolve a library to its canonical id and the version YOUR project uses (drift-annotated).",
+    description: "Resolve a library to its canonical id and the version YOUR project uses (drift-annotated). Call once per library and reuse the returned targetId for every library_docs follow-up \u2014 never guess an id.",
     // Canonical §4: `query` (+ optional `context_project`). `name` kept as a back-compat alias.
     inputSchema: obj(
       {
-        query: { type: "string", description: "library name or query" },
+        query: {
+          type: "string",
+          description: 'the package name as written in the dependency file. Good: "react-hook-form". Bad: "forms"'
+        },
         name: { type: "string" },
         context_project: { type: "string" }
       },
@@ -6631,17 +6648,22 @@ var TOOLS = [
   },
   {
     name: "library_docs",
-    description: "Version-correct usage docs for a library, sliced to a token budget.",
+    description: "Version-correct usage docs for a library, sliced to a token budget \u2014 official content matched to the version this project has installed, not web-search results. Ask a focused question via query; one call usually answers. After 2 calls without the section you need, stop and read the package source under node_modules instead of searching again.",
     // Canonical §4: `targetId`/`query`, `verbosity`, `max_tokens`. `name`/`tokens` kept as aliases.
     inputSchema: obj(
       {
-        targetId: { type: "string", description: "id from resolve_library" },
-        query: { type: "string", description: "library name or query" },
+        targetId: { type: "string", description: "id from resolve_library (preferred over query)" },
+        query: {
+          type: "string",
+          description: 'the library plus the specific need. Good: "zod refine custom error message". Bad: "zod" or "docs"'
+        },
         name: { type: "string" },
         context_project: { type: "string" },
         verbosity: { type: "string", enum: ["concise", "balanced", "exhaustive"] },
-        max_tokens: { type: "number", description: "token budget" },
-        tokens: { type: "number" },
+        // Tolerant on purpose: models often send budgets as strings — the
+        // handler coerces, so don't fail validation over "4000" vs 4000.
+        max_tokens: { type: ["number", "string"], description: "token budget (a numeric string is accepted)" },
+        tokens: { type: ["number", "string"] },
         enterprise_strict: { type: "boolean" },
         follow_up: { type: "boolean" }
       },
@@ -6867,7 +6889,7 @@ function createServer(source, opts = {}) {
       // Routing guidance once at the server level (hosts that surface
       // `instructions` get it at zero per-step schema cost): the flashlight
       // vs the map.
-      instructions: 'vg is a code map. Use search_symbols to find a known name or literal string fast \u2014 a multi-word/quoted phrase runs a complete literal sweep and reports totalTextMatches, so reach for it instead of grep even for plain-string "find every occurrence" lookups. Use orient/query_graph for meaning: symptoms, relationships, and what-breaks-if. Responses are concise by default; pass response_format:"detailed" only when a node proves load-bearing. Navigate as little as possible: one good search/query usually locates the code. As soon as you have the file and line, read that file and make the edit \u2014 do not call further graph tools unless the edit fails or the match was wrong.'
+      instructions: 'vg is a code map. Use search_symbols to find a known name or literal string fast \u2014 a multi-word/quoted phrase runs a complete literal sweep and reports totalTextMatches, so reach for it instead of grep even for plain-string "find every occurrence" lookups. Use orient/query_graph for meaning: symptoms, relationships, and what-breaks-if. Responses are concise by default; pass response_format:"detailed" only when a node proves load-bearing. Navigate as little as possible: one good search/query usually locates the code. As soon as you have the file and line, read that file and make the edit \u2014 do not call further graph tools unless the edit fails or the match was wrong. For how-do-I-use-this-library questions call resolve_library once, then library_docs with the returned targetId and a focused query: the docs are official and matched to the version THIS project has installed (drift-annotated) \u2014 prefer them over web search or training-data recall when they conflict. Skip them for language built-ins or APIs already shown in context. If two library_docs calls have not surfaced the section you need, read the package source under node_modules instead of searching again.'
     }
   );
   server.setRequestHandler(ListToolsRequestSchema, async () => ({
@@ -7029,6 +7051,21 @@ tools improved):
 - **Version-correct docs:** \`vg lib <name>\` returns drift-annotated, version-
   specific usage docs for a library \u2014 inject these instead of guessing an API.
 
+### Library-docs discipline
+
+When a task needs a library's API, use the docs tools before web search or
+training-data recall \u2014 they are official content matched to the version **this
+project has installed**, and they win when the two conflict.
+
+- **Workflow:** \`resolve_library\` once per library, then \`library_docs\` with the
+  returned \`targetId\` and a focused query (good: "zod refine custom error
+  message"; bad: "zod"). Never guess a targetId.
+- **Budget:** at most **3 docs calls per task**. If 2 \`library_docs\` calls have
+  not surfaced the section you need, read the package source under
+  \`node_modules\` instead of searching again.
+- **Skip the docs tools** for language built-ins, stable well-known syntax, or
+  an API already shown in the current context \u2014 they add nothing there.
+
 ## Keep it fresh
 
 The map keeps itself fresh: \`vg ask\` and the MCP tools detect changed files
@@ -7078,60 +7115,96 @@ var ASSISTANTS = [
     label: "Claude Code",
     skill: ".claude/skills/vg/SKILL.md",
     mcp: { file: ".mcp.json", key: "mcpServers" },
-    nudge: { file: "CLAUDE.md", kind: "block" }
+    nudge: { file: "CLAUDE.md", kind: "block" },
+    markers: ["CLAUDE.md", ".claude"],
+    homeMarkers: [".claude", ".claude.json"],
+    bin: ["claude"]
   },
   {
     id: "cursor",
     label: "Cursor",
     mcp: { file: ".cursor/mcp.json", key: "mcpServers" },
-    nudge: { file: ".cursor/rules/vg.mdc", kind: "file" }
+    nudge: { file: ".cursor/rules/vg.mdc", kind: "file" },
+    markers: [".cursor", ".cursorrules"],
+    homeMarkers: [".cursor"],
+    bin: ["cursor-agent"]
   },
   {
     id: "windsurf",
     label: "Windsurf",
     mcp: { file: ".windsurf/mcp.json", key: "mcpServers" },
-    nudge: { file: ".windsurf/rules/vg.md", kind: "file" }
+    nudge: { file: ".windsurf/rules/vg.md", kind: "file" },
+    markers: [".windsurf", ".windsurfrules"],
+    homeMarkers: [".codeium/windsurf"]
   },
   {
     id: "vscode",
     label: "VS Code (Copilot Chat)",
     mcp: { file: ".vscode/mcp.json", key: "servers", vscode: true },
-    nudge: { file: ".github/copilot-instructions.md", kind: "block" }
+    nudge: { file: ".github/copilot-instructions.md", kind: "block" },
+    markers: [".github/copilot-instructions.md"]
   },
   {
     id: "codex",
     label: "Codex",
     skill: ".codex/skills/vg/SKILL.md",
-    nudge: { file: "AGENTS.md", kind: "block" }
+    nudge: { file: "AGENTS.md", kind: "block" },
+    markers: [".codex"],
+    homeMarkers: [".codex"],
+    bin: ["codex"]
   },
   {
     id: "gemini",
     label: "Gemini CLI",
     skill: ".gemini/skills/vg/SKILL.md",
-    nudge: { file: "GEMINI.md", kind: "block" }
+    nudge: { file: "GEMINI.md", kind: "block" },
+    markers: ["GEMINI.md", ".gemini"],
+    homeMarkers: [".gemini"],
+    bin: ["gemini"]
   },
   // Skill + advisory AGENTS.md nudge (the broad-reach common denominator). MCP
   // registration for these hosts is host-specific and added as their formats
   // stabilise; the skill + nudge work today.
-  { id: "opencode", label: "OpenCode", skill: ".opencode/skills/vg/SKILL.md", nudge: { file: "AGENTS.md", kind: "block" } },
-  { id: "kilo", label: "Kilo Code", skill: ".kilo/skills/vg/SKILL.md", nudge: { file: "AGENTS.md", kind: "block" } },
-  { id: "aider", label: "Aider", skill: ".aider/vg/SKILL.md", nudge: { file: "AGENTS.md", kind: "block" } },
-  { id: "factory", label: "Factory Droid", skill: ".factory/skills/vg/SKILL.md", nudge: { file: "AGENTS.md", kind: "block" } },
-  { id: "trae", label: "Trae", skill: ".trae/skills/vg/SKILL.md", nudge: { file: "AGENTS.md", kind: "block" } },
-  { id: "kiro", label: "Kiro", skill: ".kiro/skills/vg/SKILL.md", nudge: { file: ".kiro/steering/vg.md", kind: "file" } },
-  { id: "amp", label: "Amp", skill: ".agents/skills/vg/SKILL.md", nudge: { file: "AGENTS.md", kind: "block" } },
-  { id: "kimi", label: "Kimi Code", skill: ".kimi/skills/vg/SKILL.md", nudge: { file: "AGENTS.md", kind: "block" } },
-  { id: "codebuddy", label: "CodeBuddy", skill: ".codebuddy/skills/vg/SKILL.md", nudge: { file: "CODEBUDDY.md", kind: "block" } },
-  { id: "copilot-cli", label: "GitHub Copilot CLI", skill: ".copilot/skills/vg/SKILL.md", nudge: { file: "AGENTS.md", kind: "block" } },
-  { id: "pi", label: "Pi", skill: ".pi/agent/skills/vg/SKILL.md", nudge: { file: "AGENTS.md", kind: "block" } },
-  { id: "devin", label: "Devin CLI", skill: ".devin/skills/vg/SKILL.md", nudge: { file: "AGENTS.md", kind: "block" } },
-  { id: "hermes", label: "Hermes", skill: ".hermes/skills/vg/SKILL.md", nudge: { file: "AGENTS.md", kind: "block" } },
-  { id: "openclaw", label: "OpenClaw", skill: ".openclaw/skills/vg/SKILL.md", nudge: { file: "AGENTS.md", kind: "block" } },
-  { id: "agents", label: "Agent-Skills (generic)", skill: ".agents/skills/vg/SKILL.md", nudge: { file: "AGENTS.md", kind: "block" } }
+  { id: "grok", label: "Grok CLI", skill: ".grok/skills/vg/SKILL.md", nudge: { file: "AGENTS.md", kind: "block" }, markers: [".grok", "GROK.md"], homeMarkers: [".grok"], bin: ["grok"] },
+  { id: "opencode", label: "OpenCode", skill: ".opencode/skills/vg/SKILL.md", nudge: { file: "AGENTS.md", kind: "block" }, markers: [".opencode", "opencode.json"], homeMarkers: [".config/opencode"], bin: ["opencode"] },
+  { id: "kilo", label: "Kilo Code", skill: ".kilo/skills/vg/SKILL.md", nudge: { file: "AGENTS.md", kind: "block" }, markers: [".kilo", ".kilocode"], homeMarkers: [".kilocode"] },
+  { id: "aider", label: "Aider", skill: ".aider/vg/SKILL.md", nudge: { file: "AGENTS.md", kind: "block" }, markers: [".aider", ".aider.conf.yml"], homeMarkers: [".aider.conf.yml"], bin: ["aider"] },
+  { id: "factory", label: "Factory Droid", skill: ".factory/skills/vg/SKILL.md", nudge: { file: "AGENTS.md", kind: "block" }, markers: [".factory"], homeMarkers: [".factory"], bin: ["droid"] },
+  { id: "trae", label: "Trae", skill: ".trae/skills/vg/SKILL.md", nudge: { file: "AGENTS.md", kind: "block" }, markers: [".trae"], homeMarkers: [".trae"] },
+  { id: "kiro", label: "Kiro", skill: ".kiro/skills/vg/SKILL.md", nudge: { file: ".kiro/steering/vg.md", kind: "file" }, markers: [".kiro"], homeMarkers: [".kiro"] },
+  { id: "amp", label: "Amp", skill: ".agents/skills/vg/SKILL.md", nudge: { file: "AGENTS.md", kind: "block" }, homeMarkers: [".config/amp"], bin: ["amp"] },
+  { id: "kimi", label: "Kimi Code", skill: ".kimi/skills/vg/SKILL.md", nudge: { file: "AGENTS.md", kind: "block" }, markers: [".kimi"], homeMarkers: [".kimi"] },
+  { id: "codebuddy", label: "CodeBuddy", skill: ".codebuddy/skills/vg/SKILL.md", nudge: { file: "CODEBUDDY.md", kind: "block" }, markers: ["CODEBUDDY.md", ".codebuddy"], homeMarkers: [".codebuddy"] },
+  { id: "copilot-cli", label: "GitHub Copilot CLI", skill: ".copilot/skills/vg/SKILL.md", nudge: { file: "AGENTS.md", kind: "block" }, markers: [".copilot"], homeMarkers: [".copilot"], bin: ["copilot"] },
+  { id: "pi", label: "Pi", skill: ".pi/agent/skills/vg/SKILL.md", nudge: { file: "AGENTS.md", kind: "block" }, markers: [".pi"], homeMarkers: [".pi"] },
+  { id: "devin", label: "Devin CLI", skill: ".devin/skills/vg/SKILL.md", nudge: { file: "AGENTS.md", kind: "block" }, markers: [".devin"], homeMarkers: [".devin"] },
+  { id: "hermes", label: "Hermes", skill: ".hermes/skills/vg/SKILL.md", nudge: { file: "AGENTS.md", kind: "block" }, markers: [".hermes"], homeMarkers: [".hermes"] },
+  { id: "openclaw", label: "OpenClaw", skill: ".openclaw/skills/vg/SKILL.md", nudge: { file: "AGENTS.md", kind: "block" }, markers: [".openclaw"], homeMarkers: [".openclaw"], bin: ["openclaw"] },
+  { id: "agents", label: "Agent-Skills (generic)", skill: ".agents/skills/vg/SKILL.md", nudge: { file: "AGENTS.md", kind: "block" }, markers: ["AGENTS.md", ".agents"] }
 ];
 function assistantById(id) {
   return ASSISTANTS.find((a) => a.id === id);
 }
+function detectAssistants(root, opts = {}) {
+  const home = opts.home ?? os.homedir();
+  const which = opts.which ?? whichOnPath;
+  const found = [];
+  for (const assistant of ASSISTANTS) {
+    const repoHit = (assistant.markers ?? []).find((m) => fs19.existsSync(path19.join(root, m)));
+    if (repoHit) {
+      found.push({ assistant, via: "repo", marker: repoHit });
+      continue;
+    }
+    const homeHit = (assistant.homeMarkers ?? []).find((m) => fs19.existsSync(path19.join(home, m)));
+    if (homeHit) {
+      found.push({ assistant, via: "home", marker: homeHit });
+      continue;
+    }
+    const binHit = (assistant.bin ?? []).find((b) => which(b) !== null);
+    if (binHit) found.push({ assistant, via: "path", marker: binHit });
+  }
+  return found;
+}
 function detectServeLaunch(which = whichOnPath) {
   const vg = which("vg");
   if (vg && isInstalledOwnBinary(vg)) return { command: "vg", args: ["serve"] };
@@ -7491,6 +7564,6 @@ function spdx(ctx) {
   return JSON.stringify(doc, null, 2) + "\n";
 }
 
-export { ASSISTANTS, CLI_TOOL_ALIASES, CliError, ECOSYSTEMS, ExitCode, FREE_PACK, GraphIndex, GraphSource, NPX_INVOCATION, ResourceLimitError, SCHEMA_VERSION, SKIP_DIRS, SKIP_FILES, TOOLS, UsageError, addLibrary, analyze, applyCoverage, applyStaticTestLinkage, assessDocQuality, assistantById, availableRegionIds, buildFacts, buildGraph, buildModuleResolver, cacheDir, catalogPath, clearModelCache, clearStoredCredentials, cosine, countPending, countTokens, coveringTests, createServer, createWorkspaceDsn, credentialsPath, dashHostForIngestHost, decodeScipIndex, defaultGraphPath, detectRunner, detectServeLaunch, discover, discoverModels, driftCount, driftFor, dsnCommand, embeddingsCached, enrichOnline, ensureGitignored, epistemicBreakdown, exportGraph, fetchHostedDocsCached, findGitRoot, findNodes, formatForExt, getNodeEmbeddings, gitignoreEntryForCredentials, groundGraph, hasDrift, identifierParts, impactOf, indexFor, ingestHostForRegionId, installAssistant, inventory, isModelReady, isTestFile, libDir, libId, loadCatalog, loadCoverage, loadEmbedder, loadGraph, loadSnapshot, localApiSurface, localPackageDocs, modelCacheInfo, nodeById, nodeEmbedText, parseDsn, parseGraph, parseJsonc, probeFreshness, publishPrivateLibrary, pushCommand, queryGraph, queryGraphSemantic, readDoc, readSavings, readScanArtifact, readUsage, recordCliCall, recordSaving, refreshIfStale, relativeResolver, renderHtml, renderReport, resolveCliInvocation, resolveDsn, resolveEmbedModel, resolveIngestHost, resolveLib, resolveLimits, resolveOne, resolveVersion, saveCatalog, savingsRecorded, scipEdges, selectForBudget, serializeGraph, serveStdio, shortestPath, stableStringify, symbolsFromApi, testsToRun, unavailableMessage, uninstallAssistant, uploadScanArtifact, usageError, verifyDeterminism, vibgrateDir, writeArtifacts, writeNavigationConfig, writeSnapshot, writeStoredCredentials };
-//# sourceMappingURL=chunk-D4BPWARI.js.map
-//# sourceMappingURL=chunk-D4BPWARI.js.map
+export { ASSISTANTS, CLI_TOOL_ALIASES, CliError, ECOSYSTEMS, ExitCode, FREE_PACK, GraphIndex, GraphSource, NPX_INVOCATION, ResourceLimitError, SCHEMA_VERSION, SKIP_DIRS, SKIP_FILES, TOOLS, UsageError, addLibrary, analyze, applyCoverage, applyStaticTestLinkage, assessDocQuality, assistantById, availableRegionIds, buildFacts, buildGraph, buildModuleResolver, cacheDir, catalogPath, clearModelCache, clearStoredCredentials, cosine, countPending, countTokens, coveringTests, createServer, createWorkspaceDsn, credentialsPath, dashHostForIngestHost, decodeScipIndex, defaultGraphPath, detectAssistants, detectRunner, detectServeLaunch, discover, discoverModels, driftCount, driftFor, dsnCommand, embeddingsCached, enrichOnline, ensureGitignored, epistemicBreakdown, exportGraph, fetchHostedDocsCached, findGitRoot, findNodes, formatForExt, getNodeEmbeddings, gitignoreEntryForCredentials, groundGraph, hasDrift, homeCredentialsPath, hostedBase, identifierParts, impactOf, indexFor, ingestHostForRegionId, installAssistant, inventory, isModelReady, isTestFile, libDir, libId, loadCatalog, loadCoverage, loadEmbedder, loadGraph, loadSnapshot, localApiSurface, localPackageDocs, modelCacheInfo, nodeById, nodeEmbedText, parseDsn, parseGraph, parseJsonc, probeFreshness, projectCredentialsPath, publishPrivateLibrary, pushCommand, queryGraph, queryGraphSemantic, readDoc, readSavings, readScanArtifact, readStoredCredentials, readUsage, recordCliCall, recordSaving, refreshIfStale, relativeResolver, renderHtml, renderReport, resolveCliInvocation, resolveDsn, resolveEmbedModel, resolveIngestHost, resolveLib, resolveLimits, resolveOne, resolveVersion, saveCatalog, savingsRecorded, scipEdges, selectForBudget, serializeGraph, serveStdio, shortestPath, stableStringify, symbolsFromApi, testsToRun, unavailableMessage, uninstallAssistant, uploadScanArtifact, usageError, verifyDeterminism, vibgrateDir, writeArtifacts, writeNavigationConfig, writeSnapshot, writeStoredCredentials };
+//# sourceMappingURL=chunk-H5M7CXE6.js.map
+//# sourceMappingURL=chunk-H5M7CXE6.js.map