context-mcp-server 1.1.2 → 1.1.4

package/pyproject.toml

@@ -1,72 +1,72 @@
-[build-system]
-requires = ["hatchling"]
-build-backend = "hatchling.build"
-
-[project]
-name = "codegraph-mcp"
-version = "1.1.2"
-description = "Codebase knowledge graph MCP server — AST extraction, graph queries, community detection"
-readme = "README.md"
-requires-python = ">=3.11"
-license = { text = "MIT" }
-keywords = ["mcp", "ai", "codegraph", "knowledge-graph", "ast"]
-dependencies = [
-    "mcp>=1.0.0",
-    "networkx>=3.0",
-    "pymupdf>=1.24",
-    "tree-sitter>=0.23.0",
-]
-
-[project.optional-dependencies]
-leiden = [
-    "graspologic>=3.3",
-]
-treesitter = [
-    "tree-sitter>=0.23.0",
-    "tree-sitter-python",
-    "tree-sitter-javascript",
-    "tree-sitter-typescript",
-    "tree-sitter-go",
-    "tree-sitter-rust",
-    "tree-sitter-java",
-    "tree-sitter-c",
-    "tree-sitter-cpp",
-    "tree-sitter-c-sharp",
-    "tree-sitter-ruby",
-    "tree-sitter-php",
-    "tree-sitter-swift",
-    "tree-sitter-lua",
-    "tree-sitter-kotlin",
-]
-
-[project.scripts]
-codegraph-mcp = "codegraph.server:main"
-
-[tool.hatch.build.targets.wheel]
-packages = ["codegraph"]
-
-# ── uv ────────────────────────────────────────────────────────────────────────
-
-[dependency-groups]
-dev = [
-    "pytest>=8.0",
-    "pytest-asyncio>=0.23",
-    "ruff>=0.4",
-    "mypy>=1.10",
-]
-
-# ── ruff ─────────────────────────────────────────────────────────────────────
-
-[tool.ruff]
-target-version = "py311"
-line-length = 100
-
-[tool.ruff.lint]
-select = ["E", "F", "I"]
-ignore = ["E501"]
-
-# ── pytest ────────────────────────────────────────────────────────────────────
-
-[tool.pytest.ini_options]
-asyncio_mode = "auto"
-testpaths = ["tests"]
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "codegraph-mcp"
+version = "1.1.4"
+description = "Codebase knowledge graph MCP server — AST extraction, graph queries, community detection"
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "MIT" }
+keywords = ["mcp", "ai", "codegraph", "knowledge-graph", "ast"]
+dependencies = [
+    "mcp>=1.0.0",
+    "networkx>=3.0",
+    "pymupdf>=1.24",
+    "tree-sitter>=0.23.0",
+]
+
+[project.optional-dependencies]
+leiden = [
+    "graspologic>=3.3",
+]
+treesitter = [
+    "tree-sitter>=0.23.0",
+    "tree-sitter-python",
+    "tree-sitter-javascript",
+    "tree-sitter-typescript",
+    "tree-sitter-go",
+    "tree-sitter-rust",
+    "tree-sitter-java",
+    "tree-sitter-c",
+    "tree-sitter-cpp",
+    "tree-sitter-c-sharp",
+    "tree-sitter-ruby",
+    "tree-sitter-php",
+    "tree-sitter-swift",
+    "tree-sitter-lua",
+    "tree-sitter-kotlin",
+]
+
+[project.scripts]
+codegraph-mcp = "codegraph.server:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["codegraph"]
+
+# ── uv ────────────────────────────────────────────────────────────────────────
+
+[dependency-groups]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.23",
+    "ruff>=0.4",
+    "mypy>=1.10",
+]
+
+# ── ruff ─────────────────────────────────────────────────────────────────────
+
+[tool.ruff]
+target-version = "py311"
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "I"]
+ignore = ["E501"]
+
+# ── pytest ────────────────────────────────────────────────────────────────────
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]

package/src/cli.js

@@ -5,7 +5,7 @@
  */
 
 import readline from 'node:readline';
