gitnexus 1.6.8-rc.9 → 1.6.8

package/dist/cli/i18n/zh-CN.d.ts

@@ -51,6 +51,7 @@ export declare const zhCN: {
     'tool.usage.query': string;
     'tool.usage.context': string;
     'tool.usage.impact': string;
+    'tool.usage.trace': string;
     'tool.usage.cypher': string;
     'tool.warn.unknownKind': string;
     'tool.detectChanges.noChanges': string;
@@ -124,8 +125,10 @@ export declare const zhCN: {
     'help.command.query.description': string;
     'help.command.context.description': string;
     'help.command.impact.description': string;
+    'help.command.trace.description': string;
     'help.command.cypher.description': string;
     'help.command.detectChanges.description': string;
+    'help.command.check.description': string;
     'help.command.evalServer.description': string;
     'help.command.group.description': string;
     'help.command.group.create.description': string;
@@ -137,6 +140,7 @@ export declare const zhCN: {
     'help.command.group.impact.description': string;
     'help.command.group.query.description': string;
     'help.command.group.contracts.description': string;
+    'help.option.setup.codingAgent': string;
     'help.option.analyze.force': string;
     'help.option.analyze.repairFts': string;
     'help.option.analyze.embeddings': string;
@@ -162,6 +166,9 @@ export declare const zhCN: {
     'help.option.index.allowNonGit': string;
     'help.option.port': string;
     'help.option.serve.host': string;
+    'help.option.mcp.http': string;
+    'help.option.mcp.host': string;
+    'help.option.mcp.authToken': string;
     'help.option.force.confirmation': string;
     'help.option.uninstall.force': string;
     'help.option.clean.all': string;
@@ -198,8 +205,15 @@ export declare const zhCN: {
     'help.option.impact.limit': string;
     'help.option.impact.offset': string;
     'help.option.impact.summaryOnly': string;
+    'help.option.trace.fromUid': string;
+    'help.option.trace.fromFile': string;
+    'help.option.trace.toUid': string;
+    'help.option.trace.toFile': string;
+    'help.option.trace.depth': string;
+    'help.option.trace.includeTests': string;
     'help.option.detectChanges.scope': string;
     'help.option.detectChanges.baseRef': string;
+    'help.option.check.cycles': string;
     'help.option.evalServer.host': string;
     'help.option.evalServer.idleTimeout': string;
     'help.option.group.create.force': string;

package/dist/cli/i18n/zh-CN.js

@@ -51,6 +51,7 @@ export const zhCN = {
     'tool.usage.query': '用法：gitnexus query <搜索词>',
     'tool.usage.context': '用法：gitnexus context <符号名> [--uid <uid>] [--file <路径>]',
     'tool.usage.impact': '用法：gitnexus impact <符号名> [--uid <uid>] [--file <路径>] [--kind <类型>] [--direction upstream|downstream]',
+    'tool.usage.trace': '用法：gitnexus trace <起点> <终点> [--from-uid <uid>] [--to-uid <uid>] [--depth <n>]',
     'tool.usage.cypher': '用法：gitnexus cypher <Cypher 查询>',
     'tool.warn.unknownKind': "--kind '{{kind}}' 不是已知的符号类型（如 Function、Class、Method），不会用于缩小结果范围。",
     'tool.detectChanges.noChanges': '未检测到变更。',
@@ -112,7 +113,7 @@ export const zhCN = {
     'help.command.analyze.description': '索引仓库（完整分析）',
     'help.command.index.description': '将现有 .gitnexus/ 文件夹注册到全局注册表（无需重新分析）',
     'help.command.serve.description': '启动供 Web UI 连接的本地 HTTP 服务器',
-    'help.command.mcp.description': '启动 MCP 服务器（stdio）— 提供所有已索引仓库',
+    'help.command.mcp.description': '启动 MCP 服务器。默认为 stdio。使用 --http 启动远程 HTTP 服务器（Streamable HTTP: POST /mcp + 遗留 SSE: GET /sse, POST /messages）。',
     'help.command.list.description': '列出所有已索引仓库',
     'help.command.status.description': '显示当前仓库的索引状态',
     'help.command.doctor.description': '显示运行平台能力和嵌入配置',
@@ -124,8 +125,10 @@ export const zhCN = {
     'help.command.query.description': '搜索知识图谱中与概念相关的执行流程',
     'help.command.context.description': '查看代码符号的 360 度视图：调用者、被调用者、流程',
     'help.command.impact.description': '影响面分析：修改符号会影响什么',
+    'help.command.trace.description': '查找两个符号之间的最短有向路径（调用与类成员边）',
     'help.command.cypher.description': '对知识图谱执行原始 Cypher 查询',
     'help.command.detectChanges.description': '将 git diff hunk 映射到已索引符号和受影响执行流程',
+    'help.command.check.description': '对已索引图谱运行结构检查',
     'help.command.evalServer.description': '启动轻量 HTTP 服务器，用于评测期间的快速工具调用',
     'help.command.group.description': '管理仓库组，用于跨索引影响分析',
     'help.command.group.create.description': '使用模板 group.yaml 创建新仓库组',
@@ -137,6 +140,7 @@ export const zhCN = {
     'help.command.group.impact.description': '分析仓库组中某个成员仓库符号的跨仓库影响',
     'help.command.group.query.description': '跨仓库组所有仓库搜索执行流程',
     'help.command.group.contracts.description': '查看 Contract Registry',
+    'help.option.setup.codingAgent': '仅配置这些编码代理（逗号分隔或重复传入）',
     'help.option.analyze.force': '即使已是最新也强制完整重建索引',
     'help.option.analyze.repairFts': '修复/重建搜索 FTS 索引，不执行完整重新分析',
     'help.option.analyze.embeddings': '启用语义搜索的嵌入生成（默认关闭）。可选 [limit] 覆盖 50,000 节点安全上限；传 0 可完全禁用上限。',
@@ -162,6 +166,9 @@ export const zhCN = {
     'help.option.index.allowNonGit': '允许注册非 Git 仓库文件夹',
     'help.option.port': '端口号',
     'help.option.serve.host': '绑定地址（默认：127.0.0.1；远程访问可用 0.0.0.0）',
+    'help.option.mcp.http': '使用 HTTP 代替 stdio 提供 MCP 服务（适合远程客户端）',
+    'help.option.mcp.host': 'HTTP 绑定地址（仅与 --http 搭配使用）。默认：127.0.0.1（回环）。使用 0.0.0.0 向所有接口开放。',
+    'help.option.mcp.authToken': '要求 Authorization 头携带此 Bearer Token（仅与 --http 搭配使用）；也可通过 GITNEXUS_MCP_AUTH_TOKEN 环境变量设置。非回环绑定（--host 0.0.0.0/::）时必填，否则拒绝启动。',
     'help.option.force.confirmation': '跳过确认提示',
     'help.option.uninstall.force': '应用更改（默认仅为预演预览）',
     'help.option.clean.all': '清理所有已索引仓库',
@@ -198,8 +205,15 @@ export const zhCN = {
     'help.option.impact.limit': '每层深度最大符号数（默认：100）',
     'help.option.impact.offset': '每层深度跳过 N 个符号（分页用）',
     'help.option.impact.summaryOnly': '仅返回计数和风险等级，省略符号列表',
+    'help.option.trace.fromUid': '源符号 UID（零歧义查找）',
+    'help.option.trace.fromFile': '源文件路径，用于消除常见名称歧义',
+    'help.option.trace.toUid': '目标符号 UID（零歧义查找）',
+    'help.option.trace.toFile': '目标文件路径，用于消除常见名称歧义',
+    'help.option.trace.depth': '最大路径跳数（默认：10）',
+    'help.option.trace.includeTests': '遍历时包含测试文件中的符号（默认：false）',
     'help.option.detectChanges.scope': '分析范围：unstaged、staged、all 或 compare',
     'help.option.detectChanges.baseRef': 'compare 范围的分支/提交（例如 main）',
+    'help.option.check.cycles': '检测循环导入，并在发现循环时失败',
     'help.option.evalServer.host': '绑定地址（默认：127.0.0.1；用 0.0.0.0 暴露到所有网卡）',
     'help.option.evalServer.idleTimeout': '空闲 N 秒后自动关闭（0 = 禁用）',
     'help.option.group.create.force': '覆盖现有仓库组',

package/dist/cli/index.js

@@ -4,22 +4,35 @@
 import { Command } from 'commander';
 import { createRequire } from 'node:module';
 import { createLazyAction, createLbugLazyAction } from './lazy-action.js';
+import { EMBEDDING_DIMS_ERROR, normalizeEmbeddingDims } from './embedding-dims.js';
 import { registerGroupCommands } from './group.js';
 import { localizeCliHelp } from './help-i18n.js';
 import { t } from './i18n/index.js';
 const _require = createRequire(import.meta.url);
 const pkg = _require('../../package.json');
 const program = new Command();
+function collectCodingAgents(value, previous) {
+    return [...(previous ?? []), ...value.split(',')];
+}
 program.name('gitnexus').description('GitNexus local CLI and MCP server').version(pkg.version);
 program
     .command('setup')
     .description('One-time setup: configure MCP for Cursor, Claude Code, Antigravity, OpenCode, Codex')
+    .option('-c, --coding-agent <agents>', 'Configure only these coding agents (comma-separated or repeatable)', collectCodingAgents)
     .action(createLazyAction(() => import('./setup.js'), 'setupCommand'));
 program
     .command('uninstall')
     .description('Reverse `setup`: remove GitNexus MCP entries, skills, and hooks from all detected editors')
     .option('-f, --force', 'Apply the changes (default is a dry-run preview)')
     .action(createLazyAction(() => import('./uninstall.js'), 'uninstallCommand'));
+// Baseline of GITNEXUS_EMBEDDING_DIMS captured by the analyze preAction hook
+// before it overwrites the var, so the postAction hook can restore it. The
+// analyzeCommand env snapshot is taken AFTER this hook runs, so it cannot undo
+// the hook's write on its own — without this restore a CLI --embedding-dims
+// would leak into a later in-process program.parseAsync (tests / long-running
+// hosts). Single-shot CLI exits the process, making the restore a no-op there.
+let dimsEnvBaseline;
+let dimsEnvCaptured = false;
 program
     .command('analyze [path]')
     .description('Index a repository (full analysis)')
@@ -32,6 +45,8 @@ program
     .option('--skills', 'Generate repo-specific skill files from detected communities ' +
     '(no-op when --index-only is also set).')
     .option('--skip-agents-md', 'Skip updating the gitnexus section in AGENTS.md and CLAUDE.md')
+    .option('--pdg', 'Build the control-flow-graph / PDG substrate (BasicBlock nodes + CFG edges) ' +
+    'for supported languages. Opt-in; off by default. (#2081 M1)')
     .option('--default-branch <branch>', 'Default branch used in the generated regression-compare example (base_ref). ' +
     'Falls back to .gitnexusrc, then auto-detected origin/HEAD, then "main".')
     .option('--branch <name>', 'Index the working tree under a specific branch slot (multi-branch indexing). ' +
@@ -57,7 +72,53 @@ program
     .option('--embedding-batch-size <n>', 'Number of nodes per embedding batch')
     .option('--embedding-sub-batch-size <n>', 'Number of chunks per embedding model call')
     .option('--embedding-device <device>', 'Embedding device: auto, cpu, dml, cuda, or wasm')
+    .option('--embedding-base-url <url>', 'OpenAI-compatible embeddings base URL including the /v1 suffix ' +
+    '(e.g. http://10.219.32.29:11434/v1 for Ollama). Overrides GITNEXUS_EMBEDDING_URL.')
+    .option('--embedding-model <model>', 'Embedding model name (e.g. qwen3-embedding:8b). Overrides GITNEXUS_EMBEDDING_MODEL.')
+    .option('--embedding-auth-token <token>', 'Bearer token for the embeddings endpoint (omit for unauthenticated servers like Ollama). ' +
+    'Overrides GITNEXUS_EMBEDDING_API_KEY.')
+    .option('--embedding-dims <number>', 'Embedding vector dimensions (positive integer; e.g. 4096 for Qwen3-Embedding-8B). ' +
+    'Must match what the index was built with. Overrides GITNEXUS_EMBEDDING_DIMS.')
     .addHelpText('after', () => t('help.analyze.environment'))
+    .hook('preAction', (thisCommand) => {
+    // ONLY GITNEXUS_EMBEDDING_DIMS must be set here: schema.ts reads it at
+    // module-load time during the lazy import('./analyze.js') below (via the
+    // static chain analyze.ts → run-analyze.ts → schema.ts), so deferring to
+    // analyzeCommandImpl would be too late. URL / MODEL / API_KEY are read
+    // lazily at runtime (readConfig), so analyzeCommandImpl is their sole
+    // setter — keeping them out of this hook means they fall under the impl's
+    // env snapshot/restore and don't leak across in-process invocations.
+    const dimsOpt = thisCommand.opts()['embeddingDims'];
+    if (dimsOpt !== undefined) {
+        // Validate + normalize BEFORE writing the env var: schema.ts throws on a
+        // bad value at module-load, which — on the synchronous program.parse()
+        // path, before the analyze fatal-handlers are installed — would surface
+        // as a raw unhandled rejection instead of this friendly message.
+        const dims = normalizeEmbeddingDims(String(dimsOpt));
+        if (dims === null) {
+            process.stderr.write(`\n  ${EMBEDDING_DIMS_ERROR}\n\n`);
+            process.exit(1);
+        }
+        dimsEnvBaseline = process.env.GITNEXUS_EMBEDDING_DIMS;
+        dimsEnvCaptured = true;
+        process.env.GITNEXUS_EMBEDDING_DIMS = dims;
+    }
+})
+    .hook('postAction', () => {
+    // Restore the pre-hook GITNEXUS_EMBEDDING_DIMS so a CLI override doesn't
+    // persist into a later program.parseAsync in the same process. (Fires on a
+    // microtask after a successful parse; the crash path never reaches here,
+    // but the hook validates dims before writing, so there's nothing to undo.)
+    if (!dimsEnvCaptured)
+        return;
+    dimsEnvCaptured = false;
+    if (dimsEnvBaseline === undefined) {
+        delete process.env.GITNEXUS_EMBEDDING_DIMS;
+    }
+    else {
+        process.env.GITNEXUS_EMBEDDING_DIMS = dimsEnvBaseline;
+    }
+})
     .action(createLbugLazyAction(() => import('./analyze.js'), 'analyzeCommand'));
 program
     .command('index [path...]')
@@ -73,7 +134,12 @@ program
     .action(createLbugLazyAction(() => import('./serve.js'), 'serveCommand'));
 program
     .command('mcp')
-    .description('Start MCP server (stdio) — serves all indexed repos')
+    .description('Start MCP server. Default: stdio. Use --http for a remote HTTP server ' +
+    '(Streamable HTTP at POST /mcp + legacy SSE at GET /sse, POST /messages).')
+    .option('--http', 'Serve MCP over HTTP instead of stdio (for remote clients)')
+    .option('-p, --port <port>', 'HTTP port (only with --http). Default: 3000', '3000')
+    .option('--host <host>', 'HTTP bind address (only with --http). Default: 127.0.0.1 (loopback). Use 0.0.0.0 to expose to all interfaces.', '127.0.0.1')
+    .option('--auth-token <token>', 'Require this bearer token in the Authorization header (only with --http); may also be set via the GITNEXUS_MCP_AUTH_TOKEN env var. Required for a non-loopback bind (--host 0.0.0.0/::), which otherwise refuses to start.')
     .action(createLbugLazyAction(() => import('./mcp.js'), 'mcpCommand'));
 program
     .command('list')
@@ -158,6 +224,8 @@ program
     .command('impact [target]')
     .description('Blast radius analysis: what breaks if you change a symbol')
     .option('-d, --direction <dir>', 'upstream (dependants) or downstream (dependencies)', 'upstream')
+    .option('--mode <mode>', 'Engine: callgraph (default) or pdg (opt-in, intra-procedural; needs analyze --pdg)', 'callgraph')
+    .option('--line <number>', '1-based source line — PDG-only statement anchor (--mode pdg): slice the dependence from the statement at this line and show what depends on it')
     .option('-r, --repo <name>', 'Target repository')
     .option('--branch <name>', 'Scope to a specific branch index (multi-branch repos)')
     .option('-u, --uid <uid>', 'Direct symbol UID (zero-ambiguity lookup)')
@@ -169,6 +237,18 @@ program
     .option('--offset <n>', 'Skip N symbols per depth level for pagination')
     .option('--summary-only', 'Return counts and risk only, omit symbol list')
     .action(createLbugLazyAction(() => import('./tool.js'), 'impactCommand'));
+program
+    .command('trace <from> <to>')
+    .description('Find the shortest directed path between two symbols (call + class-member edges)')
+    .option('--from-uid <uid>', 'Source symbol UID (zero-ambiguity)')
+    .option('--from-file <path>', 'Source file path hint')
+    .option('--to-uid <uid>', 'Target symbol UID (zero-ambiguity)')
+    .option('--to-file <path>', 'Target file path hint')
+    .option('--depth <n>', 'Max path length in hops (default: 10)')
+    .option('--include-tests', 'Include test files in results')
+    .option('-r, --repo <name>', 'Target repository')
+    .option('--branch <name>', 'Scope to a specific branch index')
+    .action(createLbugLazyAction(() => import('./tool.js'), 'traceCommand'));
 program
     .command('cypher <query>')
     .description('Execute raw Cypher query against the knowledge graph')
@@ -184,6 +264,14 @@ program
     .option('-r, --repo <name>', 'Target repository')
     .option('--branch <name>', 'Scope to a specific branch index (multi-branch repos)')
     .action(createLbugLazyAction(() => import('./tool.js'), 'detectChangesCommand'));
+program
+    .command('check')
+    .description('Run structural checks against the indexed graph')
+    .option('--cycles', 'Detect circular imports and fail when any are found')
+    .option('--json', 'Emit machine-readable JSON')
+    .option('-r, --repo <name>', 'Target repository')
+    .option('--branch <name>', 'Scope to a specific branch index (multi-branch repos)')
+    .action(createLbugLazyAction(() => import('./tool.js'), 'checkCommand'));
 // ─── Eval Server (persistent daemon for SWE-bench) ─────────────────
 program
     .command('eval-server')

package/dist/cli/mcp.d.ts

@@ -26,4 +26,9 @@
  * `mcpCommand` after the sentinel install. The regression test at
  * `gitnexus/test/integration/mcp/import-closure.test.ts` enforces this.
  */
-export declare const mcpCommand: () => Promise<void>;
+export declare const mcpCommand: (options?: {
+    http?: boolean;
+    port?: string;
+    host?: string;
+    authToken?: string;
+}) => Promise<void>;

package/dist/cli/mcp.js

@@ -27,7 +27,7 @@
  * `gitnexus/test/integration/mcp/import-closure.test.ts` enforces this.
  */
 import { installGlobalStdoutSentinel } from '../mcp/stdio-context.js';
-export const mcpCommand = async () => {
+export const mcpCommand = async (options) => {
     // Install the global stdout sentinel as the very first thing — before
     // ANY other module loads. The static-import closure above is leaf-only
     // (stdio-context → stdio-capture, zero non-`node:` deps), so this is
@@ -68,6 +68,31 @@ export const mcpCommand = async () => {
     else {
         logger.info({ repoCount: repos.length, repos: repos.map((r) => r.name) }, 'GitNexus: MCP server starting');
     }
+    // Start HTTP server or fall back to stdio (default).
+    if (options?.http) {
+        // Dynamically import the HTTP transport module AFTER the sentinel installs.
+        // http-transport.ts pulls in express/cors/MCP SDK HTTP transport; these must
+        // not load before installGlobalStdoutSentinel() runs (see module doc above).
+        const port = Number(options.port ?? 3000);
+        if (!Number.isInteger(port) || port < 1 || port > 65535) {
+            logger.error({ port: options.port }, `Invalid --port value: "${options.port ?? ''}". Must be an integer between 1 and 65535.`);
+            process.exit(1);
+        }
+        // Dynamic import keeps express/cors out of mcp.ts's static graph (stdio sentinel).
+        const { startMcpHttpServer, resolveAuthToken } = await import('../mcp/http-transport.js');
+        try {
+            await startMcpHttpServer(backend, {
+                port,
+                host: options.host ?? '127.0.0.1',
+                authToken: resolveAuthToken(options.authToken, process.env),
+            });
+        }
+        catch (err) {
+            logger.error({ err: err instanceof Error ? err.message : err }, 'Failed to start the MCP HTTP server');
+            process.exit(1);
+        }
+        return;
+    }
     // Start MCP server (serves all repos, discovers new ones lazily)
     await startMCPServer(backend);
 };

package/dist/cli/optional-grammars.d.ts

@@ -1,15 +1,13 @@
 /**
  * Optional grammar availability check.
  *
- * tree-sitter-dart, tree-sitter-proto, and tree-sitter-swift are vendored
- * under vendor/ and materialized into node_modules/ at postinstall. Dart
- * and Proto are built from source with node-gyp; Swift ships platform
- * prebuilds activated via node-gyp-build. tree-sitter-kotlin is a declared
- * optionalDependency (not vendored). All can be skipped via
+ * tree-sitter-dart, -proto, -swift, and -kotlin are vendored under vendor/ and
+ * loaded from there by absolute path (NEVER copied into node_modules — see
+ * core/tree-sitter/vendored-grammars.ts / #2111). Each ships committed platform
+ * prebuilds activated via node-gyp-build. All can be skipped via
  * GITNEXUS_SKIP_OPTIONAL_GRAMMARS=1 (postinstall scripts), or can silently
- * soft-fail when the toolchain is missing (Dart/Proto), when no prebuild
- * matches the host platform (Swift), or when the optional install was
- * skipped or its native build failed (Kotlin).
+ * soft-fail when no prebuild matches the host platform (and a source build was
+ * unavailable / not attempted).
  *
  * Either path produces the same observable: the .node binding is absent
  * at runtime. This helper detects that condition and surfaces a single

package/dist/cli/optional-grammars.js

@@ -1,26 +1,23 @@
 /**
  * Optional grammar availability check.
  *
- * tree-sitter-dart, tree-sitter-proto, and tree-sitter-swift are vendored
- * under vendor/ and materialized into node_modules/ at postinstall. Dart
- * and Proto are built from source with node-gyp; Swift ships platform
- * prebuilds activated via node-gyp-build. tree-sitter-kotlin is a declared
- * optionalDependency (not vendored). All can be skipped via
+ * tree-sitter-dart, -proto, -swift, and -kotlin are vendored under vendor/ and
+ * loaded from there by absolute path (NEVER copied into node_modules — see
+ * core/tree-sitter/vendored-grammars.ts / #2111). Each ships committed platform
+ * prebuilds activated via node-gyp-build. All can be skipped via
  * GITNEXUS_SKIP_OPTIONAL_GRAMMARS=1 (postinstall scripts), or can silently
- * soft-fail when the toolchain is missing (Dart/Proto), when no prebuild
- * matches the host platform (Swift), or when the optional install was
- * skipped or its native build failed (Kotlin).
+ * soft-fail when no prebuild matches the host platform (and a source build was
+ * unavailable / not attempted).
  *
  * Either path produces the same observable: the .node binding is absent
  * at runtime. This helper detects that condition and surfaces a single
  * stderr line per missing grammar so users learn why .dart/.proto/.swift/.kt
  * support is unavailable instead of silently getting a degraded index.
  */
-import { createRequire } from 'module';
 import { SupportedLanguages } from '../_shared/index.js';
 import { isGrammarRuntimeSkipped } from '../core/tree-sitter/parser-loader.js';
+import { requireVendoredGrammar } from '../core/tree-sitter/vendored-grammars.js';
 import { cliWarn } from './cli-message.js';
-const _require = createRequire(import.meta.url);
 const OPTIONAL_GRAMMARS = [
     {
         name: 'tree-sitter-dart',
@@ -76,7 +73,7 @@ export function detectMissingOptionalGrammars() {
             continue;
         }
         try {
-            _require(g.pkg);
+            requireVendoredGrammar(g.pkg);
         }
         catch (err) {
             const code = err?.code;

package/dist/cli/setup.d.ts

@@ -37,5 +37,7 @@ interface SetupResult {
  * install paths copy this same list from hooks/claude/ (the canonical source).
  */
 export declare function copyHookHelpers(srcDir: string, destDir: string, label: string, result: SetupResult): Promise<string[]>;
-export declare const setupCommand: () => Promise<void>;
+export declare const setupCommand: (options?: {
+    codingAgent?: string[] | string;
+}) => Promise<void>;
 export {};

package/dist/cli/setup.js

@@ -61,6 +61,33 @@ export function formatHookCommand(hookPath, isWindows = process.platform === 'wi
 // changes this literal, the guard records an actionable error instead of
 // silently shipping a hook with an unresolved relative cliPath.
 const CLI_PATH_SOURCE_LITERAL = "let cliPath = path.resolve(__dirname, '..', '..', 'dist', 'cli', 'index.js');";
+const CODING_AGENT_IDS = {
+    cursor: 'cursor',
+    claude: 'claude',
+    antigravity: 'antigravity',
+    opencode: 'opencode',
+    codex: 'codex',
+};
+const SUPPORTED_CODING_AGENTS = Object.values(CODING_AGENT_IDS);
+function selectedCodingAgents(values) {
+    if (values == null)
+        return new Set(SUPPORTED_CODING_AGENTS);
+    const rawValues = Array.isArray(values) ? values : [values];
+    const requested = rawValues
+        .flatMap((value) => value.split(','))
+        .map((value) => value.trim().toLowerCase())
+        .filter(Boolean);
+    const invalid = requested.filter((value) => !SUPPORTED_CODING_AGENTS.includes(value));
+    if (requested.length === 0 || invalid.length > 0) {
+        const detail = requested.length === 0
+            ? 'No coding agents were provided.'
+            : `Unknown: ${invalid.join(', ')}.`;
+        process.stderr.write(`${detail} Valid values: ${SUPPORTED_CODING_AGENTS.join(', ')}.\n`);
+        process.exitCode = 1;
+        return null;
+    }
+    return new Set(requested);
+}
 /**
  * Resolve the absolute path to the `gitnexus` binary if it's installed
  * globally (or via npm -g / yarn global). Returns null when not found.
@@ -832,7 +859,11 @@ async function installCodexSkills(result) {
     }
 }
 // ─── Main command ──────────────────────────────────────────────────
-export const setupCommand = async () => {
+export const setupCommand = async (options) => {
+    const explicitSelection = options?.codingAgent != null;
+    const selected = selectedCodingAgents(options?.codingAgent);
+    if (!selected)
+        return;
     console.log('');
     console.log('  GitNexus Setup');
     console.log('  ==============');
@@ -846,19 +877,31 @@ export const setupCommand = async () => {
         errors: [],
     };
     // Detect and configure each editor's MCP
-    await setupCursor(result);
-    await setupClaudeCode(result);
-    await setupAntigravity(result);
-    await setupOpenCode(result);
-    await setupCodex(result);
+    if (selected.has('cursor'))
+        await setupCursor(result);
+    if (selected.has('claude'))
+        await setupClaudeCode(result);
+    if (selected.has('antigravity'))
+        await setupAntigravity(result);
+    if (selected.has('opencode'))
+        await setupOpenCode(result);
+    if (selected.has('codex'))
+        await setupCodex(result);
     // Install global skills for platforms that support them
-    await installClaudeCodeSkills(result);
-    await installClaudeCodeHooks(result);
-    await installAntigravitySkills(result);
-    await installAntigravityHooks(result);
-    await installCursorSkills(result);
-    await installOpenCodeSkills(result);
-    await installCodexSkills(result);
+    if (selected.has('claude')) {
+        await installClaudeCodeSkills(result);
+        await installClaudeCodeHooks(result);
+    }
+    if (selected.has('antigravity')) {
+        await installAntigravitySkills(result);
+        await installAntigravityHooks(result);
+    }
+    if (selected.has('cursor'))
+        await installCursorSkills(result);
+    if (selected.has('opencode'))
+        await installOpenCodeSkills(result);
+    if (selected.has('codex'))
+        await installCodexSkills(result);
     // Print results
     if (result.configured.length > 0) {
         console.log('  Configured:');
@@ -884,10 +927,17 @@ export const setupCommand = async () => {
     console.log('  Summary:');
     console.log(`    MCP configured for: ${result.configured.filter((c) => !c.includes('skills')).join(', ') || 'none'}`);
     console.log(`    Skills installed to: ${result.configured.filter((c) => c.includes('skills')).length > 0 ? result.configured.filter((c) => c.includes('skills')).join(', ') : 'none'}`);
+    const configurationSucceeded = result.configured.length > 0;
+    if (explicitSelection && !configurationSucceeded) {
+        process.stderr.write('None of the explicitly selected coding agents were configured.\n');
+        process.exitCode = 1;
+    }
     console.log('');
-    console.log('  Next steps:');
-    console.log('    1. cd into any git repo');
-    console.log('    2. Run: gitnexus analyze');
-    console.log('    3. Open the repo in your editor — MCP is ready!');
+    if (configurationSucceeded) {
+        console.log('  Next steps:');
+        console.log('    1. cd into any git repo');
+        console.log('    2. Run: gitnexus analyze');
+        console.log('    3. Open the repo in your editor — MCP is ready!');
+    }
     console.log('');
 };

package/dist/cli/skill-gen.js

@@ -483,8 +483,9 @@ const renderSkillMarkdown = (community, projectName, members, files, entryPoints
     lines.push('## How to Explore');
     lines.push('');
     lines.push(`1. \`context({name: "${firstEntry}"})\` \u2014 see callers and callees`);
-    lines.push(`2. \`query({query: "${community.label.toLowerCase()}"})\` \u2014 find related execution flows`);
+    lines.push(`2. \`query({search_query: "${community.label.toLowerCase()}"})\` \u2014 find related execution flows`);
     lines.push('3. Read key files listed above for implementation details');
+    lines.push('4. `explain({target: "<file or symbol>"})` — persisted taint findings (source→sink data flows), when indexed with `--pdg`');
     lines.push('');
     return lines.join('\n');
 };

package/dist/cli/tool.d.ts

@@ -1,7 +1,7 @@
 /**
  * Direct CLI Tool Commands
  *
- * Exposes GitNexus tools (query, context, impact, cypher) as direct CLI commands.
+ * Exposes GitNexus tools (query, context, impact, cypher, check) as direct CLI commands.
  * Bypasses MCP entirely — invokes LocalBackend directly for minimal overhead.
  *
  * Usage:
@@ -31,6 +31,8 @@ export declare function contextCommand(name: string, options?: {
 }): Promise<void>;
 export declare function impactCommand(target?: string, options?: {
     direction?: string;
+    mode?: string;
+    line?: string;
     repo?: string;
     branch?: string;
     uid?: string;
@@ -52,3 +54,19 @@ export declare function detectChangesCommand(options?: {
     repo?: string;
     branch?: string;
 }): Promise<void>;
+export declare function checkCommand(options?: {
+    cycles?: boolean;
+    json?: boolean;
+    repo?: string;
+    branch?: string;
+}): Promise<void>;
+export declare function traceCommand(from?: string, to?: string, options?: {
+    fromUid?: string;
+    fromFile?: string;
+    toUid?: string;
+    toFile?: string;
+    depth?: string;
+    repo?: string;
+    branch?: string;
+    includeTests?: boolean;
+}): Promise<void>;