gitnexus 1.1.7 → 1.1.9

package/dist/cli/ai-context.js

@@ -17,55 +17,60 @@ const GITNEXUS_END_MARKER = '<!-- gitnexus:end -->';
  * Generate the full GitNexus context content.
  *
  * Design principles (learned from real agent behavior):
- * - AGENTS.md is the ROUTER — it tells the agent WHICH skill to use
+ * - AGENTS.md is the ROUTER — it tells the agent WHICH skill to read
  * - Skills contain the actual workflows — AGENTS.md does NOT duplicate them
- * - Use MUST/ALWAYS language — agents skip "examples" and "suggestions"
- * - Keep reference material (tools, resources, schema) in AGENTS.md as a quick lookup
+ * - Bold **IMPORTANT** block + "Skills — Read First" heading — agents skip soft suggestions
+ * - One-line quick start (read context resource) gives agents an entry point
+ * - Tools/Resources sections are labeled "Reference" — agents treat them as lookup, not workflow
  */
 function generateGitNexusContent(projectName, stats) {
-    const clusterCount = stats.clusters || stats.communities || 0;
     return `${GITNEXUS_START_MARKER}
 # GitNexus MCP
 
-This project is indexed by GitNexus as **${projectName}** (${stats.nodes || 0} symbols, ${stats.edges || 0} relationships, ${clusterCount} clusters, ${stats.processes || 0} processes).
+This project is indexed by GitNexus as **${projectName}** (${stats.nodes || 0} symbols, ${stats.edges || 0} relationships, ${stats.processes || 0} execution flows).
 
-GitNexus adds a knowledge graph layer to this codebase — use it to understand architecture, trace call chains, analyze blast radius, and navigate code by meaning rather than just filenames. It complements your existing tools (read, grep, etc.) with structural and semantic intelligence.
+GitNexus provides a knowledge graph over this codebase — call chains, blast radius, execution flows, and semantic search.
 
-IMPORTANT: GitNexus MCP tool usage is highly encouraged, especially for gathering deep and accurate codebase knowledge.
+## Always Start Here
 
-> **Staleness:** The \`gitnexus://repo/{name}/context\` resource warns when the index is out of date. Refresh with \`npx gitnexus analyze\` in the terminal.
+For any task involving code understanding, debugging, impact analysis, or refactoring, you must:
 
-## Skills
+1. **Read \`gitnexus://repo/{name}/context\`** — codebase overview + check index freshness
+2. **Match your task to a skill below** and **read that skill file**
+3. **Follow the skill's workflow and checklist**
+
+> If step 1 warns the index is stale, run \`npx gitnexus analyze\` in the terminal first.
 
-For these tasks, read the matching skill and follow its workflow:
+## Skills
 
-| Task | Skill | Path |
-|------|-------|------|
-| Understand architecture / "How does X work?" | **Exploring** | \`.claude/skills/gitnexus/exploring/SKILL.md\` |
-| Blast radius / "What breaks if I change X?" | **Impact Analysis** | \`.claude/skills/gitnexus/impact-analysis/SKILL.md\` |
-| Trace bugs / "Why is X failing?" | **Debugging** | \`.claude/skills/gitnexus/debugging/SKILL.md\` |
-| Rename / extract / split / refactor | **Refactoring** | \`.claude/skills/gitnexus/refactoring/SKILL.md\` |
+| Task | Read this skill file |
+|------|---------------------|
+| Understand architecture / "How does X work?" | \`.claude/skills/gitnexus/exploring/SKILL.md\` |
+| Blast radius / "What breaks if I change X?" | \`.claude/skills/gitnexus/impact-analysis/SKILL.md\` |
+| Trace bugs / "Why is X failing?" | \`.claude/skills/gitnexus/debugging/SKILL.md\` |
+| Rename / extract / split / refactor | \`.claude/skills/gitnexus/refactoring/SKILL.md\` |
 
-## Tools
+## Tools Reference
 
 | Tool | What it gives you |
 |------|-------------------|
-| \`search\` | Semantic + keyword code search with cluster context |
-| \`explore\` | Symbol deep dive — callers, callees, cluster membership, processes |
-| \`impact\` | Blast radius — what breaks at depth 1/2/3 with confidence scores |
-| \`overview\` | All clusters and processes at a glance |
+| \`query\` | Process-grouped code intelligence — execution flows related to a concept |
+| \`context\` | 360-degree symbol view — categorized refs, processes it participates in |
+| \`impact\` | Symbol blast radius — what breaks at depth 1/2/3 with confidence |
+| \`detect_changes\` | Git-diff impact — what do your current changes affect |
+| \`rename\` | Multi-file coordinated rename with confidence-tagged edits |
 | \`cypher\` | Raw graph queries (read \`gitnexus://repo/{name}/schema\` first) |
 | \`list_repos\` | Discover indexed repos |
 
-## Resources
+## Resources Reference
 
 Lightweight reads (~100-500 tokens) for navigation:
 
 | Resource | Content |
 |----------|---------|
 | \`gitnexus://repo/{name}/context\` | Stats, staleness check |
-| \`gitnexus://repo/{name}/clusters\` | All clusters with cohesion scores |
-| \`gitnexus://repo/{name}/cluster/{clusterName}\` | Cluster members |
+| \`gitnexus://repo/{name}/clusters\` | All functional areas with cohesion scores |
+| \`gitnexus://repo/{name}/cluster/{clusterName}\` | Area members |
 | \`gitnexus://repo/{name}/processes\` | All execution flows |
 | \`gitnexus://repo/{name}/process/{processName}\` | Step-by-step trace |
 | \`gitnexus://repo/{name}/schema\` | Graph schema for Cypher |

package/dist/cli/analyze.js

@@ -4,17 +4,29 @@
  * Indexes a repository and stores the knowledge graph in .gitnexus/
  */
 import path from 'path';
-import ora from 'ora';
+import cliProgress from 'cli-progress';
 import { runPipelineFromRepo } from '../core/ingestion/pipeline.js';
 import { initKuzu, loadGraphToKuzu, getKuzuStats, executeQuery, executeWithReusedStatement, closeKuzu, createFTSIndex } from '../core/kuzu/kuzu-adapter.js';
 import { runEmbeddingPipeline } from '../core/embeddings/embedding-pipeline.js';
-import { getStoragePaths, saveMeta, loadMeta, addToGitignore, registerRepo, getGlobalRegistryPath } from '../storage/repo-manager.js';
+import { disposeEmbedder } from '../core/embeddings/embedder.js';
+import { getStoragePaths, saveMeta, loadMeta, addToGitignore, registerRepo, getGlobalRegistryPath, getGlobalDir } from '../storage/repo-manager.js';
 import { getCurrentCommit, isGitRepo, getGitRoot } from '../storage/git.js';
 import { generateAIContextFiles } from './ai-context.js';
 import fs from 'fs/promises';
+import { registerClaudeHook } from './claude-hooks.js';
+const PHASE_LABELS = {
+    extracting: 'Scanning files',
+    structure: 'Building structure',
+    parsing: 'Parsing code',
+    imports: 'Resolving imports',
+    calls: 'Tracing calls',
+    heritage: 'Extracting inheritance',
+    communities: 'Detecting communities',
+    processes: 'Detecting processes',
+    complete: 'Complete',
+};
 export const analyzeCommand = async (inputPath, options) => {
-    const spinner = ora('Checking repository...').start();
-    // If path provided, use it directly. Otherwise, find git root from cwd.
+    console.log('\n  GitNexus Analyzer\n');
     let repoPath;
     if (inputPath) {
         repoPath = path.resolve(inputPath);
@@ -22,36 +34,39 @@ export const analyzeCommand = async (inputPath, options) => {
     else {
         const gitRoot = getGitRoot(process.cwd());
         if (!gitRoot) {
-            spinner.fail('Not inside a git repository');
+            console.log('  ✗ Not inside a git repository\n');
             process.exitCode = 1;
             return;
         }
         repoPath = gitRoot;
     }
     if (!isGitRepo(repoPath)) {
-        spinner.fail('Not a git repository');
+        console.log('  ✗ Not a git repository\n');
         process.exitCode = 1;
         return;
     }
     const { storagePath, kuzuPath } = getStoragePaths(repoPath);
     const currentCommit = getCurrentCommit(repoPath);
     const existingMeta = await loadMeta(storagePath);
-    // Skip if already indexed at same commit
     if (existingMeta && !options?.force && existingMeta.lastCommit === currentCommit) {
-        spinner.succeed('Repository already up to date');
+        console.log('  ✓ Repository already up to date\n');
         return;
     }
-    // Run ingestion pipeline
-    spinner.text = 'Running ingestion pipeline...';
+    const multibar = new cliProgress.MultiBar({
+        format: '  {bar} {percentage}% | {phase}',
+        barCompleteChar: '█',
+        barIncompleteChar: '░',
+        hideCursor: true,
+        barGlue: '',
+        autopadding: true,
+    }, cliProgress.Presets.shades_grey);
+    const progressBar = multibar.create(100, 0, { phase: 'Initializing...' });
     const pipelineResult = await runPipelineFromRepo(repoPath, (progress) => {
-        spinner.text = `${progress.phase}: ${progress.percent}%`;
+        const phaseLabel = PHASE_LABELS[progress.phase] || progress.phase;
+        progressBar.update(progress.percent, { phase: phaseLabel });
     });
-    // Load graph into KuzuDB
-    // Always start fresh - remove existing kuzu DB to avoid stale/corrupt data
-    spinner.text = 'Loading graph into KuzuDB...';
+    progressBar.update(100, { phase: 'Loading graph into KuzuDB...' });
     await closeKuzu();
-    // Kuzu 0.11 stores databases as: <name> (main file) + <name>.wal (WAL file)
-    // BOTH must be deleted or kuzu will find the orphaned WAL and corrupt the database
     const fsClean = await import('fs/promises');
     const kuzuFiles = [kuzuPath, `${kuzuPath}.wal`, `${kuzuPath}.lock`];
     for (const f of kuzuFiles) {
@@ -62,9 +77,7 @@ export const analyzeCommand = async (inputPath, options) => {
     }
     await initKuzu(kuzuPath);
     await loadGraphToKuzu(pipelineResult.graph, pipelineResult.fileContents, storagePath);
-    // Create FTS indexes for keyword search
-    // Indexes searchable content on: File, Function, Class, Method
-    spinner.text = 'Creating FTS indexes...';
+    progressBar.update(100, { phase: 'Creating search indexes...' });
     try {
         await createFTSIndex('File', 'file_fts', ['name', 'content']);
         await createFTSIndex('Function', 'function_fts', ['name', 'content']);
@@ -73,17 +86,14 @@ export const analyzeCommand = async (inputPath, options) => {
         await createFTSIndex('Interface', 'interface_fts', ['name', 'content']);
     }
     catch (e) {
-        // FTS index creation may fail if tables are empty (no data for that type)
-        console.error('Note: Some FTS indexes may not have been created:', e.message);
+        console.error('  Note: Some FTS indexes may not have been created:', e.message);
     }
-    // Generate embeddings
     if (!options?.skipEmbeddings) {
-        spinner.text = 'Generating embeddings...';
+        progressBar.update(100, { phase: 'Generating embeddings...' });
         await runEmbeddingPipeline(executeQuery, executeWithReusedStatement, (progress) => {
-            spinner.text = `Embeddings: ${progress.percent}%`;
+            progressBar.update(progress.percent, { phase: `Embeddings ${progress.percent}%` });
         });
     }
-    // Save metadata
     const stats = await getKuzuStats();
     const meta = {
         repoPath,
@@ -98,14 +108,11 @@ export const analyzeCommand = async (inputPath, options) => {
         },
     };
     await saveMeta(storagePath, meta);
-    // Register in global registry
     await registerRepo(repoPath, meta);
-    // Add .gitnexus to .gitignore
     await addToGitignore(repoPath);
-    // Generate AI context files
+    // Auto-register Claude Code hook (idempotent)
+    const hookResult = await registerClaudeHook();
     const projectName = path.basename(repoPath);
-    // Compute aggregated cluster count (grouped by heuristicLabel, >=5 symbols)
-    // This matches the aggregation logic in local-backend.ts for tool output consistency.
     let aggregatedClusterCount = 0;
     if (pipelineResult.communityResult?.communities) {
         const groups = new Map();
@@ -123,22 +130,25 @@ export const analyzeCommand = async (inputPath, options) => {
         clusters: aggregatedClusterCount,
         processes: pipelineResult.processResult?.stats.totalProcesses,
     });
-    // Close database
     await closeKuzu();
-    spinner.succeed('Repository indexed successfully');
-    console.log(`  Path: ${repoPath}`);
-    console.log(`  Storage: ${storagePath}`);
-    console.log(`  Stats: ${stats.nodes} nodes, ${stats.edges} edges`);
+    await disposeEmbedder();
+    multibar.stop();
+    console.log('\n  ✓ Repository indexed successfully\n');
+    console.log(`  Path:     ${repoPath}`);
+    console.log(`  Storage:  ${storagePath}`);
+    console.log(`  Registry: ${getGlobalDir()}`);
+    console.log(`  Stats:    ${stats.nodes} nodes, ${stats.edges} edges, ${pipelineResult.communityResult?.stats.totalCommunities || 0} clusters, ${pipelineResult.processResult?.stats.totalProcesses || 0} processes`);
     if (aiContext.files.length > 0) {
-        console.log(`  AI Context: ${aiContext.files.join(', ')}`);
+        console.log(`  Context:  ${aiContext.files.join(', ')}`);
+    }
+    if (hookResult.registered) {
+        console.log(`  Hooks:    ${hookResult.message}`);
     }
-    // Hint about setup if it hasn't been run
     try {
         await fs.access(getGlobalRegistryPath());
     }
     catch {
-        // Registry didn't exist before this run — suggest setup
-        console.log('');
-        console.log('  Tip: Run `gitnexus setup` to configure MCP for your editor.');
+        console.log('\n  Tip: Run `gitnexus setup` to configure MCP for your editor.');
     }
+    console.log('');
 };

package/dist/cli/augment.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Augment CLI Command
+ *
+ * Fast-path command for platform hooks.
+ * Shells out from Claude Code PreToolUse / Cursor beforeShellExecution hooks.
+ *
+ * Usage: gitnexus augment <pattern>
+ * Returns enriched text to stdout.
+ *
+ * Performance: Must cold-start fast (<500ms).
+ * Skips unnecessary initialization (no web server, no full DB warmup).
+ */
+export declare function augmentCommand(pattern: string): Promise<void>;

package/dist/cli/augment.js

@@ -0,0 +1,33 @@
+/**
+ * Augment CLI Command
+ *
+ * Fast-path command for platform hooks.
+ * Shells out from Claude Code PreToolUse / Cursor beforeShellExecution hooks.
+ *
+ * Usage: gitnexus augment <pattern>
+ * Returns enriched text to stdout.
+ *
+ * Performance: Must cold-start fast (<500ms).
+ * Skips unnecessary initialization (no web server, no full DB warmup).
+ */
+import { augment } from '../core/augmentation/engine.js';
+export async function augmentCommand(pattern) {
+    if (!pattern || pattern.length < 3) {
+        process.exit(0);
+    }
+    try {
+        const result = await augment(pattern, process.cwd());
+        if (result) {
+            // IMPORTANT: Write to stderr, NOT stdout.
+            // KuzuDB's native module captures stdout fd at OS level during init,
+            // which makes stdout permanently broken in subprocess contexts.
+            // stderr is never captured, so it works reliably everywhere.
+            // The hook reads from the subprocess's stderr.
+            process.stderr.write(result + '\n');
+        }
+    }
+    catch {
+        // Graceful failure — never break the calling hook
+        process.exit(0);
+    }
+}

package/dist/cli/claude-hooks.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Claude Code Hook Registration
+ *
+ * Registers the GitNexus PreToolUse hook in ~/.claude/hooks.json
+ * so that grep/glob/bash calls are automatically augmented with
+ * knowledge graph context.
+ *
+ * Idempotent — safe to call multiple times.
+ */
+/**
+ * Register (or verify) the GitNexus hook in Claude Code's global hooks.json.
+ *
+ * - Creates ~/.claude/ and hooks.json if they don't exist
+ * - Preserves existing hooks from other tools
+ * - Skips if GitNexus hook is already registered
+ *
+ * Returns a status message for the CLI output.
+ */
+export declare function registerClaudeHook(): Promise<{
+    registered: boolean;
+    message: string;
+}>;

package/dist/cli/claude-hooks.js

@@ -0,0 +1,97 @@
+/**
+ * Claude Code Hook Registration
+ *
+ * Registers the GitNexus PreToolUse hook in ~/.claude/hooks.json
+ * so that grep/glob/bash calls are automatically augmented with
+ * knowledge graph context.
+ *
+ * Idempotent — safe to call multiple times.
+ */
+import fs from 'fs/promises';
+import path from 'path';
+import os from 'os';
+import { fileURLToPath } from 'url';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+/**
+ * Get the absolute path to the gitnexus-hook.js file.
+ * Works for both local dev and npm-installed packages.
+ */
+function getHookScriptPath() {
+    // From dist/cli/claude-hooks.js → hooks/claude/gitnexus-hook.js
+    const packageRoot = path.resolve(__dirname, '..', '..');
+    return path.join(packageRoot, 'hooks', 'claude', 'gitnexus-hook.cjs');
+}
+/**
+ * Register (or verify) the GitNexus hook in Claude Code's global hooks.json.
+ *
+ * - Creates ~/.claude/ and hooks.json if they don't exist
+ * - Preserves existing hooks from other tools
+ * - Skips if GitNexus hook is already registered
+ *
+ * Returns a status message for the CLI output.
+ */
+export async function registerClaudeHook() {
+    const claudeDir = path.join(os.homedir(), '.claude');
+    const hooksFile = path.join(claudeDir, 'hooks.json');
+    const hookScript = getHookScriptPath();
+    // Check if the hook script exists
+    try {
+        await fs.access(hookScript);
+    }
+    catch {
+        return { registered: false, message: 'Hook script not found (package may be incomplete)' };
+    }
+    // Build the hook command — use node + absolute path for reliability
+    const hookCommand = `node "${hookScript}"`;
+    // Check if ~/.claude/ exists (user has Claude Code installed)
+    try {
+        await fs.access(claudeDir);
+    }
+    catch {
+        // No Claude Code installation — skip silently
+        return { registered: false, message: 'Claude Code not detected (~/.claude/ not found)' };
+    }
+    // Read existing hooks.json or start fresh
+    let hooksConfig = {};
+    try {
+        const existing = await fs.readFile(hooksFile, 'utf-8');
+        hooksConfig = JSON.parse(existing);
+    }
+    catch {
+        // File doesn't exist or is invalid — we'll create it
+    }
+    // Ensure the hooks structure exists
+    if (!hooksConfig.hooks) {
+        hooksConfig.hooks = {};
+    }
+    if (!Array.isArray(hooksConfig.hooks.PreToolUse)) {
+        hooksConfig.hooks.PreToolUse = [];
+    }
+    // Check if GitNexus hook is already registered
+    const existingEntry = hooksConfig.hooks.PreToolUse.find((entry) => {
+        if (!entry.hooks || !Array.isArray(entry.hooks))
+            return false;
+        return entry.hooks.some((h) => h.command && (h.command.includes('gitnexus-hook') ||
+            h.command.includes('gitnexus augment')));
+    });
+    if (existingEntry) {
+        return { registered: true, message: 'Claude Code hook already registered' };
+    }
+    // Add the GitNexus hook entry
+    hooksConfig.hooks.PreToolUse.push({
+        matcher: {
+            tool_name: "Grep|Glob|Bash"
+        },
+        hooks: [
+            {
+                type: "command",
+                command: hookCommand,
+                timeout: 8000
+            }
+        ]
+    });
+    // Write back
+    await fs.writeFile(hooksFile, JSON.stringify(hooksConfig, null, 2) + '\n', 'utf-8');
+    return { registered: true, message: 'Claude Code hook registered' };
+}

package/dist/cli/index.js

@@ -7,6 +7,7 @@ import { statusCommand } from './status.js';
 import { mcpCommand } from './mcp.js';
 import { cleanCommand } from './clean.js';
 import { setupCommand } from './setup.js';
+import { augmentCommand } from './augment.js';
 const program = new Command();
 program
     .name('gitnexus')
@@ -45,4 +46,8 @@ program
     .option('-f, --force', 'Skip confirmation prompt')
     .option('--all', 'Clean all indexed repos')
     .action(cleanCommand);
+program
+    .command('augment <pattern>')
+    .description('Augment a search pattern with knowledge graph context (used by hooks)')
+    .action(augmentCommand);
 program.parse(process.argv);

package/dist/cli/setup.js

@@ -8,7 +8,10 @@
 import fs from 'fs/promises';
 import path from 'path';
 import os from 'os';
+import { fileURLToPath } from 'url';
 import { getGlobalDir } from '../storage/repo-manager.js';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
 /**
  * The MCP server entry for all editors
  */
@@ -82,8 +85,6 @@ async function setupCursor(result) {
     }
 }
 async function setupClaudeCode(result) {
-    // Claude Code uses `claude mcp add` — we just print the command
-    // Check for common Claude Code indicators
     const claudeDir = path.join(os.homedir(), '.claude');
     const hasClaude = await dirExists(claudeDir);
     if (!hasClaude) {
@@ -92,11 +93,82 @@ async function setupClaudeCode(result) {
     }
     // Claude Code uses a JSON settings file at ~/.claude.json or claude mcp add
     console.log('');
-    console.log('  Claude Code detected. Run this command to add GitNexus:');
+    console.log('  Claude Code detected. Run this command to add GitNexus MCP:');
     console.log('');
     console.log('    claude mcp add gitnexus -- npx -y gitnexus mcp');
     console.log('');
-    result.configured.push('Claude Code (manual step printed)');
+    result.configured.push('Claude Code (MCP manual step printed)');
+}
+/**
+ * Install GitNexus skills to ~/.claude/skills/ for Claude Code.
+ */
+async function installClaudeCodeSkills(result) {
+    const claudeDir = path.join(os.homedir(), '.claude');
+    if (!(await dirExists(claudeDir)))
+        return;
+    const skillsDir = path.join(claudeDir, 'skills');
+    try {
+        const installed = await installSkillsTo(skillsDir);
+        if (installed.length > 0) {
+            result.configured.push(`Claude Code skills (${installed.length} skills → ~/.claude/skills/)`);
+        }
+    }
+    catch (err) {
+        result.errors.push(`Claude Code skills: ${err.message}`);
+    }
+}
+/**
+ * Install GitNexus hooks to ~/.claude/settings.json for Claude Code.
+ * Merges hook config without overwriting existing hooks.
+ */
+async function installClaudeCodeHooks(result) {
+    const claudeDir = path.join(os.homedir(), '.claude');
+    if (!(await dirExists(claudeDir)))
+        return;
+    const settingsPath = path.join(claudeDir, 'settings.json');
+    // Source hooks bundled within the gitnexus package (hooks/claude/)
+    const pluginHooksPath = path.join(__dirname, '..', '..', 'hooks', 'claude');
+    // Copy unified hook script to ~/.claude/hooks/gitnexus/
+    const destHooksDir = path.join(claudeDir, 'hooks', 'gitnexus');
+    try {
+        await fs.mkdir(destHooksDir, { recursive: true });
+        const src = path.join(pluginHooksPath, 'gitnexus-hook.cjs');
+        const dest = path.join(destHooksDir, 'gitnexus-hook.cjs');
+        try {
+            const content = await fs.readFile(src, 'utf-8');
+            await fs.writeFile(dest, content, 'utf-8');
+        }
+        catch {
+            // Script not found in source — skip
+        }
+        const hookCmd = `node "${path.join(destHooksDir, 'gitnexus-hook.cjs').replace(/\\/g, '/')}"`;
+        // Merge hook config into ~/.claude/settings.json
+        const existing = await readJsonFile(settingsPath) || {};
+        if (!existing.hooks)
+            existing.hooks = {};
+        // NOTE: SessionStart hooks are broken on Windows (Claude Code bug #23576).
+        // Session context is delivered via CLAUDE.md / skills instead.
+        // Add PreToolUse hook if not already present
+        if (!existing.hooks.PreToolUse)
+            existing.hooks.PreToolUse = [];
+        const hasPreToolHook = existing.hooks.PreToolUse.some((h) => h.hooks?.some((hh) => hh.command?.includes('gitnexus')));
+        if (!hasPreToolHook) {
+            existing.hooks.PreToolUse.push({
+                matcher: 'Grep|Glob|Bash',
+                hooks: [{
+                        type: 'command',
+                        command: hookCmd,
+                        timeout: 8000,
+                        statusMessage: 'Enriching with GitNexus graph context...',
+                    }],
+            });
+        }
+        await writeJsonFile(settingsPath, existing);
+        result.configured.push('Claude Code hooks (PreToolUse)');
+    }
+    catch (err) {
+        result.errors.push(`Claude Code hooks: ${err.message}`);
+    }
 }
 async function setupOpenCode(result) {
     const opencodeDir = path.join(os.homedir(), '.config', 'opencode');
@@ -118,6 +190,67 @@ async function setupOpenCode(result) {
         result.errors.push(`OpenCode: ${err.message}`);
     }
 }
+// ─── Skill Installation ───────────────────────────────────────────
+const SKILL_NAMES = ['exploring', 'debugging', 'impact-analysis', 'refactoring'];
+/**
+ * Install GitNexus skills to a target directory.
+ * Each skill is installed as {targetDir}/gitnexus-{skillName}/SKILL.md
+ * following the Agent Skills standard (both Cursor and Claude Code).
+ */
+async function installSkillsTo(targetDir) {
+    const installed = [];
+    for (const skillName of SKILL_NAMES) {
+        const sourcePath = path.join(__dirname, '..', '..', 'skills', `${skillName}.md`);
+        const skillDir = path.join(targetDir, `gitnexus-${skillName}`);
+        const destPath = path.join(skillDir, 'SKILL.md');
+        try {
+            const content = await fs.readFile(sourcePath, 'utf-8');
+            await fs.mkdir(skillDir, { recursive: true });
+            await fs.writeFile(destPath, content, 'utf-8');
+            installed.push(skillName);
+        }
+        catch {
+            // Source skill file not found — skip
+        }
+    }
+    return installed;
+}
+/**
+ * Install global Cursor skills to ~/.cursor/skills/gitnexus/
+ */
+async function installCursorSkills(result) {
+    const cursorDir = path.join(os.homedir(), '.cursor');
+    if (!(await dirExists(cursorDir)))
+        return;
+    const skillsDir = path.join(cursorDir, 'skills');
+    try {
+        const installed = await installSkillsTo(skillsDir);
+        if (installed.length > 0) {
+            result.configured.push(`Cursor skills (${installed.length} skills → ~/.cursor/skills/)`);
+        }
+    }
+    catch (err) {
+        result.errors.push(`Cursor skills: ${err.message}`);
+    }
+}
+/**
+ * Install global OpenCode skills to ~/.config/opencode/skill/gitnexus/
+ */
+async function installOpenCodeSkills(result) {
+    const opencodeDir = path.join(os.homedir(), '.config', 'opencode');
+    if (!(await dirExists(opencodeDir)))
+        return;
+    const skillsDir = path.join(opencodeDir, 'skill');
+    try {
+        const installed = await installSkillsTo(skillsDir);
+        if (installed.length > 0) {
+            result.configured.push(`OpenCode skills (${installed.length} skills → ~/.config/opencode/skill/)`);
+        }
+    }
+    catch (err) {
+        result.errors.push(`OpenCode skills: ${err.message}`);
+    }
+}
 // ─── Main command ──────────────────────────────────────────────────
 export const setupCommand = async () => {
     console.log('');
@@ -132,10 +265,15 @@ export const setupCommand = async () => {
         skipped: [],
         errors: [],
     };
-    // Detect and configure each editor
+    // Detect and configure each editor's MCP
     await setupCursor(result);
     await setupClaudeCode(result);
     await setupOpenCode(result);
+    // Install global skills for platforms that support them
+    await installClaudeCodeSkills(result);
+    await installClaudeCodeHooks(result);
+    await installCursorSkills(result);
+    await installOpenCodeSkills(result);
     // Print results
     if (result.configured.length > 0) {
         console.log('  Configured:');
@@ -158,6 +296,10 @@ export const setupCommand = async () => {
         }
     }
     console.log('');
+    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'}`);
+    console.log('');
     console.log('  Next steps:');
     console.log('    1. cd into any git repo');
     console.log('    2. Run: gitnexus analyze');