gitnexus 1.1.6 → 1.1.7

package/dist/cli/ai-context.js

@@ -14,89 +14,68 @@ const __dirname = path.dirname(__filename);
 const GITNEXUS_START_MARKER = '<!-- gitnexus:start -->';
 const GITNEXUS_END_MARKER = '<!-- gitnexus:end -->';
 /**
- * Generate the full GitNexus context content (resources-first approach)
+ * 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
+ * - 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
  */
 function generateGitNexusContent(projectName, stats) {
     const clusterCount = stats.clusters || stats.communities || 0;
     return `${GITNEXUS_START_MARKER}
 # GitNexus MCP
 
-This project is indexed as **${projectName}** by GitNexus, providing AI agents with deep code intelligence.
+This project is indexed by GitNexus as **${projectName}** (${stats.nodes || 0} symbols, ${stats.edges || 0} relationships, ${clusterCount} clusters, ${stats.processes || 0} processes).
 
-## Project: ${projectName}
+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.
 
-| Metric | Count |
-|--------|-------|
-| Files | ${stats.files || 0} |
-| Symbols | ${stats.nodes || 0} |
-| Relationships | ${stats.edges || 0} |
-| Clusters | ${clusterCount} |
-| Processes | ${stats.processes || 0} |
+IMPORTANT: GitNexus MCP tool usage is highly encouraged, especially for gathering deep and accurate codebase knowledge.
 
-> **Staleness:** If the index is out of date, run \`npx gitnexus analyze\` in the terminal to refresh. The \`gitnexus://repo/${projectName}/context\` resource will warn you when the index is stale.
+> **Staleness:** The \`gitnexus://repo/{name}/context\` resource warns when the index is out of date. Refresh with \`npx gitnexus analyze\` in the terminal.
 
-## Quick Start
+## Skills
 
-\`\`\`
-1. READ gitnexus://repos                          → Discover all indexed repos
-2. READ gitnexus://repo/${projectName}/context     → Get codebase overview (~150 tokens)
-3. READ gitnexus://repo/${projectName}/clusters    → See all functional clusters
-4. gitnexus_search({query: "...", repo: "${projectName}"}) → Find code by query
-\`\`\`
+For these tasks, read the matching skill and follow its workflow:
 
-## Available Resources
+| 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\` |
 
-| Resource | Purpose |
-|----------|---------|
-| \`gitnexus://repos\` | List all indexed repositories |
-| \`gitnexus://repo/${projectName}/context\` | Codebase stats, tools, and resources overview |
-| \`gitnexus://repo/${projectName}/clusters\` | All clusters with symbol counts and cohesion |
-| \`gitnexus://repo/${projectName}/cluster/{name}\` | Cluster members and details |
-| \`gitnexus://repo/${projectName}/processes\` | All execution flows with types |
-| \`gitnexus://repo/${projectName}/process/{name}\` | Full process trace with steps |
-| \`gitnexus://repo/${projectName}/schema\` | Graph schema for Cypher queries |
+## Tools
 
-## Available Tools
+| 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 |
+| \`cypher\` | Raw graph queries (read \`gitnexus://repo/{name}/schema\` first) |
+| \`list_repos\` | Discover indexed repos |
 
-| Tool | Purpose | When to Use |
-|------|---------|-------------|
-| \`list_repos\` | Discover indexed repos | First step with multiple repos |
-| \`search\` | Semantic + keyword search | Finding code by query |
-| \`overview\` | List clusters & processes | Understanding architecture |
-| \`explore\` | Deep dive on symbol/cluster/process | Detailed investigation |
-| \`impact\` | Blast radius analysis | Before making changes |
-| \`cypher\` | Raw graph queries | Complex analysis |
+## Resources
 
-> **Re-indexing:** To refresh a stale index, run \`npx gitnexus analyze\` in the terminal. Use \`--force\` only to rebuild from scratch. This is a CLI command, not an MCP tool.
+Lightweight reads (~100-500 tokens) for navigation:
 
-> **Multi-repo:** When multiple repos are indexed, pass \`repo: "${projectName}"\` to target this project.
-
-## Workflow Examples
-
-### Exploring the Codebase
-\`\`\`
-READ gitnexus://repos                            → Discover repos
-READ gitnexus://repo/${projectName}/context       → Stats and overview (check for staleness)
-READ gitnexus://repo/${projectName}/clusters      → Find relevant cluster by name
-READ gitnexus://repo/${projectName}/cluster/{name} → See members of that cluster
-gitnexus_explore({name: "<symbol_name>", type: "symbol", repo: "${projectName}"})
-\`\`\`
-
-### Planning a Change
-\`\`\`
-gitnexus_search({query: "<what you want to change>", repo: "${projectName}"})
-gitnexus_impact({target: "<symbol_name>", direction: "upstream", repo: "${projectName}"})
-READ gitnexus://repo/${projectName}/processes     → Check affected execution flows
-\`\`\`
+| 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}/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
-
-**Relationships:** CALLS, IMPORTS, EXTENDS, IMPLEMENTS, DEFINES, MEMBER_OF, STEP_IN_PROCESS
+**Edges (via CodeRelation.type):** CALLS, IMPORTS, EXTENDS, IMPLEMENTS, DEFINES, MEMBER_OF, STEP_IN_PROCESS
 
 \`\`\`cypher
-// Example: Find callers of a function
 MATCH (caller)-[:CodeRelation {type: 'CALLS'}]->(f:Function {name: "myFunc"})
 RETURN caller.name, caller.filePath
 \`\`\`

package/dist/mcp/server.js

@@ -15,6 +15,47 @@ import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
 import { CallToolRequestSchema, ListToolsRequestSchema, ListResourcesRequestSchema, ReadResourceRequestSchema, ListResourceTemplatesRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
 import { GITNEXUS_TOOLS } from './tools.js';
 import { getResourceDefinitions, getResourceTemplates, readResource } from './resources.js';
+/**
+ * Next-step hints appended to tool responses.
+ *
+ * Agents often stop after one tool call. These hints guide them to the
+ * logical next action, creating a self-guiding workflow without hooks.
+ *
+ * Design: Each hint is a short, actionable instruction (not a suggestion).
+ * The hint references the specific tool/resource to use next.
+ */
+function getNextStepHint(toolName, args) {
+    const repo = args?.repo;
+    const repoParam = repo ? `, repo: "${repo}"` : '';
+    const repoPath = repo || '{name}';
+    switch (toolName) {
+        case 'list_repos':
+            return `\n\n---\n**Next:** READ gitnexus://repo/{name}/context for any repo above to get its overview and check staleness.`;
+        case 'search':
+            return `\n\n---\n**Next:** To understand a result in context, use explore({name: "<symbol_name>", type: "symbol"${repoParam}}) to see its callers, callees, and cluster membership.`;
+        case 'explore': {
+            const exploreType = args?.type || 'symbol';
+            if (exploreType === 'symbol') {
+                return `\n\n---\n**Next:** If planning changes, use impact({target: "${args?.name || '<name>'}", direction: "upstream"${repoParam}}) to check blast radius. To see execution flows, READ gitnexus://repo/${repoPath}/processes.`;
+            }
+            if (exploreType === 'cluster') {
+                return `\n\n---\n**Next:** To drill into a specific symbol, use explore({name: "<symbol_name>", type: "symbol"${repoParam}}). To see execution flows, READ gitnexus://repo/${repoPath}/processes.`;
+            }
+            if (exploreType === 'process') {
+                return `\n\n---\n**Next:** To explore any step in detail, use explore({name: "<step_name>", type: "symbol"${repoParam}}).`;
+            }
+            return '';
+        }
+        case 'overview':
+            return `\n\n---\n**Next:** To drill into a cluster, READ gitnexus://repo/${repoPath}/cluster/{name} or use explore({name: "<cluster_name>", type: "cluster"${repoParam}}).`;
+        case 'impact':
+            return `\n\n---\n**Next:** Review d=1 items first (WILL BREAK). To check affected execution flows, READ gitnexus://repo/${repoPath}/processes.`;
+        case 'cypher':
+            return `\n\n---\n**Next:** To explore a result symbol, use explore({name: "<name>", type: "symbol"${repoParam}}). For schema reference, READ gitnexus://repo/${repoPath}/schema.`;
+        default:
+            return '';
+    }
+}
 export async function startMCPServer(backend) {
     const server = new Server({
         name: 'gitnexus',
@@ -84,16 +125,18 @@ export async function startMCPServer(backend) {
             inputSchema: tool.inputSchema,
         })),
     }));
