@colbymchenry/codegraph 1.0.1 → 1.1.0

package/README.md

@@ -10,7 +10,7 @@ Follow [@getcodegraph](https://x.com/getcodegraph) on X for updates.
 
 ### Supercharge Claude Code, Cursor, Codex, OpenCode, Hermes Agent, Gemini, Antigravity, and Kiro with Semantic Code Intelligence
 
-**~16% cheaper · ~58% fewer tool calls · 100% local**
+**Surgical context · fewer tool calls · faster answers · 100% local**
 
 ### [Documentation & Website →](https://colbymchenry.github.io/codegraph/)
 
@@ -76,7 +76,7 @@ In a **new terminal**, run the installer to connect CodeGraph to the agents you
 codegraph install
 ```
 
-<sub>Detects and auto-configures Claude Code, Cursor, Codex CLI, opencode, Hermes Agent, Gemini CLI, Antigravity IDE, and Kiro — wiring the CodeGraph MCP server into each. **This is the step that connects CodeGraph to your agent;** installing the CLI in step 1 does not do it on its own. (Shortcut: `npx @colbymchenry/codegraph` downloads and runs this in one go.)</sub>
+<sub>Detects and auto-configures Claude Code, Cursor, Codex CLI, opencode, Hermes Agent, Gemini CLI, Antigravity IDE, and Kiro — wiring the CodeGraph MCP server into each. **This is the step that connects CodeGraph to your agent;** installing the CLI in step 1 does not do it on its own. It only wires up your agent — it does **not** index any code; building each project's graph is the separate `codegraph init` in step 3. (Shortcut: `npx @colbymchenry/codegraph` downloads and runs this in one go.)</sub>
 
 ### 3. Initialize each project
 
@@ -111,27 +111,33 @@ codegraph uninstall
 
 ## Why CodeGraph?
 
-When Claude Code explores a codebase, it spawns **Explore agents** that scan files with grep, glob, and Read — consuming tokens on every tool call.
+When an AI agent needs to understand code — to answer a question or make a change — it discovers structure the slow way: grep, glob, and Read, one file at a time, rebuilding call paths and dependencies by hand. That's a pile of tool calls and round-trips before it even starts the real work.
 
-**CodeGraph gives those agents a pre-indexed knowledge graph** — symbol relationships, call graphs, and code structure. Agents query the graph instantly instead of scanning files.
+**CodeGraph hands the agent the exact code it needs in one call.** It's a pre-built knowledge graph of every symbol, call edge, and dependency in your codebase — so instead of crawling files, the agent asks one question and gets back the relevant source, the call paths between those symbols (including dynamic-dispatch hops grep can't follow), and the blast radius of a change. **Surgical context, not a file-by-file search** — which means fewer tool calls and faster answers on every codebase, large or small.
+
+<img width="1536" height="1024" alt="token-cost-savings-scale" src="https://github.com/user-attachments/assets/eb74a11a-a3ab-4b01-80a6-19f78352ae8e" />
+
+> **A note on cost:** CodeGraph's win on *every* codebase is precision and speed — fewer tool calls, faster answers. It cuts token and dollar cost too, but those savings are **scale-dependent**: small and noisy on a modest codebase, and material only once a repo is large and tangled — at the scale of a Google or Microsoft monorepo, multiplied by a whole team's daily agent usage — for them to compound into a real line item. On a 500-file project, adopt CodeGraph for the speed; the cost savings show up when the codebase (and the team) gets big.
 
 ### Benchmark Results
 
-Tested across **7 real-world open-source codebases** spanning 7 languages, comparing an agent (Claude Code, headless) answering one architecture question **with** and **without** CodeGraph. Each cell is the savings at the **median of 4 runs per arm**. _Re-validated on Opus 4.8 (2026-06-02), on the current build (`codegraph_explore` as the primary tool)._
+Tested across **7 real-world open-source codebases** spanning 7 languages, comparing an agent (Claude Code, headless) answering one architecture question **with** and **without** CodeGraph, at the **median of 4 runs per arm**. _Re-validated on Opus 4.8 (2026-06-02), on the current build (`codegraph_explore` as the primary tool)._
 
-> **Average: 16% cheaper · 47% fewer tokens · 22% faster · 58% fewer tool calls**
+> **The universal win — every repo, every size: 58% fewer tool calls · 22% faster · file reads cut to ~zero.**
 
-| Codebase | Language | Cost | Tokens | Time | Tool calls |
-|----------|----------|------|--------|------|------------|
-| **VS Code** | TypeScript · ~10k files | 18% cheaper | 64% fewer | 11% faster | 81% fewer |
-| **Excalidraw** | TypeScript · ~640 | even | 25% fewer | 27% faster | 40% fewer |
-| **Django** | Python · ~3k | 8% cheaper | 60% fewer | 13% faster | 77% fewer |
-| **Tokio** | Rust · ~790 | even | 38% fewer | 18% faster | 57% fewer |
-| **OkHttp** | Java · ~645 | 25% cheaper | 54% fewer | 31% faster | 50% fewer |
-| **Gin** | Go · ~110 | 19% cheaper | 23% fewer | 24% faster | 44% fewer |
-| **Alamofire** | Swift · ~110 | 40% cheaper | 64% fewer | 33% faster | 58% fewer |
+The reliable, universal payoff is **surgical context and speed**: CodeGraph collapses the agent's grep/find/Read crawl into a few direct queries — returning the exact methods you asked about even when they're buried in a multi-thousand-line file — so it answers with **near-zero file reads** while the no-CodeGraph agent spends its budget on discovery. The **Tokens** and **Cost** columns are real too, but — as noted above — they're **scale-dependent**: small and noisy per query, compounding into real money only at large-codebase, high-volume scale.
 
-CodeGraph cuts **tokens, tool calls, and wall-clock time on every repo** — across small, medium, and large codebases — and answers them with **near-zero file reads**, while the no-CodeGraph agent spends its budget on grep/find/Read discovery. `codegraph_explore` shows the answer in full — the mechanism plus the exact methods you asked about, even when they're buried in a multi-thousand-line file — while collapsing redundant interchangeable implementations to signatures, so the response is sized to the *answer* rather than the file count. **Cost stays flat-to-cheaper everywhere** — largest on the small repos (Alamofire, OkHttp), roughly break-even on the most response-heavy ones (Excalidraw, Tokio), where CodeGraph trades the no-CodeGraph agent's many small grep/read round-trips for a few large, cache-heavy tool responses.
+| Codebase | Language | Tool calls | Time | File reads | Tokens | Cost |
+|----------|----------|------------|------|------------|--------|------|
+| **VS Code** | TypeScript · ~10k files | 81% fewer | 11% faster | 0 vs 9 | 64% fewer | 18% cheaper |
+| **Excalidraw** | TypeScript · ~640 | 40% fewer | 27% faster | 0 vs 7 | 25% fewer | even |
+| **Django** | Python · ~3k | 77% fewer | 13% faster | 0 vs 9 | 60% fewer | 8% cheaper |
+| **Tokio** | Rust · ~790 | 57% fewer | 18% faster | 0 vs 8 | 38% fewer | even |
+| **OkHttp** | Java · ~645 | 50% fewer | 31% faster | 0 vs 4 | 54% fewer | 25% cheaper |
+| **Gin** | Go · ~110 | 44% fewer | 24% faster | 1 vs 6 | 23% fewer | 19% cheaper |
+| **Alamofire** | Swift · ~110 | 58% fewer | 33% faster | 0 vs 9 | 64% fewer | 40% cheaper |
+
+<sub>**File reads** = median files the agent opened **with** vs **without** CodeGraph — the surgical-context win in one column. **Tokens** and **Cost** are the same with-vs-without deltas; they're directional (they move run-to-run) and, per query, small in absolute terms — which is why they only become a line item at scale. `codegraph_explore` also collapses redundant interchangeable implementations to signatures, so a response is sized to the *answer* rather than the file count.</sub>
 
 <details>
 <summary><strong>Per-repo breakdown — WITH vs WITHOUT (median of 4)</strong></summary>
@@ -234,7 +240,7 @@ CodeGraph cuts **tokens, tool calls, and wall-clock time on every repo** — acr
 
 | | |
 |---|---|
-| **Smart Context Building** | One tool call returns entry points, related symbols, and code snippets — no expensive exploration agents |
+| **Surgical Context** | One tool call returns entry points, related symbols, and code snippets — no slow file-by-file exploration |
 | **Full-Text Search** | Find code by name instantly across your entire codebase, powered by FTS5 |
 | **Impact Analysis** | Trace callers, callees, and the full impact radius of any symbol before making changes |
 | **Always Fresh** | File watcher uses native OS events (FSEvents/inotify/ReadDirectoryChangesW) with debounced auto-sync — the graph stays current as you code, zero config |
@@ -262,7 +268,7 @@ agent writes src/Widget.ts
   → next agent query sees it
 ```
 
-**Verify any time** with `codegraph_status` (via MCP) or `codegraph status` (CLI). If anything is pending, you'll see a `### Pending sync:` section naming the files and their edit age.
+**Verify any time** with `codegraph status` (CLI). If anything is pending, you'll see a `### Pending sync:` section naming the files and their edit age.
 
 The handful of cases where manual `codegraph sync` makes sense: the watcher is disabled (sandboxed environments, or `CODEGRAPH_NO_DAEMON=1`), or you're scripting against the index outside an agent session and want a pre-flight sync at the start of your script.
 
@@ -300,7 +306,7 @@ CodeGraph detects web-framework routing files and emits `route` nodes linked by
 
 ## Mixed iOS / React Native / Expo bridging
 
-Real iOS and React Native codebases live across multiple languages — a Swift caller invokes an Objective-C selector that's been auto-bridged, a JS file calls into a native module via the React Native bridge, a JSX component delegates to a native view manager. Static tree-sitter extraction stops at each language boundary. CodeGraph bridges them so `trace`, `callers`, `callees`, and `impact` connect end-to-end across the gap.
+Real iOS and React Native codebases live across multiple languages — a Swift caller invokes an Objective-C selector that's been auto-bridged, a JS file calls into a native module via the React Native bridge, a JSX component delegates to a native view manager. Static tree-sitter extraction stops at each language boundary. CodeGraph bridges them so `codegraph_explore` connects the flow end-to-end across the gap — call paths and blast radius cross the boundary instead of stopping at it.
 
 | Boundary | JS / Swift side | Native side | How |
 |---|---|---|---|
@@ -339,9 +345,10 @@ The installer will:
 - Ask which agent(s) to configure — auto-detects installed ones from: **Claude Code**, **Cursor**, **Codex CLI**, **opencode**, **Hermes Agent**, **Gemini CLI**, **Antigravity IDE**, **Kiro**
 - Prompt to install `codegraph` on your PATH (so agents can launch the MCP server)
 - Ask whether configs apply to all your projects or just this one
-- Write each chosen agent's MCP server config, plus a small marker-fenced CodeGraph section in the agent's instructions file (`CLAUDE.md` / `AGENTS.md` / `GEMINI.md`) — that's how subagents and non-MCP agents learn the `codegraph explore` / `codegraph node` commands, since the MCP server's own guidance only reaches the main agent. Removed cleanly by `codegraph uninstall`.
+- Write each chosen agent's MCP server config, plus a small marker-fenced CodeGraph section in the agent's instructions file (`CLAUDE.md` / `AGENTS.md` / `GEMINI.md`) — that's how subagents and non-MCP agents learn the `codegraph explore` command, since the MCP server's own guidance only reaches the main agent. Removed cleanly by `codegraph uninstall`.
 - Set up auto-allow permissions when Claude Code is one of the targets
-- Initialize your current project (local installs only)
+
+The installer **wires up your agents only — it does not index your code.** After it finishes, build each project's graph yourself with `codegraph init` (step 3). One global `codegraph install` covers every project; you run `codegraph init` once per project.
 
 **Non-interactive (scripting / CI):**
 
@@ -401,19 +408,14 @@ npm install -g @colbymchenry/codegraph
 {
   "permissions": {
     "allow": [
-      "mcp__codegraph__codegraph_search",
-      "mcp__codegraph__codegraph_explore",
-      "mcp__codegraph__codegraph_callers",
-      "mcp__codegraph__codegraph_callees",
-      "mcp__codegraph__codegraph_impact",
-      "mcp__codegraph__codegraph_node",
-      "mcp__codegraph__codegraph_status",
-      "mcp__codegraph__codegraph_files"
+      "mcp__codegraph__*"
     ]
   }
 }
 ```
 
+<sub>One wildcard auto-approves every CodeGraph tool — `codegraph_explore` is the only one listed by default, but if you re-enable others via `CODEGRAPH_MCP_TOOLS` they're already permitted, no prompt.</sub>
+
 </details>
 
 <details>
@@ -422,11 +424,11 @@ npm install -g @colbymchenry/codegraph
 CodeGraph's MCP server delivers its usage guidance to your agent **automatically**, in the MCP `initialize` response. In short, it tells the agent to:
 
 - **Answer structural questions directly with CodeGraph** — it *is* the pre-built index, so a grep/read loop just repeats work it already did. Treat the returned source as already read.
-- **Pick the tool by intent:** `codegraph_explore` for almost anything — "how does X work", a flow/"how does X reach Y", or surveying an area (one call returns the relevant symbols' source grouped by file); `codegraph_search` to just locate a symbol; `codegraph_callers` for every call site (including callback registrations); `codegraph_node` for one symbol's full source + callers, or to read a file like the Read tool.
+- **Reach for `codegraph_explore` for almost anything** — "how does X work", a flow/"how does X reach Y", or surveying an area. One call returns the relevant symbols' verbatim source grouped by file, the call paths between them (dynamic-dispatch hops included), and a blast-radius summary. Name a file or symbol in the query to read its current line-numbered source.
 - **Trust the results — don't re-verify with grep**, and check the staleness banner after edits.
-- In a workspace with no index, CodeGraph announces itself inactive and serves no tools — indexing stays your decision.
+- Works **per project**: query any project that has a `.codegraph/` index by passing `projectPath` — so a monorepo where only some services are indexed, or a second repo, works in one session. A path with no index returns clean guidance to use built-in tools; indexing stays your decision.
 
-The exact text is `src/mcp/server-instructions.ts` — the single source of truth for the main agent. Because subagents and non-MCP harnesses never see the MCP guidance, the installer also writes a four-line marker-fenced section into the agent's instructions file pointing at the `codegraph explore` / `codegraph node` CLI equivalents.
+The exact text is `src/mcp/server-instructions.ts` — the single source of truth for the main agent. Because subagents and non-MCP harnesses never see the MCP guidance, the installer also writes a short marker-fenced section into the agent's instructions file pointing at the `codegraph explore` CLI equivalent.
 
 </details>
 
@@ -447,7 +449,7 @@ The exact text is `src/mcp/server-instructions.ts` — the single source of trut
 ┌───────────────────────────────────────────────────────────────────┐
 │                        CodeGraph MCP Server                       │
 │                                                                   │
-│       explore · search · callers · callees · impact · node        │
+│ explore  ·  one call → verbatim source + call flow + blast radius │
 │                                 │                                 │
 │                                 ▼                                 │
 │                       SQLite knowledge graph                      │
@@ -471,7 +473,7 @@ The exact text is `src/mcp/server-instructions.ts` — the single source of trut
 codegraph                         # Run interactive installer
 codegraph install                 # Run installer (explicit)
 codegraph uninstall               # Remove CodeGraph from your agents (inverse of install)
-codegraph init [path]             # Initialize in a project (--index to also index)
+codegraph init [path]             # Initialize a project + build its graph (one step)
 codegraph uninit [path]           # Remove CodeGraph from a project (--force to skip prompt)
 codegraph index [path]            # Full index (--force to re-index, --quiet for less output)
 codegraph sync [path]             # Incremental update
@@ -524,18 +526,15 @@ fi
 
 ## MCP Tools
 
-When running as an MCP server, CodeGraph exposes a focused set of four tools — measured agent behavior showed a leaner list steers agents to the right tool and saves context every session:
+When running as an MCP server, CodeGraph exposes a **single tool** — `codegraph_explore`. Measured agent behavior showed that one strong tool steers agents better than a menu of narrower ones — fewer mis-picks, and it saves context every session:
 
 | Tool | Purpose |
 |------|---------|
-| `codegraph_explore` | **Primary.** Answer almost any question in one call — "how does X work", a flow ("how does X reach Y"), or surveying an area — returning the relevant symbols' verbatim source grouped by file, plus a relationship map and blast radius. Surfaces dynamic-dispatch hops (callbacks, React re-render, interface→impl) grep can't follow. |
-| `codegraph_node` | One symbol's full source + caller/callee trail (every overload for an ambiguous name) — or pass a file path to **read a whole file like the Read tool** (same line-numbered output, `offset`/`limit`), with its dependents attached. |
-| `codegraph_search` | Find symbols by name across the codebase |
-| `codegraph_callers` | Every call site of a function — including where it's registered as a callback — with one section per definition when several share a name |
+| `codegraph_explore` | Answer almost any question in one call — "how does X work", a flow ("how does X reach Y"), or surveying an area — returning the relevant symbols' verbatim source grouped by file, plus the call paths between them and a blast-radius summary. Surfaces dynamic-dispatch hops (callbacks, React re-render, interface→impl) grep can't follow. Name a file or symbol in the query to read its current line-numbered source, the same shape the Read tool gives you. |
 
-Four more tools (`codegraph_callees`, `codegraph_impact`, `codegraph_files`, `codegraph_status`) stay fully functional but unlisted by default — measured across eval runs, agents never or rarely picked them, and their information already arrives inline on the four above (explore's blast-radius section, node's dependents note, a symbol's body as its callee list). Re-enable any of them with the `CODEGRAPH_MCP_TOOLS` environment variable (e.g. `CODEGRAPH_MCP_TOOLS=explore,node,search,callers,impact`), or use their CLI equivalents (`codegraph callees` / `impact` / `files` / `status`).
+The other tools (`codegraph_node`, `codegraph_search`, `codegraph_callers`, `codegraph_callees`, `codegraph_impact`, `codegraph_files`, `codegraph_status`) stay fully functional but **unlisted by default** — everything they return already arrives inline on `codegraph_explore` (its blast-radius section, the relationship map, a symbol's body as its callee list). Re-enable any of them for the MCP surface with the `CODEGRAPH_MCP_TOOLS` environment variable (e.g. `CODEGRAPH_MCP_TOOLS=explore,node,search,callers`), or use their CLI equivalents (`codegraph node` / `query` / `callers` / `callees` / `impact` / `files` / `status`).
 
-In a workspace with no `.codegraph/` index, the server announces itself inactive and lists **no** tools — agents work normally with their built-in tools, and indexing stays your decision.
+Even when the server's own root has no `.codegraph/` index, the tools stay available: pass `projectPath` to query any indexed project — a sub-service in a monorepo, or a second repo — in the same session. A path that has no index returns clean guidance to use built-in tools instead, so nothing fails loudly, and indexing stays your decision.
 
 ---
 
@@ -586,9 +585,10 @@ that drive the graph directly: `DatabaseConnection`, `QueryBuilder`,
 
 ## Configuration
 
-There isn't any — CodeGraph is zero-config, with **no config file** to write or
-keep in sync. Language support is automatic from the file extension; there's
-nothing to wire up per language.
+Next to none — CodeGraph is **zero-config by default**, with nothing to write or
+keep in sync to get started. Language support is automatic from the file
+extension; there's nothing to wire up per language. The one optional file is for
+mapping [custom file extensions](#custom-file-extensions).
 
 What it skips out of the box:
 
@@ -606,6 +606,29 @@ add a negation — `!vendor/`. The defaults apply uniformly, so committing a
 dependency or build directory doesn't force it into the graph; the `.gitignore`
 negation is the explicit opt-in.
 
+### Custom file extensions
+
+If your project uses a non-standard extension for a [supported
+language](#supported-languages) — say `.dota_lua` for Lua, or `.tpl` for PHP —
+those files are skipped by default, because the extension isn't one CodeGraph
+recognizes. Map them with an optional **`codegraph.json`** at your project root:
+
+```json
+{
+  "extensions": {
+    ".dota_lua": "lua",
+    ".tpl": "php"
+  }
+}
+```
+
+Each value is a supported language id. The mappings merge on top of the built-in
+defaults and win on conflict, so you can also re-point a built-in (e.g.
+`".h": "cpp"`). Commit the file to share the mapping with your team. A typo'd
+language or a malformed file is warned about and skipped — it never breaks
+indexing — and a project with no `codegraph.json` behaves exactly as before.
+Re-index (`codegraph index`) after adding or changing mappings.
+
 ## Telemetry
 
 CodeGraph collects **anonymous usage statistics** — which tools and commands get

package/dist/db/index.d.ts

@@ -13,6 +13,15 @@ export declare class DatabaseConnection {
     private db;
     private dbPath;
     private backend;
+    /**
+     * `dev:ino` of the DB file at the moment we opened it (or null when the
+     * platform/filesystem reports no usable inode). Lets us notice when the file
+     * we hold open has been unlinked and REPLACED by a new file at the same path
+     * — a git worktree removed and re-added, or `.codegraph/` deleted and
+     * re-`init`ed under a long-lived server — at which point our fd reads a now
+     * dead inode forever (#925). See `isReplacedOnDisk`.
+     */
+    private openedInode;
     private constructor();
     /**
      * Initialize a new database at the given path
@@ -41,7 +50,7 @@ export declare class DatabaseConnection {
      *
      * SQLite silently keeps the prior mode if WAL can't be enabled — e.g. on
      * filesystems without shared-memory support (some network/virtualized mounts,
-     * WSL2 /mnt), and always on the wasm backend. So the effective mode can differ
+     * WSL2 /mnt). So the effective mode can differ
      * from what `configureConnection` requested. Surfaced in `codegraph status` so
      * a "database is locked" report is triageable: 'wal' ⇒ readers never block on a
      * writer; anything else ⇒ they can. See issue #238.
@@ -89,6 +98,18 @@ export declare class DatabaseConnection {
      * Check if the database connection is open
      */
     isOpen(): boolean;
+    /**
+     * True when the DB file at our path has been REPLACED on disk since we opened
+     * it — a different inode now lives at the same path, so the fd we still hold
+     * points at a now-unlinked inode that can never receive new writes (#925).
+     * The trigger is removing and recreating `.codegraph/` at the same path under
+     * a long-lived process (`git worktree remove` + re-add, or `rm -rf
+     * .codegraph` + `codegraph init`). Returns false when the inode is unchanged,
+     * when the file is momentarily absent (mid-recreate — nothing to reopen onto
+     * yet), or when the platform doesn't report a usable inode (Windows can't
+     * unlink an open file and its st_ino is unreliable, so this never fires there).
+     */
+    isReplacedOnDisk(): boolean;
 }
 /**
  * Default database filename

package/dist/db/queries.d.ts

@@ -268,6 +268,20 @@ export declare class QueryBuilder {
      * (all kinds except `contains`); same reason imports-only is insufficient.
      */
     getDependencyFilePaths(filePath: string): string[];
+    /**
+     * Cross-file edges whose TARGET is a node in `filePath` and whose SOURCE is a
+     * node in a *different* file, paired with the target node's (name, kind) so a
+     * caller can re-resolve the edge to the re-indexed target's new ID (node IDs
+     * are `sha256(filePath:kind:name:line)`, so any line shift in the callee file
+     * changes target IDs and a naive re-insert by old ID silently drops them).
+     * Used by `storeExtractionResult` to preserve incoming edges across a file
+     * re-index (issue #899). Same edge-kind rules as
+     * {@link getDependentFilePaths}: all kinds except `contains`.
+     */
+    getCrossFileIncomingEdgesWithTarget(filePath: string): Array<Edge & {
+        targetName: string;
+        targetKind: NodeKind;
+    }>;
     /**
      * Insert or update a file record
      */

package/dist/directory.d.ts

@@ -73,6 +73,49 @@ export declare function isInitialized(projectRoot: string): boolean;
  */
 export declare function unsafeIndexRootReason(projectRoot: string): string | null;
 export declare function findNearestCodeGraphRoot(startPath: string): string | null;
+/**
+ * Indexed sub-project roots beneath `root` (bounded breadth-first scan). For
+ * the monorepo case behind #964: the index lives in a CHILD
+ * (`packages/x/.codegraph/`), not at the workspace root the agent's cwd points
+ * at. Descent stops at the first indexed directory on a branch (a project's
+ * own sub-dirs aren't separate projects) and is bounded by depth + count so it
+ * never turns into a full-tree crawl on a large repo.
+ */
+export declare function findIndexedSubprojectRoots(root: string, opts?: {
+    maxDepth?: number;
+    max?: number;
+}): string[];
+/**
+ * What the front-load hook should do for a prompt issued from a directory.
+ */
+export interface FrontloadPlan {
+    /** Open + explore this project and inject its source as context. `null` when
+     *  there's no single project to front-load (none indexed, or several indexed
+     *  sub-projects with no clear match — see {@link nudgeProjects}). */
+    exploreRoot: string | null;
+    /** Indexed sub-projects to surface in a "pass `projectPath`" nudge: the rest
+     *  of a monorepo's indexed projects alongside `exploreRoot`, or — when no one
+     *  project clearly matches — the full list (with `exploreRoot` null). */
+    nudgeProjects: string[];
+    /** True when the plan came from scanning DOWN into sub-projects (cwd itself
+     *  is not under any index) — the monorepo case, where a follow-up
+     *  `codegraph_explore` needs an explicit `projectPath`. */
+    viaSubScan: boolean;
+}
+/**
+ * Decide what the front-load hook injects for a `prompt` issued from `cwd`,
+ * shaped by where the `.codegraph/` index(es) actually are:
+ *   1. **cwd (or an ancestor) is indexed** → front-load that project. The
+ *      normal single-project / nested-file case.
+ *   2. **cwd isn't indexed but looks like a workspace root** → the indexes live
+ *      in sub-projects (the monorepo case behind #964). One indexed
+ *      sub-project → front-load it; several → front-load the one the prompt
+ *      names (by relative path like `packages/api`, or package directory name)
+ *      and nudge about the rest; several with no match → nudge the full list so
+ *      the agent passes `projectPath`, rather than guessing wrong.
+ *   3. **nothing indexed reachable** → do nothing (the agent's own tools apply).
+ */
+export declare function planFrontload(cwd: string, prompt: string): FrontloadPlan;
 /**
  * Create the .codegraph directory structure
  * Note: Only throws if codegraph.db already exists, not just if .codegraph/ exists.

package/dist/extraction/grammars.d.ts

@@ -16,8 +16,12 @@ export declare const EXTENSION_MAP: Record<string, Language>;
  * Whether a file is one CodeGraph can parse, based purely on its extension.
  * This is the single source of truth for "should we index this file" — derived
  * from EXTENSION_MAP so parser support and indexing selection never drift.
+ *
+ * `overrides` is the project's validated custom extension → language map (from
+ * `codegraph.json`); when present its extensions count as indexable in addition
+ * to the built-ins. Omitting it is byte-identical to the zero-config behavior.
  */
-export declare function isSourceFile(filePath: string): boolean;
+export declare function isSourceFile(filePath: string, overrides?: Record<string, Language>): boolean;
 /**
  * Shopify OS 2.0 JSON template (`templates/*.json`) or section group
  * (`sections/*.json`) — these reference sections by `"type"`, so the Liquid
@@ -57,9 +61,13 @@ export declare function isGrammarsInitialized(): boolean;
  */
 export declare function getParser(language: Language): Parser | null;
 /**
- * Detect language from file extension
+ * Detect language from file extension.
+ *
+ * `overrides` is the project's validated custom extension → language map (from
+ * `codegraph.json`); when present its mappings take precedence over the built-in
+ * `EXTENSION_MAP`. Omitting it is byte-identical to the zero-config behavior.
  */
-export declare function detectLanguage(filePath: string, source?: string): Language;
+export declare function detectLanguage(filePath: string, source?: string, overrides?: Record<string, Language>): Language;
 /**
  * Check if a language is supported (has a grammar defined).
  * Returns true if the grammar exists, even if not yet loaded.

package/dist/extraction/tree-sitter-types.d.ts

@@ -147,6 +147,19 @@ export interface LanguageExtractor {
      * Used by languages with fundamentally different AST structures (e.g. Pascal).
      */
     visitNode?: (node: SyntaxNode, ctx: ExtractorContext) => boolean;
+    /**
+     * Synthesize members that exist at compile time but not in the source AST,
+     * called at the end of class extraction with the class still on the scope
+     * stack (so `ctx.createNode` attaches containment + qualified names) and the
+     * class's real members already extracted (so the hook can skip a member the
+     * source explicitly declares). Used by Java for Lombok-generated accessors
+     * (`@Getter`/`@Setter`/`@Data`/`@Value`/`@Builder` → `getX`/`setX`/`builder`/
+     * `equals`/`hashCode`/`toString` + the `log` field), which are otherwise
+     * invisible and break call-chain analysis (#912). The created nodes carry a
+     * `lombok` decorator + a docstring naming the generating annotation, so an
+     * agent can tell them apart from hand-written code.
+     */
+    synthesizeMembers?: (classNode: SyntaxNode, ctx: ExtractorContext) => void;
     /**
      * Classify a class_declaration node when the grammar reuses one node type
      * for multiple concepts (e.g. Swift uses class_declaration for classes, structs, and enums).

package/dist/extraction/tree-sitter.d.ts

@@ -16,12 +16,19 @@ export declare class TreeSitterExtractor {
     private nodes;
     private edges;
     private unresolvedReferences;
+    private static readonly VALUE_REF_LANGS;
+    private static readonly MAX_VALUE_REF_NODES;
+    private readonly valueRefsEnabled;
+    private fileScopeValues;
+    private fileScopeValueCounts;
+    private valueRefScopes;
     private errors;
     private extractor;
     private nodeStack;
     private methodIndex;
     private fnRefSpec;
     private fnRefCandidates;
+    private vueStoreFile;
     constructor(filePath: string, source: string, language?: Language);
     /**
      * Parse and extract from the source code
@@ -59,6 +66,21 @@ export declare class TreeSitterExtractor {
      * callback + same-file ops struct) — is.
      */
     private flushFnRefCandidates;
+    /**
+     * Record value-reference bookkeeping as nodes are created: file-scope const/var symbols with
+     * distinctive names become reference targets; function/method/const/var symbols become reader
+     * scopes whose bodies flushValueRefs scans.
+     */
+    private captureValueRefScope;
+    /**
+     * Emit same-file `references` edges from a symbol to the file-scope const/var it reads (TS/JS).
+     * The engine doesn't edge const→consumer, so impact analysis misses "change this table, affect
+     * its readers" (the ReScript-PR false positive). Same-file only (resolution is unambiguous),
+     * distinctive target names only (dodges the local-shadowing precision trap documented on
+     * function_ref), deduped per (reader, target). Default on (CODEGRAPH_VALUE_REFS=0 disables) +
+     * additive. Shadowed targets are pruned — see below.
+     */
+    private flushValueRefs;
     /**
      * Visit a node and extract information
      */
@@ -92,10 +114,41 @@ export declare class TreeSitterExtractor {
      * (class, struct, interface, trait). File nodes do not count as class-like.
      */
     private isInsideClassLikeNode;
+    /**
+     * Ruby `CONST = …` assignment whose LHS is a `constant` node — a class/module
+     * (or top-level) constant worth extracting as a symbol even inside a class.
+     * Other languages don't give an assignment a `constant`-typed LHS, so this
+     * gate is effectively Ruby-only.
+     */
+    private isClassScopeConstantAssignment;
     /**
      * Extract a function
      */
     private extractFunction;
+    /**
+     * Detect a React component declared via an HOC wrapper whose result is itself a
+     * component: `forwardRef(...)`, `memo(...)`, `React.forwardRef/memo(...)`, and
+     * styled-components / emotion `styled.tag\`…\`` / `styled(Base)\`…\``. These
+     * initializers are a call / tagged-template (not a bare arrow), so the const is
+     * otherwise classified `constant` — and a constant is skipped by both the
+     * JSX-render edge synthesizer and component resolution, so `<Button/>` usages
+     * get no edge and callers/impact silently return empty (#841).
+     *
+     * Returns `{ inner }` — the inline render function to extract as the component
+     * body, or `null` when the wrapper has no inline function (`memo(Imported)`,
+     * `styled.button\`…\``) and only a bodyless component node is minted — or
+     * `undefined` when this initializer is not a recognized component wrapper.
+     */
+    private reactComponentHoc;
+    /**
+     * Emit a `component` node for an HOC-wrapped React component declaration (see
+     * reactComponentHoc). Named by the declarator (`Button`) and located at it so
+     * the node range spans the body. When the wrapper has an inline render
+     * function, its body is walked so the component's callees (hooks, helpers) are
+     * captured under the component node — matching how a plain
+     * `const Foo = () => …` arrow component already behaves.
+     */
+    private extractReactComponentNode;
     /**
      * Extract a class
      */
@@ -157,6 +210,72 @@ export declare class TreeSitterExtractor {
      * `=> { return {...} }` block. Returns null for any other body shape.
      */
     private functionReturnedObject;
+    /**
+     * RTK Query: from a `createApi({ ..., endpoints: build => ({...}) })` or a
+     * `baseApi.injectEndpoints({ endpoints: build => ({...}) })` call initializer,
+     * return the object literal of endpoint definitions (the object the `endpoints`
+     * arrow returns). Returns null for any other call — the common case — so this
+     * stays cheap and silent. Keyed on the RTK entry-point names (`createApi` /
+     * `injectEndpoints`) like the framework extractors key on their library APIs.
+     */
+    private findRtkEndpointsObject;
+    /**
+     * Extract each RTK Query endpoint (`getX: build.query({...})` / `build.mutation`)
+     * as a function node named by the endpoint key, spanning its primary handler
+     * (the `queryFn`/`query` arrow) so the fetch logic's calls attribute to the
+     * endpoint. Without this an endpoint exists only as an object-literal property —
+     * never a node — so the generated `useXQuery` hook can't be bridged to it.
+     */
+    private extractRtkEndpoints;
+    /**
+     * The primary handler arrow of a `build.query({ queryFn|query: (…) => … })`
+     * endpoint — prefers `queryFn`, then `query`, else the first function-valued
+     * property. Returns null when the endpoint is config-only (no handler arrow).
+     */
+    private rtkEndpointHandler;
+    /**
+     * RTK Query generated-hook bindings. `export const { useGetXQuery,
+     * useUpdateYMutation } = someApi` destructures the hooks RTK generates per
+     * endpoint off a createApi result. They are real exported symbols that
+     * components import, but destructured bindings aren't otherwise extracted —
+     * mint a function node per binding matching the RTK hook convention so the hook
+     * resolves and the synthesizer can bridge it to its endpoint. Gated tight by the
+     * caller (object-pattern off a bare identifier) + the name convention here, so
+     * ordinary destructures stay unextracted.
+     */
+    private extractRtkHookBindings;
+    /** Cheap per-file heuristic: the file carries ≥2 distinct Vue-store signals
+     *  (defineStore/createStore/Vuex, or the actions/mutations/getters/namespaced
+     *  vocabulary). Gates the non-exported `const actions = {…}` Vuex-module form so
+     *  a stray `const actions` in unrelated code is never mistaken for a store. */
+    private looksLikeVueStoreFile;
+    /** True if an object literal has ≥1 inline function member (`key: () => …` /
+     *  `method(){}`) — distinguishes an inline action map (zustand/SvelteKit form
+     *  actions) from a Pinia SETUP store's all-shorthand `return { foo, bar }`
+     *  (whose functions are body-local consts, walked normally instead). */
+    private objectHasInlineFunctions;
+    /** Vue store action/mutation/getter collections defined INLINE in a store call:
+     *  `defineStore({ actions: {…}, getters: {…} })` (Pinia options form),
+     *  `defineStore('id', { actions: {…} })`, `createStore({ mutations: {…} })`,
+     *  `new Vuex.Store({ actions: {…} })`. Returns the object literals under those
+     *  keys so their methods become nodes. Gated on the store-factory callee. */
+    private findVueStoreCollectionObjects;
+    /** Extract the methods of a store-config object's `actions`/`mutations`/`getters`
+     *  properties. Used for the canonical Vuex MODULE shape `export default {
+     *  namespaced, actions: {…}, mutations: {…} }` — object-literal methods aren't
+     *  otherwise extracted, so the actions/mutations would never be nodes. */
+    private extractStoreCollectionMethods;
+    /** The SETUP function of a Pinia setup store (`defineStore('id', () => {…})`)
+     *  — an arrow/function arg with a block body. Returns null for the options form
+     *  (`defineStore({…})`) and for any non-defineStore call. The setup body's local
+     *  function consts are the store's actions; the generic body walk doesn't reach
+     *  them (nested functions are separate scopes), so they're extracted explicitly. */
+    private findPiniaSetupFn;
+    /** Extract a Pinia setup store's actions: the body-local `const foo = () => …`
+     *  / `function foo(){}` declarations, named by the binding. (State refs and other
+     *  consts are left to the normal value-extraction; only the functions matter as
+     *  the store's callable surface.) */
+    private extractPiniaSetupBody;
     /**
      * Extract a variable declaration (const, let, var, etc.)
      *

package/dist/index.d.ts

@@ -66,6 +66,28 @@ export declare class CodeGraph {
     private fileLock;
     private watcher;
     private constructor();
+    /**
+     * (Re)build the query/extraction/graph layers over the current `this.queries`
+     * (which wraps `this.db`). Factored out of the constructor so `reopenIfReplaced`
+     * can rebuild them against a fresh connection without duplicating the wiring.
+     * The path-based `fileLock` is independent of the DB handle, so it stays put.
+     */
+    private wireLayers;
+    /**
+     * Heal a stale database handle in place. If `.codegraph/` was removed and
+     * recreated at the SAME path while this instance held the DB open — a git
+     * worktree removed and re-added, or `rm -rf .codegraph` + `codegraph init` —
+     * our open fd points at the now-unlinked inode and can never see the new
+     * index, so every query returns the pre-removal snapshot until the process
+     * restarts (#925). When that's detected, open the live file at the same path,
+     * rebuild the query layers, and swap them IN PLACE, so every holder of this
+     * instance (the MCP daemon's default project, cached projectPath connections)
+     * heals without a restart. Returns true iff it reopened.
+     *
+     * POSIX-only in practice: `isReplacedOnDisk` never fires on Windows (an open
+     * file can't be unlinked there, and st_ino is unreliable).
+     */
+    reopenIfReplaced(): boolean;
     /**
      * Initialize a new CodeGraph project
      *
@@ -144,6 +166,17 @@ export declare class CodeGraph {
      * Check if the file watcher is active.
      */
     isWatching(): boolean;
+    /**
+     * True once live watching has permanently degraded (OS watch-resource
+     * exhaustion, or a write lock held past the retry budget) and auto-sync is
+     * disabled until the next {@link watch} call. Distinct from `!isWatching()`:
+     * a stopped/never-started watcher is inactive but NOT degraded. MCP tools use
+     * this to surface a whole-index "results may be stale" notice, since
+     * `getPendingFiles()` goes empty once watching stops (#876).
+     */
+    isWatcherDegraded(): boolean;
+    /** The reason live watching degraded, or null if it is healthy (#876). */
+    getWatcherDegradedReason(): string | null;
     /**
      * Files seen by the file watcher since the last successful sync —
      * the per-file "stale" signal MCP tools attach to responses so an agent

package/dist/installer/instructions-template.d.ts

@@ -17,8 +17,8 @@
  *    runs without this block, and consistently with it — including runs
  *    with zero Read/grep fallback.
  *  - **Non-MCP harnesses** — agents with no MCP client at all can still
- *    run the `codegraph explore` / `codegraph node` CLI, which prints the
- *    same output as the MCP tools.
+ *    run the `codegraph explore` CLI, which prints the same output as the
+ *    MCP tool.
  *
  * Keep this block SHORT. The main agent reads it every turn on top of the
  * server instructions — the #529 duplication-cost argument still bounds
@@ -37,5 +37,5 @@ export declare const CODEGRAPH_SECTION_END = "<!-- CODEGRAPH_END -->";
  * indexed" claim would send subagents into failing codegraph calls (the
  * noise the unindexed-session policy exists to prevent).
  */
-export declare const CODEGRAPH_INSTRUCTIONS_BLOCK = "<!-- CODEGRAPH_START -->\n## CodeGraph\n\nIn repositories indexed by CodeGraph (a `.codegraph/` directory exists at the repo root), reach for it BEFORE grep/find or reading files when you need to understand or locate code:\n\n- **MCP tools** (when available): `codegraph_explore` answers most code questions in one call \u2014 the relevant symbols' verbatim source plus the call paths between them. `codegraph_node` returns one symbol's source + callers, or reads a whole file with line numbers. If the tools are listed but deferred, load them by name via tool search.\n- **Shell** (always works): `codegraph explore \"<symbol names or question>\"` and `codegraph node <symbol-or-file>` print the same output.\n\nIf there is no `.codegraph/` directory, skip CodeGraph entirely \u2014 indexing is the user's decision.\n<!-- CODEGRAPH_END -->";
+export declare const CODEGRAPH_INSTRUCTIONS_BLOCK = "<!-- CODEGRAPH_START -->\n## CodeGraph\n\nIn repositories indexed by CodeGraph (a `.codegraph/` directory exists at the repo root), reach for it BEFORE grep/find or reading files when you need to understand or locate code:\n\n- **MCP tool** (when available): `codegraph_explore` answers most code questions in one call \u2014 the relevant symbols' verbatim source plus the call paths between them, including dynamic-dispatch hops grep can't follow. Name a file or symbol in the query to read its current line-numbered source. If it's listed but deferred, load it by name via tool search.\n- **Shell** (always works): `codegraph explore \"<symbol names or question>\"` prints the same output.\n\nIf there is no `.codegraph/` directory, skip CodeGraph entirely \u2014 indexing is the user's decision.\n<!-- CODEGRAPH_END -->";
 //# sourceMappingURL=instructions-template.d.ts.map