gitnexushub 0.2.11 → 0.3.0

package/dist/api.d.ts

@@ -53,7 +53,10 @@ export interface RepoDetail {
 export declare class HubAPI {
     private hubUrl;
     private token;
+    private fingerprint;
+    private deviceName;
     constructor(hubUrl: string, token: string);
+    private get authHeaders();
     private request;
     private post;
     getMe(): Promise<UserProfile>;

package/dist/api.js

@@ -3,17 +3,29 @@
  *
  * Fetch-based, zero-dependency API client for GitNexus Hub.
  */
+import { computeFingerprint, getDeviceName } from './fingerprint.js';
 export class HubAPI {
     hubUrl;
     token;
+    fingerprint;
+    deviceName;
     constructor(hubUrl, token) {
         this.hubUrl = hubUrl;
         this.token = token;
+        this.fingerprint = computeFingerprint();
+        this.deviceName = getDeviceName();
+    }
+    get authHeaders() {
+        return {
+            Authorization: `Bearer ${this.token}`,
+            'X-Device-Fingerprint': this.fingerprint,
+            'X-Device-Name': this.deviceName,
+        };
     }
     async request(path) {
         const url = `${this.hubUrl}${path}`;
         const res = await fetch(url, {
-            headers: { Authorization: `Bearer ${this.token}` },
+            headers: this.authHeaders,
         });
         if (!res.ok) {
             const body = await res.json().catch(() => ({ error: res.statusText }));
@@ -26,7 +38,7 @@ export class HubAPI {
         const res = await fetch(url, {
             method: 'POST',
             headers: {
-                Authorization: `Bearer ${this.token}`,
+                ...this.authHeaders,
                 'Content-Type': 'application/json',
             },
             body: JSON.stringify(body),

package/dist/config.js

@@ -20,7 +20,23 @@ export async function saveConfig(updates) {
 export async function clearConfig() {
     try {
         const fs = await import('fs/promises');
-        await fs.rm(CONFIG_DIR, { recursive: true, force: true });
+        // Only remove connect-specific keys, not the entire ~/.gitnexus/ dir
+        // (other tools like `gitnexus wiki` store their own config here)
+        const existing = await loadConfig();
+        if (!existing.hubToken && !existing.hubUrl)
+            return; // nothing to clear
+        const config = await readJsonFile(CONFIG_PATH);
+        if (config) {
+            delete config.hubToken;
+            delete config.hubUrl;
+            // If nothing left, remove the file; otherwise rewrite
+            if (Object.keys(config).length === 0) {
+                await fs.rm(CONFIG_PATH, { force: true });
+            }
+            else {
+                await writeJsonFile(CONFIG_PATH, config);
+            }
+        }
     }
     catch {
         // Already gone

package/dist/content.js

@@ -16,6 +16,8 @@ export const HUB_SKILLS = [
     'gitnexus-exploring',
     'gitnexus-debugging',
     'gitnexus-impact-analysis',
+    'gitnexus-refactoring',
+    'gitnexus-guide',
     'gitnexus-pr-review',
 ];
 /**
@@ -23,68 +25,68 @@ export const HUB_SKILLS = [
  * No detect_changes or rename references (not available via Hub MCP).
  */
 function generateHubContent(projectName, stats) {
-    return `${GITNEXUS_START_MARKER}
-# GitNexus — Code Intelligence
-
-This project is indexed by GitNexus as **${projectName}** (${stats.nodes || 0} symbols, ${stats.edges || 0} relationships, ${stats.processes || 0} execution flows). Use the GitNexus MCP tools to understand code, assess impact, and navigate safely.
-
-> Re-indexing is managed from the GitNexus Hub dashboard.
-
-## Always Do
-
-- **MUST run impact analysis before editing any symbol.** Before modifying a function, class, or method, run \`gitnexus_impact({target: "symbolName", direction: "upstream"})\` and report the blast radius (direct callers, affected processes, risk level) to the user.
-- **MUST warn the user** if impact analysis returns HIGH or CRITICAL risk before proceeding with edits.
-- When exploring unfamiliar code, use \`gitnexus_query({query: "concept"})\` to find execution flows instead of grepping. It returns process-grouped results ranked by relevance.
-- When you need full context on a specific symbol — callers, callees, which execution flows it participates in — use \`gitnexus_context({name: "symbolName"})\`.
-
-## When Debugging
-
-1. \`gitnexus_query({query: "<error or symptom>"})\` — find execution flows related to the issue
-2. \`gitnexus_context({name: "<suspect function>"})\` — see all callers, callees, and process participation
-3. \`READ gitnexus://repo/${projectName}/process/{processName}\` — trace the full execution flow step by step
-
-## When Refactoring
-
-- **Extracting/Splitting**: MUST run \`gitnexus_context({name: "target"})\` to see all incoming/outgoing refs, then \`gitnexus_impact({target: "target", direction: "upstream"})\` to find all external callers before moving code.
-
-## Never Do
-
-- NEVER edit a function, class, or method without first running \`gitnexus_impact\` on it.
-- NEVER ignore HIGH or CRITICAL risk warnings from impact analysis.
-
-## Tools Quick Reference
-
-| Tool | When to use | Command |
-|------|-------------|---------|
-| \`query\` | Find code by concept | \`gitnexus_query({query: "auth validation"})\` |
-| \`context\` | 360-degree view of one symbol | \`gitnexus_context({name: "validateUser"})\` |
-| \`impact\` | Blast radius before editing | \`gitnexus_impact({target: "X", direction: "upstream"})\` |
-| \`cypher\` | Custom graph queries | \`gitnexus_cypher({query: "MATCH ..."})\` |
-
-## Impact Risk Levels
-
-| Depth | Meaning | Action |
-|-------|---------|--------|
-| d=1 | WILL BREAK — direct callers/importers | MUST update these |
-| d=2 | LIKELY AFFECTED — indirect deps | Should test |
-| d=3 | MAY NEED TESTING — transitive | Test if critical path |
-
-## Resources
-
-| Resource | Use for |
-|----------|---------|
-| \`gitnexus://repo/${projectName}/context\` | Codebase overview, check index freshness |
-| \`gitnexus://repo/${projectName}/clusters\` | All functional areas |
-| \`gitnexus://repo/${projectName}/processes\` | All execution flows |
-| \`gitnexus://repo/${projectName}/process/{name}\` | Step-by-step execution trace |
-
-## Self-Check Before Finishing
-
-Before completing any code modification task, verify:
-1. \`gitnexus_impact\` was run for all modified symbols
-2. No HIGH/CRITICAL risk warnings were ignored
-3. All d=1 (WILL BREAK) dependents were updated
-
+    return `${GITNEXUS_START_MARKER}
+# GitNexus — Code Intelligence
+
+This project is indexed by GitNexus as **${projectName}** (${stats.nodes || 0} symbols, ${stats.edges || 0} relationships, ${stats.processes || 0} execution flows). Use the GitNexus MCP tools to understand code, assess impact, and navigate safely.
+
+> Re-indexing is managed from the GitNexus Hub dashboard.
+
+## Always Do
+
+- **MUST run impact analysis before editing any symbol.** Before modifying a function, class, or method, run \`gitnexus_impact({target: "symbolName", direction: "upstream"})\` and report the blast radius (direct callers, affected processes, risk level) to the user.
+- **MUST warn the user** if impact analysis returns HIGH or CRITICAL risk before proceeding with edits.
+- When exploring unfamiliar code, use \`gitnexus_query({query: "concept"})\` to find execution flows instead of grepping. It returns process-grouped results ranked by relevance.
+- When you need full context on a specific symbol — callers, callees, which execution flows it participates in — use \`gitnexus_context({name: "symbolName"})\`.
+
+## When Debugging
+
+1. \`gitnexus_query({query: "<error or symptom>"})\` — find execution flows related to the issue
+2. \`gitnexus_context({name: "<suspect function>"})\` — see all callers, callees, and process participation
+3. \`READ gitnexus://repo/${projectName}/process/{processName}\` — trace the full execution flow step by step
+
+## When Refactoring
+
+- **Extracting/Splitting**: MUST run \`gitnexus_context({name: "target"})\` to see all incoming/outgoing refs, then \`gitnexus_impact({target: "target", direction: "upstream"})\` to find all external callers before moving code.
+
+## Never Do
+
+- NEVER edit a function, class, or method without first running \`gitnexus_impact\` on it.
+- NEVER ignore HIGH or CRITICAL risk warnings from impact analysis.
+
+## Tools Quick Reference
+
+| Tool | When to use | Command |
+|------|-------------|---------|
+| \`query\` | Find code by concept | \`gitnexus_query({query: "auth validation"})\` |
+| \`context\` | 360-degree view of one symbol | \`gitnexus_context({name: "validateUser"})\` |
+| \`impact\` | Blast radius before editing | \`gitnexus_impact({target: "X", direction: "upstream"})\` |
+| \`cypher\` | Custom graph queries | \`gitnexus_cypher({query: "MATCH ..."})\` |
+
+## Impact Risk Levels
+
+| Depth | Meaning | Action |
+|-------|---------|--------|
+| d=1 | WILL BREAK — direct callers/importers | MUST update these |
+| d=2 | LIKELY AFFECTED — indirect deps | Should test |
+| d=3 | MAY NEED TESTING — transitive | Test if critical path |
+
+## Resources
+
+| Resource | Use for |
+|----------|---------|
+| \`gitnexus://repo/${projectName}/context\` | Codebase overview, check index freshness |
+| \`gitnexus://repo/${projectName}/clusters\` | All functional areas |
+| \`gitnexus://repo/${projectName}/processes\` | All execution flows |
+| \`gitnexus://repo/${projectName}/process/{name}\` | Step-by-step execution trace |
+
+## Self-Check Before Finishing
+
+Before completing any code modification task, verify:
+1. \`gitnexus_impact\` was run for all modified symbols
+2. No HIGH/CRITICAL risk warnings were ignored
+3. All d=1 (WILL BREAK) dependents were updated
+
 ${GITNEXUS_END_MARKER}`;
 }
 /**

package/dist/editors/claude-code.js

@@ -9,6 +9,7 @@ import path from 'path';
 import fs from 'fs/promises';
 import { readJsonFile, writeJsonFile } from '../utils.js';
 import { HUB_SKILLS } from '../content.js';
+import { computeFingerprint, getDeviceName } from '../fingerprint.js';
 async function configure(hubUrl, token) {
     const mcpUrl = `${hubUrl}/mcp`;
     try {
@@ -21,7 +22,11 @@ async function configure(hubUrl, token) {
         existing.mcpServers.gitnexus = {
             type: 'http',
             url: mcpUrl,
-            headers: { Authorization: `Bearer ${token}` },
+            headers: {
+                Authorization: `Bearer ${token}`,
+                'X-Device-Fingerprint': computeFingerprint(),
+                'X-Device-Name': getDeviceName(),
+            },
         };
         await writeJsonFile(claudeJsonPath, existing);
         return { success: true, message: 'MCP configured in ~/.claude.json', overrodeCli };

package/dist/editors/cursor.js

@@ -9,11 +9,16 @@ import path from 'path';
 import fs from 'fs/promises';
 import { readJsonFile, writeJsonFile } from '../utils.js';
 import { HUB_SKILLS } from '../content.js';
+import { computeFingerprint, getDeviceName } from '../fingerprint.js';
 function getMcpConfig(hubUrl, token) {
     return {
         type: 'streamable-http',
         url: `${hubUrl}/mcp`,
-        headers: { Authorization: `Bearer ${token}` },
+        headers: {
+            Authorization: `Bearer ${token}`,
+            'X-Device-Fingerprint': computeFingerprint(),
+            'X-Device-Name': getDeviceName(),
+        },
     };
 }
 async function configure(hubUrl, token) {
@@ -70,7 +75,9 @@ async function removeSkills() {
             await fs.rm(path.join(skillsDir, name), { recursive: true, force: true });
             removed++;
         }
-        catch { /* already gone */ }
+        catch {
+            /* already gone */
+        }
     }
     return removed;
 }

package/dist/editors/opencode.js

@@ -9,11 +9,16 @@ import path from 'path';
 import fs from 'fs/promises';
 import { readJsonFile, writeJsonFile } from '../utils.js';
 import { HUB_SKILLS } from '../content.js';
+import { computeFingerprint, getDeviceName } from '../fingerprint.js';
 function getMcpConfig(hubUrl, token) {
     return {
         type: 'remote',
         url: `${hubUrl}/mcp`,
-        headers: { Authorization: `Bearer ${token}` },
+        headers: {
+            Authorization: `Bearer ${token}`,
+            'X-Device-Fingerprint': computeFingerprint(),
+            'X-Device-Name': getDeviceName(),
+        },
     };
 }
 async function configure(hubUrl, token) {
@@ -26,7 +31,11 @@ async function configure(hubUrl, token) {
         const overrodeCli = !!(existing.mcp.gitnexus && 'command' in existing.mcp.gitnexus);
         existing.mcp.gitnexus = getMcpConfig(hubUrl, token);
         await writeJsonFile(configPath, existing);
-        return { success: true, message: 'MCP configured in ~/.config/opencode/opencode.json', overrodeCli };
+        return {
+            success: true,
+            message: 'MCP configured in ~/.config/opencode/opencode.json',
+            overrodeCli,
+        };
     }
     catch (err) {
         return { success: false, message: `Failed: ${err.message}` };
@@ -70,7 +79,9 @@ async function removeSkills() {
             await fs.rm(path.join(skillsDir, name), { recursive: true, force: true });
             removed++;
         }
-        catch { /* already gone */ }
+        catch {
+            /* already gone */
+        }
     }
     return removed;
 }

package/dist/editors/windsurf.js

@@ -9,10 +9,15 @@ import path from 'path';
 import fs from 'fs/promises';
 import { readJsonFile, writeJsonFile } from '../utils.js';
 import { HUB_SKILLS } from '../content.js';
+import { computeFingerprint, getDeviceName } from '../fingerprint.js';
 function getMcpConfig(hubUrl, token) {
     return {
         serverUrl: `${hubUrl}/mcp`,
-        headers: { Authorization: `Bearer ${token}` },
+        headers: {
+            Authorization: `Bearer ${token}`,
+            'X-Device-Fingerprint': computeFingerprint(),
+            'X-Device-Name': getDeviceName(),
+        },
     };
 }
 async function configure(hubUrl, token) {
@@ -25,7 +30,11 @@ async function configure(hubUrl, token) {
         const overrodeCli = !!(existing.mcpServers.gitnexus && 'command' in existing.mcpServers.gitnexus);
         existing.mcpServers.gitnexus = getMcpConfig(hubUrl, token);
         await writeJsonFile(mcpPath, existing);
-        return { success: true, message: 'MCP configured in ~/.codeium/windsurf/mcp_config.json', overrodeCli };
+        return {
+            success: true,
+            message: 'MCP configured in ~/.codeium/windsurf/mcp_config.json',
+            overrodeCli,
+        };
     }
     catch (err) {
         return { success: false, message: `Failed: ${err.message}` };
@@ -69,7 +78,9 @@ async function removeSkills() {
             await fs.rm(path.join(skillsDir, name), { recursive: true, force: true });
             removed++;
         }
-        catch { /* already gone */ }
+        catch {
+            /* already gone */
+        }
     }
     return removed;
 }

package/dist/fingerprint.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Device Fingerprint
+ *
+ * Computes a stable fingerprint for the current device.
+ * Used to bind device tokens to specific machines.
+ * Same algorithm as gitnexus/src/cli/auth.ts:computeFingerprint().
+ */
+/** SHA-256 hash of hostname:username:platform:arch, truncated to 16 hex chars. */
+export declare function computeFingerprint(): string;
+/** Human-readable device name: USER@HOSTNAME */
+export declare function getDeviceName(): string;

package/dist/fingerprint.js

@@ -0,0 +1,18 @@
+/**
+ * Device Fingerprint
+ *
+ * Computes a stable fingerprint for the current device.
+ * Used to bind device tokens to specific machines.
+ * Same algorithm as gitnexus/src/cli/auth.ts:computeFingerprint().
+ */
+import os from 'os';
+import crypto from 'crypto';
+/** SHA-256 hash of hostname:username:platform:arch, truncated to 16 hex chars. */
+export function computeFingerprint() {
+    const identity = `${os.hostname()}:${os.userInfo().username}:${os.platform()}:${os.arch()}`;
+    return crypto.createHash('sha256').update(identity).digest('hex').slice(0, 16);
+}
+/** Human-readable device name: USER@HOSTNAME */
+export function getDeviceName() {
+    return `${os.userInfo().username}@${os.hostname()}`;
+}

package/dist/index.js

@@ -22,7 +22,7 @@ import { cursorEditor } from './editors/cursor.js';
 import { windsurfEditor } from './editors/windsurf.js';
 import { opencodeEditor } from './editors/opencode.js';
 import { claudeCodeEditor } from './editors/claude-code.js';
-const DEFAULT_HUB_URL = 'https://gitnexus-enterprise-production.up.railway.app';
+const DEFAULT_HUB_URL = process.env.GITNEXUS_HUB_URL || 'https://gitnexus-enterprise-production.up.railway.app';
 const EDITORS = {
     'claude-code': claudeCodeEditor,
     cursor: cursorEditor,

package/package.json

@@ -1,53 +1,55 @@
-{
-  "name": "gitnexushub",
-  "version": "0.2.11",
-  "description": "Connect your editor to GitNexus Hub — one command MCP setup + project context",
-  "author": "Abhigyan Patwari",
-  "license": "PolyForm-Noncommercial-1.0.0",
-  "homepage": "https://app.akonlabs.com",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/Akon-Labs/gitnexus-enterprise.git",
-    "directory": "gitnexus-connect"
-  },
-  "bugs": {
-    "url": "https://github.com/Akon-Labs/gitnexus-enterprise/issues"
-  },
-  "keywords": [
-    "gitnexus",
-    "mcp",
-    "model-context-protocol",
-    "claude",
-    "cursor",
-    "windsurf",
-    "code-intelligence",
-    "ai-agent"
-  ],
-  "type": "module",
-  "bin": {
-    "gnx": "dist/index.js",
-    "gitnexus-connect": "dist/index.js"
-  },
-  "scripts": {
-    "build": "tsc",
-    "dev": "tsx src/index.ts",
-    "prepare": "npm run build"
-  },
-  "dependencies": {
-    "commander": "^12.0.0",
-    "picocolors": "^1.1.1"
-  },
-  "devDependencies": {
-    "@types/node": "^20.19.37",
-    "tsx": "^4.0.0",
-    "typescript": "^5.4.5"
-  },
-  "engines": {
-    "node": ">=18.0.0"
-  },
-  "files": [
-    "dist",
-    "skills"
-  ],
-  "publishConfig": {}
-}
+{
+  "name": "gitnexushub",
+  "version": "0.3.0",
+  "description": "Connect your editor to GitNexus Hub — one command MCP setup + project context",
+  "author": "Abhigyan Patwari",
+  "license": "PolyForm-Noncommercial-1.0.0",
+  "homepage": "https://app.akonlabs.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Akon-Labs/gitnexus-enterprise.git",
+    "directory": "gitnexus-connect"
+  },
+  "bugs": {
+    "url": "https://github.com/Akon-Labs/gitnexus-enterprise/issues"
+  },
+  "keywords": [
+    "gitnexus",
+    "mcp",
+    "model-context-protocol",
+    "claude",
+    "cursor",
+    "windsurf",
+    "code-intelligence",
+    "ai-agent"
+  ],
+  "type": "module",
+  "bin": {
+    "gnx": "dist/index.js",
+    "gitnexus-connect": "dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx src/index.ts",
+    "test": "vitest run",
+    "prepare": "npm run build"
+  },
+  "dependencies": {
+    "commander": "^12.0.0",
+    "picocolors": "^1.1.1"
+  },
+  "devDependencies": {
+    "@types/node": "^20.19.37",
+    "tsx": "^4.0.0",
+    "typescript": "^5.4.5",
+    "vitest": "^4.1.4"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "files": [
+    "dist",
+    "skills"
+  ],
+  "publishConfig": {}
+}

package/skills/gitnexus-guide.md

@@ -0,0 +1,64 @@
+---
+name: gitnexus-guide
+description: "Use when the user asks about GitNexus itself — available tools, how to query the knowledge graph, MCP resources, graph schema, or workflow reference. Examples: \"What GitNexus tools are available?\", \"How do I use GitNexus?\""
+---
+
+# GitNexus Guide
+
+Quick reference for all GitNexus MCP tools, resources, and the knowledge graph schema.
+
+## Always Start Here
+
+For any task involving code understanding, debugging, impact analysis, or refactoring:
+
+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.
+
+## Skills
+
+| Task                                         | Skill to read       |
+| -------------------------------------------- | ------------------- |
+| Understand architecture / "How does X work?" | `gitnexus-exploring`         |
+| Blast radius / "What breaks if I change X?"  | `gitnexus-impact-analysis`   |
+| Trace bugs / "Why is X failing?"             | `gitnexus-debugging`         |
+| Rename / extract / split / refactor          | `gitnexus-refactoring`       |
+| Tools, resources, schema reference           | `gitnexus-guide` (this file) |
+| Index, status, clean, wiki CLI commands      | `gitnexus-cli`               |
+
+## Tools Reference
+
+| Tool             | What it gives you                                                        |
+| ---------------- | ------------------------------------------------------------------------ |
+| `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 Reference
+
+Lightweight reads (~100-500 tokens) for navigation:
+
+| Resource                                       | Content                                   |
+| ---------------------------------------------- | ----------------------------------------- |
+| `gitnexus://repo/{name}/context`               | Stats, staleness check                    |
+| `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                   |
+
+## Graph Schema
+
+**Nodes:** File, Function, Class, Interface, Method, Community, Process
+**Edges (via CodeRelation.type):** CALLS, IMPORTS, EXTENDS, IMPLEMENTS, DEFINES, MEMBER_OF, STEP_IN_PROCESS
+
+```cypher
+MATCH (caller)-[:CodeRelation {type: 'CALLS'}]->(f:Function {name: "myFunc"})
+RETURN caller.name, caller.filePath
+```

package/skills/gitnexus-refactoring.md

@@ -0,0 +1,121 @@
+---
+name: gitnexus-refactoring
+description: "Use when the user wants to rename, extract, split, move, or restructure code safely. Examples: \"Rename this function\", \"Extract this into a module\", \"Refactor this class\", \"Move this to a separate file\""
+---
+
+# Refactoring with GitNexus
+
+## When to Use
+
+- "Rename this function safely"
+- "Extract this into a module"
+- "Split this service"
+- "Move this to a new file"
+- Any task involving renaming, extracting, splitting, or restructuring code
+
+## Workflow
+
+```
+1. gitnexus_impact({target: "X", direction: "upstream"})  → Map all dependents
+2. gitnexus_query({query: "X"})                            → Find execution flows involving X
+3. gitnexus_context({name: "X"})                           → See all incoming/outgoing refs
+4. Plan update order: interfaces → implementations → callers → tests
+```
+
+> If "Index is stale" → run `npx gitnexus analyze` in terminal.
+
+## Checklists
+
+### Rename Symbol
+
+```
+- [ ] gitnexus_rename({symbol_name: "oldName", new_name: "newName", dry_run: true}) — preview all edits
+- [ ] Review graph edits (high confidence) and ast_search edits (review carefully)
+- [ ] If satisfied: gitnexus_rename({..., dry_run: false}) — apply edits
+- [ ] gitnexus_detect_changes() — verify only expected files changed
+- [ ] Run tests for affected processes
+```
+
+### Extract Module
+
+```
+- [ ] gitnexus_context({name: target}) — see all incoming/outgoing refs
+- [ ] gitnexus_impact({target, direction: "upstream"}) — find all external callers
+- [ ] Define new module interface
+- [ ] Extract code, update imports
+- [ ] gitnexus_detect_changes() — verify affected scope
+- [ ] Run tests for affected processes
+```
+
+### Split Function/Service
+
+```
+- [ ] gitnexus_context({name: target}) — understand all callees
+- [ ] Group callees by responsibility
+- [ ] gitnexus_impact({target, direction: "upstream"}) — map callers to update
+- [ ] Create new functions/services
+- [ ] Update callers
+- [ ] gitnexus_detect_changes() — verify affected scope
+- [ ] Run tests for affected processes
+```
+
+## Tools
+
+**gitnexus_rename** — automated multi-file rename:
+
+```
+gitnexus_rename({symbol_name: "validateUser", new_name: "authenticateUser", dry_run: true})
+→ 12 edits across 8 files
+→ 10 graph edits (high confidence), 2 ast_search edits (review)
+→ Changes: [{file_path, edits: [{line, old_text, new_text, confidence}]}]
+```
+
+**gitnexus_impact** — map all dependents first:
+
+```
+gitnexus_impact({target: "validateUser", direction: "upstream"})
+→ d=1: loginHandler, apiMiddleware, testUtils
+→ Affected Processes: LoginFlow, TokenRefresh
+```
+
+**gitnexus_detect_changes** — verify your changes after refactoring:
+
+```
+gitnexus_detect_changes({scope: "all"})
+→ Changed: 8 files, 12 symbols
+→ Affected processes: LoginFlow, TokenRefresh
+→ Risk: MEDIUM
+```
+
+**gitnexus_cypher** — custom reference queries:
+
+```cypher
+MATCH (caller)-[:CodeRelation {type: 'CALLS'}]->(f:Function {name: "validateUser"})
+RETURN caller.name, caller.filePath ORDER BY caller.filePath
+```
+
+## Risk Rules
+
+| Risk Factor         | Mitigation                                |
+| ------------------- | ----------------------------------------- |
+| Many callers (>5)   | Use gitnexus_rename for automated updates |
+| Cross-area refs     | Use detect_changes after to verify scope  |
+| String/dynamic refs | gitnexus_query to find them               |
+| External/public API | Version and deprecate properly            |
+
+## Example: Rename `validateUser` to `authenticateUser`
+
+```
+1. gitnexus_rename({symbol_name: "validateUser", new_name: "authenticateUser", dry_run: true})
+   → 12 edits: 10 graph (safe), 2 ast_search (review)
+   → Files: validator.ts, login.ts, middleware.ts, config.json...
+
+2. Review ast_search edits (config.json: dynamic reference!)
+
+3. gitnexus_rename({symbol_name: "validateUser", new_name: "authenticateUser", dry_run: false})
+   → Applied 12 edits across 8 files
+
+4. gitnexus_detect_changes({scope: "all"})
+   → Affected: LoginFlow, TokenRefresh
+   → Risk: MEDIUM — run tests for these flows
+```