-    // Handle tool calls
+    // Handle tool calls — append next-step hints to guide agent workflow
     server.setRequestHandler(CallToolRequestSchema, async (request) => {
         const { name, arguments: args } = request.params;
         try {
             const result = await backend.callTool(name, args);
+            const resultText = typeof result === 'string' ? result : JSON.stringify(result, null, 2);
+            const hint = getNextStepHint(name, args);
             return {
                 content: [
                     {
                         type: 'text',
-                        text: typeof result === 'string' ? result : JSON.stringify(result, null, 2),
+                        text: resultText + hint,
                     },
                 ],
             };

package/dist/mcp/tools.js

@@ -10,7 +10,9 @@ export const GITNEXUS_TOOLS = [
         description: `List all indexed repositories available to GitNexus.
 
 Returns each repo's name, path, indexed date, last commit, and stats.
-Use this to discover which repos are available before querying.
+
+WHEN TO USE: First step when multiple repos are indexed, or to discover available repos.
+AFTER THIS: READ gitnexus://repo/{name}/context for the repo you want to work with.
 
 When multiple repos are indexed, you MUST specify the "repo" parameter
 on other tools (search, explore, impact, etc.) to target the correct one.`,
@@ -25,7 +27,10 @@ on other tools (search, explore, impact, etc.) to target the correct one.`,
         description: `Hybrid search (keyword + semantic) across the codebase.
 Returns code nodes with cluster context and optional graph connections.
 
-BETTER THAN IDE search because:
+WHEN TO USE: Finding code by concept, name, or keyword. Use alongside grep/IDE search for richer results.
+AFTER THIS: Use explore() on interesting results to see callers/callees and cluster membership.
+
+Complements grep/IDE search by adding:
 - Cluster context (which functional area each result belongs to)
 - Relationship data (callers/callees with depth=full)
 - Hybrid ranking (BM25 + semantic via Reciprocal Rank Fusion)
@@ -46,6 +51,9 @@ RETURNS: Array of {name, type, filePath, cluster?, connections[]?, fusedScore, s
         name: 'cypher',
         description: `Execute Cypher query against the code knowledge graph.
 
+WHEN TO USE: Complex structural queries that search/explore can't answer. READ gitnexus://repo/{name}/schema first for the full schema.
+AFTER THIS: Use explore() on result symbols for deeper context.
+
 SCHEMA:
 - Nodes: File, Folder, Function, Class, Interface, Method, Community, Process
 - Edges via CodeRelation.type: CALLS, IMPORTS, EXTENDS, IMPLEMENTS, CONTAINS, DEFINES, MEMBER_OF, STEP_IN_PROCESS
@@ -77,13 +85,16 @@ TIPS:
         name: 'explore',
         description: `Deep dive on a symbol, cluster, or process.
 
+WHEN TO USE: After search() to understand context, or to drill into a specific node.
+AFTER THIS (symbol): Use impact() if planning changes, or READ process resource to see execution flows.
+AFTER THIS (cluster): Use explore() on specific members, or READ processes resource.
+AFTER THIS (process): Use explore() on individual steps for detail.
+
 TYPE: symbol | cluster | process
 
 For SYMBOL: Shows cluster membership, process participation, callers/callees
 For CLUSTER: Shows members, cohesion score, processes touching it
-For PROCESS: Shows step-by-step trace, clusters traversed, entry/terminal points
-
-Use after search to understand context of a specific node.`,
+For PROCESS: Shows step-by-step trace, clusters traversed, entry/terminal points`,
         inputSchema: {
             type: 'object',
             properties: {
@@ -98,12 +109,13 @@ Use after search to understand context of a specific node.`,
         name: 'overview',
         description: `Get codebase map showing all clusters and processes.
 
+WHEN TO USE: Understanding overall architecture. Prefer READ gitnexus://repo/{name}/clusters resource for a lighter-weight alternative.
+AFTER THIS: Drill into a specific cluster with explore({type: "cluster"}) or search() for specific code.
+
 Returns:
 - All communities (clusters) with member counts and cohesion scores
 - All processes with step counts and types (intra/cross-community)
-- High-level architectural view
-
-Use to understand overall codebase structure before diving deep.`,
+- High-level architectural view`,
         inputSchema: {
             type: 'object',
             properties: {
@@ -120,7 +132,8 @@ Use to understand overall codebase structure before diving deep.`,
         description: `Analyze the impact of changing a code element.
 Returns all nodes affected by modifying the target, with distance, edge type, and confidence.
 
-USE BEFORE making changes to understand ripple effects.
+WHEN TO USE: Before making code changes, especially refactoring, renaming, or modifying shared code. Shows what would be affected.
+AFTER THIS: Review d=1 items (WILL BREAK). READ gitnexus://repo/{name}/processes to check affected flows. If risk > MEDIUM, warn the user.
 
 Output includes:
 - Affected processes (with step positions)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gitnexus",
-  "version": "1.1.6",
+  "version": "1.1.7",
   "description": "Graph-powered code intelligence for AI agents. Index any codebase, query via MCP or CLI.",
   "author": "Abhigyan Patwari",
   "license": "PolyForm-Noncommercial-1.0.0",

package/skills/debugging.md

@@ -5,78 +5,64 @@ description: Trace bugs through call chains using knowledge graph
 
 # Debugging with GitNexus
 
-## Quick Start
-```
-0. READ gitnexus://repos                          → Discover indexed repos
-1. If "Index is stale" → run `npx gitnexus analyze` in terminal
-2. gitnexus_search({query: "...", repo: "my-app"})  → Find code related to error
-3. gitnexus_explore({name, type: "symbol", repo: "my-app"}) → Get callers and callees
-4. READ gitnexus://repo/my-app/process/{name}      → Trace execution flow
-```
-
 ## When to Use
 - "Why is this function failing?"
 - "Trace where this error comes from"
 - "Who calls this method?"
-- "Debug the payment issue"
+- "This endpoint returns 500"
+- Investigating bugs, errors, or unexpected behavior
+
+## Workflow
 
-## Workflow Checklist
 ```
-Bug Investigation:
-- [ ] READ gitnexus://repos to find the right repo
-- [ ] Understand the symptom (error message, behavior)
-- [ ] gitnexus_search to find related code
-- [ ] Identify the suspect function
-- [ ] gitnexus_explore to see callers/callees
-- [ ] READ gitnexus://repo/{name}/process/{name} if suspect is in a process
-- [ ] READ gitnexus://repo/{name}/schema for Cypher query help
-- [ ] gitnexus_cypher for custom traces
+1. gitnexus_search({query: "<error or symptom>"})            → Find related code
+2. gitnexus_explore({name: "<suspect>", type: "symbol"})     → See callers/callees
+3. READ gitnexus://repo/{name}/process/{name}                → Trace execution flow
+4. gitnexus_cypher({query: "MATCH path..."})                 → Custom traces if needed
 ```
 
-## Resource Reference
-
-### gitnexus://repo/{name}/schema
-Graph schema for writing Cypher queries:
-```yaml
-nodes: [Function, Class, Method, File, Community, Process]
-relationships: [CALLS, IMPORTS, EXTENDS, IMPLEMENTS, MEMBER_OF, STEP_IN_PROCESS]
-example_queries:
-  find_callers: |
-    MATCH (caller)-[:CodeRelation {type: 'CALLS'}]->(f:Function {name: "X"})
-    RETURN caller.name
-```
+> If "Index is stale" → run `npx gitnexus analyze` in terminal.
+
+## Checklist
 
-### gitnexus://repo/{name}/process/{processName}
-Trace execution flow to find where bug might occur:
-```yaml
-name: CheckoutFlow
-trace:
-  1: handleCheckout
-  2: validateCart
-  3: processPayment  ← bug here?
-  4: sendConfirmation
 ```
+- [ ] Understand the symptom (error message, unexpected behavior)
+- [ ] gitnexus_search for error text or related code
+- [ ] Identify the suspect function
+- [ ] gitnexus_explore to see callers and callees
+- [ ] Trace execution flow via process resource if applicable
+- [ ] gitnexus_cypher for custom call chain traces if needed
+- [ ] Read source files to confirm root cause
+```
+
+## Debugging Patterns
+
+| Symptom | GitNexus Approach |
+|---------|-------------------|
+| Error message | `gitnexus_search` for error text → `explore` throw sites |
+| Wrong return value | `explore` the function → trace callees for data flow |
+| Intermittent failure | `explore` → look for external calls, async deps |
+| Performance issue | `explore` → find symbols with many callers (hot paths) |
+| Recent regression | `gitnexus_impact` on recently changed symbols |
 
-## Tool Reference
+## Tools
 
-### gitnexus_search
-Find code related to error or symptom:
+**gitnexus_search** — find code related to error:
 ```
-gitnexus_search({query: "payment validation error", depth: "full", repo: "my-app"})
+gitnexus_search({query: "payment validation error", depth: "full"})
+→ validatePayment, handlePaymentError, PaymentException
 ```
 
-### gitnexus_explore
-Get symbol context:
+**gitnexus_explore** — full context for a suspect:
 ```
-gitnexus_explore({name: "validatePayment", type: "symbol", repo: "my-app"})
+gitnexus_explore({name: "validatePayment", type: "symbol"})
 → Callers: processCheckout, webhookHandler
-→ Callees: verifyCard, fetchRates
+→ Callees: verifyCard, fetchRates (external API!)
+→ Cluster: Payment
 ```
 
-### gitnexus_cypher
-Custom graph queries for tracing:
+**gitnexus_cypher** — custom call chain traces:
 ```cypher
-// Trace call chain (2 hops)
 MATCH path = (a)-[:CodeRelation {type: 'CALLS'}*1..2]->(b:Function {name: "validatePayment"})
 RETURN [n IN nodes(path) | n.name] AS chain
 ```
@@ -84,23 +70,14 @@ RETURN [n IN nodes(path) | n.name] AS chain
 ## Example: "Payment endpoint returns 500 intermittently"
 
 ```
-1. gitnexus_search({query: "payment error handling", repo: "my-app"})
+1. gitnexus_search({query: "payment error handling"})
    → validatePayment, handlePaymentError, PaymentException
 
-2. gitnexus_explore({name: "validatePayment", type: "symbol", repo: "my-app"})
+2. gitnexus_explore({name: "validatePayment", type: "symbol"})
    → Callees: verifyCard, fetchRates (external API!)
 
 3. READ gitnexus://repo/my-app/process/CheckoutFlow
-   → Step 3: validatePayment → calls external API
+   → Step 3: validatePayment → calls fetchRates (external)
 
 4. Root cause: fetchRates calls external API without proper timeout
 ```
-
-## Debugging Patterns
-
-| Symptom | Approach |
-|---------|----------|
-| Error message | Search for error text, trace throw sites |
-| Wrong return value | Trace data flow through callees |
-| Intermittent failure | Look for external calls, timeouts |
-| Performance issue | Find hot paths via callers count |

package/skills/exploring.md

@@ -3,124 +3,71 @@ name: gitnexus-exploring
 description: Navigate unfamiliar code using GitNexus knowledge graph
 ---
 
-# Exploring Codebases
-
-## Quick Start
-```
-0. READ gitnexus://repos            → Discover indexed repos (use repo param if multiple)
-1. If "Index is stale" → run `npx gitnexus analyze` in terminal
-2. READ gitnexus://repo/{name}/context        → Get codebase overview (~150 tokens)
-3. READ gitnexus://repo/{name}/clusters       → See all functional clusters
-4. READ gitnexus://repo/{name}/cluster/{name} → Deep dive on specific cluster
-```
+# Exploring Codebases with GitNexus
 
 ## When to Use
 - "How does authentication work?"
 - "What's the project structure?"
 - "Show me the main components"
 - "Where is the database logic?"
+- Understanding code you haven't seen before
+
+## Workflow
 
-## Workflow Checklist
 ```
-Exploration Progress:
-- [ ] READ gitnexus://repos to discover available repos
-- [ ] READ gitnexus://repo/{name}/context for codebase overview
-- [ ] READ gitnexus://repo/{name}/clusters to list all clusters
-- [ ] Identify the relevant cluster by name
-- [ ] READ gitnexus://repo/{name}/cluster/{name} for cluster details
-- [ ] Use gitnexus_explore for specific symbols
+1. READ gitnexus://repos                          → Discover indexed repos
+2. READ gitnexus://repo/{name}/context             → Codebase overview, check staleness
+3. READ gitnexus://repo/{name}/clusters            → See all functional areas
+4. READ gitnexus://repo/{name}/cluster/{name}      → Drill into relevant cluster
+5. gitnexus_explore({name, type: "symbol"})        → Deep dive on specific symbol
 ```
 
-## Resource Reference
+> If step 2 says "Index is stale" → run `npx gitnexus analyze` in terminal.
 
-### gitnexus://repos
-Discover all indexed repositories. **Read first.**
-```yaml
-repos:
-  - name: "my-app"
-    path: "/home/user/my-app"
-    files: 42
-    symbols: 918
-```
+## Checklist
 
-### gitnexus://repo/{name}/context
-Codebase overview for a specific repo.
-```yaml
-project: my-app
-stats:
-  files: 42
-  symbols: 918
-  clusters: 12
-  processes: 45
-tools_available: [list_repos, search, explore, impact, overview, cypher]
 ```
-
-### gitnexus://repo/{name}/clusters
-All functional clusters with cohesion scores.
-```yaml
-clusters:
-  - name: "Auth"
-    symbols: 47
-    cohesion: 92%
-  - name: "Database"
-    symbols: 32
-    cohesion: 88%
+- [ ] READ gitnexus://repos
+- [ ] READ gitnexus://repo/{name}/context
+- [ ] READ gitnexus://repo/{name}/clusters
+- [ ] Identify the relevant cluster
+- [ ] READ gitnexus://repo/{name}/cluster/{name}
+- [ ] gitnexus_explore for key symbols
+- [ ] Read source files for implementation details
 ```
 
-### gitnexus://repo/{name}/cluster/{clusterName}
-Members of a specific cluster.
-```yaml
-name: Auth
-symbols: 47
-cohesion: 92%
-members:
-  - name: validateUser
-    type: Function
-    file: src/auth/validator.ts
-```
+## Resources
 
-### gitnexus://repo/{name}/process/{processName}
-Full execution trace.
-```yaml
-name: LoginFlow
-type: cross_community
-steps:
-  1: handleLogin (src/auth/handler.ts)
-  2: validateUser (src/auth/validator.ts)
-  3: createSession (src/auth/session.ts)
-```
+| Resource | What you get |
+|----------|-------------|
+| `gitnexus://repo/{name}/context` | Stats, staleness warning (~150 tokens) |
+| `gitnexus://repo/{name}/clusters` | All clusters with cohesion scores (~300 tokens) |
+| `gitnexus://repo/{name}/cluster/{name}` | Cluster members with file paths (~500 tokens) |
+| `gitnexus://repo/{name}/process/{name}` | Step-by-step execution trace (~200 tokens) |
 
-## Tool Reference (When Resources Aren't Enough)
+## Tools
 
-### gitnexus_explore
-For detailed symbol context with callers/callees:
+**gitnexus_explore** — symbol context with callers/callees:
 ```
-gitnexus_explore({name: "validateUser", type: "symbol", repo: "my-app"})
+gitnexus_explore({name: "validateUser", type: "symbol"})
 → Callers: loginHandler, apiMiddleware
 → Callees: checkToken, getUserById
+→ Cluster: Auth (92% cohesion)
 ```
 
-### gitnexus_search
-For finding code by query:
+**gitnexus_search** — find code by query when you don't know the cluster:
 ```
-gitnexus_search({query: "payment validation", depth: "full", repo: "my-app"})
+gitnexus_search({query: "payment validation", depth: "full"})
 ```
 
 ## Example: "How does payment processing work?"
 
 ```
-1. READ gitnexus://repos
-   → Repos: my-app (918 symbols)
-
-2. READ gitnexus://repo/my-app/context
-   → 918 symbols, 12 clusters
-
-3. READ gitnexus://repo/my-app/clusters
-   → Clusters: Auth, Payment, Database, API...
-
-4. READ gitnexus://repo/my-app/cluster/Payment
-   → Members: processPayment, validateCard, PaymentService
-
-5. READ gitnexus://repo/my-app/process/CheckoutFlow
-   → handleCheckout → validateCart → processPayment → sendConfirmation
+1. READ gitnexus://repo/my-app/context       → 918 symbols, 12 clusters
+2. READ gitnexus://repo/my-app/clusters       → Auth, Payment, Database, API...
+3. READ gitnexus://repo/my-app/cluster/Payment → processPayment, validateCard, PaymentService
+4. gitnexus_explore({name: "processPayment", type: "symbol"})
+   → Callers: checkoutHandler, webhookHandler
+   → Callees: validateCard, chargeStripe, saveTransaction
+5. Read src/payments/processor.ts for implementation details
 ```

package/skills/impact-analysis.md

@@ -3,74 +3,64 @@ name: gitnexus-impact-analysis
 description: Analyze blast radius before making code changes
 ---
 
-# Impact Analysis
-
-## Quick Start
-```
-0. READ gitnexus://repos                                    → Discover indexed repos
-1. If "Index is stale" → run `npx gitnexus analyze` in terminal
-2. gitnexus_impact({target, direction: "upstream", repo: "my-app"}) → What depends on this
-3. READ gitnexus://repo/my-app/clusters                     → Check affected areas
-4. READ gitnexus://repo/my-app/processes                    → Affected execution flows
-```
+# Impact Analysis with GitNexus
 
 ## When to Use
 - "Is it safe to change this function?"
 - "What will break if I modify X?"
 - "Show me the blast radius"
 - "Who uses this code?"
+- Before making non-trivial code changes
 
-## Understanding Output
+## Workflow
 
-| Depth | Risk Level | Meaning |
-|-------|-----------|---------|
-| d=1 | WILL BREAK | Direct callers/importers |
-| d=2 | LIKELY AFFECTED | Indirect dependencies |
-| d=3 | MAY NEED TESTING | Transitive effects |
+```
+1. gitnexus_impact({target: "X", direction: "upstream"})  → What depends on this
+2. READ gitnexus://repo/{name}/clusters                    → Check which areas are affected
+3. READ gitnexus://repo/{name}/processes                   → Check affected execution flows
+4. Assess risk and report to user
+```
+
+> If "Index is stale" → run `npx gitnexus analyze` in terminal.
+
+## Checklist
 
-## Workflow Checklist
 ```
-Impact Analysis:
-- [ ] READ gitnexus://repos to find the right repo
-- [ ] gitnexus_impact(target, "upstream", repo) to find dependents
-- [ ] READ gitnexus://repo/{name}/clusters to understand affected areas
-- [ ] Check high-confidence (>0.8) dependencies first
+- [ ] gitnexus_impact({target, direction: "upstream"}) to find dependents
+- [ ] Review d=1 items first (these WILL BREAK)
+- [ ] Check high-confidence (>0.8) dependencies
+- [ ] READ clusters to understand which areas are affected
 - [ ] Count affected clusters (cross-cutting = higher risk)
-- [ ] If >10 processes affected, consider splitting change
+- [ ] READ processes to check affected execution flows
+- [ ] Assess risk level and report to user
 ```
 
-## Resource Reference
+## Understanding Output
 
-### gitnexus://repo/{name}/clusters
-Check which clusters might be affected:
-```yaml
-clusters:
-  - name: Auth
-    symbols: 47
-  - name: API
-    symbols: 32
-```
+| Depth | Risk Level | Meaning |
+|-------|-----------|---------|
+| d=1 | **WILL BREAK** | Direct callers/importers |
+| d=2 | LIKELY AFFECTED | Indirect dependencies |
+| d=3 | MAY NEED TESTING | Transitive effects |
 
-### gitnexus://repo/{name}/processes
-Find which processes touch the target:
-```yaml
-processes:
-  - name: LoginFlow
-    type: cross_community
-    steps: 5
-```
+## Risk Assessment
 
-## Tool Reference
+| Affected | Risk |
+|----------|------|
+| <5 symbols, 1 cluster | LOW |
+| 5-15 symbols, 1-2 clusters | MEDIUM |
+| >15 symbols or 3+ clusters | HIGH |
+| Critical path (auth, payments) | CRITICAL |
+
+## Tools
 
-### gitnexus_impact
-Analyze blast radius:
+**gitnexus_impact** — the primary tool:
 ```
 gitnexus_impact({
   target: "validateUser",
   direction: "upstream",
   minConfidence: 0.8,
-  maxDepth: 3,
-  repo: "my-app"
+  maxDepth: 3
 })
 
 → d=1 (WILL BREAK):
@@ -84,34 +74,15 @@ gitnexus_impact({
 → Risk: MEDIUM (3 processes)
 ```
 
-## Risk Assessment
-
-| Affected | Risk |
-|----------|------|
-| <5 symbols, 1 cluster | LOW |
-| 5-15 symbols, 1-2 clusters | MEDIUM |
-| >15 symbols or 3+ clusters | HIGH |
-| Critical path (auth, payments) | CRITICAL |
-
-## Pre-Change Checklist
-```
-Before Committing:
-- [ ] Run impact analysis
-- [ ] Review all d=1 (WILL BREAK) items
-- [ ] Verify test coverage for affected processes
-- [ ] If risk > MEDIUM, get code review
-- [ ] If cross-cluster, coordinate with other teams
-```
-
 ## Example: "What breaks if I change validateUser?"
 
 ```
-1. gitnexus_impact({target: "validateUser", direction: "upstream", repo: "my-app"})
-   → d=1: loginHandler, apiMiddleware
-   → d=2: authRouter, sessionManager
+1. gitnexus_impact({target: "validateUser", direction: "upstream"})
+   → d=1: loginHandler, apiMiddleware (WILL BREAK)
+   → d=2: authRouter, sessionManager (LIKELY AFFECTED)
 
 2. READ gitnexus://repo/my-app/clusters
-   → Auth and API clusters affected
+   → Auth and API clusters affected (2 clusters)
 
-3. Decision: 2 direct callers, 2 clusters = MEDIUM risk
+3. Risk: 2 direct callers, 2 clusters = MEDIUM
 ```

package/skills/refactoring.md

@@ -5,116 +5,98 @@ description: Plan safe refactors using blast radius and dependency mapping
 
 # Refactoring with GitNexus
 
-## Quick Start
-```
-0. READ gitnexus://repos                                    → Discover indexed repos
-1. If "Index is stale" → run `npx gitnexus analyze` in terminal
-2. gitnexus_impact({target, direction: "upstream", repo: "my-app"}) → Map all dependents
-3. READ gitnexus://repo/my-app/schema                       → Understand graph structure
-4. gitnexus_cypher({query: "...", repo: "my-app"})           → Find all references
-```
-
 ## When to Use
 - "Rename this function safely"
 - "Extract this into a module"
 - "Split this service"
-- "Refactor without breaking things"
+- "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_search({query: "X"})                           → Find string/dynamic references
+3. READ gitnexus://repo/{name}/cluster/{name}              → Check cohesion impact
+4. Plan update order: interfaces → implementations → callers → tests
+```
+
+> If "Index is stale" → run `npx gitnexus analyze` in terminal.
 
 ## Checklists
 
 ### Rename Symbol
 ```
-Rename Refactoring:
-- [ ] gitnexus_impact({target: oldName, direction: "upstream", repo: "my-app"}) — find all callers
-- [ ] gitnexus_search({query: oldName, repo: "my-app"}) — find string literals
-- [ ] Check for reflection/dynamic references
-- [ ] Update in order: interface → implementation → usages
+- [ ] gitnexus_impact({target: oldName, direction: "upstream"}) — find all callers
+- [ ] gitnexus_search({query: oldName}) — find string literals and dynamic references
+- [ ] Check for reflection/dynamic invocation patterns
+- [ ] Plan update order: interface → implementation → callers → tests
+- [ ] Update all d=1 (WILL BREAK) items
 - [ ] Run tests for affected processes
 ```
 
 ### Extract Module
 ```
-Extract Module:
-- [ ] gitnexus_explore({name: target, type: "symbol", repo: "my-app"}) — map dependencies
-- [ ] gitnexus_impact({target, direction: "upstream", repo: "my-app"}) — find callers
-- [ ] READ gitnexus://repo/my-app/cluster/{name} — check cohesion
+- [ ] gitnexus_explore({name: target, type: "symbol"}) — map internal dependencies
+- [ ] gitnexus_impact({target, direction: "upstream"}) — find all external callers
+- [ ] READ cluster resource — check if extraction preserves cohesion
 - [ ] Define new module interface
-- [ ] Update imports across affected files
+- [ ] Extract code, update imports
+- [ ] Run tests for affected processes
 ```
 
-### Split Function
+### Split Function/Service
 ```
-Split Function:
-- [ ] gitnexus_explore({name: target, type: "symbol", repo: "my-app"}) — understand callees
-- [ ] Group related logic
-- [ ] gitnexus_impact — verify callers won't break
-- [ ] Create new functions
+- [ ] gitnexus_explore({name: target, type: "symbol"}) — understand all callees
+- [ ] Group callees by responsibility/domain
+- [ ] gitnexus_impact({target, direction: "upstream"}) — map callers to update
+- [ ] Create new functions/services
 - [ ] Update callers
+- [ ] Run tests for affected processes
 ```
 
-## Resource Reference
+## Tools
 
-### gitnexus://repo/{name}/schema
-Graph structure for Cypher queries:
-```yaml
-nodes: [Function, Class, Method, Community, Process]
-relationships: [CALLS, IMPORTS, EXTENDS, MEMBER_OF]
-
-example_queries:
-  find_callers: |
-    MATCH (caller)-[:CodeRelation {type: 'CALLS'}]->(f:Function {name: "X"})
-    RETURN caller.name
+**gitnexus_impact** — map all dependents first:
 ```
-
-### gitnexus://repo/{name}/cluster/{clusterName}
-Check if extraction preserves cohesion:
-```yaml
-name: Payment
-cohesion: 92%
-members: [processPayment, validateCard, PaymentService]
+gitnexus_impact({target: "validateUser", direction: "upstream"})
+→ d=1: loginHandler, apiMiddleware, testUtils
+→ Affected Processes: LoginFlow, TokenRefresh
 ```
 
-## Tool Reference
+**gitnexus_search** — find string/dynamic references impact() might miss:
+```
+gitnexus_search({query: "validateUser"})
+→ Found in: config.json (dynamic reference!), test fixtures
+```
 
-### Finding all references
+**gitnexus_cypher** — custom reference queries:
 ```cypher
 MATCH (caller)-[:CodeRelation {type: 'CALLS'}]->(f:Function {name: "validateUser"})
-RETURN caller.name, caller.filePath
-ORDER BY caller.filePath
+RETURN caller.name, caller.filePath ORDER BY caller.filePath
 ```
 
-### Finding imports of a module
-```cypher
-MATCH (importer)-[:CodeRelation {type: 'IMPORTS'}]->(f:File {name: "utils.ts"})
-RETURN importer.name, importer.filePath
-```
+## Risk Rules
+
+| Risk Factor | Mitigation |
+|-------------|------------|
+| Many callers (>5) | Update in small batches |
+| Cross-cluster refs | Coordinate with affected areas |
+| String/dynamic refs | `gitnexus_search` to find them |
+| External/public API | Version and deprecate properly |
 
-## Example: Safely Rename `validateUser` to `authenticateUser`
+## Example: Rename `validateUser` to `authenticateUser`
 
 ```
-1. gitnexus_impact({target: "validateUser", direction: "upstream", repo: "my-app"})
-   → loginHandler, apiMiddleware, testUtils
+1. gitnexus_impact({target: "validateUser", direction: "upstream"})
+   → d=1: loginHandler, apiMiddleware, testUtils
 
-2. gitnexus_search({query: "validateUser", repo: "my-app"})
+2. gitnexus_search({query: "validateUser"})
    → Found in: config.json (dynamic reference!)
 
-3. READ gitnexus://repo/my-app/processes
-   → LoginFlow, TokenRefresh, APIGateway
-
-4. Plan update order:
-   1. Update declaration in auth.ts
+3. Plan update order:
+   1. Update declaration in src/auth/validator.ts
    2. Update config.json string reference
-   3. Update loginHandler
-   4. Update apiMiddleware
-   5. Run tests for LoginFlow, TokenRefresh
+   3. Update loginHandler, apiMiddleware, testUtils
+   4. Run tests for LoginFlow, TokenRefresh
 ```
-
-## Refactoring Safety Rules
-
-| Risk Factor | Mitigation |
-|-------------|------------|
-| Many callers (>5) | Update in small batches |
-| Cross-cluster | Coordinate with other teams |
-| String references | Search for dynamic usage |
-| Reflection | Check for dynamic invocation |
-| External exports | May break downstream repos |