-import { readFileSync, writeFileSync, mkdirSync, existsSync, unlinkSync } from 'node:fs';
+import { readFileSync, writeFileSync, mkdirSync, existsSync, unlinkSync, chmodSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { homedir } from 'node:os';
 import { fileURLToPath } from 'node:url';
@@ -414,7 +414,6 @@ const _GLOBAL_GITIGNORE_ENTRIES = [
   '.gemini/',
   '.codex/',
   '.windsurf/',
-  '.agents/',
   // Build outputs and session artifacts
   'codegraph-cache/',
   '.mcp.json',
@@ -429,7 +428,6 @@ function _graphForProject(graphs, projectName) {
 
 const _PROJECT_GITIGNORE_ENTRIES = [
   '.claude/', '.cursor/', '.vscode/', '.gemini/', '.codex/',
-  '.agents/',
   'codegraph-cache/', '.mcp.json', 'CLAUDE.md', 'GEMINI.md', 'AGENTS.md',
 ];
 
@@ -498,7 +496,12 @@ function _copyHooks(platform, dotDir, dir, hookFiles) {
   for (const file of hookFiles) {
     const src = join(hooksSrc, file);
     if (existsSync(src)) {
-      _writeFile(join(hooksDest, file), readFileSync(src, 'utf8'), `${dotDir}/hooks/${file}`);
+      const dest = join(hooksDest, file);
+      _writeFile(dest, readFileSync(src, 'utf8'), `${dotDir}/hooks/${file}`);
+      // Make executable on Unix so shells can run it without explicit `node` prefix
+      if (process.platform !== 'win32') {
+        try { chmodSync(dest, 0o755); } catch {}
+      }
     }
   }
 }
@@ -618,11 +621,11 @@ const PLATFORMS = {
       _mergeHooksIntoSettings(settingsPath, {
         PreToolUse: [{
           matcher: 'Bash',
-          hooks: [{ type: 'command', command: preHook, timeout: 30, statusMessage: 'Checking shell command' }],
+          hooks: [{ type: 'command', command: `node "${preHook}"`, timeout: 30, statusMessage: 'Checking shell command' }],
         }],
         PostToolUse: [{
           matcher: 'Bash',
-          hooks: [{ type: 'command', command: postHook, timeout: 30, statusMessage: 'Saving failed shell context' }],
+          hooks: [{ type: 'command', command: `node "${postHook}"`, timeout: 30, statusMessage: 'Saving failed shell context' }],
         }],
       }, scope === 'project' ? '.claude/settings.json' : '~/.claude/settings.json');
       // Register MCP server via claude CLI
@@ -732,11 +735,11 @@ const PLATFORMS = {
       );
       settings.hooks.BeforeTool = stripOld(settings.hooks.BeforeTool).concat([{
         matcher: 'run_shell_command',
-        hooks: [{ type: 'command', command: `node ${beforeHook}`, timeout: 30 }],
+        hooks: [{ type: 'command', command: `node "${beforeHook}"`, timeout: 30 }],
       }]);
       settings.hooks.AfterTool = stripOld(settings.hooks.AfterTool).concat([{
         matcher: 'run_shell_command',
-        hooks: [{ type: 'command', command: `node ${afterHook}`, timeout: 30 }],
+        hooks: [{ type: 'command', command: `node "${afterHook}"`, timeout: 30 }],
       }]);
       _writeFile(settingsPath,
         JSON.stringify(settings, null, 2),
@@ -829,39 +832,6 @@ const PLATFORMS = {
       }
     },
   },
-  antigravity: {
-    label: 'Antigravity IDE',
-    restartNote: 'Restart your Antigravity session to pick up hooks and rules.',
-    install(dir, scope) {
-      // Antigravity uses stdio-incompatible MCP transport — integrate via ctx CLI + GEMINI.md instead.
-      if (scope === 'project') {
-        // Post-tool hook — saves failed tool calls to context-mcp via ctx CLI
-        _copyHooks('antigravity', '.agents', dir, ['context-mcp-post-tool-use.js']);
-        const hookPath = join(dir, '.agents', 'hooks', 'context-mcp-post-tool-use.js');
-        _mergeJsonFile(join(dir, '.agents', 'hooks.json'), '.agents/hooks.json', obj => {
-          const strip = arr => (arr || []).filter(h => !String(h.command || '').includes('context-mcp-'));
-          obj.hooks = strip(obj.hooks).concat([{
-            event: 'PostToolUse',
-            command: `node "${hookPath}"`,
-          }]);
-        });
-        // Workflows (slash commands) — .agents/workflows/
-        const wfSrc = join(TPLS, 'antigravity', 'workflows');
-        for (const file of ['context-resume.md', 'graph-build.md', 'save-context.md']) {
-          const src = join(wfSrc, file);
-          if (existsSync(src)) _writeFile(join(dir, '.agents', 'workflows', file), readFileSync(src, 'utf8'), `.agents/workflows/${file}`);
-        }
-      }
-      // Rules file — project root for project scope, ~/.config/antigravity/GEMINI.md for global
-      const agMd = _tpl('antigravity/GEMINI.md');
-      if (agMd) {
-        const agMdPath = scope === 'project'
-          ? join(dir, 'GEMINI.md')
-          : join(homedir(), '.config', 'antigravity', 'GEMINI.md');
-        _writeFile(agMdPath, agMd, scope === 'project' ? 'GEMINI.md' : '~/.config/antigravity/GEMINI.md');
-      }
-    },
-  },
 };
 
 async function cmdInstall(args) {
@@ -923,7 +893,7 @@ async function cmdInstall(args) {
 
   if (!keys.length) {
     printSection('Install');
-    console.log(`  ${muted('Usage:')}  ctx install ${faint('[--initial] [--claude] [--cursor] [--vscode] [--gemini] [--codex] [--windsurf] [--antigravity] [--all]')}`);
+    console.log(`  ${muted('Usage:')}  ctx install ${faint('[--initial] [--claude] [--cursor] [--vscode] [--gemini] [--codex] [--windsurf] [--all]')}`);
     console.log('');
     console.log(`  ${accent('--initial      ')}  ${faint('Install / update Node.js + Python (codegraph) deps')}`);
     console.log('');

package/src/db.js

@@ -178,6 +178,11 @@ function findEntryById(id, projectHint) {
     const e = search(data);
     if (e) return { entry: e, projectName: name };
   }
+  // Always check 'global' — it is never in the projects index
+  if (!_projectData.has('global') && 'global' !== projectHint) {
+    const e = search(loadProjectData('global'));
+    if (e) return { entry: e, projectName: 'global' };
+  }
   const idx = loadProjectsIndex();
   for (const proj of idx) {
     if (_projectData.has(proj.name) || proj.name === projectHint) continue;
@@ -384,10 +389,12 @@ export function getContext({ project, tags, limit = 20, compact = false, ids } =
 
   if (ids && ids.length) {
     const idSet = new Set(ids);
-    // Load all projects to find entries
+    // Load all projects to find entries — always include 'global' since it is
+    // never registered in the projects index (ensureProject skips it)
     const idx = loadProjectsIndex();
     const all = [];
     const loaded = new Set(_projectData.keys());
+    loaded.add('global'); // ensure global is always searched
     for (const proj of idx) loaded.add(proj.name);
     for (const name of loaded) {
       for (const e of getAllEntries(name)) {
@@ -403,10 +410,11 @@ export function getContext({ project, tags, limit = 20, compact = false, ids } =
     const globalEntries = project !== 'global' ? getAllEntries('global') : [];
     results = [...entries, ...globalEntries];
   } else {
-    // No project filter: load all
+    // No project filter: load all — always include 'global' since it is never in the index
     const idx = loadProjectsIndex();
     const all = [];
     const seen = new Set(_projectData.keys());
+    seen.add('global');
     for (const proj of idx) seen.add(proj.name);
     for (const name of seen) {
       all.push(...getAllEntries(name));
@@ -434,7 +442,7 @@ export function getContextSince(since, project) {
   } else {
     const idx = loadProjectsIndex();
     results = [];
-    const seen = new Set([..._projectData.keys(), ...idx.map(p => p.name)]);
+    const seen = new Set([..._projectData.keys(), 'global', ...idx.map(p => p.name)]);
     for (const name of seen) results.push(...getAllEntries(name));
   }
   return results.filter(c => c.createdAt >= since);
@@ -450,12 +458,15 @@ export function searchContext({ query, project, limit = 10, compact = false }) {
   } else {
     const idx = loadProjectsIndex();
     results = [];
-    const seen = new Set([..._projectData.keys(), ...idx.map(p => p.name)]);
+    const seen = new Set([..._projectData.keys(), 'global', ...idx.map(p => p.name)]);
     for (const name of seen) results.push(...getAllEntries(name));
   }
   const scored = results.map(c => {
     const haystack = `${c.title || ''} ${c.content || ''} ${(Array.isArray(c.tags) ? c.tags : []).join(' ')}`.toLowerCase();
-    const score = terms.reduce((s, t) => s + (haystack.split(t).length - 1), 0);
+    const score = terms.reduce((s, t) => {
+      try { return s + (haystack.match(new RegExp(`\\b${t.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\b`, 'g'))?.length ?? 0); }
+      catch { return s; }
+    }, 0);
     return { ...c, score };
   }).filter(c => c.score > 0).sort((a, b) => b.score - a.score);
   const sliced = scored.slice(0, limit).map(({ score, ...c }) => c);
@@ -467,8 +478,9 @@ export function deleteContext({ id, ids }) {
   const idSet = new Set(ids && ids.length ? ids : (id ? [id] : []));
   if (!idSet.size) return { deleted: 0 };
   let deleted = 0;
-  // Scan all loaded projects
+  // Scan all loaded projects — always include 'global' since it is never in the index
   const seen = new Set(_projectData.keys());
+  seen.add('global');
   loadProjectsIndex().forEach(p => seen.add(p.name));
   for (const name of seen) {
     const data = loadProjectData(name);
@@ -524,7 +536,7 @@ export function countContext(project) {
   if (!project) {
     const idx = loadProjectsIndex();
     let total = 0;
-    const seen = new Set([..._projectData.keys(), ...idx.map(p => p.name)]);
+    const seen = new Set([..._projectData.keys(), 'global', ...idx.map(p => p.name)]);
     for (const name of seen) total += getAllEntries(name).length;
     return total;
   }
@@ -658,7 +670,7 @@ export function updateDiscussion({ id, name, title, description, content, status
   let disc = null;
   let projName = null;
   const idx = loadProjectsIndex();
-  const seen = new Set([..._projectData.keys(), ...idx.map(p => p.name)]);
+  const seen = new Set([..._projectData.keys(), 'global', ...idx.map(p => p.name)]);
   for (const pName of seen) {
     const d = loadProjectData(pName);
     const found = id ? d.discussions.find(x => x.id === id) : d.discussions.find(x => x.name === name);
@@ -690,9 +702,9 @@ export function getDiscussion({ project, name, id } = {}) {
     if (name) return list.find(d => d.name === name) || null;
     return null;
   }
-  // Search all
+  // Search all — always include 'global' since it is never in the projects index
   const idx = loadProjectsIndex();
-  const seen = new Set([..._projectData.keys(), ...idx.map(p => p.name)]);
+  const seen = new Set([..._projectData.keys(), 'global', ...idx.map(p => p.name)]);
   for (const pName of seen) {
     const d = loadProjectData(pName);
     const found = id ? d.discussions.find(x => x.id === id) : d.discussions.find(x => x.name === name);
@@ -709,7 +721,7 @@ export function listDiscussions({ project, status, type } = {}) {
     if (project !== 'global') list = [...list, ...loadProjectData('global').discussions];
   } else {
     const idx = loadProjectsIndex();
-    const seen = new Set([..._projectData.keys(), ...idx.map(p => p.name)]);
+    const seen = new Set([..._projectData.keys(), 'global', ...idx.map(p => p.name)]);
     for (const pName of seen) list.push(...loadProjectData(pName).discussions);
   }
   if (status) list = list.filter(d => d.status === status);
@@ -730,7 +742,7 @@ export function linkContextToDiscussion({ discussionId, discussionName, contextI
   let disc = null;
   let discProject = null;
   const idx = loadProjectsIndex();
-  const seen = new Set([..._projectData.keys(), ...idx.map(p => p.name)]);
+  const seen = new Set([..._projectData.keys(), 'global', ...idx.map(p => p.name)]);
   for (const pName of seen) {
     const d = loadProjectData(pName);
     const found = discussionId
@@ -764,7 +776,7 @@ export function linkContextToDiscussion({ discussionId, discussionName, contextI
 export function deleteDiscussion({ name, id }) {
   init();
   const idx = loadProjectsIndex();
-  const seen = new Set([..._projectData.keys(), ...idx.map(p => p.name)]);
+  const seen = new Set([..._projectData.keys(), 'global', ...idx.map(p => p.name)]);
   for (const pName of seen) {
     const data = loadProjectData(pName);
     const before = data.discussions.length;
@@ -803,7 +815,7 @@ export function archiveExpired(project) {
     processEntries(getAllEntries(project), project);
   } else {
     const idx = loadProjectsIndex();
-    const seen = new Set([..._projectData.keys(), ...idx.map(p => p.name)]);
+    const seen = new Set([..._projectData.keys(), 'global', ...idx.map(p => p.name)]);
     for (const name of seen) processEntries(getAllEntries(name).slice(), name);
   }
   if (count > 0) markDirty();

package/src/http.js

@@ -622,7 +622,7 @@ async function handleRequest(req, res) {
               <div class="step">
                 <span class="step-num">2</span>
                 <span class="step-title">Server URL</span>
-                <span class="step-content">Enter: <code>${req.headers['x-forwarded-proto'] || req.socket?.encrypted ? 'https' : 'http'}://${req.headers.host}</code></span>
+                <span class="step-content">Enter: <code>${req.headers['x-forwarded-proto'] === 'https' || req.socket?.encrypted ? 'https' : 'http'}://${req.headers.host}</code></span>
               </div>
 
               <div class="step">

package/src/search.js

@@ -98,15 +98,10 @@ export function search({ query, mode = 'semantic', project, limit = 10, id, comp
       const all = getContext({ limit: 1000 });
       const target = all.find(e => e.id === id || e.id.startsWith(id));
       if (!target) throw new Error(`No entry found with id starting "${id}"`);
-      const explicitIds = new Set([
-        ...(target.relations  || []).map(r => r.id),
-        ...(target.relatedBy  || []).map(r => r.id),
-      ]);
-      const explicit = all.filter(e => explicitIds.has(e.id));
-      const semantic = explicitIds.size < limit
-        ? findRelated(target, all.filter(e => !explicitIds.has(e.id) && e.id !== target.id), limit - explicitIds.size)
-        : [];
-      return { target, results: [...explicit, ...semantic].slice(0, limit) };
+      // ponytail: relations/relatedBy never populated — pure semantic fallback
+      const others = all.filter(e => e.id !== target.id);
+      const results = findRelated(target, others, limit);
+      return { target, results };
     }
     default:
       throw new Error(`Unknown search mode: ${mode}. Use: keyword, semantic, related`);

package/src/server.js

@@ -9,17 +9,20 @@ import { getConfig } from './config.js';
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const { version } = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf8'));
 
-import * as contextTool    from './tools/context.js';
-import * as searchTool     from './tools/search.js';
-import * as planTool        from './tools/plan.js';
-import * as errorCheckTool from './tools/errorCheck.js';
-import * as fileTool       from './tools/fileTools.js';
-import * as gitTool        from './tools/gitTools.js';
-import * as codegraphTool  from './tools/codegraph.js';
+import * as contextTool      from './tools/context.js';
+import * as searchTool       from './tools/search.js';
+import * as planTool          from './tools/plan.js';
+import * as errorCheckTool   from './tools/errorCheck.js';
+import * as fileTool         from './tools/fileTools.js';
+import * as gitTool          from './tools/gitTools.js';
+import * as codegraphTool    from './tools/codegraph.js';
+import * as symbolDetailTool from './tools/symbolDetail.js';
+import * as toolRegistryTool from './tools/toolRegistry.js';
 
 const FILE_TOOL_NAMES      = new Set(fileTool.definitions.map(d => d.name));
 const GIT_TOOL_NAMES       = new Set(gitTool.definitions.map(d => d.name));
 const CODEGRAPH_TOOL_NAMES = codegraphTool.TOOL_NAMES;
+const REGISTRY_TOOL_NAMES  = toolRegistryTool.TOOL_NAMES;
 
 export function createServer({ enableFileTools = false, enableGitTools = getConfig().access_git === true } = {}) {
   const state = {
@@ -43,6 +46,8 @@ export function createServer({ enableFileTools = false, enableGitTools = getConf
     if (enableFileTools) tools.push(...fileTool.definitions);
     if (enableGitTools)  tools.push(...gitTool.definitions);
     tools.push(...codegraphTool.definitions);
+    tools.push(symbolDetailTool.definition);
+    tools.push(...toolRegistryTool.definitions);
     return { tools };
   });
 
@@ -73,6 +78,10 @@ export function createServer({ enableFileTools = false, enableGitTools = getConf
         result = await gitTool.handle(name, args, state);
       } else if (CODEGRAPH_TOOL_NAMES.has(name)) {
         result = codegraphTool.handle(name, args, state);
+      } else if (name === symbolDetailTool.definition.name) {
+        result = await symbolDetailTool.handle(args, state);
+      } else if (REGISTRY_TOOL_NAMES.has(name)) {
+        result = toolRegistryTool.handle(name);
       } else {
         throw new Error(`Unknown tool: ${name}`);
       }

package/src/templates/antigravity/GEMINI.md

@@ -74,14 +74,26 @@ Run `ctx search "<query>" --project <project>` before asking the user to re-expl
 ## 6. ContextGraph CLI
 
 ```
-ctx graph build <path>            → build AST graph (run once, incremental)
-ctx graph arch <path>             → module map: files, exports, imports
-ctx graph query <path> "<question>"  → structural question about the codebase
-ctx graph nodes <path> <type>     → list all nodes of a type
-ctx graph report <path>           → god nodes, clusters, surprising connections
+ctx graph build <path>              → build AST graph (run once, incremental)
+ctx graph arch <path>               → module map: files, exports, imports
+ctx graph query <path> "<question>" → structural question about the codebase
+ctx graph nodes <path> <type>       → list all nodes of a type (class|function|module|file|struct|table)
+ctx graph report <path>             → god nodes, clusters, surprising connections
+ctx graph affected <path> <node>    → blast radius — what breaks if X changes?
 ```
 
-Use `ctx graph arch` first. Never read files for structure questions.
+MCP tools (when available):
+- `get_symbol_detail(name, path)` — source code for one function, no full file read
+- `tool_registry()` — which tools have side effects
+- `safety_policy()` — which actions need confirmation
+
+Decision rules:
+- **Unknown codebase**: `ctx graph report` first
+- **Before any refactor**: `ctx graph affected <path> <node>` — FIRST
+- **"Show me function X"**: `get_symbol_detail` or `ctx graph query`
+- **`ctx search`** finds past decisions. **`ctx graph query`** finds code. Different tools.
+
+Never read files for structure questions.
 
 ---
 

package/src/templates/claude/CLAUDE.md

@@ -122,10 +122,23 @@ codegraph_html(path, formats?)           → regenerate visualizations (auto-run
 | Where is function X defined? | `codegraph_query node:"X"` |
 | What does module Y depend on? | `codegraph_query question:"what does Y import?"` |
 | What are all the classes? | `codegraph_nodes type:"class"` |
-| Most connected files? | `codegraph_report` |
+| Most connected files / god nodes? | `codegraph_report` |
 | What breaks if I change X? | `codegraph_affected node:"X"` |
+| Show me only the code for function X? | `get_symbol_detail name:"X"` |
+| Which tools have side effects? | `tool_registry` |
+
+### When to reach for each graph tool
+
+- **Unknown territory** (first look at any codebase): `codegraph_report` — shows bottlenecks + surprises first
+- **"Where is X defined?"**: `codegraph_query node:"X"` — faster than grep
+- **"What does this module do?"**: `codegraph_arch` — static module map, no reads needed
+- **Before any refactor or rename**: `codegraph_affected node:"X"` — see blast radius FIRST
+- **"List all classes/functions"**: `codegraph_nodes type:"class"` or `type:"function"`
+- **Files changed since last session**: `codegraph_build` is incremental — re-run after adding files
+- **"Show me just that function"**: `get_symbol_detail` — avoids reading the whole file
 
 **Never read files for structure questions — use graph tools first.**
+**`search` finds past decisions. `codegraph_query` finds code symbols. Different tools.**
 
 ---
 

package/src/templates/claude/skills/SKILL.md

@@ -34,7 +34,7 @@ Call `context` tool **before any tool or response** with:
 - `rootPath: "<absolute path to git repo root>"` — required for sandbox + graph lookup
 
 Returns:
-- `recentEntries` — last 15 entries; newest 5 have full content, rest have 200-char preview
+- `recentEntries` — last 15 entries; newest 2 + high-signal entries have full content, rest have 200-char preview
 - `activePlans` — in-progress plans; read them before starting any new work
 - `codegraph` — `{ built: true/false, nodes, edges, communities }`
 - `stats.totalEntries` — if ≥ 20, write a compaction summary before proceeding (see Rule 4)
@@ -116,10 +116,13 @@ codegraph_build(path)  →  AST graph: functions, classes, imports, edges
 ```
 codegraph_arch(path)                     → module map: every file, exports, imports
 codegraph_query(path, question?, node?)  → find symbol or answer structural question
-codegraph_nodes(path, type)              → list all nodes of a type
+codegraph_nodes(path, type)              → list all nodes of a type (class|function|module|file|struct|table)
 codegraph_report(path)                   → god nodes, clusters, structural analysis
 codegraph_affected(path, node, depth?)   → blast radius BFS — what breaks if X changes?
 codegraph_html(path, formats?)           → regenerate visualizations (auto-runs on every build)
+get_symbol_detail(name, path)            → source code for one function/class — no full file read
+tool_registry()                          → which tools have side effects + approval requirements
+safety_policy()                          → which actions need user confirmation
 ```
 
 | Question | Tool |
@@ -130,6 +133,15 @@ codegraph_html(path, formats?)           → regenerate visualizations (auto-run
 | List all classes/functions | `codegraph_nodes type:"class"` |
 | Most connected / central files | `codegraph_report` |
 | What breaks if I change X? | `codegraph_affected node:"X"` |
+| Show me just the code for function X | `get_symbol_detail name:"X"` |
+| Which tools are dangerous? | `tool_registry` or `safety_policy` |
+
+### When to reach for each graph tool
+
+- **Unknown territory**: `codegraph_report` first — god nodes + surprises
+- **Before any refactor or rename**: `codegraph_affected` — blast radius FIRST
+- **"Show me just that function"**: `get_symbol_detail` — avoids reading the whole file
+- **`search`** finds past decisions. **`codegraph_query`** finds code symbols. Different tools.
 
 ---
 
@@ -141,4 +153,4 @@ codegraph_html(path, formats?)           → regenerate visualizations (auto-run
 4. Compaction at ≥ 20 entries — before starting task
 5. Plan for multi-file work — `status:"done"` deletes it
 6. Search before asking about past work
-7. Graph tools before files
+7. Graph tools before files — `codegraph_affected` before any refactor

package/src/templates/codex/AGENTS.md

@@ -90,8 +90,15 @@ codegraph_affected(path, node, depth?)   -> blast radius BFS — what breaks if
 codegraph_html(path, formats?)           -> regenerate visualizations on demand
 ```
 
-Use `codegraph_arch` first. Read files only when you need exact bug or
-implementation details.
+Decision rules:
+- Unknown codebase: `codegraph_report` first (god nodes + surprises)
+- "Where is X?": `codegraph_query node:"X"`
+- Before any refactor: `codegraph_affected node:"X"` (blast radius)
+- List all classes: `codegraph_nodes type:"class"`
+- Just the function body: `get_symbol_detail name:"X"` (no full file read)
+- `search` finds past decisions. `codegraph_query` finds code symbols. Different tools.
+
+Read files only when you need exact bug or implementation details not in the graph.
 
 ---
 

package/src/templates/cursor/cursor-rules.mdc

@@ -34,18 +34,27 @@ Build once: `codegraph_build(path)` — auto-generates visualizations, then quer
 ```
 codegraph_arch(path)                   → module map (files, exports, imports)
 codegraph_query(path, question?, node?) → find symbol or answer structural question
-codegraph_nodes(path, type)            → list all nodes of a type
+codegraph_nodes(path, type)            → list all nodes of a type (class|function|module|file|struct|table)
 codegraph_report(path)                 → god nodes, clusters, structural analysis
 codegraph_affected(path, node, depth?) → blast radius — what breaks if X changes?
 codegraph_html(path, formats?)         → regenerate visualizations on demand
+get_symbol_detail(name, path)          → source code for one function/class — no full file read
+tool_registry()                        → which tools have side effects + approval requirements
+safety_policy()                        → which actions need user confirmation before running
 ```
 
-Use `codegraph_arch` for structural questions. Read files for bugs/logic.
+Decision rules:
+- **Unknown codebase**: `codegraph_report` first (god nodes + surprises)
+- **"Where is X?"**: `codegraph_query node:"X"` — faster than grep
+- **Before any refactor**: `codegraph_affected node:"X"` — see blast radius FIRST
+- **"Show me function X"**: `get_symbol_detail` — no full file read needed
+- **List all classes**: `codegraph_nodes type:"class"`
+- **`search`** finds past decisions. **`codegraph_query`** finds code symbols. Different tools.
 
 ## Rules
 
 1. `context.resume` first — every conversation
 2. Always pass `project`
 3. `search` before asking the user about past work
-4. `codegraph_arch` before reading files
-5. Files only for bugs and logic
+4. Graph tools before reading files — `codegraph_affected` before any refactor
+5. Files only for bugs and exact logic