@codragraph/cli 1.6.4 → 2.1.0

package/hooks/claude/codragraph-hook.cjs

@@ -12,8 +12,27 @@
  */
 
 const fs = require('fs');
+const os = require('os');
 const path = require('path');
-const { spawnSync } = require('child_process');
+const { spawnSync, spawn } = require('child_process');
+
+/**
+ * Decide whether background auto-reindex is opted in. Two equivalent signals:
+ *   1. CODRAGRAPH_AUTO_REINDEX=1 in env (good for shells, CI)
+ *   2. `{ "autoReindex": true }` in ~/.codragraph/config.json (good for GUI
+ *      editor launches on Windows, where shell env doesn't propagate to
+ *      hook child processes reliably)
+ */
+function isAutoReindexEnabled() {
+  if (process.env.CODRAGRAPH_AUTO_REINDEX === '1') return true;
+  try {
+    const configPath = path.join(os.homedir(), '.codragraph', 'config.json');
+    const config = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+    return config && config.autoReindex === true;
+  } catch {
+    return false;
+  }
+}
 
 /**
  * Read JSON input from stdin synchronously.
@@ -217,8 +236,8 @@ function handlePostToolUse(input) {
 
   const cwd = input.cwd || process.cwd();
   if (!path.isAbsolute(cwd)) return;
-  const gitNexusDir = findCodraGraphDir(cwd);
-  if (!gitNexusDir) return;
+  const codragraphDir = findCodraGraphDir(cwd);
+  if (!codragraphDir) return;
 
   // Compare HEAD against last indexed commit — skip if unchanged
   let currentHead = '';
@@ -239,7 +258,7 @@ function handlePostToolUse(input) {
   let lastCommit = '';
   let hadEmbeddings = false;
   try {
-    const meta = JSON.parse(fs.readFileSync(path.join(gitNexusDir, 'meta.json'), 'utf-8'));
+    const meta = JSON.parse(fs.readFileSync(path.join(codragraphDir, 'meta.json'), 'utf-8'));
     lastCommit = meta.lastCommit || '';
     hadEmbeddings = meta.stats && meta.stats.embeddings > 0;
   } catch {
@@ -250,10 +269,84 @@ function handlePostToolUse(input) {
   if (currentHead && currentHead === lastCommit) return;
 
   const analyzeCmd = `npx @codragraph/cli analyze${hadEmbeddings ? ' --embeddings' : ''}`;
+
+  // Opt-in background auto-reindex.
+  // Default stays as notification-only because spawning analyze while an MCP
+  // server holds LadybugDB will fail with a database-busy error — the
+  // notification path lets the agent reindex at a quiet moment instead.
+  // Power users who run MCP outside Claude Code's lifecycle can opt in via
+  // CODRAGRAPH_AUTO_REINDEX=1 or `{ "autoReindex": true }` in
+  // ~/.codragraph/config.json.
+  if (isAutoReindexEnabled()) {
+    // The "coalesce" file is a single-process gate: it exists only while a
+    // reindex is in flight. The spawned analyze removes it on exit (success or
+    // failure) via CODRAGRAPH_REINDEX_LOCK_PATH; the 10-min mtime fallback
+    // catches the rare crash that bypasses analyze's exit handler.
+    const coalescePath = path.join(codragraphDir, '.reindex.coalesce');
+    const crashSafetyTtlMs = 10 * 60 * 1000;
+    let inFlight = false;
+    try {
+      const stat = fs.statSync(coalescePath);
+      if (Date.now() - stat.mtimeMs < crashSafetyTtlMs) inFlight = true;
+    } catch {
+      /* no coalesce file — no reindex in flight */
+    }
+
+    if (!inFlight) {
+      try {
+        fs.writeFileSync(coalescePath, String(process.pid));
+      } catch {
+        /* best-effort — gate is for coalescing, not correctness */
+      }
+
+      const cliPath = resolveCliPath();
+      const reindexArgs = hadEmbeddings
+        ? ['analyze', '--embeddings', '--no-setup']
+        : ['analyze', '--no-setup'];
+      const spawnEnv = { ...process.env, CODRAGRAPH_REINDEX_LOCK_PATH: coalescePath };
+      const spawnOpts = {
+        cwd,
+        detached: true,
+        stdio: 'ignore',
+        windowsHide: true,
+        env: spawnEnv,
+      };
+      try {
+        let child;
+        if (cliPath) {
+          child = spawn(process.execPath, [cliPath, ...reindexArgs], spawnOpts);
+        } else if (process.platform === 'win32') {
+          child = spawn('cmd', ['/c', 'npx', '-y', '@codragraph/cli', ...reindexArgs], spawnOpts);
+        } else {
+          child = spawn('npx', ['-y', '@codragraph/cli', ...reindexArgs], spawnOpts);
+        }
+        child.unref();
+      } catch {
+        /* spawn failed — fall through to notification */
+      }
+
+      sendHookResponse(
+        'PostToolUse',
+        `CodraGraph: auto-reindex started in background ` +
+          `(HEAD ${lastCommit ? lastCommit.slice(0, 7) : 'never'} → ${currentHead.slice(0, 7)}). ` +
+          `If an MCP server is currently holding the database, the reindex will fail silently — ` +
+          `run \`${analyzeCmd}\` manually after closing the agent session.`,
+      );
+      return;
+    }
+
+    sendHookResponse(
+      'PostToolUse',
+      `CodraGraph: auto-reindex coalesced — another reindex is in flight (will pick up your latest commit when it finishes).`,
+    );
+    return;
+  }
+
   sendHookResponse(
     'PostToolUse',
     `CodraGraph index is stale (last indexed: ${lastCommit ? lastCommit.slice(0, 7) : 'never'}). ` +
-      `Run \`${analyzeCmd}\` to update the knowledge graph.`,
+      `Run \`${analyzeCmd}\` to update the knowledge graph. ` +
+      `Set CODRAGRAPH_AUTO_REINDEX=1 (or autoReindex: true in ~/.codragraph/config.json) for background auto-reindex.`,
   );
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codragraph/cli",
-  "version": "1.6.4",
+  "version": "2.1.0",
   "description": "Graph-powered code intelligence for AI agents. Index any codebase, query via MCP or CLI.",
   "author": {
     "name": "Anit Chaudhary",
@@ -56,10 +56,10 @@
     "prepack": "node scripts/build.js"
   },
   "dependencies": {
+    "@codragraph/graphstore": "^2.1.0",
     "@huggingface/transformers": "^4.1.0",
-    "@ladybugdb/core": "^0.15.2",
+    "@ladybugdb/core": "^0.16.0",
     "@modelcontextprotocol/sdk": "^1.0.0",
-    "@codragraph/graphstore": "^0.1.1",
     "@scarf/scarf": "^1.4.0",
     "cli-progress": "^3.12.0",
     "commander": "^14.0.3",
@@ -99,6 +99,7 @@
     "tree-sitter-swift": "^0.6.0"
   },
   "devDependencies": {
+    "@codragraph/shared": "file:../shared",
     "@types/cli-progress": "^3.11.6",
     "@types/cors": "^2.8.17",
     "@types/express": "^4.17.21",
@@ -106,7 +107,6 @@
     "@types/node": "^25.6.0",
     "@types/uuid": "^11.0.0",
     "@vitest/coverage-v8": "^4.0.18",
-    "@codragraph/shared": "file:../codragraph-shared",
     "tsx": "^4.0.0",
     "typescript": "^5.4.5",
     "vitest": "^4.0.18"

package/scripts/build-tree-sitter-proto.cjs

@@ -34,14 +34,26 @@ const fs = require('fs');
 const path = require('path');
 const { execSync } = require('child_process');
 
-const protoDir = path.join(__dirname, '..', 'node_modules', 'tree-sitter-proto');
+// Resolve tree-sitter-proto from BOTH the codragraph package itself AND any
+// monorepo root that hoisted the dep. npm workspaces hoist optional deps to
+// the workspace root, so the package-local path doesn't exist on a workspace
+// install. Same trap as patch-tree-sitter-swift.cjs — see that file for the
+// full failure mode.
+const protoCandidates = [
+  path.join(__dirname, '..', 'node_modules', 'tree-sitter-proto'),
+  path.join(__dirname, '..', '..', 'node_modules', 'tree-sitter-proto'),
+];
+const protoDir = protoCandidates.find((d) => fs.existsSync(path.join(d, 'binding.gyp')));
+if (!protoDir) {
+  // tree-sitter-proto is an optionalDependency; absent when install
+  // skipped optional deps or the file: dep was not resolved.
+  process.exit(0);
+}
 const bindingGyp = path.join(protoDir, 'binding.gyp');
 const bindingNode = path.join(protoDir, 'build', 'Release', 'tree_sitter_proto_binding.node');
 
 try {
   if (!fs.existsSync(bindingGyp)) {
-    // tree-sitter-proto is an optionalDependency; absent when install
-    // skipped optional deps or the file: dep was not resolved.
     process.exit(0);
   }
 

package/scripts/build.js

@@ -17,20 +17,19 @@ import { fileURLToPath } from 'node:url';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const ROOT = path.resolve(__dirname, '..');
-// Workspace directory names (NOT package names — package names are
-// `@codragraph/shared` / `@codragraph/graphstore`, but the on-disk
-// dirs stay as `codragraph-shared` / `codragraph-graphstore`).
-const SHARED_ROOT = path.resolve(ROOT, '..', 'codragraph-shared');
-const GRAPHSTORE_ROOT = path.resolve(ROOT, '..', 'codragraph-graphstore');
+// Workspace directory names — packages live under `packages/<short>` on disk
+// and publish as `@codragraph/<short>` on npm.
+const SHARED_ROOT = path.resolve(ROOT, '..', 'shared');
+const GRAPHSTORE_ROOT = path.resolve(ROOT, '..', 'graphstore');
 const DIST = path.join(ROOT, 'dist');
 const SHARED_DEST = path.join(DIST, '_shared');
 
-// ── 1. Build codragraph-shared ───────────────────────────────────────
-console.log('[build] compiling codragraph-shared…');
+// ── 1. Build @codragraph/shared ──────────────────────────────────────
+console.log('[build] compiling @codragraph/shared…');
 execSync('npx tsc', { cwd: SHARED_ROOT, stdio: 'inherit' });
 
-// ── 2. Build codragraph-graphstore ───────────────────────────────────
-// codragraph depends on this for snapshot/branch/diff types. On a
+// ── 2. Build @codragraph/graphstore ──────────────────────────────────
+// core depends on this for snapshot/branch/diff types. On a
 // fresh checkout (CI, npm ci) the graphstore dist is empty until we
 // build it here, so step 3 would otherwise fail to resolve
 // `@codragraph/graphstore` imports. Skip gracefully if the workspace

package/scripts/patch-tree-sitter-swift.cjs

@@ -29,13 +29,26 @@ const fs = require('fs');
 const path = require('path');
 const { execSync } = require('child_process');
 
-const swiftDir = path.join(__dirname, '..', 'node_modules', 'tree-sitter-swift');
+// Resolve tree-sitter-swift from BOTH the codragraph package itself AND any
+// monorepo root that hoisted the dep. npm workspaces hoist optional deps to
+// the workspace root, so `codragraph/node_modules/tree-sitter-swift` doesn't
+// exist when this script runs as the codragraph postinstall — checking only
+// that path silently no-ops, which is exactly the failure that left
+// Windows Node 22.14 users without a Swift parser.
+//
+// Order matters: the package-local dir takes precedence (standalone install),
+// then the parent monorepo root (workspace install).
+const candidateDirs = [
+  path.join(__dirname, '..', 'node_modules', 'tree-sitter-swift'),
+  path.join(__dirname, '..', '..', 'node_modules', 'tree-sitter-swift'),
+];
+const swiftDir = candidateDirs.find((d) => fs.existsSync(path.join(d, 'binding.gyp')));
+if (!swiftDir) {
+  process.exit(0);
+}
 const bindingPath = path.join(swiftDir, 'binding.gyp');
 
 try {
-  if (!fs.existsSync(bindingPath)) {
-    process.exit(0);
-  }
 
   const content = fs.readFileSync(bindingPath, 'utf8');
   let needsRebuild = false;

package/skills/codragraph-api-surface.md

@@ -0,0 +1,110 @@
+---
+name: codragraph-api-surface
+description: "Use when the user wants to enumerate the public API of a package or codebase, understand what's exported, audit breaking change risk, or compare API shapes across versions. Examples: \"what's our public API\", \"list exports\", \"API surface\", \"what would break if I remove X\", \"document the public interface\""
+---
+
+# API Surface Audit with CodraGraph
+
+## When to Use
+
+- "What's the public API of this package?"
+- "List every exported function / class / type"
+- "What would break if I remove or rename `<symbol>`?"
+- Pre-release API freeze audit
+- Generating API documentation from the graph
+- Comparing API surface across versions (with `codragraph diff --semantic`)
+
+## Why CodraGraph helps here
+
+Reading every `index.ts` / `__init__.py` / `mod.rs` by hand misses re-exports
+and framework-magic exports (Next.js page routes, decorators, registered
+plugins). CodraGraph's `isExported` property is computed by language-aware
+export detection — covers default exports, named re-exports, `__all__`,
+`pub use`, etc., consistently across all 16 supported languages.
+
+## Workflow
+
+```
+1. codragraph_cypher({query: `
+     MATCH (n) WHERE n.isExported = true
+     RETURN labels(n)[0] AS table, n.name, n.filePath, n.id
+     ORDER BY table, n.filePath, n.name
+   `})
+   → every exported symbol, grouped by table
+
+2. For each high-traffic export:
+   codragraph_impact({target: "<name>", direction: "upstream"})
+   → who depends on it (within this repo)
+
+3. For cross-repo audits (multi-repo group):
+   codragraph_impact({repo: "@<group>", target: "<name>", direction: "upstream"})
+   → blast radius across every group member
+
+4. Compare across versions:
+   codragraph diff <baseline> <head> --semantic --json
+   → addedAPIs / removedAPIs / classifiedModifications
+   → produces a versioned changelog of what your public surface gained / lost
+```
+
+> Pair with `codragraph-pr-review` skill when reviewing a PR that touches
+> exported symbols — the impact-across-group check is the difference between
+> "breaks our consumers" and "internal refactor."
+
+## Checklist
+
+```
+- [ ] Cypher query for n.isExported = true
+- [ ] Group by file or by community (Leiden cluster)
+- [ ] For each non-trivial export, run impact upstream
+- [ ] If the package is in a group, run impact with repo: "@group" too
+- [ ] Compare with previous release: codragraph diff <prev-tag> HEAD --semantic
+- [ ] Flag exports with no documented consumers — candidates for visibility
+      reduction (export → internal)
+```
+
+## Example: "What's our public API?"
+
+```
+1. codragraph_cypher({
+     query: `MATCH (n) WHERE n.isExported = true
+              RETURN labels(n)[0] AS table, n.name, n.filePath`
+   })
+   → 47 exports: 22 Function, 12 Class, 8 Interface, 5 Constant
+
+2. Top-level functions:
+   - createClient (src/index.ts) ← 14 callers
+   - fetchUser (src/api.ts)      ← 6 callers
+   - validate (src/utils.ts)     ← 1 internal caller only ⚠ over-exported
+
+3. codragraph_impact({target: "validate", direction: "upstream"})
+   → d=1: only formatPayload (same package). No external consumers.
+   → Recommend: drop the `export` keyword. Internal-only.
+
+4. Compare with v1.5.3 release:
+   codragraph diff v1.5.3 HEAD --semantic
+   → +3 added APIs, -1 removed API (mappings.toCamelCase), ~2 modified
+   → Removed API is a SemVer major bump.
+```
+
+## Output Format
+
+```markdown
+## API Surface: <package>
+
+### Exports (47 total)
+| Symbol | Table | File | Callers (internal) | Notes |
+|--------|-------|------|-------------------:|-------|
+| createClient | Function | src/index.ts | 14 | core entry |
+| validate | Function | src/utils.ts | 1 | over-exported, suggest internal |
+| ...
+
+### Diff vs <previous-tag>
+- **Added (3):** `subscribe`, `unsubscribe`, `EventBus`
+- **Removed (1):** `toCamelCase` ⚠ SemVer major
+- **Modified (2):** `createClient` (param 3→4), `fetchUser` (return type)
+
+### Recommendations
+- Reduce visibility on 4 over-exported internals
+- Document the 3 new APIs in the release notes
+- The removed `toCamelCase` requires a major version bump
+```

package/skills/codragraph-config-audit.md

@@ -0,0 +1,146 @@
+---
+name: codragraph-config-audit
+description: "Use to audit how environment variables, config files, and feature flags are read and used across the codebase — find unused config, missing defaults, undocumented env vars, secrets read into logs. Examples: \"audit env vars\", \"unused config\", \"who reads FOO_BAR env\", \"feature flag usage\", \"config sprawl\""
+---
+
+# Configuration Audit with CodraGraph
+
+## When to Use
+
+- "Which env vars do we actually read?"
+- "Which env vars are read but never set in deploy configs?"
+- "Find the unused feature flags I can delete."
+- "Who reads `STRIPE_SECRET_KEY`?"
+- "Is `<config>` ever logged or sent to telemetry?"
+- "Audit config sprawl before consolidating."
+
+## Why CodraGraph helps here
+
+Configuration enters your code through a small set of helpers:
+`process.env.X`, `os.getenv("X")`, `config.get("foo.bar")`,
+`featureFlags.isEnabled("flag")`. CodraGraph indexes the calls to those
+helpers and the literal arguments — so a `query` for the helper plus a
+`context` of each call site produces a complete picture of which keys
+are read where.
+
+## Workflow
+
+```
+1. Identify the config helpers (per-language patterns):
+   codragraph_query({query: "process.env getenv ConfigService featureFlags"})
+   → list of config-read helpers
+
+2. For each helper, find every call site and its key argument:
+   codragraph_cypher({query: `
+     MATCH (caller)-[:CALLS]->(helper {name: 'getenv'})
+     RETURN caller.name, caller.filePath
+   `})
+   → For richer key-extraction, read the bodies via context:
+   codragraph_context({name: "<caller>", content: true})
+   → look for the literal string passed to getenv()
+
+3. Cross-check with deploy configs:
+   - Read .env / .env.example / docker-compose.yml / k8s ConfigMaps
+   - Build the SET of keys actually defined
+   - For each key your code reads but isn't defined: undocumented env var
+   - For each key defined but no code reads: dead config — delete
+
+4. Feature-flag specific audit:
+   codragraph_query({query: "featureFlags.isEnabled flag.evaluate"})
+   → For each flag-read site: codragraph_impact upstream
+   → Flags with no callers can be removed
+   → Flags with one branch always returning true / false are stale
+
+5. Secret-leakage check:
+   codragraph_query({query: "STRIPE_SECRET DATABASE_URL API_KEY"})
+   → For each match: codragraph_context to confirm the value is not
+     piped to logger / tracer / metrics
+```
+
+## Audit dimensions
+
+| Dimension | Question | CodraGraph approach |
+|---|---|---|
+| **Used** | Is this env var read anywhere? | `query` for the literal key |
+| **Documented** | Is the key in `.env.example` / docs? | grep deploy files; subtract from used set |
+| **Defaulted** | Does the read have a default? | `context` shows the surrounding code |
+| **Validated** | Is the value parsed / type-checked? | `context` for `parseInt` / `URL` / Zod schema in the caller |
+| **Logged** | Does the value flow to telemetry? | `impact` downstream from the read site → check telemetry helpers |
+| **Stale flag** | Is the flag still toggled in production? | combine with deploy-config check |
+
+## Feature flag lifecycle audit
+
+```
+codragraph_cypher({query: `
+  MATCH (caller)-[:CALLS]->(ff {name: 'isEnabled'})
+  RETURN caller.name, caller.filePath, count(*) AS uses
+  ORDER BY uses DESC
+`})
+→ for each call site, codragraph_context to extract the flag NAME literal
+
+# Then:
+- Flag name read by 0 callers → remove
+- Flag name with both branches identical → stale (always-true or always-false)
+- Flag still wired in code, but config has it pinned `true` for >90 days → graduate
+```
+
+## Checklist
+
+```
+- [ ] Listed config helpers (env / config / featureFlag readers)
+- [ ] Built the read-set: { key: [ call sites ] }
+- [ ] Built the defined-set from deploy configs
+- [ ] Diff: undocumented (in code, not in config) + dead (in config, not in code)
+- [ ] Spot-check defaults / validation / secret leakage on critical keys
+- [ ] Feature-flag staleness check
+- [ ] Output: read map + recommended deletions / required deploy changes
+```
+
+## Example: "Audit our feature flags"
+
+```
+1. codragraph_query({query: "featureFlags.isEnabled"})
+   → 47 call sites in 23 files
+
+2. For each call site, extract the flag string (codragraph_context):
+   - 'new_checkout' (12 sites)
+   - 'experimental_search' (4 sites)
+   - 'use_new_pricing' (8 sites)
+   - 'kill_legacy_admin' (1 site)
+   - 'canary_v3' (0 sites — defined in code dead)
+
+3. Cross-check deploys:
+   - 'new_checkout' set to TRUE for 100%% prod since 2026-01 (graduate it)
+   - 'experimental_search' set to TRUE for 5%% prod (active experiment, keep)
+   - 'use_new_pricing' set to TRUE for 100%% prod since 2026-03 (graduate)
+   - 'kill_legacy_admin' set to TRUE for 100%% prod since 2026-02 (graduate)
+   - 'canary_v3' not configured anywhere (truly dead)
+
+4. Findings:
+   - DELETE: 'canary_v3' (dead code, no callers, no config)
+   - GRADUATE: 'new_checkout', 'use_new_pricing', 'kill_legacy_admin' →
+     remove the flag check; keep the new behavior unconditionally
+   - KEEP: 'experimental_search'
+   - Codebase loses: 21 call sites, 1 unused flag definition
+```
+
+## Output Format
+
+```markdown
+## Config Audit: <scope>
+
+### Env vars / config keys
+| Key | Read sites | Defined? | Default? | Validated? | Notes |
+|---|--:|---|---|---|---|
+| DATABASE_URL | 4 | ✓ | ✗ | ✗ | add Zod parse |
+| EXPERIMENTAL_FOO | 1 | ✗ | ✓ ('false') | ✓ | undocumented; either document or delete |
+| ... | ... | ... | ... | ... | ... |
+
+### Feature flags
+- DELETE (no callers): canary_v3, legacy_dashboard_b
+- GRADUATE (100%% production for >90 days): new_checkout, kill_legacy_admin
+- KEEP (active experiment): experimental_search, ai_summarize_v2
+
+### Secret-leak check
+- 0 paths from secret reads to logger/metrics/tracer found ✓
+```

package/skills/codragraph-cross-repo-impact.md

@@ -0,0 +1,135 @@
+---
+name: codragraph-cross-repo-impact
+description: "Use when assessing the blast radius of a change that crosses repository boundaries — a shared library used by multiple services, a contract / protobuf / OpenAPI schema consumed by N consumers, a microservices change. Examples: \"what services consume X\", \"cross-repo blast radius\", \"will this break the consumers\", \"who depends on this contract\""
+---
+
+# Cross-Repo Impact Analysis with CodraGraph
+
+## When to Use
+
+- "What other repos consume `<symbol>` from this one?"
+- "If I change this gRPC method / OpenAPI route / protobuf message, what breaks?"
+- "Cross-repo blast radius for `<change>`"
+- Microservices architecture: assessing a contract change
+- Shared-library author: deciding if a function is safe to remove
+
+## Why CodraGraph helps here
+
+CodraGraph's **groups** (sets of related repos sharing a `group.yaml`)
+maintain a Contract Registry — provider/consumer rows for every cross-repo
+reference (gRPC service / method, OpenAPI route, protobuf message). The
+group-mode `impact` walks both the local call graph AND the contract
+bridges, so a single call returns the blast radius across every member
+repo. You don't need to re-run impact in each consumer separately.
+
+## Workflow
+
+```
+1. Identify the group:
+   codragraph_group_list({})
+   → list of groups + their member repos
+
+2. Confirm the symbol exists in the producer repo:
+   codragraph_context({repo: "<producerRepo>", name: "<symbol>"})
+
+3. Run group-mode impact:
+   codragraph_impact({repo: "@<group>", target: "<symbol>", direction: "upstream"})
+   → d=1 callers spanning every group member
+     (in-repo callers + contract-bridge consumers)
+
+4. Inspect the Contract Registry to see provider/consumer rows directly:
+   READ codragraph://group/<groupName>/contracts
+   → list of contracts touching the symbol or its API
+
+5. Check group-status / staleness:
+   READ codragraph://group/<groupName>/status
+   → which member repos haven't been re-indexed recently
+     (stale members produce stale impact results)
+
+6. Surface the worst-case consumer:
+   any consumer not updated since the schema change = potential breakage
+```
+
+> If any member repo's index is stale, group-mode impact may underreport.
+> Re-analyze stale members before relying on the results.
+
+## Checklist
+
+```
+- [ ] group_list to confirm the group exists and the producer is a member
+- [ ] context on the symbol in the producer repo
+- [ ] Group-mode impact upstream
+- [ ] Inspect Contract Registry for provider/consumer rows
+- [ ] Check group/status for stale members; re-analyze if needed
+- [ ] List affected consumer repos by impact depth
+- [ ] Recommend coordinated PRs across consumers (if breaking)
+```
+
+## When to Use Which Tool
+
+| Question | Tool |
+| --- | --- |
+| "Which repos are in my group?" | `group_list` |
+| "What contracts cross between member A and member B?" | Contract Registry resource |
+| "If I change this provider method, what breaks?" | Group-mode `impact` |
+| "Are all consumers up to date with the latest provider commit?" | `group/<name>/status` resource |
+| "What's the structural diff between last release and now in repo X?" | Per-repo `diff --semantic` |
+
+## Example: "Will renaming `getUserProfile` break my microservices?"
+
+```
+1. codragraph_group_list({})
+   → group "platform": [user-service, web-app, mobile-bff, admin-portal]
+
+2. codragraph_context({repo: "user-service", name: "getUserProfile"})
+   → exported gRPC method in user.proto, defined in user-service
+
+3. codragraph_impact({repo: "@platform", target: "getUserProfile", direction: "upstream"})
+   → d=1 callers (across the group):
+       - web-app/src/api/userClient.ts (CALLS via grpc-web)
+       - mobile-bff/internal/user.go (CALLS via grpc.NewClient)
+       - admin-portal/src/services/users.tsx (CALLS via grpc-web)
+   → 3 consumer repos depend on this method by exact name.
+
+4. READ codragraph://group/platform/contracts
+   → user.UserService.getUserProfile: provider=user-service,
+     consumers=[web-app, mobile-bff, admin-portal]
+
+5. READ codragraph://group/platform/status
+   → web-app last indexed 2 hours ago ✓
+   → mobile-bff last indexed 3 days ago ⚠ (might miss recent callers)
+   → admin-portal last indexed 1 month ago ⚠⚠ (re-analyze first!)
+
+6. Recommendation:
+   - HIGH-RISK rename. 3 consumer repos must change in lockstep.
+   - Re-index admin-portal before trusting the d=1 list.
+   - Coordinated PR sequence:
+     1. Add new method (getUserProfileV2) in user-service
+     2. Migrate web-app, mobile-bff, admin-portal to V2
+     3. Remove getUserProfile in user-service after all consumers ship
+   - Alternative: keep both, deprecate old, drop in next major.
+```
+
+## Output Format
+
+```markdown
+## Cross-Repo Impact: `<symbol>` in `<producer-repo>` (group `@<group>`)
+
+### Consumers (d=1)
+| Repo | Caller | Path | Notes |
+| --- | --- | --- | --- |
+| web-app | userClient.ts | grpc-web | active |
+| mobile-bff | internal/user.go | grpc native | active |
+| admin-portal | services/users.tsx | grpc-web | last indexed 1mo ago ⚠ |
+
+### Contracts touching this symbol
+- `user.UserService.getUserProfile` (provider: user-service)
+
+### Staleness
+Re-analyze `admin-portal` before trusting these results.
+
+### Recommended migration sequence
+1. Add `getUserProfileV2` alongside the old method
+2. Migrate consumers to V2 (separate PRs per repo)
+3. Remove old method after all consumers ship
+```